Xdebug MCP Server

Instructions

Implementation Reference

• src/tools/breakpoints.ts:378-445 (handler)

  The main handler function for the 'update_breakpoint' MCP tool. It handles updates for both pending breakpoints (enable/disable only) and active session breakpoints by calling session.updateBreakpoint.

  async ({ breakpoint_id, state, hit_value, hit_condition, session_id }) => {
    // Check if it's a pending breakpoint
    if (breakpoint_id.startsWith('pending_')) {
      const enabled = state === undefined ? undefined : state === 'enabled';
      if (enabled !== undefined) {
        const success = pendingBreakpoints.setBreakpointEnabled(breakpoint_id, enabled);
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                success,
                breakpoint_id,
                updates: { state },
                message: success
                  ? 'Pending breakpoint updated'
                  : 'Failed to update pending breakpoint (may not exist)',
              }),
            },
          ],
        };
      }
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              success: false,
              breakpoint_id,
              message: 'Only enable/disable is supported for pending breakpoints',
            }),
          },
        ],
      };
    }
  
    const session = sessionManager.resolveSession(session_id);
  
    if (!session) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({ error: 'No active debug session' }),
          },
        ],
      };
    }
  
    const success = await session.updateBreakpoint(breakpoint_id, {
      state: state as 'enabled' | 'disabled' | undefined,
      hitValue: hit_value,
      hitCondition: hit_condition as HitCondition | undefined,
    });
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            success,
            breakpoint_id,
            updates: { state, hit_value, hit_condition },
          }),
        },
      ],
    };
  }

• src/tools/breakpoints.ts:365-377 (schema)

  Input schema definition (Zod) for the 'update_breakpoint' tool parameters.

  {
    breakpoint_id: z.string().describe('The breakpoint ID to update'),
    state: z
      .enum(['enabled', 'disabled'])
      .optional()
      .describe('Enable or disable the breakpoint'),
    hit_value: z.number().int().optional().describe('New hit count value'),
    hit_condition: z
      .enum(['>=', '==', '%'])
      .optional()
      .describe('New hit condition'),
    session_id: z.string().optional().describe('Session ID'),
  },

• src/tools/breakpoints.ts:362-446 (registration)

  Registration of the 'update_breakpoint' tool using server.tool() in registerBreakpointTools function.

  server.tool(
    'update_breakpoint',
    'Update a breakpoint (enable/disable or change hit conditions). Works for both active session and pending breakpoints.',
    {
      breakpoint_id: z.string().describe('The breakpoint ID to update'),
      state: z
        .enum(['enabled', 'disabled'])
        .optional()
        .describe('Enable or disable the breakpoint'),
      hit_value: z.number().int().optional().describe('New hit count value'),
      hit_condition: z
        .enum(['>=', '==', '%'])
        .optional()
        .describe('New hit condition'),
      session_id: z.string().optional().describe('Session ID'),
    },
    async ({ breakpoint_id, state, hit_value, hit_condition, session_id }) => {
      // Check if it's a pending breakpoint
      if (breakpoint_id.startsWith('pending_')) {
        const enabled = state === undefined ? undefined : state === 'enabled';
        if (enabled !== undefined) {
          const success = pendingBreakpoints.setBreakpointEnabled(breakpoint_id, enabled);
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify({
                  success,
                  breakpoint_id,
                  updates: { state },
                  message: success
                    ? 'Pending breakpoint updated'
                    : 'Failed to update pending breakpoint (may not exist)',
                }),
              },
            ],
          };
        }
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                success: false,
                breakpoint_id,
                message: 'Only enable/disable is supported for pending breakpoints',
              }),
            },
          ],
        };
      }
  
      const session = sessionManager.resolveSession(session_id);
  
      if (!session) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({ error: 'No active debug session' }),
            },
          ],
        };
      }
  
      const success = await session.updateBreakpoint(breakpoint_id, {
        state: state as 'enabled' | 'disabled' | undefined,
        hitValue: hit_value,
        hitCondition: hit_condition as HitCondition | undefined,
      });
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              success,
              breakpoint_id,
              updates: { state, hit_value, hit_condition },
            }),
          },
        ],
      };
    }
  );

• src/session/session.ts:243-259 (helper)

  Session class method that performs the actual DBGP 'breakpoint_update' command to update an active breakpoint.

  async updateBreakpoint(
    breakpointId: string,
    options: {
      state?: 'enabled' | 'disabled';
      hitValue?: number;
      hitCondition?: HitCondition;
    }
  ): Promise<boolean> {
    const args: Record<string, string> = { d: breakpointId };
  
    if (options.state) args['s'] = options.state;
    if (options.hitValue !== undefined) args['h'] = options.hitValue.toString();
    if (options.hitCondition) args['o'] = options.hitCondition;
  
    const response = await this.connection.sendCommand('breakpoint_update', args);
    return !response.error;
  }