debugpy-mcp

Implementation Reference

• src/debugpy_mcp/server.py:553-564 (handler)

  Main handler function for the debugpy_breakpoint_plan tool. It checks if the container is running, retrieves debugpy logs and context, then builds and returns a breakpoint plan by calling build_breakpoint_plan.

  @mcp.tool()
  def debugpy_breakpoint_plan(container: str, tail: int = 250, python_bin: str = "python") -> dict[str, Any]:
      if not docker_inspect_running(container):
          return BreakpointPlanResult(ok=False, container=container, notes=["Container is not running or does not exist."]).model_dump()
      logs_resp = debugpy_logs(container=container, tail=tail)
      ctx_resp = debugpy_context(container=container, python_bin=python_bin)
      logs = str(logs_resp.get("logs", ""))
      processes = [ProcessInfo(**p) for p in ctx_resp.get("processes", [])]
      working_dir = ctx_resp.get("working_dir")
      plan = build_breakpoint_plan(logs, processes, working_dir)
      plan.container = container
      return plan.model_dump()

• src/debugpy_mcp/server.py:90-102 (schema)

  Schema definitions for breakpoint planning: BreakpointTarget defines individual breakpoint suggestions with file_hint, rationale, and breakpoint_kind; BreakpointPlanResult is the output schema containing ok status, container, inferred_endpoint, inferred_modules, targets list, and notes.

  class BreakpointTarget(BaseModel):
      file_hint: str
      rationale: str
      breakpoint_kind: Literal["route", "dependency", "middleware", "startup", "exception", "worker", "service"]
  
  
  class BreakpointPlanResult(BaseModel):
      ok: bool
      container: str
      inferred_endpoint: str | None = None
      inferred_modules: list[str] = Field(default_factory=list)
      targets: list[BreakpointTarget] = Field(default_factory=list)
      notes: list[str] = Field(default_factory=list)

• src/debugpy_mcp/server.py:31-35 (schema)

  ProcessInfo schema used as input for breakpoint planning - defines process metadata with pid, ppid, cmd, and kind (uvicorn, gunicorn-master, gunicorn-worker, python, other).

  class ProcessInfo(BaseModel):
      pid: int
      ppid: int
      cmd: str
      kind: Literal["uvicorn", "gunicorn-master", "gunicorn-worker", "python", "other"]

• src/debugpy_mcp/server.py:360-425 (helper)

  Core helper function that builds the breakpoint plan by analyzing logs and processes. It infers modules from logs, creates BreakpointTarget suggestions based on endpoint activity, middleware, errors, and provides fallback defaults.

  def build_breakpoint_plan(logs: str, processes: list[ProcessInfo], working_dir: str | None) -> BreakpointPlanResult:
      inferred_modules, endpoint = infer_modules_from_logs(logs)
      notes: list[str] = []
      targets: list[BreakpointTarget] = []
  
      if endpoint:
          targets.append(BreakpointTarget(
              file_hint="app/routes/* or api/routes/*",
              rationale=f"Recent logs suggest endpoint activity around {endpoint}; route handler is the first high-value breakpoint.",
              breakpoint_kind="route",
          ))
  
      if any("middleware" in p.cmd.lower() for p in processes) or "middleware" in logs.lower():
          targets.append(BreakpointTarget(
              file_hint="app/main.py or app/middleware/*",
              rationale="Logs or process metadata suggest middleware involvement; break before request dispatch and on exception wrapping.",
              breakpoint_kind="middleware",
          ))
  
      if "traceback" in logs.lower() or "exception" in logs.lower() or "error" in logs.lower():
          targets.append(BreakpointTarget(
              file_hint="file from top traceback frame",
              rationale="Container logs contain an error signal; set a breakpoint on the first application frame above framework internals.",
              breakpoint_kind="exception",
          ))
  
      if not targets:
          targets.append(BreakpointTarget(
              file_hint="app/main.py",
              rationale="Default fallback: break in FastAPI app setup to inspect router registration, dependencies, and middleware.",
              breakpoint_kind="startup",
          ))
          targets.append(BreakpointTarget(
              file_hint="app/api/* or app/routes/*",
              rationale="Default fallback: break in the route handler for the suspect endpoint or resource.",
              breakpoint_kind="route",
          ))
          targets.append(BreakpointTarget(
              file_hint="app/services/*",
              rationale="Default fallback: break inside the business logic layer called by the route.",
              breakpoint_kind="service",
          ))
  
      for mod in inferred_modules[:3]:
          targets.append(BreakpointTarget(
              file_hint=mod,
              rationale="This file path appeared in recent logs and is a likely code path for the failure.",
              breakpoint_kind="exception" if mod.endswith(".py") else "service",
          ))
  
      if working_dir:
          notes.append(f"Likely remote source root is near {working_dir}.")
      if inferred_modules:
          notes.append("Inferred modules were extracted from container logs and stack traces.")
      else:
          notes.append("No explicit file paths were found in logs; plan is heuristic.")
  
      deduped: list[BreakpointTarget] = []
      seen: set[tuple[str, str]] = set()
      for t in targets:
          key = (t.file_hint, t.breakpoint_kind)
          if key not in seen:
              seen.add(key)
              deduped.append(t)
  
      return BreakpointPlanResult(ok=True, container="", inferred_endpoint=endpoint, inferred_modules=inferred_modules, targets=deduped[:6], notes=notes)

• src/debugpy_mcp/server.py:347-357 (helper)

  Helper function that parses logs to extract file paths using regex patterns and detect HTTP endpoints (GET/POST/PUT/PATCH/DELETE). Returns a tuple of inferred modules and optional endpoint.

  def infer_modules_from_logs(logs: str) -> tuple[list[str], str | None]:
      inferred_modules: list[str] = []
      endpoint: str | None = None
      for pattern in [r"File \"([^\"]+)\"", r"(/[^\s:'\"]+\.py)", r"([A-Za-z0-9_./-]+\.py)"]:
          for match in re.findall(pattern, logs):
              if match not in inferred_modules:
                  inferred_modules.append(match)
      endpoint_match = re.search(r'\b(GET|POST|PUT|PATCH|DELETE)\s+([^\s]+)', logs)
      if endpoint_match:
          endpoint = f"{endpoint_match.group(1)} {endpoint_match.group(2)}"
      return inferred_modules[:10], endpoint