Xdebug MCP Server

Instructions

Implementation Reference

• src/tools/inspection.ts:247-310 (handler)

  MCP tool handler function for 'get_variable'. Resolves debug session, fetches variable using session.getVariable with provided context/stack/max_depth, formats result with formatProperty, handles errors and no-session cases.

  async ({ name, context_id, stack_depth, max_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 variable = await session.getVariable(name, {
        contextId: context_id,
        stackDepth: stack_depth,
        maxDepth: max_depth,
      });
  
      if (!variable) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                error: 'Variable not found',
                name,
                message: `Variable "${name}" does not exist in the current scope`,
              }),
            },
          ],
        };
      }
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(
              {
                variable: formatProperty(variable),
              },
              null,
              2
            ),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              error: 'Failed to get variable',
              message: error instanceof Error ? error.message : String(error),
            }),
          },
        ],
      };
    }
  }

• src/tools/inspection.ts:232-246 (schema)

  Zod input schema for 'get_variable' tool parameters: name (required), context_id/stack_depth/max_depth (optional with defaults), session_id (optional).

  {
    name: z
      .string()
      .describe(
        "Variable name with $ prefix (e.g., '$user', '$data[\"key\"]', '$obj->property')"
      ),
    context_id: z.number().int().default(0).describe('Context ID'),
    stack_depth: z.number().int().default(0).describe('Stack frame depth'),
    max_depth: z
      .number()
      .int()
      .default(2)
      .describe('Maximum depth for nested properties'),
    session_id: z.string().optional().describe('Session ID'),
  },

• src/tools/inspection.ts:228-247 (registration)

  Primary registration of 'get_variable' MCP tool via server.tool() call within registerInspectionTools function.

  // Get a specific variable
  server.tool(
    'get_variable',
    "Get a specific variable by name, including nested properties. Use PHP syntax for nested access (e.g., '$user->name', '$array[0]', '$obj->items[2]->value')",
    {
      name: z
        .string()
        .describe(
          "Variable name with $ prefix (e.g., '$user', '$data[\"key\"]', '$obj->property')"
        ),
      context_id: z.number().int().default(0).describe('Context ID'),
      stack_depth: z.number().int().default(0).describe('Stack frame depth'),
      max_depth: z
        .number()
        .int()
        .default(2)
        .describe('Maximum depth for nested properties'),
      session_id: z.string().optional().describe('Session ID'),
    },
    async ({ name, context_id, stack_depth, max_depth, session_id }) => {

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

  Helper function to format DBGP Property objects into JSON-friendly structure used in get_variable response.

  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:374-407 (helper)

  Core implementation of variable retrieval via DBGP 'property_get' command, called by the tool handler.

  async getVariable(
    name: string,
    options?: {
      contextId?: number;
      stackDepth?: number;
      maxDepth?: number;
      page?: number;
    }
  ): Promise<Property | null> {
    const args: Record<string, string> = {
      n: name,
    };
  
    if (options?.contextId !== undefined) {
      args['c'] = options.contextId.toString();
    }
    if (options?.stackDepth !== undefined) {
      args['d'] = options.stackDepth.toString();
    }
    if (options?.maxDepth !== undefined) {
      args['m'] = options.maxDepth.toString();
    }
    if (options?.page !== undefined) {
      args['p'] = options.page.toString();
    }
  
    const response = await this.connection.sendCommand('property_get', args);
  
    if (response.error) {
      return null;
    }
  
    return this.connection.parseProperty(response);
  }

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

  Top-level call to registerInspectionTools (which includes get_variable) during registerAllTools.

  registerInspectionTools(server, ctx.sessionManager);