Xdebug MCP Server

Instructions

Implementation Reference

• src/tools/inspection.ts:178-226 (handler)

  The main handler function for the 'get_variables' MCP tool. It resolves the debug session, fetches variables from the specified context and stack depth using session.getVariables, formats each property using formatProperty, and returns a JSON-formatted text content block with error handling.

    async ({ context_id, 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 variables = await session.getVariables(context_id, stack_depth);
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(
                {
                  variables: variables.map((v) => formatProperty(v)),
                  count: variables.length,
                  context_id,
                  stack_depth,
                },
                null,
                2
              ),
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                error: 'Failed to get variables',
                message: error instanceof Error ? error.message : String(error),
              }),
            },
          ],
        };
      }
    }
  );

• src/tools/inspection.ts:165-177 (schema)

  Input schema for the 'get_variables' tool using Zod validation, defining parameters context_id, stack_depth, and optional session_id.

  {
    context_id: z
      .number()
      .int()
      .default(0)
      .describe('Context ID: 0=Local variables, 1=Superglobals, 2=User constants'),
    stack_depth: z
      .number()
      .int()
      .default(0)
      .describe('Stack frame depth (0 = current frame)'),
    session_id: z.string().optional().describe('Session ID'),
  },

• src/tools/inspection.ts:163-226 (registration)

  Registration of the 'get_variables' tool on the McpServer using server.tool(), including name, description, input schema, and handler function.

    'get_variables',
    'Get all variables at the current execution point. Use context_id to switch between local variables, superglobals, etc.',
    {
      context_id: z
        .number()
        .int()
        .default(0)
        .describe('Context ID: 0=Local variables, 1=Superglobals, 2=User constants'),
      stack_depth: z
        .number()
        .int()
        .default(0)
        .describe('Stack frame depth (0 = current frame)'),
      session_id: z.string().optional().describe('Session ID'),
    },
    async ({ context_id, 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 variables = await session.getVariables(context_id, stack_depth);
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(
                {
                  variables: variables.map((v) => formatProperty(v)),
                  count: variables.length,
                  context_id,
                  stack_depth,
                },
                null,
                2
              ),
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                error: 'Failed to get variables',
                message: error instanceof Error ? error.message : String(error),
              }),
            },
          ],
        };
      }
    }
  );

• src/tools/inspection.ts:12-31 (helper)

  Helper function to format DBGP Property objects into a serializable record, recursively handling nested properties up to depth 3.

  function formatProperty(prop: Property, depth: number = 0): Record<string, unknown> {
    const result: Record<string, unknown> = {
      name: prop.name,
      type: prop.type,
    };
  
    if (prop.classname) result.classname = prop.classname;
    if (prop.value !== undefined) result.value = prop.value;
    if (prop.numchildren !== undefined && prop.numchildren > 0) {
      result.numchildren = prop.numchildren;
    }
    if (prop.constant) result.constant = true;
  
    // Include nested properties if present and not too deep
    if (prop.properties && prop.properties.length > 0 && depth < 3) {
      result.children = prop.properties.map((p) => formatProperty(p, depth + 1));
    }
  
    return result;
  }

• src/session/session.ts:363-372 (helper)

  Core helper method in DebugSession that sends the DBGP 'context_get' command to retrieve variables from the specified context and stack frame, then parses the response into Property array.

  async getVariables(
    contextId: number = 0,
    stackDepth: number = 0
  ): Promise<Property[]> {
    const response = await this.connection.sendCommand('context_get', {
      c: contextId.toString(),
      d: stackDepth.toString(),
    });
    return this.connection.parseProperties(response);
  }