Codumentor logo Codumentor

Phase 7 — Codumentor Self-Adapter + MCP Bridge

Goal

Two related additions:

  1. codumentor adapter — treat a Codumentor instance (potentially a different instance, or the same one) as an external agent. Unlike every other backend, the transport here is HTTP, not a CLI subprocess.
  2. MCP bridge — expose a curated set of Codumentor's own tools (e.g., Memory) to external agents over MCP so they can call Codumentor tools from inside their sandbox.

These two are bundled because both involve breaking the "external agent = CLI subprocess" assumption, and the design ergonomics around that are cleaner if tackled together.

Preconditions

Phases 1–6 shipped.

Deliverables

Codumentor self-adapter

  1. adapters/codumentor.py implementing AgentAdapter but with HTTP transport. This will likely require extending AgentAdapter or introducing a TransportAdapter abstraction above it — the current Protocol assumes argv + env + stdout streaming, which doesn't fit HTTP. Decide and propose; the orchestrator must approve before you implement.
  2. tools/codumentor.py — registry entry — config schema for the Codumentor backend (URL, auth token, optional instance label).
  3. Auth: per-user API token stored via byo_key (reuse, don't reinvent). For pointing at the same Codumentor instance, the user's own session token works.
  4. Tests with a mocked Codumentor API.

MCP bridge

  1. mcp_bridge.py implementing a minimal MCP server that exposes selected Codumentor tools to a subprocess. Expose-list is configurable per backend: codumentor.yaml.external_agent.backends.<name>.expose_mcp_tools: [memory_store, memory_search, ...].
  2. Inject the MCP bridge as a Unix-socket-bound server inside the sandbox (Tier-0 via env hint, Tier-1 via bind-mount). External CLIs that speak MCP can then call memory_store(...) etc.
  3. A proposed minimal expose-set (see step 4 below) flagged for orchestrator approval before implementation. Do not expose arbitrary Codumentor tools.
  4. Tests: subprocess calls a tool via MCP and the call lands in Codumentor's actual tool runtime with proper permission gating.

New files

src/codumentor/plugins/external_agent/adapters/codumentor.py
src/codumentor/plugins/external_agent/tools/codumentor.py
src/codumentor/plugins/external_agent/mcp_bridge.py
src/codumentor/plugins/external_agent/transport.py    (if you extract a TransportAdapter abstraction)
tests/test_external_agent_adapter_codumentor.py
tests/test_external_agent_mcp_bridge.py

Touched: adapter_base.py (Protocol extension), runner.py (route HTTP transport vs subprocess transport), sandbox/tier0.py and sandbox/tier1.py (MCP socket injection).

Implementation steps

  1. First: surface the Protocol extension proposal to the orchestrator. Before writing the Codumentor adapter, sketch the proposed TransportAdapter extension or AgentAdapter changes, post them in your interim message, and pause for orchestrator approval. The two viable shapes are: - Inheritance: class HTTPAdapter(AgentAdapter) that overrides build_argv to a no-op and adds async def call_http(...). The runner detects the kind and dispatches. - Composition: class AgentAdapter keeps its existing shape; a sibling protocol class TransportAdapter (with subprocess and http variants) is what AgentAdapter actually uses internally. More refactor, cleaner long-term.
  2. Build the Codumentor adapter after approval, conforming to whichever shape was chosen. Use Codumentor's existing API client if one exists; otherwise hit /api/conversations etc. directly with aiohttp.
  3. Event mapping: the Codumentor API returns events that already look quite like our AgentEvent union (it's our own format). Map cleanly; do not introduce new kinds.
  4. MCP expose-set: propose a minimal initial set for orchestrator approval before implementing. Candidates: - memory_store (let external agents persist learnings) - memory_search (let external agents retrieve) - read_file (read a file from the host repo — sandbox-safe) - list_files (list a directory in the repo)

Explicitly NOT in the initial set: anything that writes to the host repo, anything that spawns further subagents, anything network-touching.

  1. MCP server implementation: use the existing MCP SDK if Codumentor already depends on one; otherwise the MCP protocol is simple enough to implement directly. Bind to a Unix socket at <sandbox_dir>/mcp.sock. In Tier 0, pass the socket path via env (CODUMENTOR_MCP_SOCKET); in Tier 1, bind-mount the socket into the sandbox at a fixed path.
  2. Tool gating: every MCP call must run through Codumentor's normal PermissionProvider. From the user's perspective, the external agent calling memory_store through MCP is no different from the main agent calling it directly — same approval rules apply.
  3. Tests: a fake subprocess that connects to the MCP socket, calls memory_search, and verifies the call shows up in the host's tool runtime with the correct caller attribution (subagent id should be visible).

Acceptance criteria

Out of scope

Handoff

Fill out the template. In "Contracts established/changed":

In "Open questions":