Files
archie/docs/prds/mcp-tool-completion.md
T

196 lines
13 KiB
Markdown

# MCP client and tool-guardrail completion
**Status:** Approved
Epic: `archie-core-1786637493439-140-2cee2e9b` / GitHub `#161` ("[EPIC] Tools:
central registry, MCP client, guardrails").
This document is scoped to five sub-features of that epic: MCP
server-initiated sampling, the per-server parallel-tool-calls flag, sandboxed
MCP tool servers, a Firecracker sandbox backend, and sequential dispatch with
per-result previews.
Out of scope, and not to be touched: the central registry
(`internal/tools/registry.go`), all three MCP transports (stdio/HTTP/SSE,
`internal/tools/mcp/transport*.go`), reconnect-with-backoff
(`transport.go`), guardrail loop detection
(`internal/tools/guardrail.go`), idempotent/mutating classification
(`internal/tools/classification.go`), concurrent tool dispatch (`#183`), and
progressive disclosure wiring (`internal/app/archied`). These are settled and
production-wired.
## Problem
`bd search "MCP client"` shows five closed transport beads and one open:
server-initiated sampling (`#151`). `internal/tools/mcp/client.go`
holds a single `callMu *sync.Mutex` that serialises every `tools/call`
regardless of server — `ParallelToolCalls` does not exist on the `MCPServer`
config struct (`internal/config/config.go`), confirming `#177` is a
real gap, not a stale bead. `#178` (wire MCP tool servers for the chat agent,
sandboxed) and `#179` (Firecracker substrate) have no corresponding code —
MCP servers run as whatever the config's `Command`/`Args` launches,
unsandboxed. `#182` (sequential tool dispatch with per-result previews) is
open; concurrent dispatch (`#183`) is closed, so there are two dispatch paths
and this PRD decides how they coexist.
## Design
Sub-features are independent; there is no new shared type this document
introduces. Each section below stands alone.
## MCP server-initiated sampling (`#151`)
**Decision.** Implement as a callback on `mcp.Client`, not a second
transport. The MCP spec's `sampling/createMessage` request flows server→client
over the same connection each transport already maintains
(`transport.go`'s stdio/HTTP/SSE all multiplex request and response frames).
Add a `SamplingHandler func(context.Context, SamplingRequest) (SamplingResult, error)`
field to the client's config struct next to the existing transport fields,
defaulting to nil (server sampling requests get a JSON-RPC "not supported"
error when unset — never a silent drop).
**Call site.** `internal/tools/mcp/client.go` — add the handler field and a
dispatch branch in whatever function demuxes incoming server
messages by method name (the same switch that already routes
`notifications/*`). Wire a concrete handler in
`internal/app/archied/main.go` that routes the sampling request through the
same chat-model call path `chatGenerateOptions` already uses, so a
server-initiated sample gets the daemon's configured model, not a second
provider client.
**Reuse check.** The chat model invocation path already exists
(`chatGenerateOptions`, `main.go`); this reuses it rather than adding a
parallel model-calling path for MCP sampling.
**Failure mapping.**
| condition | contract error |
| ------------------------------- | ------------------------------------------------------------------------------------------ |
| no `SamplingHandler` configured | JSON-RPC method-not-found, per spec |
| handler returns error | JSON-RPC internal error, message from handler |
| handler timeout | JSON-RPC timeout error; use the transport's existing request-timeout config, not a new one |
**Testing.** Fakeable entirely — a stub `SamplingHandler` and a fake
transport that emits a `sampling/createMessage` frame. No real backend
needed; belongs in `task check`.
## Per-server parallel-tool-calls flag (`#177`)
**Decision.** `ParallelToolCalls bool` (default `false`) goes on `MCPServer`
in `internal/config/config.go`, next to `Transport`/`Command`. The
mutex in `client.go` becomes per-server: when `ParallelToolCalls` is
false (default, and the only behaviour), keep the single `callMu`
serialising that server's calls exactly as now; when true, drop the mutex for
that server's `Client` instance entirely and let the caller's own
concurrency (already proven by the closed concurrent-dispatch bead, `#183`)
handle it. This is additive — no server's behaviour changes unless an operator
opts in.
**Call site.** `internal/config/config.go` (struct field),
`internal/tools/mcp/client.go` (make the mutex conditional on the
field), and wherever `MCPServer` configs are turned into `Client` instances
at daemon startup (the constructor that reads `internal/config`'s MCP block).
`config.example.toml`'s commented MCP block gets the new field documented
with its default.
**Testing.** Unit test asserting two concurrent `Call`s to the same
`Client` block on each other when the flag is false and don't when true —
fakeable with a slow fake transport. `task check`.
## Sandboxed MCP tool servers for the chat agent (`#178`) and Firecracker substrate (`#179`)
**Decision.** These two beads are one design decision, not two: `#179` is an
alternate execution backend for `#178`, not separate scope. Sandbox MCP
servers that a chat-turn config marks as untrusted (a new
`Sandboxed bool` field on `MCPServer`, default `false` — existing
configured servers are unaffected) behind the same `ContainerPool` the
daemon already uses to run agent work
(`internal/container/pool.go`, per CLAUDE.md's `WriteTaskJSON` trap and the
`Acquire`/`Release` lifecycle `daemon.go`'s `acquireTaskContainer` already
proves). Do not build a second sandbox mechanism: an MCP stdio server is a
subprocess exactly like an agent task container's entrypoint, so launching it
via `ContainerPool.Acquire` with stdio piped to the `mcp.Client` transport is
the smallest change, not new plumbing.
Firecracker is **not** built now. `ContainerPool`'s existing Docker-backed
isolation is the shipped backend; Firecracker becomes a second
implementation of the same acquire/release contract only if a concrete
escape or resource-isolation gap is measured against Docker-backed sandboxing
in production. Recording this as the deletion/promotion gate keeps `#179`
honestly `OPEN` instead of speculatively building an unused backend, per
CLAUDE.md's Architectural Simplicity rule.
**Call site.** `internal/config/config.go` (`MCPServer.Sandboxed`), the MCP
client constructor (route sandboxed servers' process launch through
`container.Pool.Acquire` instead of `os/exec` directly), and
`internal/container/pool.go` (confirm its `Acquire` contract accepts a
stdio-piped, non-worktree workload — if it assumes a git worktree
per CLAUDE.md's `WriteTaskJSON` note, add the narrower entrypoint variant
there rather than duplicating the pool).
**Error/failure mapping.**
| condition | contract error |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| pool exhausted (no container slot) | MCP client returns connection-refused equivalent; server marked unavailable in the registry until retried |
| container fails health/start | same as `#151`'s handler-error path — surfaced through the client's existing reconnect/backoff (`transport.go`), not a new retry loop |
**Testing.** `Sandboxed=false` path is the existing, already-tested
unsandboxed flow — no change. `Sandboxed=true` needs a real
`ContainerPool` (Docker) — manual smoke command, not `task check`; document
the exact command in the runbook this PRD's issue links to once implemented.
## Sequential tool dispatch with per-result previews (`#182`)
**Decision.** This coexists with concurrent dispatch (`#183`, closed) as a
second, explicit mode selected by the caller — not a replacement. Concurrent
dispatch is for independent tool calls in one turn; sequential-with-preview
is for a turn where each result should be surfaced to the operator (or the
next tool call) before the next call fires — e.g. a mutating tool chain where
showing intermediate state matters. Add a `DispatchMode` enum
(`Concurrent`/`Sequential`) to whatever type selects the closed
`#183` concurrent path, defaulting to `Concurrent` (its only behaviour).
**Call site.** The tool-dispatch entry point that `#183`'s closed
implementation lives in (grep the concurrent-dispatch symbol added for
`#183` — same file gets the sequential branch, not a parallel file). Preview
surfacing reuses whatever channel-adapter interface already streams
intermediate turn output (the same seam `internal/channels/telegram/` and
other adapters use for streaming deltas) — do not invent a second preview
transport.
**Testing.** Fakeable with a fake tool that returns staged results; assert
preview callbacks fire in order before the next call starts. `task check`.
## Call site inventory
| concern | file | change |
| --------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------- |
| MCP client transports (stdio/HTTP/SSE) | `internal/tools/mcp/transport*.go` | none — already handles this |
| MCP client call serialisation | `internal/tools/mcp/client.go` | change (`#177`) |
| MCP server config | `internal/config/config.go` | new fields: `ParallelToolCalls`, `Sandboxed` |
| Sampling dispatch | `internal/tools/mcp/client.go` | new (`#151`) |
| Sampling handler wiring | `internal/app/archied/main.go` | new (`#151`), reuses `chatGenerateOptions` |
| Sandboxed MCP launch | MCP client constructor + `internal/container/pool.go` | new (`#178`/`#179`) |
| Concurrent tool dispatch | dispatch entry point (closed `#183`) | none — already handles this |
| Sequential tool dispatch + previews | same dispatch entry point | new (`#182`) |
| Guardrails / classification / registry / disclosure | `internal/tools/guardrail.go`, `classification.go`, `registry.go`, `disclosure.go` | none — already handles this |
| `config.example.toml` MCP block | `config.example.toml` | doc update for new fields |
## Execution: multi-agent team breakdown
| sub-feature | issue | implementer scope | suggested council lenses | why |
| ------------------------------------ | -------------- | ---------------------------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- |
| Server-initiated sampling | `#151` | `client.go` dispatch branch, `main.go` handler wiring | `lens-contract` | new JSON-RPC method surface crossing the MCP wire contract |
| Parallel-tool-calls flag | `#177` | config field, conditional mutex, constructor wiring | `lens-boundary` | per-server behaviour change must not leak into other servers' serialisation |
| Sandboxed MCP + Firecracker deferral | `#178`, `#179` | config field, constructor routing through `ContainerPool`, pool entrypoint variant | `lens-operator`, `lens-deletionist` | operator: sandbox-down failure path; deletionist: keeps `#179` from becoming unused scaffolding |
| Sequential dispatch with previews | `#182` | `DispatchMode` enum, sequential branch, preview reuse of streaming seam | `lens-maintainer` | two coexisting dispatch modes need a reader to tell which applies without re-deriving both |
## File and link the beads
- `#151`, `#177`, `#178`, `#179`, `#182` each get their description updated to
point at this doc's matching `##` heading instead of restating the design.
- Close `#179` as a design decision (link here) rather than leaving it open
as separate scope — it is not built now, and the doc records why.
- Add the suggested lenses to each issue directly.