@event4u/agent-config 1.36.1 → 1.38.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "1.36.1"
+    "version": "1.38.0"
   },
   "plugins": [
     {

package/CHANGELOG.md

@@ -318,6 +318,83 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [1.38.0](https://github.com/event4u-app/agent-config/compare/1.37.0...1.38.0) (2026-05-11)
+
+### Features
+
+* **mcp:** add cloud setup tasks + operator README ([c5aebba](https://github.com/event4u-app/agent-config/commit/c5aebba37a608d0a41b1586acacdb055996a961d))
+* **scripts:** MCP content packer + cloud parity smoke ([e0d132a](https://github.com/event4u-app/agent-config/commit/e0d132afb487b720386bd54b68e10f1a342d6b0c))
+
+### Documentation
+
+* **readme:** surface hosted Remote MCP as zero-install option ([de6161e](https://github.com/event4u-app/agent-config/commit/de6161e3660b81a460f057bc46c1b75e6fe8693c))
+* **mcp:** add A0-cloud invariant 8 — ingress protection via edge cache + platform rate-limit ([c4b9371](https://github.com/event4u-app/agent-config/commit/c4b9371da2db55958bca29a7d10291626d13782f))
+* **mcp:** drop archived-roadmap refs from stable contracts ([15418de](https://github.com/event4u-app/agent-config/commit/15418de5a65c3cd5968bbeecc20ed5ad5c4a4958))
+* **mcp:** surface experimental hosted-MCP channel ([cecae08](https://github.com/event4u-app/agent-config/commit/cecae08ad647c7e28931e7328047fdef5ca3d3a3))
+* **setup:** MCP cloud endpoints, R2 bootstrap, registry listing ([7cb3341](https://github.com/event4u-app/agent-config/commit/7cb334110ff940d3703ada013ef5163c899d96b2))
+* **mcp:** add A0-cloud contract + cross-links (Phase 1 of cloudflare-mcp-hosting) ([2fc5084](https://github.com/event4u-app/agent-config/commit/2fc50845c3b194e861b54f82c852ba4bb9fc406a))
+* **roadmap:** add Cloudflare-hosted MCP roadmap, archive distribution ([fd1c437](https://github.com/event4u-app/agent-config/commit/fd1c437ea8a918eebc8604ee7958d8c842c7aac8))
+
+### CI
+
+* **deploy-mcp-worker:** release-tag triggered Worker deploy ([4297514](https://github.com/event4u-app/agent-config/commit/4297514b80457852511ad90674f4d633a75a92bf))
+
+### Chores
+
+* **linter:** raise README overloaded threshold to 750 lines ([1e3fbb7](https://github.com/event4u-app/agent-config/commit/1e3fbb7c649398ba56bc32677c7b588131f7e949))
+* **mcp:** mark dev content.json stub with explanatory _comment ([8f6c7ff](https://github.com/event4u-app/agent-config/commit/8f6c7ffe493b72ccb2d0ec66121a9d32d0b2fe8c))
+* **roadmap:** archive road-to-cloudflare-mcp-hosting (100% complete) ([99e07f9](https://github.com/event4u-app/agent-config/commit/99e07f92293e62841ff87f315e41c5ceabd7b277))
+* **workers/mcp:** scaffold TypeScript Cloudflare Worker ([447e071](https://github.com/event4u-app/agent-config/commit/447e071984f86fc084058d05f22d0e0a7c936a5e))
+
+Tests: 2679 (+0 since 1.37.0)
+
+## [1.37.0](https://github.com/event4u-app/agent-config/compare/1.36.1...1.37.0) (2026-05-10)
+
+### Features
+
+* **mcp:** add Phase 6 F3 stdio Docker bundle ([acd5e47](https://github.com/event4u-app/agent-config/commit/acd5e47a56b9fb42f57751771087c6b73759d3d5))
+* **mcp:** add Phase 6 F1 identity metadata ([f4700ff](https://github.com/event4u-app/agent-config/commit/f4700ff1f093611220c08fba75c29d12ed57110c))
+* **mcp:** add Phase 4 tool layer with lint_skills and chat_history_append ([fe02108](https://github.com/event4u-app/agent-config/commit/fe0210817e46f4d1710b0d96b7a176c872fc5545))
+* **cli:** expose mcp:setup + mcp:run via ./agent-config ([bf7ff65](https://github.com/event4u-app/agent-config/commit/bf7ff65ab040b482d5f4e716a78148e95ba3bc7f))
+* **mcp:** expose rules, guidelines, contexts as resources ([21d85c5](https://github.com/event4u-app/agent-config/commit/21d85c5142a35dade1129f835821c72944442ead))
+* **mcp:** full skill + command coverage with pagination + hot-reload ([126c976](https://github.com/event4u-app/agent-config/commit/126c976f30e7bf3b714f8b72131b53fcc3e07878))
+* **mcp:** add experimental stdio MCP server exposing 5 stack-agnostic skills ([8e692cf](https://github.com/event4u-app/agent-config/commit/8e692cfbdc14e67f178b11068773d50dd199b4ab))
+
+### Bug Fixes
+
+* **agents-md:** revert MCP pointer to keep root under 3000-char cap ([02bed8e](https://github.com/event4u-app/agent-config/commit/02bed8edb13fdcae369bac3843a836c01dc04248))
+* **lint:** emit valid JSON when no skill/rule files changed ([caef1cb](https://github.com/event4u-app/agent-config/commit/caef1cb91def6089cad3ba3d2fd7c728b39731d0))
+* **mcp:** relocate Phase 1 smoke transcript out of agents/roadmaps/ ([addd7c2](https://github.com/event4u-app/agent-config/commit/addd7c2ac4aa7a6527fb9e750ed38d02f1cd51bc))
+* **mcp:** drop roadmap link from Phase 1 scope contract ([ca3c2e8](https://github.com/event4u-app/agent-config/commit/ca3c2e89b6c5ebf06cbc6a55883cf3cf1fbd015a))
+
+### Documentation
+
+* **contracts:** amend MCP scope contract for Phase 6 F1 + F3 ([45989c5](https://github.com/event4u-app/agent-config/commit/45989c53d6c9b361ad29b4214984db6cff8f5b5f))
+* **contracts:** amend MCP scope contract for Phase 4 tool allowlist ([87c9622](https://github.com/event4u-app/agent-config/commit/87c9622d165d783a5b1f8c266035791cafbf3ab9))
+* **roadmap:** mark MCP Phase 3 + Phase 5 done ([9ec9494](https://github.com/event4u-app/agent-config/commit/9ec9494be18b6634dcf4383af921b54f283c86ff))
+* **mcp:** canonical MCP server setup guide ([4fd149f](https://github.com/event4u-app/agent-config/commit/4fd149f0b1c6e6b009d2bdd3b4ea80759e31055d))
+* **roadmap:** mark MCP Phase 2 (B1-B5) done + extend scope contract ([5ea1c56](https://github.com/event4u-app/agent-config/commit/5ea1c56d027f432f9c950e8b35805ab91758fd26))
+* **roadmap:** mark MCP Phase 1 (A1–A7) done + record stdio smoke transcript ([aaf8332](https://github.com/event4u-app/agent-config/commit/aaf833292aba530bdeae138fa2255b4576fe699c))
+* **mcp:** add Phase 1 scope contract (experimental, read-only) ([2fa275e](https://github.com/event4u-app/agent-config/commit/2fa275eec70c02741b76abef2b6356c7d0d1c6a7))
+
+### Tests
+
+* **mcp:** cover Phase 6 F1 identity metadata ([d3f79ef](https://github.com/event4u-app/agent-config/commit/d3f79eff30f61914fe09667693b41e2ed8c29855))
+* **mcp:** cover Phase 4 tool layer ([217c4ab](https://github.com/event4u-app/agent-config/commit/217c4ab2ed1041006e1ac3102369b8c1569f3653))
+* **mcp:** cover Phase 2 — full coverage, pagination, hot-reload ([f93c019](https://github.com/event4u-app/agent-config/commit/f93c0199adc558119be614fadd677cf37c8c2d5a))
+* **mcp:** make loader tests run when mcp SDK is absent ([8378621](https://github.com/event4u-app/agent-config/commit/8378621be8ec24ccba59be10c49a4384abdc335f))
+* **mcp:** cover Phase 1 loader + import-surface guard + server handlers ([f4fee8b](https://github.com/event4u-app/agent-config/commit/f4fee8b899b0163ea2bfe7099ffa9221b70bf488))
+
+### Chores
+
+* **roadmap:** close road-to-mcp-server at 100%, defer F4 to distribution ([0127991](https://github.com/event4u-app/agent-config/commit/01279913f3b2a5caa1eb65f8a7b07a2f841d41af))
+* **roadmap:** defer Phase 6 F2 to road-to-mcp-distribution ([b5e0be7](https://github.com/event4u-app/agent-config/commit/b5e0be7473296bfd5381dc1ace9bc99ae79f5090))
+* **roadmap:** mark MCP Phase 4 (D1-D4) complete ([8c342c8](https://github.com/event4u-app/agent-config/commit/8c342c8508f17133d71528b16d727d5c3c56acfd))
+* **mcp:** add task mcp:setup for one-line install ([ae1f6f9](https://github.com/event4u-app/agent-config/commit/ae1f6f9d355dd5a782fdadb5e67929552caab5ed))
+* ignore .venv-mcp/ for MCP server work ([8bd44d4](https://github.com/event4u-app/agent-config/commit/8bd44d49e359021a000a989bfd7ae7f6f48800db))
+
+Tests: 2679 (+58 since 1.36.1)
+
 ## [1.36.1](https://github.com/event4u-app/agent-config/compare/1.36.0...1.36.1) (2026-05-10)
 
 ### Refactoring

package/README.md

@@ -90,6 +90,30 @@ Install directly in your agent for global, cross-project use:
 → [Full getting started guide](docs/getting-started.md) ·
 [More examples & expected behavior](docs/showcase.md)
 
+### Remote MCP — zero install
+
+Skills, commands, rules, and guidelines are also served as a hosted MCP
+endpoint. No clone, no `task mcp:setup`, no Python venv — point any
+MCP-capable client (Claude Desktop, Cursor, Zed, Continue, hosted agents)
+at:
+
+```
+https://agent-config-mcp.event4u.workers.dev
+```
+
+Verify it's live:
+
+```bash
+curl https://agent-config-mcp.event4u.workers.dev
+# → { "ok": true, "name": "agent-config-mcp", "release_key": "v…", … }
+```
+
+Read-only, identity-stable per release. Client config snippets and URL
+shapes (latest vs. pinned `/v<X.Y.Z>`) live in
+[`docs/setup/mcp-cloud-endpoints.md`](docs/setup/mcp-cloud-endpoints.md).
+Operator setup (account, R2, secrets) — [`docs/setup/mcp-cloud-setup.md`](docs/setup/mcp-cloud-setup.md).
+Experimental — A0-cloud contract in [`docs/contracts/mcp-cloud-scope.md`](docs/contracts/mcp-cloud-scope.md).
+
 ### Optional: persistent agent memory
 
 `agent-config` integrates with [`@event4u/agent-memory`](https://www.npmjs.com/package/@event4u/agent-memory)
@@ -109,7 +133,7 @@ Install in the same project (dev-only):
 npm install --save-dev @event4u/agent-memory
 ```
 
-→ [Memory contract & retrieval API](docs/contracts/agent-memory-contract.md) (beta)
+→ [Memory contract & retrieval API](docs/contracts/agent-memory-contract.md) (beta) · [Built-in MCP server](docs/mcp-server.md) (experimental — local stdio access from Claude Desktop / Cursor / Zed / Continue, install with `task mcp:setup`)
 
 ---
 

package/docs/contracts/mcp-cloud-scope.md

@@ -0,0 +1,182 @@
+---
+stability: experimental
+---
+
+# MCP Server — Cloud Scope (A0-cloud Hard Contract)
+
+> **Status:** Active · covers `workers/mcp/` (TypeScript Cloudflare
+> Worker bridge), MVP-1 surface. Extends — does **not** supersede —
+> [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md), which retains
+> exclusive ownership of `scripts/mcp_server/` (local stdio).
+> **Stability:** experimental — not linked from README, AGENTS.md, or
+> `docs/architecture.md`. Internal index reference only per `STABILITY.md`.
+
+## Purpose
+
+Locks the **execution-safety boundary** for the hosted MCP Worker. Any
+code under `workers/mcp/` must satisfy this contract verbatim. The
+local stdio kernel and the hosted Worker are two distinct surfaces; a
+deviation in one is **not** authorized by a precedent in the other.
+
+The Worker IS the bridge described in
+[`mcp-request-signing § Appendix`](../guidelines/agent-infra/mcp-request-signing.md#appendix--http-bridge-stdio-kernel-pattern-reference)
+— but with two material differences from the appendix pattern: (1) no
+spawned stdio child (content is read from a release-pinned R2 blob,
+not a sub-process), and (2) no HMAC for MVP-1 (content is OSS and
+read-only; the appendix pattern's `verifyRequest` is deferred to MVP-2
+alongside auth).
+
+## In-scope (MVP-1)
+
+- **Transport:** HTTP + SSE (Cloudflare Worker `fetch` handler). The
+  local stdio kernel is out-of-scope for this contract and stays
+  governed by `mcp-phase-1-scope.md`.
+- **MCP primitives:** `prompts/list` + `prompts/get` + `resources/list`
+  + `resources/read` — read-only, parity with the local stdio surface.
+- **Source data:** release-pinned content blob in R2 under the key
+  shape `releases/v<X.Y.Z>-<sha>/` (immutable per release). The blob
+  bundles `.agent-src/skills/<name>/SKILL.md`,
+  `.agent-src/commands/**/*.md`, and `docs/guidelines/` (the same
+  projection the local kernel reads). Never reads `.agent-src.uncompressed/`.
+- **Identity surface:** `serverInfo.version` reads from a Worker-
+  bundled constant, `_meta.packageVersion` reads from a
+  `wrangler.toml` env var, `_meta.skillSetSignature` reads from a
+  **prebaked manifest JSON** shipped with the content blob. The
+  Worker never computes the signature at runtime.
+- **URL shape:** two pinned shapes only —
+  `mcp.<host>/v<X.Y.Z>/sse` (immutable, cache TTL 1 h) and
+  `mcp.<host>/latest/sse` (pointer, cache TTL 5 min). The `latest`
+  pointer is repointed atomically by the release pipeline after a
+  green smoke run; pre-smoke failures leave it on the previous
+  release.
+- **Pagination + hot-reload parity:** `prompts/list` paginates with
+  `nextCursor` the same way the stdio kernel does; the Worker has no
+  hot-reload because the content blob is immutable per release —
+  the **release** is the cache-bust event.
+- **Deprecated tool stubs:** `tools/list` returns exactly two entries,
+  `lint_skills` and `chat_history_append`, both with
+  `deprecated: true` and a description pointing to the local stdio
+  server. `tools/call` against either returns `isError=true` with a
+  message naming the local-stdio successor. No other tool name is
+  reachable.
+
+## Out-of-scope (MVP-1)
+
+- **Tool execution.** `lint_skills` and `chat_history_append` are
+  exposed as deprecated stubs only — no TS port, no FS access, no
+  shell, no Python runtime in the Worker. Restoration is the
+  Phase-7-DEFERRED block of the roadmap, gated on a real consumer ask
+  plus a multi-tenant security review.
+- **`.agent-settings.yml` exposure.** Consumer-machine config, never
+  surfaced as a resource. The Worker has no access to consumer FS at
+  any layer.
+- **Agent memory** — separate MCP server, different roadmap.
+- **Chat history persistence** — the local kernel writes to
+  `agents/.agent-chat-history`; the Worker has no equivalent. Listed
+  as a deprecated stub per above.
+- **Authentication / multi-tenancy.** MVP-1 is open (OSS content,
+  read-only). Bearer / CF Access / HMAC moves to MVP-2 alongside
+  tool restoration.
+- **Network egress from the Worker** beyond an **explicit subrequest
+  allowlist** — see invariants below.
+
+## A0-cloud invariants
+
+The Worker code must satisfy all of:
+
+1. **Origin allowlist** — `fetch()` calls from the Worker are limited
+   to R2 (content read) and an explicit observability sink (optional).
+   No calls to consumer infrastructure, no calls to upstream LLM
+   APIs, no calls to `api.github.com`, no DNS-based egress. Enforced
+   in `wrangler.toml` via Worker-level network policies.
+2. **R2 write boundary** — the Worker never writes to R2. The release
+   pipeline writes under `releases/v<X.Y.Z>-<sha>/` and atomically
+   repoints `releases/latest.txt`; the Worker only reads.
+3. **Per-versioned-URL immutability** — for any
+   `mcp.<host>/v<X.Y.Z>/sse`, the response body is deterministic for
+   the lifetime of the deployment. Patch fixes ship a new version key;
+   the existing key is never rewritten. R2 eventual consistency is
+   handled by the unique-key-per-release shape.
+4. **Cache-TTL policy** — pinned URLs cache at the edge for 1 h
+   (safe because immutable); `latest` caches for 5 min (bounded
+   staleness window after a repoint). No client may rely on `latest`
+   for reproducibility — that is what the pinned URL is for.
+5. **Prebaked signature** — `skillSetSignature` is computed once by
+   the release pipeline against the worktree at the tag and stored in
+   `releases/v<X.Y.Z>-<sha>/manifest.json`. The Worker reads, never
+   computes. Any signature drift at runtime is a contract violation.
+6. **No consumer code execution.** No `eval`, no dynamic import of
+   content, no shelling out, no spawning a runtime. The Worker is a
+   read-and-route function.
+7. **Single deployment per release.** One `wrangler deploy` per tag.
+   Concurrent deployments are not supported; the release pipeline
+   serializes through `release: published` + `workflow_dispatch`
+   hotfix paths.
+8. **Ingress protection = edge cache + platform rate limit.** MVP-1
+   is auth-less by design; the public surface is shielded by two
+   layers Cloudflare provides without code: (a) edge caching per
+   invariant 4 (1 h on pinned URLs, 5 min on `latest`) absorbs
+   read-loop traffic before it reaches the Worker, and (b)
+   Cloudflare's account-level anti-abuse + DDoS shielding caps
+   per-IP burst on `*.workers.dev`. These two together **are** the
+   MVP-1 auth surrogate. **Promotion triggers** — any of these
+   flips HMAC (currently MVP-2 §Out-of-scope) from deferred to
+   active before the wake-up triggers below would otherwise fire:
+   sustained 429 spikes from origin (cache miss storm), Workers
+   request-cost line item exceeding the free-tier budget for two
+   consecutive billing periods, or a CVE-class abuse report
+   against the endpoint. A per-Worker `[[unsafe.bindings]]`
+   rate-limiter in `wrangler.toml` is **not** configured in MVP-1
+   — adding one is a contract amendment, not a free hand.
+
+## Deprecated tool stub contract
+
+`tools/list` returns:
+
+```json
+[
+  {
+    "name": "lint_skills",
+    "description": "Deprecated on hosted MCP — use the local stdio server (scripts/mcp_server/) which retains this tool. See road-to-cloudflare-mcp-hosting Phase 7 for restoration triggers.",
+    "deprecated": true
+  },
+  {
+    "name": "chat_history_append",
+    "description": "Deprecated on hosted MCP — filesystem-bound, local-only. Use the local stdio server.",
+    "deprecated": true
+  }
+]
+```
+
+`tools/call` against either name returns `isError=true` with the same
+deprecation message. No other tool name is reachable.
+
+## MVP-2 wake-up triggers
+
+The Phase-7 deferred items in the roadmap (tool restoration, history
+persistence, auth) wake up only when **all** of these fire:
+
+- A named consumer (internal or external) requests hosted lint or
+  history.
+- A security review has approved the validation layer for
+  `lint_skills` (URI regex allowlist, size limits, timeout,
+  concurrency cap).
+- An auth model has been selected (bearer vs. CF Access vs. HMAC).
+- The server stability label has been promoted from *experimental*
+  to *beta*.
+
+## Revision policy
+
+This contract is **experimental** — breaking changes are allowed in
+any release with a CHANGELOG note. Promotion to `beta` requires at
+least one shipped client connecting to the hosted endpoint end-to-end
+without a contract amendment.
+
+## See also
+
+- [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md) — local-stdio kernel
+  contract (sibling, not parent).
+- [`STABILITY.md`](../../STABILITY.md) — stability policy for
+  `docs/contracts/`.
+- [`mcp-request-signing § Appendix`](../guidelines/agent-infra/mcp-request-signing.md#appendix--http-bridge-stdio-kernel-pattern-reference)
+  — bridge pattern reference (the Worker is a flavor of this).

package/docs/contracts/mcp-phase-1-scope.md

@@ -0,0 +1,195 @@
+---
+stability: experimental
+---
+
+# MCP Server — Phase 1–6 Scope (A0 Hard Contract)
+
+> **Status:** Active · covers Phase 1 (A1–A7) + Phase 2 (B1–B5) +
+> Phase 3 (C1–C4) + Phase 4 (D1–D4) + Phase 6 F1/F3 of
+> `road-to-mcp-server.md`. Phase 6 F2 (SSE transport) is owned by
+> [`mcp-cloud-scope.md`](mcp-cloud-scope.md) — the hosted Cloudflare
+> Worker bridge — and remains out of scope here. This contract retains
+> exclusive ownership of `scripts/mcp_server/` (local stdio).
+> **Stability:** experimental — not linked from README, AGENTS.md, or
+> `docs/architecture.md`. Internal index reference only per `STABILITY.md`.
+
+## Purpose
+
+Locks the **execution-safety boundary** for the MCP server through
+Phase 2. Any code under `scripts/mcp_server/` must satisfy this
+contract verbatim. Deviation → not Phase 1/2; promote to a follow-up
+phase with its own design-call gate.
+
+## In-scope (Phase 1 + Phase 2)
+
+- Transport: **stdio**. No SSE, no HTTP, no WebSocket.
+- MCP primitives: **`prompts/list`** + **`prompts/get`** — read-only.
+- Source data: **`.agent-src/skills/<name>/SKILL.md`** and
+  **`.agent-src/commands/**/*.md`** (compressed projections, never the
+  uncompressed source-of-truth tree).
+- Loaded set (Phase 2): every well-formed skill + command under
+  `.agent-src/` (Phase 1 hand-picked set retained as a smoke fixture
+  in `prompts.py::PHASE_1_SKILLS`).
+- **Pagination** (B4): cursor-based `nextCursor` on `prompts/list`,
+  default `page_size=100`. Cursor is an opaque stringified offset.
+- **Hot-reload** (B5): `PromptCache` re-scans on mtime / path-set
+  change before each `prompts/list` response. No background thread,
+  no inotify, no debounce — the request itself is the rate-limiter.
+- **Frontmatter validation** (B3): entries missing `name` or
+  `description` are skipped with a stderr warning at boot; malformed
+  files do not crash the server.
+- Process lifetime: one server per project, launched per-client by the
+  consumer (Claude Desktop, Zed, Continue) at MCP-config time.
+
+## Out-of-scope (Phase 1 + Phase 2)
+
+- **`tools/*` beyond the Phase 4 allowlist** — only the two
+  built-in tools listed below in *Phase 4 amendment* are reachable.
+  Any other name raises `ValueError`. `work_engine` is not exposed.
+- **`resources/*` beyond rules / guidelines / contexts** — no model
+  outputs, no roadmaps, no chat history surfaced as resources.
+- **Filesystem writes outside the Phase 4 write allowlist** — the only
+  writable targets are `agents/.agent-chat-history` and
+  `.agent-chat-history` under `<consumer_root>`. No log files, no
+  telemetry writes, no `.work-state.json` mutation.
+- **Direct shell execution from `mcp_server/*`** — modules under
+  `scripts/mcp_server/` do not `import subprocess`, `os.system`, or
+  `os.popen` directly. Project helpers that internally spawn shells
+  (`skill_linter`'s `--changed` git mode, etc.) may be called only via
+  read-only wrappers that bypass those code paths.
+- **Network egress** — the server does not call external APIs;
+  the AI Council, anthropic SDK, and openai SDK are not imported by
+  any module under `scripts/mcp_server/`.
+- **Authentication / multi-tenancy** — single-process, single-project.
+  Multi-tenant SSE is Phase 6 (F2).
+
+## Static guarantees enforced by tests
+
+`tests/test_mcp_server.py` asserts the boundary at unit level:
+
+1. `prompts/list` returns the full skills + commands set with
+   `skill.<name>` and `command.<name>` wire-name prefixes.
+2. `prompts/get` returns a non-empty `messages[].content.text` body
+   matching the SKILL.md / command-file body (frontmatter stripped).
+3. `prompts/get` for an unknown name raises `ValueError` (no silent
+   fallback to filesystem scan).
+4. `scripts.mcp_server.prompts` imports cleanly without `subprocess`,
+   `os.system`, `os.popen`, or any `requests` / `httpx` call.
+5. `prompts/list` paginates with `nextCursor` and pages do not
+   overlap.
+6. `PromptCache` re-scans on mtime change (hot-reload).
+7. Malformed frontmatter is skipped with an error line, not crashed.
+
+A future regression that adds a `tools/*` handler outside the
+allowlist or writes outside the Phase 4 write allowlist fails the
+import-surface + behaviour assertions and the contract review in code
+review.
+
+## Phase 4 amendment — tool allowlist (D1–D4)
+
+Phase 4 lifts the read-only line for **exactly** the two built-in
+tools registered in `scripts/mcp_server/tools.py::ALLOWLIST`. Every
+other tool name is unreachable: `tools/call` against an unlisted name
+returns `isError=True`.
+
+| Tool name | Mode | Side effects |
+|---|---|---|
+| `lint_skills` | read-only | Wraps `scripts.skill_linter.lint_file`. Never spawns `git` (no `--changed`). Returns the same JSON shape as `scripts/skill_linter.py --format json`. |
+| `chat_history_append` | path-scoped write | Wraps `scripts.chat_history.append`. Writes are allowed only when the resolved target is `agents/.agent-chat-history` or `.agent-chat-history` under `<consumer_root>`. `dry_run=True` validates the payload without touching the filesystem. |
+
+**Path-scoping invariant** — any tool that writes must resolve its
+target through `_validate_in_tree_path` before the underlying writer
+runs. Escapes (absolute paths outside the root, relative paths that
+resolve outside, or filenames not in the write allowlist) raise
+`ValueError` and surface as `isError=True` in `tools/call`.
+
+**Boot-time enumeration** — `run_stdio` prints one stderr line
+listing the registered tool names so operators see the surface at
+launch. Adding a tool to `ALLOWLIST` is a code-review event; no
+settings flag can enable an unlisted tool.
+
+Additional tool tests in `tests/test_mcp_server.py`:
+
+8. `tools/list` returns exactly the allowlisted names.
+9. `tools/call` against a valid `dry_run` payload returns
+   `isError=False` with a JSON-serialized result.
+10. `tools/call` with a path escape returns `isError=True` referencing
+    the escape — no exception propagates past the handler.
+11. `tools/call` against an unknown tool name returns `isError=True`.
+12. `scripts.mcp_server.tools` does not import `subprocess`,
+    `os.system`, `os.popen`, or any HTTP client directly.
+
+## Phase 6 amendment — identity metadata + Docker bundle (F1, F3)
+
+Phase 6 adds **observability** and **packaging** without changing the
+A0 wire surface. F2 (SSE transport) is explicitly deferred — see
+status header.
+
+### F1 — Identity metadata
+
+Three values surface at server boot, written to **stderr** in a single
+`mcp-server: identity …` line (the canonical surface — the high-level
+MCP SDK builds `serverInfo` with a fixed field set, so wire-surface
+lift waits on SDK support):
+
+- **`serverVersion`** — hand-maintained SemVer in
+  `scripts/mcp_server/__init__.py::__version__`. Bumps on
+  **wire-surface** changes only: new tool, new resource MIME type,
+  protocol-level break. Does **not** bump for content edits inside
+  `.agent-src/`.
+- **`packageVersion`** — read from `package.json::version` at boot.
+  Bumps on every agent-config bundle release; build-ID semantics, not
+  a stability signal.
+- **`skillSetSignature`** — first 12 hex chars of the SHA-256 over the
+  joined sorted `(path, mtime)` tuples of `PromptCache` and
+  `ResourceCache`. **Not a version** — a content fingerprint. Auto-
+  updates with every `task sync`; intended for cache-key /
+  reproducibility use, never for SemVer-style compatibility claims.
+
+Implementation: `scripts/mcp_server/metadata.py`. The signature is
+deterministic for a given snapshot of the loaded file set; any mtime
+change invalidates it.
+
+### F3 — Stdio Docker bundle
+
+`docker/mcp-server/Dockerfile` ships a stdio-only image. The contract:
+
+- **No HTTP / SSE listener** in the image. Stdio is the only wire.
+- The image embeds `scripts/mcp_server/`, the two tool dependencies
+  (`scripts/skill_linter.py`, `scripts/chat_history.py`),
+  `.agent-src/`, `docs/guidelines/`, and `package.json`. Nothing
+  outside the COPY-listed paths reaches the runtime stage.
+- The image runs as a non-root user (`mcp:mcp`); host volumes mounted
+  for `chat_history_append` writes must be writable by that uid/gid.
+- The A0 contract from Phase 1–4 transfers verbatim — the import-
+  surface guard tests run identically inside and outside the image.
+
+Operator documentation: `docs/setup/mcp-server-docker.md`. The image
+does not introduce a new tool, resource type, or protocol surface.
+
+### What Phase 6 explicitly does **not** add
+
+- **No HTTP/SSE transport**, native or otherwise. F2 is deferred to
+  the successor roadmap; revival is gated on a real consumer ask, and
+  the locked design is the bridge pattern from
+  [`mcp-request-signing § Appendix`](../guidelines/agent-infra/mcp-request-signing.md#appendix--http-bridge-stdio-kernel-pattern-reference)
+  — never a native SSE server inside `scripts/mcp_server/`.
+- **No new tools** beyond the Phase 4 allowlist.
+- **No multi-tenancy** — the Docker image is single-tenant, one
+  process per stdio session. Multi-tenancy lives with the future
+  bridge, not the kernel.
+
+## Revision policy
+
+This contract is **experimental** — breaking changes are allowed in any
+release with a CHANGELOG note. Promotion to `beta` follows the same
+gate as Phase 1 itself: at least one shipped client renders Phase 1
+prompts end-to-end without a contract amendment.
+
+## See also
+
+- [`mcp-cloud-scope.md`](mcp-cloud-scope.md) — hosted Worker contract
+  (sibling, not child). Extends the bridge pattern from
+  [`mcp-request-signing § Appendix`](../guidelines/agent-infra/mcp-request-signing.md#appendix--http-bridge-stdio-kernel-pattern-reference)
+  for multi-tenant SSE.
+- [`STABILITY.md`](STABILITY.md) — stability policy for `docs/contracts/`.

package/docs/guidelines/agent-infra/mcp-request-signing.md

@@ -194,3 +194,7 @@ out-of-scope until a consumer surfaces a tenancy requirement.
   starts here; the upstream link is the authoritative source.
 - `road-to-ruflo-adoption.md` **P2.1** — landed this appendix; full
   bridge fork stays out-of-scope unless the dual trigger fires.
+- [`mcp-cloud-scope.md`](../../contracts/mcp-cloud-scope.md) —
+  operationalizes this pattern as a TypeScript Cloudflare Worker (no
+  spawned stdio child; R2 blob replaces the child process). HMAC
+  `verifyRequest` is deferred to MVP-2 alongside auth.