yggdrasil/docs/mcp-spec.md

# MCP Server — Specification

> Buildable spec for a Model Context Protocol server embedded in Yggdrasil.
> Derives from the grilling decisions (2026-07-28) and `docs/mcp-research.md`.
> Spec version: 1.0.

## 1. Overview

Expose the blog as an **MCP server** so the admin's own AI clients (Claude Code,
Cursor, Cline/Continue) can (a) query published posts as a **knowledge base** and
(b) perform nearly all backend operations (write posts, moderate comments, manage
tags/settings, upload media, run code). An admin settings page generates per-token
MCP client configs with a user-selectable token lifetime and three permission scopes.

**Single-tenant model.** Tokens are minted by the admin for the admin's own clients.
No OAuth 2.1 / PKCE / dynamic client registration. The bearer-token header format is
identical to an OAuth bearer, so the path is forward-compatible if OAuth is ever added.

## 2. Decisions (locked during grilling)

| # | Decision | Choice |
|---|---|---|
| 1 | Audience | Admin's own AI clients only |
| 2 | Scope model | `read` / `write` / `admin` (3 scopes) |
| 3 | Token lifetime | Preset menu: 1d / 7d / 30d / 90d / never-expire (opt-in) |
| 4 | Knowledge-base retrieval | Full-text search MVP (reuse Postgres FTS); published posts as MCP Resources + `search_posts` tool; architecture leaves a seam for future pgvector |
| 5 | Tool surface | Post CRUD, post query, comment mgmt, tag mgmt, site settings, media upload, code runner. **Excludes** DB export/backup |
| 6 | Scope mapping | media=write; code runner=admin-only; read=published only; write/admin=includes drafts |
| 7 | Draft visibility | `read` → published only; `write`/`admin` → incl. drafts |
| 8 | Token storage | AES-GCM encrypted at rest (env key `MCP_TOKEN_ENC_KEY`); retrievable by admin |
| 9 | Config targets | Claude Code, Cursor, Cline/Continue, generic raw JSON |

## 3. Goals / Non-goals

**Goals**
- One `/mcp` Streamable HTTP endpoint, stateless, spec `2025-11-25`.
- Bearer-token auth with 3 scopes, encrypted-at-rest storage, selectable lifetime.
- Knowledge base: published posts as paginated Resources + FTS `search_posts` tool.
- Write/admin tools covering the locked surface.
- Admin UI: token CRUD + one-click config generation for 4 client formats.

**Non-goals (MVP)**
- OAuth 2.1 / PKCE / DCR (forward-compatible seam only).
- Semantic/vector retrieval (pgvector) — full-text first; interface is vector-ready.
- Prompts / Completions / Elicitation / Sampling / Roots / Tasks / Logging primitives.
- Multi-tenant / public token issuance.
- Database export/backup over MCP.

## 4. Architecture

### 4.1 Transport & mount
- **Streamable HTTP, stateless** (SEP-2567): no `Mcp-Session-Id`, no GET stream.
  Each POST is a self-contained request; the bearer token authenticates it.
- Mount the official **`rmcp`** crate's Tower `StreamableHttpService` at `/mcp` via
  `axum::Router::nest_service("/mcp", service)`, merged into the app router in
  `src/main.rs` alongside the existing `upload_route`/`export_route`/`sse_route`.
- Negotiate protocol `2025-11-25`; respond `application/json` (no SSE stream needed
  for non-streaming tools).

### 4.2 Authentication
- `Authorization: Bearer ygg_<opaque>` on every request.
- A new middleware/extractor resolves the bearer → `(user_id, scope)`:
  decrypt-stored-token lookup by token id, enforce expiry, update `last_used_at`.
- **`Origin` → 403 is a hard MUST** (spec `2025-11-25`): validate `Origin` against the
  same trusted-origin allowlist as CSRF (`APP_BASE_URL` / Host fallback).
- `MCP-Protocol-Version` header honored; reject unsupported versions with 400.
- Sessions MUST NOT be used for auth (spec); the token authenticates every request.

### 4.3 Rate limiting
- New **token-keyed** governor bucket on `/mcp` only (extract bearer → `user_id`).
  The existing IP-keyed governor stays on the web app and is NOT reused for MCP.
- Per-request body-size cap; rely on the global `statement_timeout` for DB bounds.

### 4.4 Scope enforcement
- Each tool declares its required scope. Dispatch checks `token.scope >= required`;
  mismatch → `403 insufficient_scope`-style MCP error.
