Debug-MCP

Instructions

Implementation Reference

• src/mcp_debug_tool/server.py:499-553 (handler)

  MCP tool handler for 'sessions_end': validates sessionId, calls SessionManager.end_session_async(), handles errors, returns JSON response as TextContent.

  async def _handle_sessions_end(self, arguments: dict) -> list[TextContent]:
      """
      Handler for sessions_end tool.
      
      Ends a debug session and cleans up resources.
      """
      try:
          session_id = arguments.get("sessionId")
          if not session_id:
              return [
                  TextContent(
                      type="text",
                      text=json.dumps({
                          "error": {
                              "type": "ValueError",
                              "message": "sessionId is required",
                          }
                      }),
                  )
              ]
  
          response = await self.session_manager.end_session_async(session_id)
          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 ending session")
          return [
              TextContent(
                  type="text",
                  text=json.dumps({
                      "error": {
                          "type": type(e).__name__,
                          "message": str(e),
                      }
                  }),
              )
          ]

• src/mcp_debug_tool/server.py:148-161 (registration)

  Tool registration in list_tools(): defines name, description, and inputSchema requiring 'sessionId' string.

  Tool(
      name="sessions_end",
      description="End a debug session and clean up resources",
      inputSchema={
          "type": "object",
          "properties": {
              "sessionId": {
                  "type": "string",
                  "description": "The debug session ID",
              },
          },
          "required": ["sessionId"],
      },
  ),

• src/mcp_debug_tool/schemas.py:161-164 (schema)

  Pydantic model for output response: simple confirmation {ended: true}.

  class EndSessionResponse(BaseModel):
      """Response confirming session ended."""
      ended: bool = True

• src/mcp_debug_tool/sessions.py:219-264 (helper)

  Core SessionManager.end_session(): terminates DAP wrapper or subprocess, updates status to COMPLETED, removes session from manager.

  def end_session(self, session_id: str) -> EndSessionResponse:
      """
      End a debug session and clean up resources.
  
      Args:
          session_id: Session ID
  
      Returns:
          End confirmation response
      """
      session = self.get_session(session_id)
  
      # Clean up DAP wrapper if using DAP
      if session.dap_wrapper:
          try:
              session.dap_wrapper.terminate()
          except Exception:
              pass
  
      # Clean up subprocess if running (bdb mode)
      if session.process and session.process.poll() is None:
          # Try graceful termination first
          try:
              terminate_cmd = json.dumps({"command": "terminate"}) + '\n'
              session.process.stdin.write(terminate_cmd)
              session.process.stdin.flush()
              session.process.wait(timeout=5)
          except Exception:
              pass
  
          # Force terminate if still running
          if session.process.poll() is None:
              session.process.terminate()
              try:
                  session.process.wait(timeout=5)
              except subprocess.TimeoutExpired:
                  session.process.kill()
                  session.process.wait()
  
      # Update status
      session.update_status(SessionStatus.COMPLETED)
  
      # Remove from active sessions
      del self.sessions[session_id]
  
      return EndSessionResponse(ended=True)

• src/mcp_debug_tool/sessions.py:946-952 (helper)

  Async wrapper end_session_async(): bridges sync end_session to async MCP handler via asyncio.to_thread.

  async def end_session_async(self, session_id: str) -> EndSessionResponse:
      """
      Async wrapper for end_session.
      
      Runs the synchronous end_session in a thread pool to avoid blocking.
      """
      return await asyncio.to_thread(self.end_session, session_id)