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;
    }
  }