Xdebug MCP Server

Instructions

Implementation Reference

• src/tools/advanced.ts:505-560 (handler)

  Executes the save_debug_profile tool by collecting current breakpoints, watches, step filters, and logpoints from the session managers and saving them as a DebugProfile using DebugConfigManager.
  async ({ name, description }) => { const session = ctx.sessionManager.getActiveSession(); // Create profile with current settings const profile = ctx.configManager.createProfile(name, description); // Add current breakpoints if (session) { const breakpoints = await session.listBreakpoints(); profile.breakpoints = breakpoints.map((bp) => ({ file: bp.filename || '', line: bp.lineno || 0, condition: bp.expression, enabled: bp.state === 'enabled', })); } // Add watches profile.watchExpressions = ctx.watchManager.getAllWatches().map((w) => w.expression); // Add step filters profile.stepFilters = ctx.stepFilter.getAllRules().map((r) => ({ pattern: r.pattern, type: r.type, enabled: r.enabled, })); // Add logpoints profile.logpoints = ctx.logpointManager.getAllLogpoints().map((lp) => ({ file: lp.file, line: lp.line, message: lp.message, condition: lp.condition, })); await ctx.configManager.saveAllProfiles(); return { content: [ { type: 'text', text: JSON.stringify({ success: true, profile: { name: profile.name, breakpoints: profile.breakpoints.length, watches: profile.watchExpressions.length, filters: profile.stepFilters.length, logpoints: profile.logpoints.length, }, }), }, ], }; } );
• src/tools/advanced.ts:498-560 (registration)

  Registers the 'save_debug_profile' tool with the MCP server, including description, input schema, and handler function.
  server.tool( 'save_debug_profile', 'Save the current debug configuration (breakpoints, watches, filters) as a named profile', { name: z.string().describe('Profile name'), description: z.string().optional().describe('Profile description'), }, async ({ name, description }) => { const session = ctx.sessionManager.getActiveSession(); // Create profile with current settings const profile = ctx.configManager.createProfile(name, description); // Add current breakpoints if (session) { const breakpoints = await session.listBreakpoints(); profile.breakpoints = breakpoints.map((bp) => ({ file: bp.filename || '', line: bp.lineno || 0, condition: bp.expression, enabled: bp.state === 'enabled', })); } // Add watches profile.watchExpressions = ctx.watchManager.getAllWatches().map((w) => w.expression); // Add step filters profile.stepFilters = ctx.stepFilter.getAllRules().map((r) => ({ pattern: r.pattern, type: r.type, enabled: r.enabled, })); // Add logpoints profile.logpoints = ctx.logpointManager.getAllLogpoints().map((lp) => ({ file: lp.file, line: lp.line, message: lp.message, condition: lp.condition, })); await ctx.configManager.saveAllProfiles(); return { content: [ { type: 'text', text: JSON.stringify({ success: true, profile: { name: profile.name, breakpoints: profile.breakpoints.length, watches: profile.watchExpressions.length, filters: profile.stepFilters.length, logpoints: profile.logpoints.length, }, }), }, ], }; } );
• src/tools/advanced.ts:501-504 (schema)

  Zod input schema for the tool parameters: profile name (required) and optional description.
  { name: z.string().describe('Profile name'), description: z.string().optional().describe('Profile description'), },
• src/session/debug-config.ts:19-42 (schema)

  TypeScript interface defining the structure of a debug profile, used to store breakpoints, watches, logpoints, step filters, etc.
  export interface DebugProfile { name: string; description?: string; createdAt: Date; updatedAt: Date; breakpoints: BreakpointConfig[]; watchExpressions: string[]; logpoints: Array<{ file: string; line: number; message: string; condition?: string; }>; stepFilters: Array<{ pattern: string; type: 'include' | 'exclude'; enabled: boolean; }>; settings: { maxDepth?: number; maxChildren?: number; skipVendor?: boolean; }; }
• src/session/debug-config.ts:139-155 (helper)

  Persists all debug profiles to disk in profiles.json, called by the tool handler to save the new profile.
  async saveAllProfiles(): Promise<void> { try { await fs.mkdir(this.configDir, { recursive: true }); const data = { activeProfile: this.activeProfileName, profiles: Array.from(this.profiles.entries()).map(([, profile]) => profile), }; const filePath = path.join(this.configDir, 'profiles.json'); await fs.writeFile(filePath, JSON.stringify(data, null, 2), 'utf8'); logger.info(`Saved ${this.profiles.size} profiles to ${filePath}`); } catch (error) { logger.error('Failed to save profiles:', error); throw error; } }