Skip to content

DEBUG.md

Latest commit

 

History

History
511 lines (391 loc) · 8.57 KB

DEBUG.md

File metadata and controls

511 lines (391 loc) · 8.57 KB

Debug Endpoint Guide

Overview

The debug endpoints provide real-time visibility into bridge operations. Use these tools to monitor connections, troubleshoot issues, and understand message flow.

Debug Dashboard

Access

http://localhost:8081/debug

Features:

  • Connection list
  • Active sessions
  • Subprocess states
  • Message counts
  • Real-time updates

Information Displayed

Active connections:

  • Session ID
  • Namespace
  • Connection time
  • Message count

Subprocess states:

  • stopped - Process not running
  • starting - Process starting up
  • running - Process active
  • stopping - Process shutting down
  • error - Process error

Metrics:

  • Total messages (in/out)
  • Connection duration
  • Last activity timestamp

Debug Stream

Access

Browser:

http://localhost:8081/debug/stream

curl:

curl -N http://localhost:8081/debug/stream

WebSocket (if supported):

ws://localhost:8081/debug/stream

Message Format

{
  "event": "message" | "connection" | "ping",
  "direction": "in" | "out",  // For message events
  "namespace": "git",
  "session": "session-123",
  "timestamp": "2025-03-08T12:00:00Z",
  "message": {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {...}
  }
}

Event Types

Message Event

Shows JSON-RPC messages flowing through the bridge.

Incoming (client → bridge → server):

event: message
data: {
  "direction": "in",
  "namespace": "git",
  "session": "session-123",
  "message": {"jsonrpc":"2.0","id":1,"method":"ping"}
}

Outgoing (server → bridge → client):

event: message
data: {
  "direction": "out",
  "namespace": "git",
  "session": "session-123",
  "message": {"jsonrpc":"2.0","id":1,"result":{...}}
}

Connection Event

Shows connection lifecycle events.

Connected:

event: connection
data: {
  "event": "connected",
  "namespace": "git",
  "session": "session-123"
}

Disconnected:

event: connection
data: {
  "event": "disconnected",
  "namespace": "git",
  "session": "session-123"
}

Ping Event

Heartbeat from debug stream.

event: ping
data: {"time":"2025-03-08T12:00:00Z"}

Connection States

connecting

Subprocess is starting up.

Symptoms: No messages yet Action: Wait for process to start

running

Subprocess is active and handling requests.

Symptoms: Messages flowing Action: Normal operation

disconnected

Client disconnected.

Symptoms: No more messages from client Action: Session cleanup

error

Subprocess error occurred.

Symptoms: Error messages, connection dropped Action: Check logs and subprocess stderr

stopping

Graceful shutdown in progress.

Symptoms: Closing connections Action: Wait for cleanup

Troubleshooting Scenarios

Scenario 1: Subprocess Won't Start

Symptoms:

  • Connection hangs
  • No messages appear
  • /health/{namespace} shows "no subprocess"

Debug Steps:

  1. Watch /debug/stream
  2. See "connection" event?
  3. Check bridge logs for errors

Common Causes:

  • Binary not found
  • Wrong arguments
  • Permission denied
  • Port conflict

Fix:

# Check if binary exists
which npx

# Verify binary path
ls -la /path/to/binary

# Test manually
npx -y @modelcontextprotocol/server-git

# Check permissions
chmod +x /path/to/binary

Scenario 2: Messages Not Streaming

Symptoms:

  • POST returns 202
  • No response received
  • SSE stream empty

Debug Steps:

  1. Watch /debug/stream
  2. See "in" message?
  3. See "out" message?

If "in" but no "out":

Problem: Subprocess not processing
Causes:
  - Subprocess crashed
  - Invalid JSON-RPC
  - Subprocess not outputting to stdout

If no "in" message:

Problem: Request not reaching bridge
Causes:
  - Network issue
  - Wrong endpoint
  - CORS blocked

Fix:

# Validate JSON-RPC
cat request.json | jq

# Check subprocess output
# Ensure each message ends with newline (\n)

# Check CORS
curl -v http://localhost:8080/mcp/git/message

Scenario 3: High Restart Count

