debugpy-mcp

Implementation Reference

• src/debugpy_mcp/server.py:438-455 (handler)

  The main handler function for the 'debugpy_status' tool. It checks if a Docker container is running, whether debugpy is installed, if the debug port is listening, retrieves the process table, and returns comprehensive status information.

  @mcp.tool()
  def debugpy_status(container: str, port: int = DEFAULT_PORT, host: str = DEFAULT_HOST, python_bin: str = "python") -> dict[str, Any]:
      running = docker_inspect_running(container)
      if not running:
          return DebugpyStatusResult(ok=False, container=container, port=port, host=host, container_running=False, debugpy_installed=False, debugpy_listening=False, notes=["Container is not running or does not exist."]).model_dump()
      installed, _version = detect_debugpy_installed(container, python_bin=python_bin)
      mapped_port = docker_port_mapping(container, port)
      notes: list[str] = []
      if mapped_port is None:
          notes.append(f"No docker port mapping was found for container port {port}. Your IDE may still connect if the network path is otherwise reachable.")
      processes = get_process_table(container)
      suggested_pid, pid_notes = choose_pid(processes)
      notes.extend(pid_notes)
      listening = port_is_listening(container, port)
      notes.append(f"Port {port} is {'already' if listening else 'not'} listening inside the container.")
      if not installed:
          notes.append("debugpy is not importable inside the container.")
      return DebugpyStatusResult(ok=True, container=container, port=port, host=host, container_running=True, debugpy_installed=installed, debugpy_listening=listening, mapped_port=mapped_port, candidate_processes=processes, suggested_pid=suggested_pid, notes=notes).model_dump()

• src/debugpy_mcp/server.py:38-49 (schema)

  The Pydantic BaseModel that defines the output schema for the debugpy_status tool, including fields for container status, debugpy installation status, port listening status, process candidates, and notes.

  class DebugpyStatusResult(BaseModel):
      ok: bool
      container: str
      port: int
      host: str
      container_running: bool
      debugpy_installed: bool
      debugpy_listening: bool
      mapped_port: str | None = None
      candidate_processes: list[ProcessInfo] = Field(default_factory=list)
      suggested_pid: int | None = None
      notes: list[str] = Field(default_factory=list)

• src/debugpy_mcp/server.py:438-438 (registration)

  The @mcp.tool() decorator registers the debugpy_status function as an MCP tool, making it available to MCP clients.

  @mcp.tool()