Xdebug MCP Server

Instructions

Implementation Reference

• src/tools/advanced.ts:42-58 (handler)

  Handler function for the 'add_watch' tool. It calls ctx.watchManager.addWatch(expression) to add the watch and returns a success response with the watch ID and expression.

  async ({ expression }) => {
    const watch = ctx.watchManager.addWatch(expression);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            success: true,
            watch: {
              id: watch.id,
              expression: watch.expression,
            },
          }),
        },
      ],
    };
  }

• src/tools/advanced.ts:37-59 (registration)

  Registration of the 'add_watch' MCP tool on the server, including name, description, input schema, and handler.

    'add_watch',
    'Add a watch expression that will be evaluated on each break. Watch expressions persist across steps.',
    {
      expression: z.string().describe("PHP expression to watch (e.g., '$user->id', 'count($items)')"),
    },
    async ({ expression }) => {
      const watch = ctx.watchManager.addWatch(expression);
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              success: true,
              watch: {
                id: watch.id,
                expression: watch.expression,
              },
            }),
          },
        ],
      };
    }
  );

• src/tools/advanced.ts:40-40 (schema)

  Input schema for the 'add_watch' tool, defining the 'expression' parameter as a string.

  expression: z.string().describe("PHP expression to watch (e.g., '$user->id', 'count($items)')"),

• src/session/watch-manager.ts:40-52 (helper)

  Core implementation of adding a watch expression in WatchManager class. Creates a unique ID, initializes WatchExpression object, stores it in a Map, and logs the addition.

  addWatch(expression: string): WatchExpression {
    const id = `watch_${++this.watchIdCounter}`;
    const watch: WatchExpression = {
      id,
      expression,
      hasChanged: false,
      evaluationCount: 0,
      createdAt: new Date(),
    };
    this.watches.set(id, watch);
    logger.debug(`Watch added: ${id} = ${expression}`);
    return watch;
  }

• src/session/watch-manager.ts:12-21 (schema)

  TypeScript interface defining the structure of a WatchExpression used by the add_watch tool.

    id: string;
    expression: string;
    lastValue?: Property | null;
    previousValue?: Property | null;
    hasChanged: boolean;
    errorMessage?: string;
    evaluationCount: number;
    createdAt: Date;
    lastEvaluatedAt?: Date;
  }