set_call_breakpoint

Set a breakpoint that triggers when a specific function is called, enabling debugging of PHP applications by pausing execution at function entry points.

Instructions

Set a breakpoint that triggers when a specific function is called. Can be set before a debug session starts.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`function_name`	Yes	Function name to break on (e.g., 'myFunction' or 'MyClass::myMethod')
`session_id`	No	Session ID

Implementation Reference

src/tools/breakpoints.ts:231-298 (handler)

Executes the set_call_breakpoint tool: resolves session or adds as pending, calls session.setCallBreakpoint or pendingBreakpoints.addCallBreakpoint, returns JSON response with breakpoint info

async ({ function_name, session_id }) => {
  const session = sessionManager.resolveSession(session_id);

  // If no active session, store as pending breakpoint
  if (!session) {
    const pendingBp = pendingBreakpoints.addCallBreakpoint(function_name);

    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(
            {
              success: true,
              pending: true,
              message: 'Call breakpoint stored as pending - will be applied when a debug session connects',
              breakpoint: {
                id: pendingBp.id,
                type: 'call',
                function: function_name,
                enabled: pendingBp.enabled,
              },
            },
            null,
            2
          ),
        },
      ],
    };
  }

  try {
    const breakpoint = await session.setCallBreakpoint(function_name);

    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(
            {
              success: true,
              breakpoint: {
                id: breakpoint.id,
                type: 'call',
                function: function_name,
                state: breakpoint.state,
              },
            },
            null,
            2
          ),
        },
      ],
    };
  } catch (error) {
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            error: 'Failed to set call breakpoint',
            message: error instanceof Error ? error.message : String(error),
          }),
        },
      ],
    };
  }
}

src/tools/breakpoints.ts:223-230 (schema)

Input schema using Zod: function_name (required string), session_id (optional string)

{
  function_name: z
    .string()
    .describe(
      "Function name to break on (e.g., 'myFunction' or 'MyClass::myMethod')"
    ),
  session_id: z.string().optional().describe('Session ID'),
},

src/tools/breakpoints.ts:220-299 (registration)

Registers the MCP tool 'set_call_breakpoint' with server.tool(), including description, input schema, and handler

server.tool(
  'set_call_breakpoint',
  'Set a breakpoint that triggers when a specific function is called. Can be set before a debug session starts.',
  {
    function_name: z
      .string()
      .describe(
        "Function name to break on (e.g., 'myFunction' or 'MyClass::myMethod')"
      ),
    session_id: z.string().optional().describe('Session ID'),
  },
  async ({ function_name, session_id }) => {
    const session = sessionManager.resolveSession(session_id);

    // If no active session, store as pending breakpoint
    if (!session) {
      const pendingBp = pendingBreakpoints.addCallBreakpoint(function_name);

      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(
              {
                success: true,
                pending: true,
                message: 'Call breakpoint stored as pending - will be applied when a debug session connects',
                breakpoint: {
                  id: pendingBp.id,
                  type: 'call',
                  function: function_name,
                  enabled: pendingBp.enabled,
                },
              },
              null,
              2
            ),
          },
        ],
      };
    }

    try {
      const breakpoint = await session.setCallBreakpoint(function_name);

      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(
              {
                success: true,
                breakpoint: {
                  id: breakpoint.id,
                  type: 'call',
                  function: function_name,
                  state: breakpoint.state,
                },
              },
              null,
              2
            ),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              error: 'Failed to set call breakpoint',
              message: error instanceof Error ? error.message : String(error),
            }),
          },
        ],
      };
    }
  }
);

src/session/session.ts:207-228 (helper)

DebugSession.setCallBreakpoint: sends DBGP 'breakpoint_set -t call -m <function>' command, parses response, stores breakpoint

async setCallBreakpoint(functionName: string): Promise<Breakpoint> {
  const response = await this.connection.sendCommand('breakpoint_set', {
    t: 'call',
    m: functionName,
  });

  if (response.error) {
    throw new Error(`Failed to set call breakpoint: ${response.error.message}`);
  }

  const result = this.connection.parseBreakpointSet(response);

  const breakpoint: Breakpoint = {
    id: result.id,
    type: 'call',
    state: 'enabled',
    function: functionName,
  };

  this.breakpoints.set(breakpoint.id, breakpoint);
  return breakpoint;
}

src/session/pending-breakpoints.ts:87-100 (helper)

PendingBreakpointsManager.addCallBreakpoint: stores call breakpoint as pending before session starts, emits event

addCallBreakpoint(functionName: string): PendingBreakpoint {
  const id = `pending_${++this.breakpointIdCounter}`;
  const bp: PendingBreakpoint = {
    id,
    type: 'call',
    functionName,
    enabled: true,
    createdAt: new Date(),
  };
  this.pendingBreakpoints.set(id, bp);
  logger.info(`Pending call breakpoint added: ${id} for ${functionName}`);
  this.emit('breakpointAdded', bp);
  return bp;
}

Xdebug MCP Server