Xdebug MCP Server

Instructions

Implementation Reference

• src/tools/advanced.ts:651-693 (registration)

  Registers the 'export_session' tool with input schema and handler. The handler resolves the session, captures a snapshot with watch values, and exports as JSON or HTML using SessionExporter.

  server.tool(
    'export_session',
    'Export the current debug session as a report',
    {
      format: z.enum(['json', 'html']).default('json').describe('Export format'),
      session_id: z.string().optional().describe('Session ID'),
    },
    async ({ format, session_id }) => {
      const session = ctx.sessionManager.resolveSession(session_id);
      if (!session) {
        return {
          content: [{ type: 'text', text: JSON.stringify({ error: 'No active session' }) }],
        };
      }
  
      // Capture final snapshot
      const watchResults = await ctx.watchManager.evaluateAll(session);
      await ctx.sessionExporter.captureSnapshot(session, {
        watchValues: watchResults,
      });
  
      const exported =
        format === 'html'
          ? ctx.sessionExporter.exportAsHtml(session)
          : ctx.sessionExporter.exportAsJson(session);
  
      return {
        content: [
          {
            type: 'text',
            text:
              format === 'html'
                ? JSON.stringify({
                    format: 'html',
                    content: exported,
                    note: 'Save this content to a .html file to view the report',
                  })
                : exported,
          },
        ],
      };
    }
  );

• src/session/session-export.ts:116-127 (handler)

  Core export methods of SessionExporter: exportAsJson serializes the session data to JSON, exportAsHtml generates an HTML report.

  exportAsJson(session: DebugSession): string {
    const exported = this.buildExportedSession(session);
    return JSON.stringify(exported, null, 2);
  }
  
  /**
   * Export session as HTML report
   */
  exportAsHtml(session: DebugSession): string {
    const exported = this.buildExportedSession(session);
    return this.generateHtmlReport(exported);
  }

• src/session/session-export.ts:51-104 (helper)

  SessionExporter.captureSnapshot method: captures current debug state including stack, variables, breakpoints, watches, etc., and stores snapshots for export.

  async captureSnapshot(
    session: DebugSession,
    additionalData?: {
      watchValues?: Array<{ expression: string; value: Property | null; error?: string }>;
      requestContext?: RequestContext;
      logEntries?: LogEntry[];
    }
  ): Promise<DebugSnapshot> {
    const state = session.getState();
    let stackTrace: StackFrame[] = [];
    let variables: Record<string, Property> = {};
    let breakpoints: Breakpoint[] = [];
  
    try {
      stackTrace = await session.getStackTrace();
    } catch {
      // May fail if session is not in break state
    }
  
    try {
      const vars = await session.getVariables(0, 0);
      for (const v of vars) {
        variables[v.name] = v;
      }
    } catch {
      // May fail
    }
  
    try {
      breakpoints = await session.listBreakpoints();
    } catch {
      // May fail
    }
  
    if (state.filename) {
      this.filesVisited.add(state.filename);
    }
    this.totalSteps++;
  
    const snapshot: DebugSnapshot = {
      timestamp: new Date(),
      sessionId: session.id,
      state,
      stackTrace,
      variables,
      watchValues: additionalData?.watchValues || [],
      breakpoints,
      requestContext: additionalData?.requestContext,
      logEntries: additionalData?.logEntries,
    };
  
    this.snapshots.push(snapshot);
    return snapshot;
  }

• src/session/session-export.ts:12-41 (schema)

  TypeScript interfaces defining the structure of DebugSnapshot and ExportedSession used in the export functionality.

  export interface DebugSnapshot {
    timestamp: Date;
    sessionId: string;
    state: SessionState;
    stackTrace: StackFrame[];
    variables: Record<string, Property>;
    watchValues: Array<{ expression: string; value: Property | null; error?: string }>;
    breakpoints: Breakpoint[];
    requestContext?: RequestContext;
    logEntries?: LogEntry[];
  }
  
  export interface ExportedSession {
    exportedAt: Date;
    sessionInfo: {
      id: string;
      startTime: Date;
      endTime?: Date;
      initialFile: string;
      ideKey: string;
    };
    snapshots: DebugSnapshot[];
    summary: {
      totalSnapshots: number;
      filesVisited: string[];
      breakpointsHit: number;
      totalSteps: number;
    };
  }