Xdebug MCP Server

Instructions

Implementation Reference

• src/tools/breakpoints.ts:231-298 (handler)

  Executes the set_call_breakpoint tool: resolves session or adds as pending, calls session.setCallBreakpoint or pendingBreakpoints.addCallBreakpoint, returns JSON response with breakpoint info
  async ({ function_name, session_id }) => { const session = sessionManager.resolveSession(session_id); // If no active session, store as pending breakpoint if (!session) { const pendingBp = pendingBreakpoints.addCallBreakpoint(function_name); return { content: [ { type: 'text', text: JSON.stringify( { success: true, pending: true, message: 'Call breakpoint stored as pending - will be applied when a debug session connects', breakpoint: { id: pendingBp.id, type: 'call', function: function_name, enabled: pendingBp.enabled, }, }, null, 2 ), }, ], }; } try { const breakpoint = await session.setCallBreakpoint(function_name); return { content: [ { type: 'text', text: JSON.stringify( { success: true, breakpoint: { id: breakpoint.id, type: 'call', function: function_name, state: breakpoint.state, }, }, null, 2 ), }, ], }; } catch (error) { return { content: [ { type: 'text', text: JSON.stringify({ error: 'Failed to set call breakpoint', message: error instanceof Error ? error.message : String(error), }), }, ], }; } }
• src/tools/breakpoints.ts:223-230 (schema)

  Input schema using Zod: function_name (required string), session_id (optional string)
  { function_name: z .string() .describe( "Function name to break on (e.g., 'myFunction' or 'MyClass::myMethod')" ), session_id: z.string().optional().describe('Session ID'), },
• src/tools/breakpoints.ts:220-299 (registration)

  Registers the MCP tool 'set_call_breakpoint' with server.tool(), including description, input schema, and handler
  server.tool( 'set_call_breakpoint', 'Set a breakpoint that triggers when a specific function is called. Can be set before a debug session starts.', { function_name: z .string() .describe( "Function name to break on (e.g., 'myFunction' or 'MyClass::myMethod')" ), session_id: z.string().optional().describe('Session ID'), }, async ({ function_name, session_id }) => { const session = sessionManager.resolveSession(session_id); // If no active session, store as pending breakpoint if (!session) { const pendingBp = pendingBreakpoints.addCallBreakpoint(function_name); return { content: [ { type: 'text', text: JSON.stringify( { success: true, pending: true, message: 'Call breakpoint stored as pending - will be applied when a debug session connects', breakpoint: { id: pendingBp.id, type: 'call', function: function_name, enabled: pendingBp.enabled, }, }, null, 2 ), }, ], }; } try { const breakpoint = await session.setCallBreakpoint(function_name); return { content: [ { type: 'text', text: JSON.stringify( { success: true, breakpoint: { id: breakpoint.id, type: 'call', function: function_name, state: breakpoint.state, }, }, null, 2 ), }, ], }; } catch (error) { return { content: [ { type: 'text', text: JSON.stringify({ error: 'Failed to set call breakpoint', message: error instanceof Error ? error.message : String(error), }), }, ], }; } } );
• src/session/session.ts:207-228 (helper)

  DebugSession.setCallBreakpoint: sends DBGP 'breakpoint_set -t call -m <function>' command, parses response, stores breakpoint
  async setCallBreakpoint(functionName: string): Promise<Breakpoint> { const response = await this.connection.sendCommand('breakpoint_set', { t: 'call', m: functionName, }); if (response.error) { throw new Error(`Failed to set call breakpoint: ${response.error.message}`); } const result = this.connection.parseBreakpointSet(response); const breakpoint: Breakpoint = { id: result.id, type: 'call', state: 'enabled', function: functionName, }; this.breakpoints.set(breakpoint.id, breakpoint); return breakpoint; }
• src/session/pending-breakpoints.ts:87-100 (helper)

  PendingBreakpointsManager.addCallBreakpoint: stores call breakpoint as pending before session starts, emits event
  addCallBreakpoint(functionName: string): PendingBreakpoint { const id = `pending_${++this.breakpointIdCounter}`; const bp: PendingBreakpoint = { id, type: 'call', functionName, enabled: true, createdAt: new Date(), }; this.pendingBreakpoints.set(id, bp); logger.info(`Pending call breakpoint added: ${id} for ${functionName}`); this.emit('breakpointAdded', bp); return bp; }