# 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:**

1. Global config fails for localhost servers even with distinct names (`localerrors`)
2. Project-level `.mcp.json` successfully loads the same configuration
3. Production HTTPS servers work fine in global config
4. 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:**

1. 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

2. Updated documentation:
   - `CLAUDE.md` MCP Servers section (lines 307-327)
   - `docs/BUGSINK-SYNC.md` environment variables (line 66, 108)

3. 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:

```json
{
  "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:**

1. **Wrong environment variable name** (most common)
   - Check: Variable must be `BUGSINK_TOKEN`, not `BUGSINK_API_TOKEN`

2. **Invalid API token**
   - Check: Token must be 40-character lowercase hex
   - Verify: Token created via Django management command

3. **Bugsink instance not accessible**
   - Test: `curl -s -o /dev/null -w "%{http_code}" http://localhost:8000`
   - Expected: `302` (redirect) or `200`

4. **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:**

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

---

## Testing MCP Server

### Manual Test

Run the MCP server directly to see error output:

```bash
# 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:

```typescript
// 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)

```bash
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)

```bash
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`

---

## Related Documentation

- [CLAUDE.md MCP Servers Section](../CLAUDE.md#mcp-servers)
- [DEV-CONTAINER-BUGSINK.md](./DEV-CONTAINER-BUGSINK.md)
- [BUGSINK-SYNC.md](./BUGSINK-SYNC.md)

---

## Failed Solutions (Do Not Retry)

These approaches were tried and did NOT work:

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

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