torbo/flyer-crawler.projectium.com

Fork 0

Files

Torben Sorensen fac98f4c54 doc updates and test fixin

2026-01-22 11:23:43 -08:00

8.4 KiB

Raw Blame History

Bugsink MCP Troubleshooting Guide

This document tracks known issues and solutions for the Bugsink MCP server integration with Claude Code.

Issue History

2026-01-22: Server Name Prefix Collision (LATEST)

Problem:

bugsink-dev MCP server never starts (tools not available)
Production bugsink MCP works fine
Manual test works: BUGSINK_URL=http://localhost:8000 BUGSINK_TOKEN=<token> node d:/gitea/bugsink-mcp/dist/index.js
Configuration correct, environment variables correct, but server silently skipped

Root Cause: Claude Code silently skips MCP servers when server names share prefixes (e.g., bugsink and bugsink-dev). Debug logs showed bugsink-dev was NEVER started - no "Starting connection" message ever appeared.

Discovery Method:

Analyzed Claude Code debug logs at C:\Users\games3\.claude\debug\*.txt
Found that MCP startup messages only showed: memory, bugsink, redis, gitea-projectium, etc.
bugsink-dev was completely absent from startup sequence
No error was logged - server was silently filtered out

Solution Attempts:

Attempt 1: Renamed bugsink-dev to devbugsink

New MCP tool prefix: mcp__devbugsink__*
Changed URL from http://localhost:8000 to http://127.0.0.1:8000
Result: Still failed after full VS Code restart - server never loaded

Attempt 2: Renamed devbugsink to localerrors (completely different name)

New MCP tool prefix: mcp__localerrors__*
Uses completely unrelated name with no shared prefix
Based on infra-architect research showing name collision issues
Result: Still failed after full VS Code restart - server never loaded

Attempt 3: Created project-level .mcp.json file ✅ SUCCESS

Location: d:\gitea\flyer-crawler.projectium.com\flyer-crawler.projectium.com\.mcp.json
Contains localerrors server configuration
Project-level config bypassed the global config loader issue
Result: ✅ Working! Server loads successfully, 2 projects found
Tool prefix: mcp__localerrors__*

Alternative Solutions Researched:

Sentry MCP: Not compatible (different API endpoints /api/canonical/0/ vs /api/0/)
MCP-Proxy: Could work but requires separate process
Project-level .mcp.json: Alternative if global config continues to fail

Status: ✅ RESOLVED - Project-level .mcp.json works successfully

Root Cause Analysis: Claude Code's global settings.json has an issue loading localhost stdio MCP servers, even with completely distinct names. The exact cause is unknown, but may be related to:

Multiple servers using the same package (bugsink-mcp)
Localhost URL filtering in global config
Internal MCP loader bug specific to Windows/localhost combinations

Working Solution: Use project-level .mcp.json file instead of global settings.json for localhost MCP servers. This bypasses the global config loader issue entirely.

Key Insights:

Global config fails for localhost servers even with distinct names (localerrors)
Project-level .mcp.json successfully loads the same configuration
Production HTTPS servers work fine in global config
Both configs can coexist: global for production, project-level for dev

2026-01-21: Environment Variable Typo (RESOLVED)

Problem:

bugsink-dev MCP server fails to start (tools not available)
Production bugsink MCP works fine
User experienced repeated troubleshooting loops without resolution

Root Cause: Environment variable name mismatch:

Package expects: BUGSINK_TOKEN
Configuration had: BUGSINK_API_TOKEN

Discovery Method:

infra-architect subagent examined d:\gitea\bugsink-mcp\README.md line 47
Found correct variable name in package documentation
Production MCP continued working because it was started before config change

Solution Applied:

Updated C:\Users\games3\.claude\settings.json:
- Changed BUGSINK_API_TOKEN to BUGSINK_TOKEN for both bugsink and bugsink-dev
- Removed unused BUGSINK_ORG_SLUG environment variable
Updated documentation:
- CLAUDE.md MCP Servers section (lines 307-327)
- docs/BUGSINK-SYNC.md environment variables (line 66, 108)
Required action:
- Restart Claude Code to reload MCP servers

Status: Fixed - but superseded by server name collision issue above

Correct Configuration

