Skip to content

0010: M2 plan, Framework 0.2

Status: accepted by the owner on 11 November 2026. Each workstream below gets its own proposal and PR before it is built. No timeline: steps are ordered by dependency only.

Goal

M2 makes OunceMCP useful for every persona in spec section 4: servers that write safely, return large results by reference and run long jobs; a client broker for agent and host developers; a migration path and an audit command for maintainers of existing servers; and the remote-deployment basics teams need to run it in production.

Exit criteria (spec section 15): the pilots pass release gates 1 to 5; the migration guide works on one existing FastMCP-style server; audit totals match check within 1%. Gates 3 (no duplicate effect on replay) and 4 (approvals cannot be bypassed) are new in M2.

Scope

Spec M2 scope plus five additions the owner chose to include.

# Workstream Requirements
1 Shared store Spec 9.2 (no process-local state for correctness); SEC-6 shared single-use
2 Idempotent writes EXE-4; resolves EXE-3 ambiguous writes
3 Dependencies on the context (ctx.deps) Section 11 API sketch
4 Safe writes: preview, approve, commit Section 10, MRTR receipts; gate 4
5 Results by reference and jobs RES-5
6 Migration adapter and guide DX-7
7 Optional ouncemcp audit AUD-1 to AUD-13
8 Client broker, ouncemcp[client] CLI-1 to CLI-8
9 Pilots Section 15.1: ticketing, long-running report, migration
A1 Resources and prompts (addition) CAP-2
A2 Remote-deployment basics (addition) Spec 9.2: health and readiness, shared stores, deployment guide
A3 ouncemcp.toml configuration (addition) Section 11 sketch
A4 Metrics per tool (addition) Spec 9.4
A5 Description lints (addition) CAP-5

Design outline

1. Store. OunceStore on py-key-value-aio (already a FastMCP 4 dependency): memory by default, Redis or disk in production. Keys are namespaced by kind, principal and tenant; every entry has a TTL; put_if_absent is the primitive for exactly-once. One OunceServer(store=...) setting makes idempotency, approvals, handles and jobs safe across replicas.

2. Idempotency. Keyed by principal, tenant, operation and a digest of the normalized arguments; a client may also supply its own key. A replay returns the stored result; a concurrent duplicate waits or gets "in progress" and never runs twice. Ships a built-in write_resolver, so a timed-out write that completed is reported as done.

3. ctx.deps. Server-level dependencies (upstream HTTP clients with passthrough_guard installed by default, database pools, the store), replaceable with fakes in tests.

4. Safe writes. @server.tool(effect=Effect.WRITE, approval="never" | "required" | fn). Round 1 runs the handler's preview step and returns input_required with a confirmation and a signed receipt bound to tool, arguments, caller and tenant, single-use in the store and short-lived. Round 2 verifies and consumes the receipt and commits under idempotency. A client without elicitation, or a call without a valid receipt, fails closed. A two-call preview/commit pattern covers clients older than 2026-07-28. Composite tools report completed steps and recovery options on partial failure.

5. Handles and jobs. A tool can return a summary plus a handle read in pages with ouncemcp.read_handle; handles are bound to the caller and expire. ctx.start_job(...) runs work in the background and returns a job handle for status and result. Both live in the store, so they survive a restart and work across replicas. Jobs map onto the MCP tasks extension where FastMCP offers it.

6. Migration. OunceServer.from_fastmcp(...) wraps an existing server unchanged so it can be measured; the guide then adds effects, typed outputs, budgets, policies and shaping one tool at a time, with token counts after each step.

7. audit. Measures any server over stdio or URL with the check token engine. Lists and discovers only, unless tool calls are explicitly allowed. JSON and terminal output, --budget thresholds with CI exit codes, a discovery-mode recommendation, --compare against an earlier report.

8. Client broker. Multiple servers with stable ids and namespaced tools; cross-server search when definitions exceed budget; definition cache honoring ttlMs, cacheScope and list_changed; result validation; approval and elicitation hooks; total deadlines, connection reuse and failure isolation; token counts on every result; no cross-server authority from server text (prompt-injection tests).

9. Pilots. Each compared with a plain FastMCP version (lines of code, setup steps, tokens, turns, unsupported cases):

Pilot Proves
Ticketing Preview, approve, commit; timeout after the upstream write gives no duplicate
Long-running report Handles and jobs across two replicas and a restart
Migration of markitdown-mcp (Microsoft, MIT) Real adoption cost. Its one tool returns unbounded Markdown for any URI, so it exercises result budgets, handles (RES-5) and URL safety (the SEC-9 probe)

A1 to A5. Resources and prompts as typed, budgeted, policy-checked primitives (also makes the conformance resource and prompt scenarios pass). /healthz and /readyz for HTTP deployments plus a container deployment guide. ouncemcp.toml for budgets, discovery, tokenizer and security settings. Per-tool metrics (calls, errors by category, latency, result tokens, truncations) as a trace sink. Description lints in check: purpose, when not to use, side effects on writes.

Build order

  1. Store, idempotency, ctx.deps.
  2. Safe writes, then the ticketing pilot (gates 3 and 4).
  3. Handles and jobs, then the report pilot.
  4. Resources and prompts (A1).
  5. Migration adapter and guide, audit, then the markitdown-mcp pilot.
  6. Client broker.
  7. Deployment basics, ouncemcp.toml, metrics, description lints (A2 to A5).
  8. Spec v0.8 and release-gate checks 1 to 5.

Decisions

  1. Additions A1 to A5: included (owner, 11 November 2026).
  2. Migration pilot: markitdown-mcp.
  3. Policies over stdio: option C (owner, 11 November 2026). OunceServer(stdio_policy="trust" | "enforce"), default "trust" (FastMCP's behavior). "enforce" runs every tool's checks on stdio with the anonymous caller, for lists, search, describe and calls. Approvals for safe writes are enforced on every transport in both modes. ouncemcp check warns (stdio-skips-policy) when tools have policies and stdio is trusted. Implemented with this proposal.