Debug-MCP

Instructions

Implementation Reference

• src/mcp_debug_tool/server.py:60-87 (registration)

  Registration of the 'sessions_create' tool in list_tools(), including input schema definition and description.
  Tool( name="sessions_create", description="Create a new debug session for a Python script", inputSchema={ "type": "object", "properties": { "entry": { "type": "string", "description": "Project-relative path to Python script", }, "pythonPath": { "type": "string", "description": "Absolute path to Python interpreter (must have debugpy installed)", }, "args": { "type": "array", "items": {"type": "string"}, "description": "Command-line arguments for the script", }, "env": { "type": "object", "additionalProperties": {"type": "string"}, "description": "Environment variables", }, }, "required": ["entry", "pythonPath"], }, ),
• src/mcp_debug_tool/server.py:252-306 (handler)

  MCP tool handler _handle_sessions_create: validates input with StartSessionRequest, calls SessionManager.create_session_async, returns sessionId or error.
  async def _handle_sessions_create(self, arguments: dict) -> list[TextContent]: """ Handler for sessions_create tool. Creates a new debug session for a Python script. """ try: request = StartSessionRequest(**arguments) response = await self.session_manager.create_session_async(request) return [ TextContent( type="text", text=json.dumps({ "sessionId": response.sessionId, }), ) ] except FileNotFoundError as e: return [ TextContent( type="text", text=json.dumps({ "error": { "type": "FileNotFoundError", "message": str(e), } }), ) ] except ValueError as e: return [ TextContent( type="text", text=json.dumps({ "error": { "type": "ValueError", "message": str(e), } }), ) ] except Exception as e: logger.exception("Error creating session") return [ TextContent( type="text", text=json.dumps({ "error": { "type": type(e).__name__, "message": str(e), } }), ) ]
• src/mcp_debug_tool/schemas.py:22-57 (schema)

  Pydantic model StartSessionRequest for input validation of sessions_create tool, with field validators for args and env.
  class StartSessionRequest(BaseModel): """Request to start a new debug session.""" entry: str = Field(..., description="Project-relative path to script") pythonPath: str = Field(..., description="Absolute path to Python interpreter (must have debugpy installed)") args: list[str] | None = Field(default=None, description="Command-line arguments") env: dict[str, str] | None = Field(default=None, description="Environment variables") useDap: bool | None = Field(default=True, description="Use DAP (debugpy) instead of bdb - recommended for all use cases") @field_validator('args') @classmethod def validate_args(cls, v: list[str] | None) -> list[str] | None: """Validate args list constraints.""" if v is not None: from .utils import MAX_ARG_LENGTH, MAX_ARGS_COUNT if len(v) > MAX_ARGS_COUNT: raise ValueError(f"Too many args (max {MAX_ARGS_COUNT})") for arg in v: if len(arg) > MAX_ARG_LENGTH: raise ValueError(f"Arg too long (max {MAX_ARG_LENGTH} chars)") return v @field_validator('env') @classmethod def validate_env(cls, v: dict[str, str] | None) -> dict[str, str] | None: """Validate env map constraints.""" if v is not None: from .utils import MAX_ENV_ENTRIES, MAX_ENV_KEY_LENGTH, MAX_ENV_VALUE_LENGTH if len(v) > MAX_ENV_ENTRIES: raise ValueError(f"Too many env vars (max {MAX_ENV_ENTRIES})") for key, val in v.items(): if len(key) > MAX_ENV_KEY_LENGTH: raise ValueError(f"Env key too long (max {MAX_ENV_KEY_LENGTH} chars)") if len(val) > MAX_ENV_VALUE_LENGTH: raise ValueError(f"Env value too long (max {MAX_ENV_VALUE_LENGTH} chars)") return v
• src/mcp_debug_tool/sessions.py:100-155 (handler)

  Core implementation in SessionManager.create_session: validates paths, creates DebugSession instance, generates UUID sessionId, stores in sessions dict.
  def create_session(self, request: StartSessionRequest) -> StartSessionResponse: """ Create a new debug session. Args: request: Session creation request Returns: Response with new session ID Raises: ValueError: If entry path is invalid FileNotFoundError: If entry script doesn't exist """ # Validate and resolve entry path entry_path = resolve_workspace_path(self.workspace_root, request.entry) if not entry_path.exists(): raise FileNotFoundError(f"Entry script not found: {request.entry}") if not entry_path.is_file(): raise ValueError(f"Entry path is not a file: {request.entry}") if entry_path.suffix != ".py": raise ValueError(f"Entry must be a Python file (.py): {request.entry}") # Determine workspace root for this session # If entry is absolute path, find the workspace root from the entry path session_workspace = self._find_workspace_root(entry_path) # Validate Python path (required) python_path = Path(request.pythonPath) if not python_path.exists(): raise FileNotFoundError(f"Python interpreter not found: {request.pythonPath}") if not python_path.is_file(): raise ValueError(f"Python path is not a file: {request.pythonPath}") # Generate session ID session_id = str(uuid.uuid4()) # Create session with DAP enabled by default use_dap = request.useDap if request.useDap is not None else True session = DebugSession( session_id=session_id, entry=entry_path, python_path=request.pythonPath, workspace_root=session_workspace, args=request.args or [], env=request.env or {}, use_dap=use_dap, ) self.sessions[session_id] = session return StartSessionResponse(sessionId=session_id)
• src/mcp_debug_tool/sessions.py:32-92 (helper)

  DebugSession class: holds session state, status, timings, breakpoints; used by SessionManager for sessions_create.
  class DebugSession: """Represents an active debug session.""" def __init__( self, session_id: str, entry: Path, python_path: str, workspace_root: Path, args: list[str] | None = None, env: dict[str, str] | None = None, use_dap: bool = True, ): self.id = session_id self.entry = entry self.workspace_root = workspace_root self.args = args or [] self.env = env or {} self.python_path = python_path self.use_dap = use_dap self.status = SessionStatus.IDLE self.created_at = datetime.now() self.updated_at = datetime.now() self.last_breakpoint: BreakpointTarget | None = None self.timings = SessionTimings() # bdb mode (legacy) self.process: subprocess.Popen | None = None self.reader_task = None # Background task for reading subprocess output # DAP mode (default) self.dap_wrapper = None # Will be set if use_dap=True def update_status(self, status: SessionStatus) -> None: """Update session status and timestamp.""" self.status = status self.updated_at = datetime.now() def update_breakpoint(self, file: str, line: int) -> None: """Update last breakpoint information.""" if self.last_breakpoint and self.last_breakpoint.file == file and self.last_breakpoint.line == line: self.last_breakpoint.hitCount += 1 else: self.last_breakpoint = BreakpointTarget(file=file, line=line, hitCount=1) self.updated_at = datetime.now() def update_timings(self, last_run_ms: float) -> None: """Update timing information.""" self.timings.lastRunMs = last_run_ms self.timings.totalCpuTimeMs += last_run_ms self.updated_at = datetime.now() def to_state_response(self) -> SessionStateResponse: """Convert to state response model.""" return SessionStateResponse( status=self.status, lastBreakpoint=self.last_breakpoint, timings=self.timings, )