Required Environment Variables

The bugsink-mcp package requires exactly TWO environment variables:

{
  "bugsink": {
    "command": "node",
    "args": ["d:\\gitea\\bugsink-mcp\\dist\\index.js"],
    "env": {
      "BUGSINK_URL": "https://bugsink.projectium.com",
      "BUGSINK_TOKEN": "<40-char-hex-token>"
    }
  },
  "localerrors": {
    "command": "node",
    "args": ["d:\\gitea\\bugsink-mcp\\dist\\index.js"],
    "env": {
      "BUGSINK_URL": "http://127.0.0.1:8000",
      "BUGSINK_TOKEN": "<40-char-hex-token>"
    }
  }
}

Important:

Variable is BUGSINK_TOKEN, NOT BUGSINK_API_TOKEN
BUGSINK_ORG_SLUG is NOT used by the package
Works with both HTTPS (production) and HTTP (localhost)
Use completely distinct name like localerrors (not bugsink-dev or devbugsink) to avoid any name collision

Common Issues

MCP Server Tools Not Available

Symptoms:

mcp__localerrors__* tools return "No such tool available"
Production bugsink MCP may work while localerrors fails

Possible Causes:

Wrong environment variable name (most common)
- Check: Variable must be BUGSINK_TOKEN, not BUGSINK_API_TOKEN
Invalid API token
- Check: Token must be 40-character lowercase hex
- Verify: Token created via Django management command
Bugsink instance not accessible
- Test: curl -s -o /dev/null -w "%{http_code}" http://localhost:8000
- Expected: 302 (redirect) or 200
MCP server crashed on startup
- Check: Claude Code logs (if available)
- Test manually: BUGSINK_URL=http://localhost:8000 BUGSINK_TOKEN=<token> node d:/gitea/bugsink-mcp/dist/index.js

Solution:

Verify correct variable names in settings.json
Restart Claude Code
Test connection: Use mcp__bugsink__test_connection tool

Testing MCP Server

Manual Test

Run the MCP server directly to see error output:

# For localhost Bugsink
cd d:\gitea\bugsink-mcp
set BUGSINK_URL=http://localhost:8000
set BUGSINK_TOKEN=a609c2886daa4e1e05f1517074d7779a5fb49056
node dist/index.js

Expected output:

Bugsink MCP server started
Connected to: http://localhost:8000

Test in Claude Code

After restart, verify both MCP servers work:

// Production Bugsink
mcp__bugsink__test_connection();
// Expected: "Connection successful: Connected successfully. Found N project(s)."

// Dev Container Bugsink
mcp__localerrors__test_connection();
// Expected: "Connection successful: Connected successfully. Found N project(s)."

Creating Bugsink API Tokens

Bugsink 2.0.11 does NOT have a "Settings > API Keys" menu in the UI. Tokens must be created via Django management command.

For Dev Container (localhost:8000)

MSYS_NO_PATHCONV=1 podman exec -e DATABASE_URL=postgresql://bugsink:bugsink_dev_password@postgres:5432/bugsink -e SECRET_KEY=dev-bugsink-secret-key-minimum-50-characters-for-security flyer-crawler-dev sh -c 'cd /opt/bugsink/conf && DJANGO_SETTINGS_MODULE=bugsink_conf PYTHONPATH=/opt/bugsink/conf:/opt/bugsink/lib/python3.10/site-packages /opt/bugsink/bin/python -m django create_auth_token'

For Production (bugsink.projectium.com via SSH)

ssh root@projectium.com "cd /opt/bugsink && bugsink-manage create_auth_token"

Both commands output a 40-character hex token.

Package Information

Repository: https://github.com/j-shelfwood/bugsink-mcp.git
Local Installation: d:\gitea\bugsink-mcp
Build Command: npm install && npm run build
Main File: dist/index.js

Failed Solutions (Do Not Retry)

These approaches were tried and did NOT work:

❌ Regenerating API token multiple times
❌ Restarting Claude Code without config changes
❌ Checking Bugsink instance accessibility (was already working)
❌ Adding BUGSINK_ORG_SLUG environment variable (not used by package)

Lesson: Always verify actual package requirements in source code/README before troubleshooting.

8.4 KiB Raw Blame History