@debugmcp/mcp-debugger/docs/pythonpath-to-executablepath-migration-summary.md

Run-time step-through debugging for LLM agents.

# pythonPath to executablePath Migration Summary

## Date: 2025-07-12

## Original Task
The task began with a request to add tests for `src/utils/session-migration.ts` to improve test coverage. This file was providing backward compatibility for the `pythonPath` → `executablePath` parameter migration.

## Pivotal Decision
Upon investigation, we discovered that maintaining backward compatibility was unnecessary technical debt. The decision was made to:
1. Complete the migration from `pythonPath` to `executablePath` throughout the codebase
2. Remove all backward compatibility code
3. Delete the now-unnecessary `src/utils/session-migration.ts` file

## Work Completed

### Phase 1: Discovery and Analysis
- Analyzed `src/utils/session-migration.ts` and found it was providing temporary backward compatibility
- Identified all occurrences of `pythonPath` in the codebase
- Made the strategic decision to remove backward compatibility entirely

### Phase 2: Core Code Migration
Updated all TypeScript interfaces and implementations:

1. **Proxy Interfaces** (`src/proxy/dap-proxy-interfaces.ts`):
   - `ProxyInitPayload`: Changed `pythonPath` to `executablePath`
   - Updated all related interfaces

2. **Session Models** (`src/session/models.ts`):
   - `CreateSessionParams`: Changed `pythonPath` to `executablePath`
   - `ManagedSession`: Changed `pythonPath` to `executablePath`

3. **Proxy Configuration** (`src/proxy/proxy-config.ts`):
   - `ProxyConfig`: Changed `pythonPath` to `executablePath`

4. **Server Implementation** (`src/server.ts`):
   - Removed backward compatibility handling
   - Updated parameter processing

5. **Proxy Manager** (`src/proxy/proxy-manager.ts`):
   - Updated to use `executablePath` throughout
   - Removed compatibility mapping

6. **DAP Proxy Worker** (`src/proxy/dap-proxy-worker.ts`):
   - Updated initialization to expect `executablePath`

7. **Session Manager Core** (`src/session/session-manager-core.ts`):
   - Updated to pass `executablePath` to proxy

8. **Deleted Files**:
   - Removed `src/utils/session-migration.ts` entirely
   - Removed obsolete `src/proxy/dap-proxy-process-manager.ts`

### Phase 3: Test Updates
Updated 20+ test files to use `executablePath`:

- `tests/core/unit/session/session-manager-*.test.ts`
- `tests/core/unit/proxy/proxy-manager-*.test.ts`
- `tests/unit/proxy/dap-proxy-*.test.ts`
- `tests/e2e/*.test.ts`
- `tests/fixtures/test-utils.ts`
- And many more...

### Phase 4: Critical Bug Fix
Discovered a critical issue in `src/proxy/dap-proxy-message-parser.ts`:
- The message parser was still validating for `pythonPath` instead of `executablePath`
- This was causing all E2E tests to fail with server startup errors
- Fixed the validation and updated the corresponding tests

### Phase 5: Documentation Updates
Updated all documentation to remove `pythonPath` references:

1. **User-facing docs**:
   - `docs/tool-reference.md`: Updated parameter documentation
   - `docs/troubleshooting.md`: Updated Python path references
   - `docs/logging-format-specification.md`: Updated example logs

2. **Architecture docs**:
   - `docs/architecture/component-design.md`: Updated API signatures
   - `docs/architecture/current-component-diagram.md`: Updated diagrams
   - `docs/architecture/current-python-dependencies.md`: Updated analysis
   - `docs/architecture/refactoring-summary.md`: Added update notes
   - `docs/architecture/adapter-pattern-design.md`: Updated tool signatures

3. **Marked as superseded**:
   - `docs/archive/refactoring/task-2.2-session-manager-refactoring-summary.md`: Added superseded notice

## Test Results

### Before Migration
- 26 tests failing due to mixed `pythonPath`/`executablePath` usage
- Server startup failures in E2E tests

### After Migration
- All 978 tests passing ✅
- Clean, consistent codebase with no backward compatibility debt

## Breaking Changes

This is a **BREAKING CHANGE** for any clients using the MCP debugger:

### Before
```json
{
  "tool": "create_debug_session",
  "arguments": {
    "language": "python",
    "pythonPath": "/usr/bin/python3"
  }
}
```

### After
```json
{
  "tool": "create_debug_session",
  "arguments": {
    "language": "python",
    "executablePath": "/usr/bin/python3"
  }
}
```

## Migration Guide for Users

Users must update their code to use `executablePath` instead of `pythonPath`. There is no backward compatibility - the old parameter will cause an error.

See `docs/migration-guide.md` for full details.

## Summary

What started as a simple task to add test coverage evolved into completing a major refactoring effort. By removing the backward compatibility layer, we:

1. Simplified the codebase by removing unnecessary migration code
2. Made the API more consistent and language-agnostic
3. Fixed critical bugs that were hidden by the compatibility layer
4. Set the stage for true multi-language support

The migration is now 100% complete with no remnants of the old `pythonPath` parameter remaining in the codebase.