Xdebug MCP Server

Instructions

Implementation Reference

• src/tools/inspection.ts:99-159 (registration)

  Registration of the 'get_contexts' MCP tool, including input schema (stack_depth, session_id) and complete handler logic that resolves the debug session and retrieves contexts via session.getContexts()

  server.tool(
    'get_contexts',
    'Get available variable contexts (Local, Superglobals, User-defined constants) at the current position',
    {
      stack_depth: z
        .number()
        .int()
        .default(0)
        .describe('Stack frame depth (0 = current frame)'),
      session_id: z.string().optional().describe('Session ID'),
    },
    async ({ stack_depth, session_id }) => {
      const session = sessionManager.resolveSession(session_id);
  
      if (!session) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({ error: 'No active debug session' }),
            },
          ],
        };
      }
  
      try {
        const contexts = await session.getContexts(stack_depth);
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(
                {
                  contexts: contexts.map((ctx) => ({
                    id: ctx.id,
                    name: ctx.name,
                  })),
                  hint: 'Use context_id in get_variables to get variables from a specific context',
                },
                null,
                2
              ),
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                error: 'Failed to get contexts',
                message: error instanceof Error ? error.message : String(error),
              }),
            },
          ],
        };
      }
    }
  );

• src/session/session.ts:356-361 (handler)

  Core handler implementation in DebugSession class: sends DBGP 'context_names' command with stack depth and parses the response into Context[]

  async getContexts(stackDepth: number = 0): Promise<Context[]> {
    const response = await this.connection.sendCommand('context_names', {
      d: stackDepth.toString(),
    });
    return this.connection.parseContexts(response);
  }

• src/tools/index.ts:58-58 (registration)

  Top-level registration call that invokes registerInspectionTools, thereby registering the get_contexts tool among inspection tools

  registerInspectionTools(server, ctx.sessionManager);

• src/tools/inspection.ts:102-108 (schema)

  Zod input schema for the get_contexts tool parameters

  {
    stack_depth: z
      .number()
      .int()
      .default(0)
      .describe('Stack frame depth (0 = current frame)'),
    session_id: z.string().optional().describe('Session ID'),