Xdebug MCP Server

Instructions

Implementation Reference

• src/tools/advanced.ts:696-728 (handler)

  Primary MCP tool handler for 'capture_snapshot': resolves the debug session (optionally by ID), evaluates all watch expressions, invokes the SessionExporter to capture the current debug state snapshot, and returns success status with snapshot count and current state.
  'capture_snapshot', 'Capture a snapshot of the current debug state for the export report', { session_id: z.string().optional().describe('Session ID'), }, async ({ session_id }) => { const session = ctx.sessionManager.resolveSession(session_id); if (!session) { return { content: [{ type: 'text', text: JSON.stringify({ error: 'No active session' }) }], }; } const watchResults = await ctx.watchManager.evaluateAll(session); const snapshot = await ctx.sessionExporter.captureSnapshot(session, { watchValues: watchResults, }); return { content: [ { type: 'text', text: JSON.stringify({ success: true, snapshotCount: ctx.sessionExporter.snapshotCount, currentState: snapshot.state, }), }, ], }; } ); }
• src/session/session-export.ts:51-104 (helper)

  Core helper method in SessionExporter class that implements the snapshot capture logic: retrieves session state, stack trace, variables, breakpoints; incorporates optional watch values/request context/log entries; stores and returns the DebugSnapshot.
  async captureSnapshot( session: DebugSession, additionalData?: { watchValues?: Array<{ expression: string; value: Property | null; error?: string }>; requestContext?: RequestContext; logEntries?: LogEntry[]; } ): Promise<DebugSnapshot> { const state = session.getState(); let stackTrace: StackFrame[] = []; let variables: Record<string, Property> = {}; let breakpoints: Breakpoint[] = []; try { stackTrace = await session.getStackTrace(); } catch { // May fail if session is not in break state } try { const vars = await session.getVariables(0, 0); for (const v of vars) { variables[v.name] = v; } } catch { // May fail } try { breakpoints = await session.listBreakpoints(); } catch { // May fail } if (state.filename) { this.filesVisited.add(state.filename); } this.totalSteps++; const snapshot: DebugSnapshot = { timestamp: new Date(), sessionId: session.id, state, stackTrace, variables, watchValues: additionalData?.watchValues || [], breakpoints, requestContext: additionalData?.requestContext, logEntries: additionalData?.logEntries, }; this.snapshots.push(snapshot); return snapshot; }
• src/tools/advanced.ts:698-700 (schema)

  Input schema validation using Zod for the capture_snapshot tool: optional session_id string.
  { session_id: z.string().optional().describe('Session ID'), },
• src/session/session-export.ts:12-22 (schema)

  TypeScript interface defining the structure of a DebugSnapshot, used by the captureSnapshot implementation.
  export interface DebugSnapshot { timestamp: Date; sessionId: string; state: SessionState; stackTrace: StackFrame[]; variables: Record<string, Property>; watchValues: Array<{ expression: string; value: Property | null; error?: string }>; breakpoints: Breakpoint[]; requestContext?: RequestContext; logEntries?: LogEntry[]; }
• src/tools/advanced.ts:696-728 (registration)

  Registration of the capture_snapshot tool on the MCP server in advanced tools module.
  'capture_snapshot', 'Capture a snapshot of the current debug state for the export report', { session_id: z.string().optional().describe('Session ID'), }, async ({ session_id }) => { const session = ctx.sessionManager.resolveSession(session_id); if (!session) { return { content: [{ type: 'text', text: JSON.stringify({ error: 'No active session' }) }], }; } const watchResults = await ctx.watchManager.evaluateAll(session); const snapshot = await ctx.sessionExporter.captureSnapshot(session, { watchValues: watchResults, }); return { content: [ { type: 'text', text: JSON.stringify({ success: true, snapshotCount: ctx.sessionExporter.snapshotCount, currentState: snapshot.state, }), }, ], }; } ); }