Xdebug MCP Server

Instructions

Implementation Reference

• src/tools/inspection.ts:324-372 (handler)

  MCP tool handler for 'set_variable'. Resolves the debug session and calls session.setVariable to perform the actual variable setting, returning success status and message.

  async ({ name, value, 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 success = await session.setVariable(name, value, {
        contextId: context_id,
        stackDepth: stack_depth,
      });
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              success,
              name,
              value,
              message: success
                ? `Variable ${name} set to ${value}`
                : 'Failed to set variable',
            }),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              error: 'Failed to set variable',
              message: error instanceof Error ? error.message : String(error),
            }),
          },
        ],
      };
    }
  }

• src/tools/inspection.ts:317-322 (schema)

  Zod input schema defining parameters: name (string), value (string), context_id (number, default 0), stack_depth (number, default 0), session_id (optional string).

  {
    name: z.string().describe('Variable name (e.g., $x, $user->name)'),
    value: z.string().describe('New value as a PHP literal (e.g., 42, "hello", true, null)'),
    context_id: z.number().int().default(0).describe('Context ID'),
    stack_depth: z.number().int().default(0).describe('Stack frame depth'),
    session_id: z.string().optional().describe('Session ID'),

• src/tools/inspection.ts:314-373 (registration)

  Registration of the 'set_variable' MCP tool using server.tool(), including name, description, input schema, and handler function within registerInspectionTools.

  server.tool(
    'set_variable',
    'Set the value of a variable in the current scope',
    {
      name: z.string().describe('Variable name (e.g., $x, $user->name)'),
      value: z.string().describe('New value as a PHP literal (e.g., 42, "hello", true, null)'),
      context_id: z.number().int().default(0).describe('Context ID'),
      stack_depth: z.number().int().default(0).describe('Stack frame depth'),
      session_id: z.string().optional().describe('Session ID'),
    },
    async ({ name, value, 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 success = await session.setVariable(name, value, {
          contextId: context_id,
          stackDepth: stack_depth,
        });
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                success,
                name,
                value,
                message: success
                  ? `Variable ${name} set to ${value}`
                  : 'Failed to set variable',
              }),
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                error: 'Failed to set variable',
                message: error instanceof Error ? error.message : String(error),
              }),
            },
          ],
        };
      }
    }
  );

• src/session/session.ts:409-434 (helper)

  DebugSession.setVariable method: sends DBGP 'property_set' command with variable name, value, and optional context/stack/type parameters to set the variable in the debugged PHP process.

  async setVariable(
    name: string,
    value: string,
    options?: {
      contextId?: number;
      stackDepth?: number;
      type?: string;
    }
  ): Promise<boolean> {
    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?.type) {
      args['t'] = options.type;
    }
  
    const response = await this.connection.sendCommand('property_set', args, value);
    return response.success === true || !response.error;
  }