@debugmcp/mcp-debugger/docs/sse-environment-fix.md

Run-time step-through debugging for LLM agents.

# Debug MCP Server SSE Mode Environment Issues

## Problem Summary

When running the Debug MCP Server in SSE mode from a separate terminal, Python debugging fails with "ECONNREFUSED" errors, while the stdio mode works correctly. Both modes use identical debugging architecture, so the issue is environment-related.

## Root Cause

The SSE server runs in a different process/terminal with potentially different:
1. **PATH environment** - Python might not be accessible or might be a different installation
2. **Python modules** - debugpy might not be installed in the Python found by that terminal
3. **Timing issues** - The DAP client's error handlers abort the retry mechanism too early

## What Happens

1. SSE server starts in separate terminal
2. When debug session starts, proxy worker spawns `python -m debugpy.adapter`
3. debugpy starts (we see it log) but isn't ready to accept connections immediately
4. After 500ms, proxy tries to connect to debugpy's port
5. Connection fails with ECONNREFUSED
6. DAP client fires 'error' and 'close' events
7. These events trigger shutdown, setting `dapClient = null`
8. This aborts the retry loop prematurely (should retry 60 times over ~12 seconds)

## Solutions

### 1. Use Enhanced Launcher (Recommended)

Use `start-sse-server-enhanced.cmd` which:
- Checks Python availability before starting
- Verifies debugpy is installed
- Shows the Python location being used
- Sets environment variables to help Python discovery

### 2. Fix Timing Issue in Code

The proxy's retry mechanism is being aborted by error handlers. The connection retry loop should be more resilient to initial connection failures.

### 3. Run SSE Server in Same Environment

Instead of a separate terminal, you could:
- Configure Cline to launch the SSE server directly
- Use the same terminal/environment where stdio mode works
- Set up your terminal environment to match Cline's

## Quick Test

To verify this is an environment issue:

1. In the terminal where you run SSE server:
   ```cmd
   where python
   python -m debugpy --version
   ```

2. Compare with Cline's environment (create a test task that runs these commands)

3. Use the enhanced launcher:
   ```cmd
   start-sse-server-enhanced.cmd
   ```

## Long-term Fix

The code should be more resilient to timing issues. The DAP client shouldn't abort the entire retry mechanism on the first connection failure. Consider:

1. Don't set `dapClient = null` during connection retries
2. Increase initial delay if debugpy needs more startup time
3. Add environment detection to help users diagnose issues