196 lines
13 KiB
Markdown
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.
|