Symptoms:

  • Subprocess keeps restarting
  • /debug/stream shows crash events
  • Bridge logs show errors

Debug Steps:

  1. Check /debug/stream - see crash events
  2. Check subprocess stderr
  3. Look at bridge logs

Common Causes:

  • Subprocess error
  • Timeout
  • Out of memory
  • Config error

Fix:

# Check subprocess logs
sudo journalctl -u mcp-bridge -f

# Check resource usage
free -h
df -h

# Increase timeout if needed
# servers:
#   git:
#     timeout: 120s

# Check for memory issues
# servers:
#   git:
#     max_restarts: 10

Scenario 4: CORS Errors

Symptoms:

  • Browser console shows CORS error
  • Request blocked
  • No connection established

Debug Steps:

  1. Check browser console
  2. Verify allowed_origins in config
  3. Check origin matches exactly

Fix:

# Config
bridge:
  allowed_origins:
    - http://localhost:3000
    - http://127.0.0.1:3000

# Ensure exact match (including protocol)
# http:// not https://
# localhost not 127.0.0.1 (unless both listed)

Scenario 5: Session Duplication

Symptoms:

  • Multiple sessions for same client
  • Session ID conflicts
  • Unexpected behavior

Debug Steps:

  1. Check /debug/stream
  2. See multiple "connected" events?
  3. Same session ID?

Fix:

# Ensure unique session IDs
# Client should generate unique IDs
# Session: session-{timestamp}

Debug Commands

Monitor Stream

# Real-time monitoring
curl -N http://localhost:8081/debug/stream

# Filter by namespace (if supported)
curl -N "http://localhost:8081/debug/stream?namespace=git"

# Save to file
curl -N http://localhost:8081/debug/stream > debug.log

Check Health

# Bridge health
curl http://localhost:8080/health

# Namespace health
curl http://localhost:8080/health/git

# Pretty print
curl http://localhost:8080/health/git | jq

View Dashboard

# HTML dashboard
curl http://localhost:8081/debug

# Open in browser
xdg-open http://localhost:8081/debug

Monitor Processes

# Check subprocess status
ps aux | grep mcp

# Check ports in use
lsof -i :8080
lsof -i :8081

# Check for zombie processes
ps aux | grep defunct

Log Analysis

Bridge Logs

Location:

# Systemd
sudo journalctl -u mcp-bridge -f

# Direct
tail -f /path/to/bridge.log

Common patterns:

{"level":"INFO","msg":"Connection established","namespace":"git"}
{"level":"ERROR","msg":"Subprocess crashed","namespace":"git"}
{"level":"WARN","msg":"High restart count","namespace":"git"}

Subprocess Logs

Location:

# Depends on subprocess
# Check stderr output

Common patterns:

Error: Cannot find module
Error: Port already in use
Error: Permission denied

Performance Monitoring

Connection Metrics

Check active connections:

curl http://localhost:8081/debug

Monitor over time:

# Script to monitor connections
while true; do
  curl -s http://localhost:8081/debug | grep -c "session"
  sleep 5
done

Message Rate

Messages per minute:

# Count messages in stream
curl -N http://localhost:8081/debug/stream | grep -c "event: message"

Response Time

Measure response time:

# Time request to completion
time curl -X POST http://localhost:8080/mcp/git/message \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping","params":{}}'

Security Considerations

Debug Endpoint Security

Best practices:

  1. Only expose debug_port internally
  2. Don't expose to public internet
  3. Monitor for suspicious activity
  4. Enable authentication (future feature)

Configuration:

bridge:
  debug_port: 8081  # Internal only

Access Control

Current: No authentication Recommended: Use reverse proxy with auth Future: Built-in authentication

Tips

Effective Debugging

  1. Start with health check - Verify bridge is running
  2. Watch debug stream - See real-time activity
  3. Check subprocess logs - Find root cause
  4. Use curl with verbose - See HTTP details
  5. Monitor over time - Catch intermittent issues

Common Patterns

Normal flow:

connection (connected)
  → message (in)
  → message (out)
  → message (in)
  → message (out)
connection (disconnected)

Error flow:

connection (connected)
  → message (in)
  → error (crashed)
connection (disconnected)
  → message (reconnecting)

Additional Resources