Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,10 +61,9 @@ Include in each source file:

## Key Dependencies

- `fastmcp`: MCP server framework
- `@modelcontextprotocol/sdk`: Official MCP server framework (`McpServer`, `SSEServerTransport`)
- `zod`: Schema validation for tool parameters
- `@modelcontextprotocol/sdk`: MCP protocol types
- `express`: HTTP server (used by FastMCP)
- `express`: HTTP server for SSE transport

## Entry Points

Expand Down
23 changes: 14 additions & 9 deletions docs/architecture/debugMCPServer.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,24 +6,25 @@ The MCP server component that exposes VS Code debugging capabilities to AI agent

## Motivation

AI coding agents need a standardized way to control debuggers programmatically. MCP provides this standard, and `DebugMCPServer` implements it using FastMCP with Server-Sent Events (SSE) transport for real-time bidirectional communication.
AI coding agents need a standardized way to control debuggers programmatically. MCP provides this standard, and `DebugMCPServer` implements it using the official `@modelcontextprotocol/sdk` with Server-Sent Events (SSE) transport over an express HTTP server for real-time bidirectional communication.

## Responsibility

- Initialize and manage the FastMCP server lifecycle
- Initialize and manage the MCP server lifecycle (using `McpServer` from `@modelcontextprotocol/sdk`)
- Register debugging tools that AI agents can invoke
- Register documentation resources for agent guidance
- Delegate all debugging operations to `DebuggingHandler`
- Handle SSE transport on configurable port (default: 3001)
- Manage SSE transport connections via `SSEServerTransport` on configurable port (default: 3001)

## Architecture Position

```
AI Agent (MCP Client)
▼ SSE Connection
▼ SSE Connection (GET /sse + POST /messages)
┌───────────────────┐
│ DebugMCPServer │ ◄── You are here
│ (express + SSE) │
└───────────────────┘
▼ Delegates to
Expand All @@ -41,14 +42,18 @@ AI Agent (MCP Client)

### SSE Transport

Uses HTTP with Server-Sent Events for persistent connections. This allows the server to push updates to clients and maintain connection health via ping/keepalive.
Uses HTTP with Server-Sent Events for persistent connections. The express server exposes two endpoints:
- `GET /sse` — Establishes the SSE stream and creates a session
- `POST /messages?sessionId=...` — Receives JSON-RPC messages from the client

Each client connection creates an `SSEServerTransport` instance that is connected to the `McpServer`. The server tracks active transports by session ID and cleans them up on disconnect.

## Key Code Locations

- Class definition: `src/debugMCPServer.ts`
- Tool registration: `setupTools()` method
- Resource registration: `setupResources()` method
- Server startup: `start()` method
- Tool registration: `setupTools()` method (uses `McpServer.registerTool()`)
- Resource registration: `setupResources()` method (uses `McpServer.registerResource()`)
- Server startup: `start()` method (creates express app with SSE/message routes)

## Exposed Tools

Expand All @@ -75,4 +80,4 @@ Uses HTTP with Server-Sent Events for persistent connections. This allows the se
## Configuration

- `debugmcp.serverPort`: Port number (default: 3001)
- `debugmcp.timeoutInSeconds`: Operation timeout (default: 180)
- `debugmcp.timeoutInSeconds`: Operation timeout (default: 180)
Loading