- Read tools (search, get/list published) = `read`. Mutating post/comment/tag/media =
  `write`. Settings + code runner = `admin`.
- Search/snippet output is an **indirect-prompt-injection surface**: sanitize, keep
  read vs write on separate scopes, lean on the client's human-in-the-loop.

### 4.5 Feature gating
- All MCP code is **server-only**: `#[cfg(feature = "server")]` impl + compiling
  `#[cfg(not(feature = "server"))]` stubs for the WASM build, per AGENTS.md §1.
- The admin UI page renders on both targets; it calls token-management server fns.

## 5. Data model

### 5.1 Migration `015_mcp_tokens.sql` (+ register in `MIGRATIONS`)
```sql
CREATE TABLE IF NOT EXISTS mcp_tokens (
    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id       INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    name          TEXT NOT NULL,
    scope         TEXT NOT NULL CHECK (scope IN ('read','write','admin')),
    -- AES-GCM ciphertext of the full bearer token (nonce || ct || tag), hex-encoded.
    token_enc     TEXT NOT NULL,
    -- SHA-256 of the token for fast constant-time lookup by bearer on each request.
    token_hash    CHAR(64) NOT NULL,
    created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
    expires_at    TIMESTAMPTZ,            -- NULL = never-expire (opt-in)
    last_used_at  TIMESTAMPTZ,
    revoked_at    TIMESTAMPTZ
);
CREATE UNIQUE INDEX mcp_tokens_token_hash_active_idx
    ON mcp_tokens (token_hash) WHERE revoked_at IS NULL;
CREATE INDEX mcp_tokens_user_idx ON mcp_tokens (user_id);
```

### 5.2 Model (`src/models/mcp_token.rs`)
`McpToken` (DB row), `McpTokenSummary` (list response — no secret), `CreateTokenResponse`
(returns plaintext once), plus a `TokenScope` enum (`Read`/`Write`/`Admin`) with
`>=` ordering and serde.

## 6. Module breakdown

New top-level module `src/mcp/` (server-only impl, stubs for WASM):

| Path | Responsibility |
|---|---|
| `src/mcp/mod.rs` | Module root, re-exports, `cfg` gate |
| `src/mcp/crypto.rs` | AES-GCM encrypt/decrypt of tokens; reads `MCP_TOKEN_ENC_KEY` |
| `src/mcp/auth.rs` | Bearer extractor → `(user_id, scope)`; Origin check; `last_used_at` update |
| `src/mcp/rate_limit.rs` | Token-keyed governor for `/mcp` |
| `src/mcp/server.rs` | rmcp `ServerHandler` impl: `tools/list`, `resources/list`, `resources/read`, dispatch |
| `src/mcp/tools/` | Tool impls: `read.rs`, `posts.rs`, `comments.rs`, `tags.rs`, `settings.rs`, `media.rs`, `runner.rs` |
| `src/mcp/resources.rs` | Published-post Resources + templates (`post://{slug}`) |
| `src/mcp/router.rs` | Builds the `StreamableHttpService`, mounts at `/mcp` (called from `main.rs`) |
| `src/mcp/config.rs` | Generates the 4 client config formats from a token |

Token management lives in the existing API tree:
| Path | Responsibility |
|---|---|
| `src/api/mcp_tokens.rs` | `#[server]` fns: `create_mcp_token`, `list_mcp_tokens`, `revoke_mcp_token`, `reveal_mcp_token` (admin-guarded) |
| `src/models/mcp_token.rs` | shared DTOs |

Admin UI:
| Path | Responsibility |
|---|---|
| `src/pages/admin/mcp.rs` | Token CRUD + config generator page |
| nav entry in the admin layout | link to `/admin/mcp` |

### 6.1 Tool catalogue

**Resources** (read scope, published posts only)
- `resources/list` — paginated published posts (opaque cursor; page size server-set).
- `resources/templates/list` — `post://{slug}`.
- `resources/read` — rendered Markdown of one post.

**Tools — `read`**
- `search_posts(query, limit?, cursor?)` — FTS via existing search helper; returns
  summaries + `resource_link`s to matching posts.
- `get_post(slug|id)` — published only.
- `list_tags()`.

**Tools — `write`** (also readable incl. drafts)
- `create_post`, `update_post`, `publish_post`, `trash_post`, `delete_post`.
- `list_comments`, `approve_comment`, `delete_comment`, `set_comment_status`.
- `create_tag`, `rename_tag`.
- `upload_media` (base64 → existing upload pipeline).

