AI Integration Issues

Troubleshooting MCP server and AI CLI connection problems.

Tools Not Available

Symptoms

• AI assistant doesn't recognize Bob the Fixer tools
• "I don't have access to that tool"
• MCP tools not listed

Diagnosis

Claude Code

# List registered MCP servers
claude mcp list

# Look for "bob-the-fixer" in the output

GitHub Copilot

# Check config file exists
cat ~/.copilot/mcp-config.json | jq '.mcpServers["bob-the-fixer"]'

Gemini

gemini mcp list

OpenAI Codex

codex mcp list

Solutions

Re-register MCP Server

Claude:

claude mcp remove bob-the-fixer 2>/dev/null
claude mcp add bob-the-fixer node "/path/to/bob-the-fixer/packages/core/dist/universal-mcp-server.js" \
  --scope user \
  --env SONAR_URL=http://localhost:9000 \
  --env SONAR_TOKEN="your-token"

Gemini:

gemini mcp remove bob-the-fixer 2>/dev/null
gemini mcp add bob-the-fixer node "/path/to/universal-mcp-server.js" \
  --scope user \
  --env SONAR_URL=http://localhost:9000 \
  --env SONAR_TOKEN="your-token"

GitHub Copilot:

Create/edit ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "bob-the-fixer": {
      "type": "local",
      "command": "node",
      "tools": ["*"],
      "args": ["/path/to/bob-the-fixer/packages/core/dist/universal-mcp-server.js"],
      "env": {
        "SONAR_URL": "http://localhost:9000",
        "SONAR_TOKEN": "your-token"
      }
    }
  }
}

Restart AI CLI

After registering, restart your AI CLI session:

# Exit and restart
exit
claude  # or gemini, codex, etc.

Verify MCP Server File Exists

ls -la /path/to/bob-the-fixer/packages/core/dist/universal-mcp-server.js

# If missing, rebuild:
cd /path/to/bob-the-fixer
npm run build

MCP Server Crashes

Symptoms

• Tools work briefly then stop
• "MCP server disconnected"
• Errors mid-conversation

Diagnosis

# Check for crash logs
cat /tmp/bobthefixer-mcp.log

# Try running server directly
node /path/to/bob-the-fixer/packages/core/dist/universal-mcp-server.js

Solutions

Fix Environment Variables

Ensure all required variables are set:

# Required
SONAR_URL=http://localhost:9000
SONAR_TOKEN=your-token

# Optional but recommended
NODE_ENV=production
LOG_LEVEL=info

Check Node Version

node --version
# Requires Node 18+

# If too old:
nvm install 18
nvm use 18

Rebuild MCP Server

cd /path/to/bob-the-fixer
rm -rf packages/core/dist
npm run build

Slow Responses

Symptoms

• Long delays before tool responses
• Timeouts during operations
• "Tool execution timeout"

Causes

• SonarQube server slow
• Large project analysis
• Network latency
• Insufficient timeouts

Solutions

Increase Timeouts

OpenAI Codex (most sensitive to timeouts):

codex mcp add bob-the-fixer \
  --env MCP_REQUEST_TIMEOUT=600000 \
  --env SCAN_TIMEOUT=1200000 \
  -- node "/path/to/universal-mcp-server.js"

Also update ~/.codex/config.toml:

[mcp]
request_timeout_ms = 600000
startup_timeout_ms = 60000

Check SonarQube Performance

# Monitor resource usage
docker stats bobthefixer_sonarqube

# If maxed out, increase Docker resources

Use Lighter Operations

Instead of full scans, use targeted operations:

# Instead of: "Scan the entire project"
# Try: "Show me the current issues"

# Instead of: "Analyze all patterns"
# Try: "Get details on issue ABC123"

Authentication Errors in MCP

Symptoms

MCP Error: 401 Unauthorized
Tool execution failed: Invalid token

Solutions

Update Token in Configuration

The token in your MCP config may be outdated. Re-register with new token:

# Generate new token in SonarQube UI
# Then update:

claude mcp remove bob-the-fixer
claude mcp add bob-the-fixer node "/path/to/universal-mcp-server.js" \
  --scope user \
  --env SONAR_URL=http://localhost:9000 \
  --env SONAR_TOKEN="new-token-here"

Verify Token Format

Tokens should:

• Start with squ_
• Be alphanumeric
• Not contain spaces

# Correct
--env SONAR_TOKEN="squ_abc123def456"

# Wrong
--env SONAR_TOKEN="squ abc123" # has space
--env SONAR_TOKEN=squ_abc123   # missing quotes (may work but risky)

Tool Execution Errors

Symptoms

Error executing tool: sonar_scan_project
Unexpected error in tool handler

Diagnosis

Enable verbose logging:

# Add to MCP registration
--env LOG_LEVEL=debug
--env LOG_FILE_PATH=/tmp/bobthefixer-debug.log

Then check logs:

tail -f /tmp/bobthefixer-debug.log

Common Errors

"Project not found"

Error: Project 'xxx' not found

Solution: Run sonar_auto_setup first to create the project.

"Cannot read properties of undefined"

Solution: Usually means SonarQube returned unexpected data. Check:

1. SonarQube is fully started
2. Project exists
3. Token has access

"ENOENT: no such file or directory"

Solution: File path issue. Check:

1. You're in the correct directory
2. MCP server path is absolute
3. Project files exist

Configuration Conflicts

Symptoms

• Different behavior in different sessions
• Token works sometimes, not others
• Wrong project being scanned

Solutions

Check for Multiple Configs

# Find all Bob the Fixer configs
find ~ -name "bobthefixer.env" 2>/dev/null
find ~ -name "mcp-config.json" 2>/dev/null

# Look for duplicates and remove old ones

Reset Configuration

# In your AI assistant
Reset my SonarQube configuration and start fresh

Or manually:

# Remove local config
rm bobthefixer.env

# Clear MCP registration
claude mcp remove bob-the-fixer

# Re-setup
cd /path/to/bob-the-fixer
./install.sh

Debugging MCP Connection

Test MCP Server Directly

# Run server manually
cd /path/to/bob-the-fixer
SONAR_URL=http://localhost:9000 \
SONAR_TOKEN=your-token \
LOG_LEVEL=debug \
node packages/core/dist/universal-mcp-server.js

If it runs without errors, the server itself is working.

Check for Port Conflicts

MCP servers communicate via stdio, not network ports. However, check that no other processes interfere:

# Check for zombie node processes
ps aux | grep "universal-mcp-server"

# Kill if stuck
pkill -f "universal-mcp-server"

Verify JSON Configuration

For GitHub Copilot, ensure valid JSON:

# Validate JSON syntax
cat ~/.copilot/mcp-config.json | jq .

# If error, fix the JSON

AI CLI-Specific Issues

Claude Code

Issue: "claude: command not found"

# Reinstall
npm install -g @anthropic-ai/claude-code

# Check path
which claude

GitHub Copilot

Issue: Config file not read

# Ensure directory exists
mkdir -p ~/.copilot

# Check permissions
ls -la ~/.copilot/mcp-config.json

Gemini

Issue: "gemini: command not found"

# Reinstall
npm install -g @google/gemini-cli

# Re-authenticate
gemini auth login

OpenAI Codex

Issue: Frequent timeouts

# Codex needs longer timeouts for SonarQube operations
# Update ~/.codex/config.toml with higher values

Getting MCP Logs

Enable Logging

Add to your MCP registration:

--env LOG_FILE_PATH=/tmp/bobthefixer-mcp.log
--env LOG_LEVEL=debug

View Logs

# Real-time monitoring
tail -f /tmp/bobthefixer-mcp.log

# Search for errors
grep -i error /tmp/bobthefixer-mcp.log

Log Levels

Level	Shows
error	Only errors
warn	Errors and warnings
info	Normal operation (default)
debug	Everything (verbose)

Next Steps

After resolving AI integration issues:

1. Test with a simple command:

   What tools are available from Bob the Fixer?

2. Run a scan to verify end-to-end:

   Scan this project with SonarQube

3. If issues persist, see Connection Issues for SonarQube connectivity problems.