AI Coding Guidelines

Appearance

Troubleshooting ​

Complete troubleshooting guide for common issues in the AI Coding Guidelines workflow.

Quick Diagnostics ​

System Check Commands ​

bash
# List all installed servers
claude mcp list

# Check Node.js and npm
node --version && npm --version

# Verify UV installation
uv --version

# Test GitHub token
echo $NODE_AUTH_TOKEN | cut -c1-10  # Show first 10 chars

Environment Validation ​

bash
# Check essential environment variables
echo "NODE_AUTH_TOKEN: ${NODE_AUTH_TOKEN:+SET}" 
echo "GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_PERSONAL_ACCESS_TOKEN:+SET}"

# Verify npm authentication
npm whoami --registry=https://npm.pkg.github.com

# Test network connectivity
ping -c 3 github.com

MCP Server Issues ​

Server Installation Failures ​

Error: "command not found: npx" ​

Symptoms:

  • Installation commands fail with "npx: command not found"
  • MCP server setup scripts error out

Solutions:

  1. Install Node.js from nodejs.org (version 18+ recommended)

  2. Verify installation:

    bash
    node --version && npm --version

  3. Restart terminal/shell session

  4. Retry MCP server installation

Validation:

bash
which npx  # Should show path to npx
npx --version  # Should show version number

Error: "command not found: uvx" ​

Symptoms:

  • UV-based server installations fail
  • Git MCP server won't install

Solutions:

  1. Install UV package manager:

    bash
    curl -LsSf https://astral.sh/uv/install.sh | sh

  2. Restart terminal or source profile:

    bash
    source ~/.bashrc  # or ~/.zshrc

  3. Verify installation:

    bash
    uv --version
which uvx

Error: "EACCES: permission denied" ​

Symptoms:

  • Permission denied errors during npm operations
  • Cannot write to npm directories

Solutions:

macOS/Linux:

bash
# Fix npm permissions
sudo chown -R $(whoami) ~/.npm

# Or use npm's built-in fix
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Windows:

  • Run Command Prompt or PowerShell as Administrator
  • Install Node.js with administrator privileges

Validation:

bash
npm config get prefix  # Should show user-writable directory
npm install -g npm@latest  # Should work without sudo

Error: "Server failed to start" ​

Symptoms:

  • MCP server shows as installed but won't start
  • Claude Code can't connect to server
  • Server logs show startup errors

Diagnostic Steps:

bash
# Check server logs
claude mcp logs server-name

# Verify server configuration
claude mcp list

# Check system resources
top  # or Activity Monitor on macOS

Solutions:

  1. Check Node.js version compatibility:

    bash
    node --version  # Should be 18+

  2. Restart Claude Code session:

    • Close and reopen Claude Code
    • Clear session cache if available

  3. Reinstall problematic server:

    bash
    claude mcp remove server-name
# Reinstall with appropriate command

  4. Check port conflicts:

    bash
    # Check if ports are in use
lsof -i :3000  # or other relevant ports

  5. Verify system resources:

    • Ensure sufficient RAM (2GB+ recommended)
    • Check disk space
    • Close unnecessary applications

Authentication Issues ​

GitHub Token Problems ​

Error: "401 Unauthorized" or "403 Forbidden"

Diagnostic:

bash
# Test token validity
curl -H "Authorization: token $NODE_AUTH_TOKEN" \
     https://api.github.com/user

# Check token scopes
curl -H "Authorization: token $NODE_AUTH_TOKEN" \
     -I https://api.github.com/user | grep -i x-oauth-scopes

Solutions:

  1. Verify token exists:

    bash
    echo $NODE_AUTH_TOKEN  # Should show token

  2. Check token scopes:

    • Go to GitHub Settings > Developer settings > Personal access tokens
    • Ensure token has read:packages scope
    • For GitHub MCP server, also need repo scope

  3. Regenerate token:

    bash
    # Generate new token at github.com/settings/tokens
export NODE_AUTH_TOKEN=new_token_here
# Update shell profile for persistence

  4. Update MCP server configuration:

    bash
    claude mcp remove developer-tools
claude mcp add-json developer-tools '{
  "command": "npx", 
  "args": ["-y", "@agronod/developer-tools-mcp@latest"], 
  "env": { "NODE_AUTH_TOKEN": "'$NODE_AUTH_TOKEN'" }
}' -s user

NPM Authentication Issues ​

Error: "Unable to authenticate" or "E404: Not found"

Diagnostic:

bash
# Check npm authentication
npm whoami --registry=https://npm.pkg.github.com

# Test package access
npm view @agronod/developer-tools-mcp --registry=https://npm.pkg.github.com

Solutions:

  1. Configure npm authentication:

    bash
    npm login --scope=@agronod --registry=https://npm.pkg.github.com
# Use your GitHub username and NODE_AUTH_TOKEN as password

  2. Set registry configuration:

    bash
    npm config set @agronod:registry https://npm.pkg.github.com

  3. Verify authentication:

    bash
    npm config get //npm.pkg.github.com/:_authToken
# Should show your token

Performance Issues ​

Slow Server Response ​

Symptoms:

  • Commands take long time to execute
  • Timeouts during operations
  • High CPU/memory usage

Diagnostic:

bash
# Monitor system resources
top
htop  # if installed

# Check Claude MCP process usage
ps aux | grep mcp