**Tools — `admin`**
- `get_settings`, `update_settings`.
- `run_code` (delegates to the existing code-runner execute path; admin-only).

## 7. New dependencies & env

**Cargo.toml** (added under `[features] server`) — **pinned to the 3.x beta line,
verified 2026-07-28 by a throwaway axum-0.8 probe.** The stable `rmcp 0.2.1` is far
older and LACKS `with_json_response`, `with_allowed_origins` (Origin→403),
`with_max_request_body_bytes`, protocol-version validation, and stateless-by-default —
all of which the 3.x beta ships and which this spec relies on. `transport-worker` must
be added explicitly (`LocalSessionManager` unconditionally uses `transport::worker`).
- `rmcp = { version = "=3.0.0-beta.3", optional = true, features = ["server", "macros", "transport-streamable-http-server", "transport-worker"] }`
- `aes-gcm = { version = "0.10", optional = true }` (token encryption).

**Verified integration shape** (probe at `/tmp/rmcp-probe`):
- Mount: `Router::new().nest_service("/mcp", StreamableHttpService::new(factory, LocalSessionManager::default().into(), config))`.
- Config: `StreamableHttpServerConfig::default().with_legacy_session_mode(false).with_json_response(true).with_allowed_origins([APP_BASE_URL])`.
- Auth: axum `from_fn` middleware resolves bearer → inserts `McpPrincipal{user_id,scope}` into `request.extensions_mut()`.
- Tool reads it via `Extension<http::request::Parts>` extractor → `parts.extensions.get::<McpPrincipal>()`.
- Tool result: `CallToolResult::success(vec![ContentBlock::Text(TextContent::new(s))])`.
- rmcp handles Origin→403, protocol-version 400, body-size 413 internally.

**Env vars** (document in `.env.example`):
- `MCP_TOKEN_ENC_KEY` — 32-byte AES-256 key, base64. Required when MCP is used; the
  server warns at startup if absent (tokens cannot be minted without it).

## 8. Acceptance criteria

1. `POST /mcp` with a valid `read`-scope bearer returns `tools/list` including
   `search_posts`; a `search_posts` call returns ranked published posts.
2. `resources/list` paginates published posts; `resources/read` returns one post's
   Markdown; cursor pagination round-trips.
3. A request with no/invalid/expired/revoked token is rejected (401/403).
4. A `read` token calling a `write` tool is rejected (`insufficient_scope`).
5. `write`/`admin` tokens can read drafts; `read` tokens cannot.
6. `create_post` via MCP writes a row, renders `content_html`, and invalidates the
   matching moka + SSR caches (same write-flow as the web admin).
7. Invalid `Origin` → 403; missing `MCP-Protocol-Version` → 400.
8. Admin UI lists tokens (name, scope, created, expires, last-used), reveals plaintext
   on demand, revokes, and emits copy-ready config for all 4 client formats.
9. Token DB column never stores plaintext; `token_enc` is AES-GCM ciphertext.
10. `cargo build --no-default-features --features web` compiles (WASM stubs present);
    `cargo build --no-default-features --features server` compiles;
    `cargo clippy --all-features -- -D warnings` passes.
11. `make test` (existing suite) still passes; new unit tests cover crypto, scope
    ordering, cursor pagination, and config generation (pure, DB-free).

## 9. Risks & mitigations

- **rmcp/Axum version skew** — rmcp must target axum 0.8. Verify before pinning; if
  incompatible, the fallback is a thin hand-rolled JSON-RPC-over-POST layer (larger
  effort, research says avoid). *Mitigation: spike the mount in the tracer bullet first.*
- **Indirect prompt injection** — search/snippet output reaches the model. *Mitigation:
  sanitize, separate read/write scopes, human-in-the-loop on mutating tools.*
- **Token leak = full blog takeover** — *Mitigation: encrypted-at-rest, selectable
  short lifetimes, revocation, token-keyed rate limit, Origin enforcement.*
- **WASM build breakage** — *Mitigation: every server-only symbol gets a stub; the
  tracer bullet must prove `--features web` compiles before tool flesh-out.*

## 10. Build path

Spec → tracer-bullet tickets (`/to-tickets`) → per-ticket `/implement` with cleared
context. Ticket files live under `.scratch/mcp-server/issues/`.