get_session_state

Retrieve the current debugging session state including position and status to monitor PHP application execution during Xdebug debugging.

Instructions

Get detailed state of a specific debug session including current position and status

Input Schema

TableJSON Schema

Name	Required	Description	Default
`session_id`	No	Session ID (uses active session if not specified)

Implementation Reference

src/tools/session.ts:77-127 (handler)

The handler function for the 'get_session_state' tool. It resolves the specified or active session using SessionManager.resolveSession, retrieves its state and init packet, and returns a formatted JSON response with details like status, current position, and connection status.

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

  if (!session) {
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            error: 'No session found',
            message: session_id
              ? `Session "${session_id}" not found`
              : 'No active debug session. Start a PHP script with Xdebug enabled.',
          }),
        },
      ],
    };
  }

  const state = session.getState();
  const initPacket = session.initPacket;

  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify(
          {
            id: session.id,
            status: state.status,
            currentFile: state.filename,
            currentLine: state.lineno,
            startTime: state.startTime.toISOString(),
            init: initPacket
              ? {
                  fileUri: initPacket.fileUri,
                  ideKey: initPacket.ideKey,
                  language: initPacket.language,
                  protocolVersion: initPacket.protocolVersion,
                  engine: initPacket.engine,
                }
              : null,
            isConnected: session.isConnected,
          },
          null,
          2
        ),
      },
    ],
  };
}

src/tools/session.ts:72-76 (schema)
Zod input schema defining an optional 'session_id' string parameter for specifying which session's state to retrieve.
```
  session_id: z
    .string()
    .optional()
    .describe('Session ID (uses active session if not specified)'),
},
```

src/tools/session.ts:68-128 (registration)

The server.tool call that registers the 'get_session_state' tool, providing its name, description, input schema, and handler function.

server.tool(
  'get_session_state',
  'Get detailed state of a specific debug session including current position and status',
  {
    session_id: z
      .string()
      .optional()
      .describe('Session ID (uses active session if not specified)'),
  },
  async ({ session_id }) => {
    const session = sessionManager.resolveSession(session_id);

    if (!session) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              error: 'No session found',
              message: session_id
                ? `Session "${session_id}" not found`
                : 'No active debug session. Start a PHP script with Xdebug enabled.',
            }),
          },
        ],
      };
    }

    const state = session.getState();
    const initPacket = session.initPacket;

    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(
            {
              id: session.id,
              status: state.status,
              currentFile: state.filename,
              currentLine: state.lineno,
              startTime: state.startTime.toISOString(),
              init: initPacket
                ? {
                    fileUri: initPacket.fileUri,
                    ideKey: initPacket.ideKey,
                    language: initPacket.language,
                    protocolVersion: initPacket.protocolVersion,
                    engine: initPacket.engine,
                  }
                : null,
              isConnected: session.isConnected,
            },
            null,
            2
          ),
        },
      ],
    };
  }
);

src/session/manager.ts:118-123 (helper)
Key helper method in SessionManager used by the tool handler to resolve a DebugSession by ID or fall back to the active session.
```
resolveSession(sessionId?: string): DebugSession | undefined {
  if (sessionId) {
    return this.getSession(sessionId);
  }
  return this.getActiveSession();
}
```
src/tools/index.ts:55-55 (registration)
Invocation of registerSessionTools within registerAllTools, which ultimately registers the get_session_state tool among others.
```
registerSessionTools(server, ctx.sessionManager);
```

Xdebug MCP Server