sessions_breakpoint

Execute code to a breakpoint and capture local variables for debugging Python applications using the Debug Adapter Protocol.

Instructions

Run to a breakpoint and capture local variables

Input Schema

TableJSON Schema

Name	Required	Description
`sessionId`	Yes	The debug session ID
`file`	Yes	Project-relative file path
`line`	Yes	Line number (1-based)

Implementation Reference

src/mcp_debug_tool/server.py:308-372 (handler)

MCP tool handler for 'sessions_breakpoint'. Extracts sessionId, file, line from arguments, creates BreakpointRequest, calls SessionManager.run_to_breakpoint_async, and returns JSON-serialized response or error.

async def _handle_sessions_breakpoint(self, arguments: dict) -> list[TextContent]:
    """
    Handler for sessions_breakpoint tool.
    
    Runs to a breakpoint and captures local variables.
    """
    try:
        session_id = arguments.get("sessionId")
        if not session_id:
            return [
                TextContent(
                    type="text",
                    text=json.dumps({
                        "error": {
                            "type": "ValueError",
                            "message": "sessionId is required",
                        }
                    }),
                )
            ]

        request = BreakpointRequest(
            file=arguments["file"],
            line=arguments["line"],
        )

        response = await self.session_manager.run_to_breakpoint_async(
            session_id, request
        )

        # Convert response to dict
        result = response.model_dump()

        return [
            TextContent(
                type="text",
                text=json.dumps(result),
            )
        ]
    except KeyError as e:
        return [
            TextContent(
                type="text",
                text=json.dumps({
                    "error": {
                        "type": "SessionNotFound",
                        "message": str(e),
                    }
                }),
            )
        ]
    except Exception as e:
        logger.exception("Error at breakpoint")
        return [
            TextContent(
                type="text",
                text=json.dumps({
                    "error": {
                        "type": type(e).__name__,
                        "message": str(e),
                    }
                }),
            )
        ]

src/mcp_debug_tool/server.py:88-110 (registration)

Registers the 'sessions_breakpoint' tool with the MCP server via list_tools(), including name, description, and inputSchema for validation.

Tool(
    name="sessions_breakpoint",
    description="Run to a breakpoint and capture local variables",
    inputSchema={
        "type": "object",
        "properties": {
            "sessionId": {
                "type": "string",
                "description": "The debug session ID",
            },
            "file": {
                "type": "string",
                "description": "Project-relative file path",
            },
            "line": {
                "type": "integer",
                "description": "Line number (1-based)",
                "minimum": 1,
            },
        },
        "required": ["sessionId", "file", "line"],
    },
),

src/mcp_debug_tool/schemas.py:64-68 (schema)

Pydantic model BreakpointRequest used for type-safe input validation in the handler, matching the tool's inputSchema.

class BreakpointRequest(BaseModel):
    """Request to run to a breakpoint."""
    file: str = Field(..., description="Project-relative path to file")
    line: int = Field(..., ge=1, description="1-based line number")

src/mcp_debug_tool/sessions.py:266-299 (helper)

Core implementation in SessionManager: validates breakpoint, dispatches to DAP or BDB mode to execute run-to-breakpoint and capture locals.

def run_to_breakpoint(
    self, session_id: str, request: BreakpointRequest, timeout: float | None = None
) -> BreakpointResponse:
    """
    Run session to a breakpoint and capture locals.

    Args:
        session_id: Session ID
        request: Breakpoint request with file and line
        timeout: Optional timeout in seconds (defaults to DEFAULT_TIMEOUT_SECONDS)

    Returns:
        Breakpoint response with locals

    Raises:
        KeyError: If session not found
        ValueError: If file/line is invalid
    """
    session = self.get_session(session_id)

    # Validate breakpoint location using session's workspace root
    breakpoint_path = resolve_workspace_path(session.workspace_root, request.file)
    validate_file_and_line(breakpoint_path, request.line)

    # Use default timeout if not specified
    if timeout is None:
        timeout = DEFAULT_TIMEOUT_SECONDS

    # Use DAP if enabled (default)
    if session.use_dap:
        return self._run_to_breakpoint_dap(session, breakpoint_path, request.line, timeout)
    else:
        return self._run_to_breakpoint_bdb(session, breakpoint_path, request.line, timeout)

Debug-MCP