debugpy-mcp

Implementation Reference

• src/debugpy_mcp/server.py:156-192 (handler)

  The core handler function `autodiscover_target` that implements the autodiscovery logic. It lists running Docker containers, scores them based on service_hint and image_hint parameters, and returns the best matching container(s).

  def autodiscover_target(service_hint: str | None = None, image_hint: str | None = None) -> AutodiscoverResult:
      containers = list_containers()
      notes: list[str] = []
      scored: list[tuple[int, ContainerSummary]] = []
  
      for c in containers:
          score = 0
          haystacks = [c.name.lower(), c.image.lower(), c.ports.lower()]
          if service_hint:
              hint = service_hint.lower()
              if hint in c.name.lower():
                  score += 10
              if hint in c.image.lower():
                  score += 6
          if image_hint:
              hint = image_hint.lower()
              if hint in c.image.lower():
                  score += 10
              if hint in c.name.lower():
                  score += 3
          if "5678" in c.ports:
              score += 4
          if any(token in c.name.lower() or token in c.image.lower() for token in ["api", "fastapi", "uvicorn", "backend", "web"]):
              score += 2
          if score > 0:
              scored.append((score, c))
  
      if not scored:
          notes.append("No strong autodiscovery match found; returning all running containers.")
          return AutodiscoverResult(ok=True, candidates=containers, selected=containers[0] if containers else None, notes=notes)
  
      scored.sort(key=lambda t: (-t[0], t[1].name))
      candidates = [c for _, c in scored]
      selected = candidates[0] if candidates else None
      if selected:
          notes.append(f"Selected container '{selected.name}' as the strongest match.")
      return AutodiscoverResult(ok=True, candidates=candidates, selected=selected, notes=notes)

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

  The MCP tool registration point using `@mcp.tool()` decorator. The `debugpy_autodiscover_target` function wraps the handler and converts the result to a dict via `.model_dump()`.

  @mcp.tool()
  def debugpy_autodiscover_target(service_hint: str | None = None, image_hint: str | None = None) -> dict[str, Any]:
      return autodiscover_target(service_hint=service_hint, image_hint=image_hint).model_dump()

• src/debugpy_mcp/server.py:16-28 (schema)

  Pydantic BaseModel classes `ContainerSummary` and `AutodiscoverResult` that define the input/output schema for the autodiscovery feature.

  class ContainerSummary(BaseModel):
      id: str
      name: str
      image: str
      status: str
      ports: str
  
  
  class AutodiscoverResult(BaseModel):
      ok: bool
      candidates: list[ContainerSummary] = Field(default_factory=list)
      selected: ContainerSummary | None = None
      notes: list[str] = Field(default_factory=list)

• src/debugpy_mcp/server.py:143-153 (helper)

  Helper function `list_containers` that executes `docker ps` and parses the output into ContainerSummary objects, used by the autodiscover_target handler.

  def list_containers() -> list[ContainerSummary]:
      proc = run([
          "docker", "ps", "--format", "{{.ID}}\t{{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}"
      ], timeout=10)
      items: list[ContainerSummary] = []
      for line in proc.stdout.splitlines():
          parts = line.split("\t")
          if len(parts) != 5:
              continue
          items.append(ContainerSummary(id=parts[0], name=parts[1], image=parts[2], status=parts[3], ports=parts[4]))
      return items