---
id: SMH-PLAN-H7QBKZ4Z
type: plan
title: "Model Context Protocol Frontend"
spec: SMH-SPEC-SPEC0001
status: draft
depends_on: [SMH-PLAN-CORE0001]
---

# Model Context Protocol Frontend

## Outcome

Agent clients speak MCP to a running smith: list tools, call them with durable evidence, read sessions as resources, watch progress.
`smith-mcp` is the second `smith-ui` consumer and the generality proof that the UI vocabulary serves non-terminal audiences.

## Scope

The `smith-ui` intent vocabulary v0 with a diagnostic reference consumer, the `smith-mcp` crate over the `rmcp` engine, and the `smith mcp` interface mode.
Daemon, HTTP serving, and OAuth flows stay in the remote-frontends spec; this plan delivers the client-spawned stdio server.

## Behaviors

Ordered by delivery value.

1. **Intent vocabulary v0**: `smith-ui` defines semantic intents — progress, notification, transcript append — each with its per-intent degradation behavior.
2. **Diagnostic consumer**: `smith-ui` renders every intent as structured records; it becomes the conformance reference all frontends test against.
3. **RPC event mapping**: the existing smith-rpc event stream emits intents, proving the vocabulary against the first headless consumer in place.
4. **MCP server mode**: `smith mcp` runs a client-spawned stdio server; initialize handshake, tool listing over the built-in `read`, `write`, `edit`, `bash`, `find`, `grep`, `ls`; tool calls execute through the tool session with durable, attributable effects.
5. **Progress streaming**: long-running tool calls stream MCP progress notifications sourced from intent events.
6. **Sessions as resources**: sessions list and read as MCP resources; transcript appends surface as resource updates.
7. **Degradation conformance**: overlay and theme intents degrade under MCP per the intent law; the diagnostic consumer verifies equivalence.

## Behavior structure

```mermaid
flowchart LR
  V["Intent vocabulary v0"] --> D["Diagnostic consumer"]
  V --> R["RPC event mapping"]
  D --> M["MCP server mode"]
  R --> M
  M --> P["Progress streaming"]
  M --> S["Sessions as resources"]
  P --> G["Degradation conformance"]
  S --> G
```

## Interfaces

- `smith-ui`: intent types, degradation metadata, diagnostic renderer.
- `smith-mcp`: rmcp engine ownership, MCP constructs, intent translation.
- `smith-cli`: `mcp` interface mode.
- `smith-core`: tool session, durable effects, session store.

## Verification

- An MCP client completes initialize, tools/list, and one tools/call per built-in tool end to end.
- Progress notifications arrive during a long tool call and stop at completion.
- A session read as a resource returns the full ordered transcript.
- Diagnostic and MCP consumers produce equivalent records for identical intent scripts.
- No credential material crosses the MCP boundary.
- Tool calls made through MCP leave the same durable evidence as local calls.

## Stop conditions

- An intent cannot express its MCP translation without mode sniffing.
- rmcp cannot serve the stdio subset without pulling a runtime decision.
- A tool call through MCP would bypass the durable effect boundary.