Xdebug MCP Server

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/tools/breakpoints.ts:448-559 (registration)

  Registration of the 'list_breakpoints' tool using server.tool(), including inline Zod input schema for optional session_id and include_pending, and the full handler logic that fetches and formats active session breakpoints and pending breakpoints for JSON output.
  // List all breakpoints server.tool( 'list_breakpoints', 'List all breakpoints including both active session breakpoints and pending breakpoints', { session_id: z.string().optional().describe('Session ID'), include_pending: z.boolean().default(true).describe('Include pending breakpoints in the list'), }, async ({ session_id, include_pending }) => { const session = sessionManager.resolveSession(session_id); const pending = pendingBreakpoints.getAllPendingBreakpoints(); // If no session, just return pending breakpoints if (!session) { if (pending.length === 0) { return { content: [ { type: 'text', text: JSON.stringify({ message: 'No active debug session and no pending breakpoints', breakpoints: [], pendingBreakpoints: [], totalCount: 0, }), }, ], }; } return { content: [ { type: 'text', text: JSON.stringify( { message: 'No active debug session - showing pending breakpoints only', breakpoints: [], pendingBreakpoints: pending.map((bp) => ({ id: bp.id, type: bp.type, file: bp.file, line: bp.line, condition: bp.condition, hitValue: bp.hitValue, hitCondition: bp.hitCondition, exception: bp.exception, functionName: bp.functionName, enabled: bp.enabled, createdAt: bp.createdAt, })), totalCount: pending.length, }, null, 2 ), }, ], }; } const breakpoints = await session.listBreakpoints(); const result: { breakpoints: object[]; pendingBreakpoints?: object[]; totalCount: number; } = { breakpoints: breakpoints.map((bp) => ({ id: bp.id, type: bp.type, state: bp.state, resolved: bp.resolved, file: bp.filename, line: bp.lineno, function: bp.function, exception: bp.exception, expression: bp.expression, hitCount: bp.hitCount, hitValue: bp.hitValue, hitCondition: bp.hitCondition, })), totalCount: breakpoints.length, }; if (include_pending && pending.length > 0) { result.pendingBreakpoints = pending.map((bp) => ({ id: bp.id, type: bp.type, file: bp.file, line: bp.line, condition: bp.condition, hitValue: bp.hitValue, hitCondition: bp.hitCondition, exception: bp.exception, functionName: bp.functionName, enabled: bp.enabled, createdAt: bp.createdAt, })); result.totalCount += pending.length; } return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; } );
• src/tools/breakpoints.ts:456-558 (handler)

  The anonymous async handler function that implements the core logic of list_breakpoints: resolves session, gets pending BPs, calls session.listBreakpoints(), merges/formats data into JSON response with active and pending breakpoints.
  async ({ session_id, include_pending }) => { const session = sessionManager.resolveSession(session_id); const pending = pendingBreakpoints.getAllPendingBreakpoints(); // If no session, just return pending breakpoints if (!session) { if (pending.length === 0) { return { content: [ { type: 'text', text: JSON.stringify({ message: 'No active debug session and no pending breakpoints', breakpoints: [], pendingBreakpoints: [], totalCount: 0, }), }, ], }; } return { content: [ { type: 'text', text: JSON.stringify( { message: 'No active debug session - showing pending breakpoints only', breakpoints: [], pendingBreakpoints: pending.map((bp) => ({ id: bp.id, type: bp.type, file: bp.file, line: bp.line, condition: bp.condition, hitValue: bp.hitValue, hitCondition: bp.hitCondition, exception: bp.exception, functionName: bp.functionName, enabled: bp.enabled, createdAt: bp.createdAt, })), totalCount: pending.length, }, null, 2 ), }, ], }; } const breakpoints = await session.listBreakpoints(); const result: { breakpoints: object[]; pendingBreakpoints?: object[]; totalCount: number; } = { breakpoints: breakpoints.map((bp) => ({ id: bp.id, type: bp.type, state: bp.state, resolved: bp.resolved, file: bp.filename, line: bp.lineno, function: bp.function, exception: bp.exception, expression: bp.expression, hitCount: bp.hitCount, hitValue: bp.hitValue, hitCondition: bp.hitCondition, })), totalCount: breakpoints.length, }; if (include_pending && pending.length > 0) { result.pendingBreakpoints = pending.map((bp) => ({ id: bp.id, type: bp.type, file: bp.file, line: bp.line, condition: bp.condition, hitValue: bp.hitValue, hitCondition: bp.hitCondition, exception: bp.exception, functionName: bp.functionName, enabled: bp.enabled, createdAt: bp.createdAt, })); result.totalCount += pending.length; } return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; }
• src/session/session.ts:272-283 (helper)

  Helper method on DebugSession class: listBreakpoints() sends 'breakpoint_list' DBGP command, parses response into Breakpoint[] array, updates local cache, and returns the list. Called by the tool handler.
  async listBreakpoints(): Promise<Breakpoint[]> { const response = await this.connection.sendCommand('breakpoint_list'); const breakpoints = this.connection.parseBreakpoints(response); // Update local cache this.breakpoints.clear(); for (const bp of breakpoints) { this.breakpoints.set(bp.id, bp); } return breakpoints; }
• src/tools/index.ts:55-56 (registration)

  Top-level registration call in registerAllTools() that invokes registerBreakpointTools, which contains the list_breakpoints tool registration.
  registerSessionTools(server, ctx.sessionManager); registerBreakpointTools(server, ctx.sessionManager, ctx.pendingBreakpoints);