# Monitor network activity
netstat -an | grep ESTABLISHED

Solutions:

  1. Reduce concurrent servers:

    bash
    # Remove unused servers
claude mcp remove unused-server-name

  2. Restart specific servers:

    bash
    claude mcp remove server-name
# Reinstall server

  3. System optimization:

    • Close unnecessary applications
    • Ensure sufficient RAM (4GB+ recommended)
    • Check available disk space

  4. Network optimization:

    • Use wired connection if possible
    • Check firewall settings
    • Verify corporate proxy configuration

Network Connectivity Issues ​

Symptoms:

  • Servers fail to connect to external services
  • Package installation timeouts
  • API calls fail

Diagnostic:

bash
# Test basic connectivity
ping github.com
ping npmjs.org

# Test HTTPS connectivity
curl -I https://api.github.com

# Check DNS resolution
nslookup github.com

Solutions:

  1. Firewall configuration:

    bash
    # Check firewall status (macOS)
sudo pfctl -s all

# Check firewall status (Linux)
sudo ufw status

  2. Corporate proxy setup:

    bash
    # Set npm proxy
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy https://proxy.company.com:8080

# Set system proxy in environment
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=https://proxy.company.com:8080

  3. DNS configuration:

    bash
    # Use alternative DNS (Google)
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

Tool-Specific Issues ​

Git Operations ​

Error: "Not a git repository" ​

Solutions:

bash
# Initialize git repository
git init

# Verify git status
git status

Error: "Unable to create commit" ​

Diagnostic:

bash
# Check git configuration
git config --list | grep user

# Check working directory status
git status

Solutions:

bash
# Configure git user
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Stage changes
git add .

# Create commit
git commit -m "Initial commit"

Specification Generation ​

Low Confidence Warnings ​

Symptoms:

  • Tools report confidence < 0.7
  • Interactive mode triggered unexpectedly
  • Incomplete specifications generated

Solutions:

  1. Load project context:

    bash
    /context-prime "your specific task"

  2. Create requirements document:

    bash
    /project-prp "feature name"
# Fill out comprehensive requirements

  3. Update project documentation:

    bash
    /project-update --focus architecture

  4. Use project guidance:

    bash
    /project-next --verbose

File Operations ​

Error: "Permission denied" on file operations ​

Solutions:

bash
# Check file permissions
ls -la filename

# Fix permissions
chmod 644 filename  # for files
chmod 755 directory  # for directories

# Check directory ownership
sudo chown -R $(whoami) directory

Environment-Specific Issues ​

macOS Issues ​

Code signing issues with MCP servers ​

Solutions:

bash
# Allow unsigned code execution
sudo spctl --master-disable

# Or allow specific applications
sudo spctl --add /path/to/mcp/server

Homebrew conflicts ​

Solutions:

bash
# Update Homebrew
brew update && brew upgrade

# Check for conflicts
brew doctor

# Reinstall Node.js via Homebrew
brew reinstall node

Windows Issues ​

PowerShell execution policy ​

Error: "Execution of scripts is disabled on this system"

Solutions:

powershell
# Set execution policy (run as Administrator)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Verify policy
Get-ExecutionPolicy -List

Windows Defender interference ​

Solutions:

  1. Add exclusions for:

    • Node.js installation directory
    • npm global directory
    • Project directories

  2. Temporarily disable real-time protection during setup

Linux Issues ​

Missing development tools ​

Solutions:

bash
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install build-essential curl git

# CentOS/RHEL
sudo yum groupinstall "Development Tools"
sudo yum install curl git

# Arch Linux
sudo pacman -S base-devel curl git

Recovery Procedures ​

Complete MCP Reset ​

When all else fails, completely reset MCP configuration:

bash
# Stop Claude Code
# Remove all MCP servers
claude mcp list | grep -v "No servers" | xargs -I {} claude mcp remove {}

# Clear MCP configuration (backup first)
cp ~/.claude/mcp.json ~/.claude/mcp.json.backup
rm ~/.claude/mcp.json

# Restart Claude Code and run setup
# Run quick-setup.sh from project root

Environment Reset ​

bash
# Reset npm configuration
rm ~/.npmrc

# Clear npm cache
npm cache clean --force

# Reset Node.js (via package manager)
# macOS with Homebrew:
brew uninstall node && brew install node

# Ubuntu/Debian:
sudo apt-get remove nodejs npm && sudo apt-get install nodejs npm

Project Reset ​

bash
# Reset to clean git state (WARNING: loses uncommitted changes)
git clean -fd
git reset --hard HEAD

# Reinitialize project
/project-init --force

# Load context and continue
/context-prime

Getting Help ​

Log Collection ​

When reporting issues, collect relevant logs:

bash
# System information
uname -a
node --version
npm --version
claude --version

# MCP server logs
claude mcp logs server-name > server-logs.txt

# Environment variables (sanitized)
env | grep -E "(NODE_|GITHUB_|CLAUDE_)" | sed 's/=.*/=***/' > env-vars.txt

# Git status (if relevant)
git status > git-status.txt
git log --oneline -10 > recent-commits.txt

Debug Mode ​

Enable verbose logging:

bash
# Set debug environment variables
export DEBUG=*
export VERBOSE=true

# Run commands with additional logging
/command-name --verbose

Next Steps ​

Built with VitePress and powered by Claude Code

MIT Licensed