Xdebug MCP Server

Instructions

Implementation Reference

• src/tools/breakpoints.ts:47-133 (handler)

  The core handler function that implements the logic for setting a line breakpoint. It either applies it to an active debug session or stores it as pending if no session exists.
  async ({ file, line, condition, hit_value, hit_condition, session_id }) => { const session = sessionManager.resolveSession(session_id); // If no active session, store as pending breakpoint if (!session) { const pendingBp = pendingBreakpoints.addLineBreakpoint(file, line, { condition, hitValue: hit_value, hitCondition: hit_condition as HitCondition, }); return { content: [ { type: 'text', text: JSON.stringify( { success: true, pending: true, message: 'Breakpoint stored as pending - will be applied when a debug session connects', breakpoint: { id: pendingBp.id, type: 'line', file, line, condition: condition || null, hitValue: hit_value || null, hitCondition: hit_condition || null, enabled: pendingBp.enabled, }, }, null, 2 ), }, ], }; } try { const breakpoint = await session.setLineBreakpoint(file, line, { condition, hitValue: hit_value, hitCondition: hit_condition as HitCondition, }); return { content: [ { type: 'text', text: JSON.stringify( { success: true, breakpoint: { id: breakpoint.id, type: breakpoint.type, file, line, condition: condition || null, hitValue: hit_value || null, hitCondition: hit_condition || null, resolved: breakpoint.resolved, state: breakpoint.state, }, }, null, 2 ), }, ], }; } catch (error) { return { content: [ { type: 'text', text: JSON.stringify({ error: 'Failed to set breakpoint', message: error instanceof Error ? error.message : String(error), file, line, }), }, ], }; } }
• src/tools/breakpoints.ts:20-46 (schema)

  Zod schema defining the input parameters for the set_breakpoint tool.
  { file: z .string() .describe( 'Full file path (use container path for Docker, e.g., /var/www/html/index.php)' ), line: z.number().int().positive().describe('Line number for the breakpoint'), condition: z .string() .optional() .describe("Optional PHP condition expression (e.g., '$x > 10' or '$user !== null')"), hit_value: z .number() .int() .optional() .describe('Hit count value - break after this many hits'), hit_condition: z .enum(['>=', '==', '%']) .optional() .describe( 'Hit condition: >= (break when hits >= value), == (break on exact hit), % (break every N hits)' ), session_id: z .string() .optional() .describe('Session ID (uses active session if not specified)'), },
• src/tools/breakpoints.ts:17-134 (registration)

  Direct registration of the 'set_breakpoint' tool using server.tool() within the registerBreakpointTools function.
  server.tool( 'set_breakpoint', 'Set a breakpoint in PHP code. Supports line breakpoints and conditional breakpoints with hit counts. Can be set before a debug session starts - breakpoints will be applied when a session connects.', { file: z .string() .describe( 'Full file path (use container path for Docker, e.g., /var/www/html/index.php)' ), line: z.number().int().positive().describe('Line number for the breakpoint'), condition: z .string() .optional() .describe("Optional PHP condition expression (e.g., '$x > 10' or '$user !== null')"), hit_value: z .number() .int() .optional() .describe('Hit count value - break after this many hits'), hit_condition: z .enum(['>=', '==', '%']) .optional() .describe( 'Hit condition: >= (break when hits >= value), == (break on exact hit), % (break every N hits)' ), session_id: z .string() .optional() .describe('Session ID (uses active session if not specified)'), }, async ({ file, line, condition, hit_value, hit_condition, session_id }) => { const session = sessionManager.resolveSession(session_id); // If no active session, store as pending breakpoint if (!session) { const pendingBp = pendingBreakpoints.addLineBreakpoint(file, line, { condition, hitValue: hit_value, hitCondition: hit_condition as HitCondition, }); return { content: [ { type: 'text', text: JSON.stringify( { success: true, pending: true, message: 'Breakpoint stored as pending - will be applied when a debug session connects', breakpoint: { id: pendingBp.id, type: 'line', file, line, condition: condition || null, hitValue: hit_value || null, hitCondition: hit_condition || null, enabled: pendingBp.enabled, }, }, null, 2 ), }, ], }; } try { const breakpoint = await session.setLineBreakpoint(file, line, { condition, hitValue: hit_value, hitCondition: hit_condition as HitCondition, }); return { content: [ { type: 'text', text: JSON.stringify( { success: true, breakpoint: { id: breakpoint.id, type: breakpoint.type, file, line, condition: condition || null, hitValue: hit_value || null, hitCondition: hit_condition || null, resolved: breakpoint.resolved, state: breakpoint.state, }, }, null, 2 ), }, ], }; } catch (error) { return { content: [ { type: 'text', text: JSON.stringify({ error: 'Failed to set breakpoint', message: error instanceof Error ? error.message : String(error), file, line, }), }, ], }; } } );
• src/tools/index.ts:56-56 (registration)

  Higher-level registration where registerBreakpointTools is invoked as part of registerAllTools, including the set_breakpoint tool.
  registerBreakpointTools(server, ctx.sessionManager, ctx.pendingBreakpoints);
• src/session/pending-breakpoints.ts:39-64 (helper)

  Helper method to add line breakpoints to pending storage when no active session is available.
  addLineBreakpoint( file: string, line: number, options?: { condition?: string; hitValue?: number; hitCondition?: HitCondition; } ): PendingBreakpoint { const id = `pending_${++this.breakpointIdCounter}`; const bp: PendingBreakpoint = { id, type: 'line', file, line, condition: options?.condition, hitValue: options?.hitValue, hitCondition: options?.hitCondition, enabled: true, createdAt: new Date(), }; this.pendingBreakpoints.set(id, bp); logger.info(`Pending breakpoint added: ${id} at ${file}:${line}`); this.emit('breakpointAdded', bp); return bp; }