@event4u/agent-config 1.36.0 → 1.37.0

package/.agent-src/contexts/authority/scope-mechanics.md

@@ -5,8 +5,9 @@ detail behind the Hard Floor restatement, the brief-before-asking
 flow for separate-branch proposals, and the failure modes / bypass
 rules around fenced steps.
 
-**Size budget:** ≤ 4,000 chars. Tracked under Phase 6 of
-`road-to-pr-34-followups`.
+**Size budget:** soft cap ≤ 8,000 chars (context layer, on-demand
+loaded). The mechanics file absorbs growth so `scope-control` stays
+under the 4,000-char kernel ceiling.
 
 ## Production, infrastructure, bulk-destructive — Hard Floor
 
@@ -40,6 +41,23 @@ permission is per-operation, this-turn. Standing autonomy directives
 narrow other rules but never grant permission for items in this Hard
 Floor subset.
 
+## Roadmap shape — no release language
+
+Forbidden in roadmaps / plans / tickets / any planning artifact:
+version numbers (`v2.0`, `1.4.x`), target releases (`Q4 release`,
+`Sprint 23`), deprecation dates tied to release calendars,
+release-tied milestones (`launch milestone`, `GA`), and git tags
+(`tag v1.2.0`).
+
+Roadmaps plan **work**. Releases / tags / version pins are a
+**separate decision** the user pins explicitly on the artifact that
+owns release shape — changelog, release PR, tag annotation — not
+buried inside a planning document. Authoring verbs (`create / draft /
+write the roadmap`) authorize the planning artifact, not version
+pinning inside it. If the user names a version in a planning
+request, ask whether the artifact tracks the work or the release;
+default to work.
+
 ## Brief-before-asking — separate branch / PR / worktree
 
 If a task seems to need a separate branch or PR (spike, hotfix,

package/.agent-src/rules/scope-control.md

@@ -28,7 +28,7 @@ The user decides the git shape. Never improvise. Commit specifics: canonical [`c
 - NEVER create / switch / delete a branch without explicit permission — includes spike, scratch, throwaway, worktree branches.
 - NEVER create, close, reopen, or change the target of a pull request without permission.
 - NEVER push a tag or create a release without permission.
-- NEVER include version numbers, target releases, deprecation dates, release-tied milestones, or git tags in roadmaps, plans, tickets, or any planning artifact. Roadmaps plan **work**; releases / tags are a separate decision. User pins by saying so explicitly.
+- NEVER pin versions, release targets, deprecation dates, or git tags in roadmaps / plans / tickets — they plan **work**, not releases. Detail: [`scope-mechanics § Roadmap shape`](../contexts/authority/scope-mechanics.md).
 - Task seems to need a separate branch / PR → STOP and **brief before asking** ([`scope-mechanics § Brief-before-asking`](../contexts/authority/scope-mechanics.md)).
 - BEFORE the first commit on related work, **inventory** existing branches and open PRs. Plausible base beyond the current branch → STOP and ask with numbered options — never improvise. Commands + 4-option template + diverging-stack failure mode: [`scope-mechanics § Branch-base inventory`](../contexts/authority/scope-mechanics.md).
 
@@ -49,7 +49,7 @@ A subset is **never** autonomous, regardless of standing autonomy. Canonical: [`
 
 ## Kernel-rule edits — slow-rollout guarantee
 
-Each kernel-rule edit ships in **its own PR**, ≥ 24 h between merges. Autonomous mandate does NOT lift this — soak guarantee, not preference. CI fails > 1 kernel rule per PR unless labeled `bundled-always-rules-acknowledged`. Trigger / scope: [`kernel-rule-edits`](../contexts/authority/kernel-rule-edits.md).
+Own PR, ≥ 24 h between merges. Autonomous mandate does not lift — soak guarantee. CI / labels / scope: [`kernel-rule-edits`](../contexts/authority/kernel-rule-edits.md).
 
 ## Decline = silence — no re-asking on the same task
 
@@ -57,11 +57,9 @@ After the user **declines** a proposal (branch switch, PR creation, tag/release,
 
 ## Fenced step — user-set review gates
 
-User fences next step (*"plan only"*, *"review first"*, German equivalents) → reply is **deliverable + handoff**, never *"shall we start?"*.
-
 ```
 USER FENCED OFF EXECUTION → DELIVER + HAND BACK.
 NO "READY TO IMPLEMENT?" / "PHASE 1?" RE-ASK.
 ```
 
-Fence stands until reopened (like `Decline = silence`). Follow-ups cover **the deliverable**, never its execution. Failure modes + bypass: [`scope-mechanics § Fenced step`](../contexts/authority/scope-mechanics.md).
+Fence (*"plan only"*, *"review first"*, German equivalents) stands until reopened — like `Decline = silence`. Follow-ups cover the deliverable, not its execution. Failure modes + bypass: [`scope-mechanics § Fenced step`](../contexts/authority/scope-mechanics.md).

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.0"
+    "version": "1.37.0"
   },
   "plugins": [
     {

package/CHANGELOG.md

@@ -318,6 +318,65 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [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
+
+* **scope-control:** extract roadmap-shape, kernel-rule-edits, fenced-step detail to scope-mechanics ([e52c834](https://github.com/event4u-app/agent-config/commit/e52c834a672e6f24b1b7c1608e481b7f45a46054))
+
+### Chores
+
+* **generate-tools:** regenerate .windsurfrules for scope-control extraction ([ee7664e](https://github.com/event4u-app/agent-config/commit/ee7664ee6cd0ec5aacdf95b5e4ec1000e01a0121))
+
+Tests: 2621 (+0 since 1.36.0)
+
 ## [1.36.0](https://github.com/event4u-app/agent-config/compare/1.35.0...1.36.0) (2026-05-10)
 
 ### Features

package/README.md

@@ -109,7 +109,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 — read-only access from Claude Desktop / Cursor / Zed / Continue, install with `task mcp:setup`)
 
 ---
 

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

@@ -0,0 +1,190 @@
+---
+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 deferred to
+> [`road-to-mcp-distribution.md`](../../agents/roadmaps/road-to-mcp-distribution.md)
+> and remains out of scope here.
+> **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
+
+- [`STABILITY.md`](STABILITY.md) — stability policy for `docs/contracts/`.

package/docs/mcp-server.md

@@ -0,0 +1,156 @@
+# MCP Server
+
+> Status: **experimental** — Phase 1 + 2 + 3 shipped. No `tools/*` primitive yet (Phase 4, deferred behind a design call).
+
+`agent-config` ships a built-in [Model Context Protocol](https://modelcontextprotocol.io)
+server that exposes the package's read-only governance surface to MCP-aware
+clients (Claude Desktop, Cursor, Zed, Continue, Codex via MCP). Two channels
+coexist:
+
+- **File projection** — `task generate-tools` writes `.claude/`, `.cursor/`,
+  `.clinerules/`, `.windsurfrules`. Used by Aider, Cline, Windsurf, Gemini CLI.
+- **MCP server** — `scripts/mcp_server/` exposes the same content over
+  JSON-RPC. Used by clients that speak MCP natively.
+
+The MCP server **never executes engine code, never writes files, never spawns
+shells**. It is a read-only instructional surface — see
+[`docs/contracts/mcp-phase-1-scope.md`](contracts/mcp-phase-1-scope.md).
+
+## What the server exposes
+
+| Primitive | URIs | Source | Count (this package) |
+|---|---|---|---|
+| `prompts/list` + `prompts/get` | `skill.<name>`, `command.<name>` | `.agent-src/skills/`, `.agent-src/commands/` | 174 skills + 104 commands |
+| `resources/list` + `resources/read` | `rule://<stem>` | `.agent-src/rules/` | 60 rules |
+| ↳ | `guideline://<relpath>` | `docs/guidelines/` | 69 guidelines |
+| ↳ | `context://<relpath>` | `.agent-src/contexts/` | 31 contexts |
+
+All resources are served with `mimeType: text/markdown`. Pagination is
+cursor-based (default page size: 100). Hot-reload triggers automatically on
+file mtime changes — edit a rule, reissue `resources/list`, see the update.
+
+## Setup — one-line install
+
+```bash
+task mcp:setup            # maintainer / dev repo
+./agent-config mcp:setup  # consumer projects (uses the package CLI wrapper)
+```
+
+Either form creates `.venv-mcp/` (Python 3.11+), installs the `mcp` SDK, and
+prints the client config snippet. Run once per checkout.
+
+If you do not have `task` or the CLI wrapper available:
+
+```bash
+bash scripts/mcp_setup.sh
+```
+
+## Running the server
+
+```bash
+task mcp:run            # maintainer / dev repo
+./agent-config mcp:run  # consumer projects
+```
+
+Both forms launch `python -m scripts.mcp_server` over stdio against the
+local `.venv-mcp/`. Use these for ad-hoc smoke tests; long-running clients
+(Claude Desktop, Cursor, Zed, Continue) launch the server themselves via
+the config snippets below.
+
+## Client configuration
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "agent-config": {
+      "command": "/absolute/path/to/agent-config/.venv-mcp/bin/python",
+      "args": ["-m", "scripts.mcp_server"],
+      "cwd": "/absolute/path/to/agent-config"
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The skills, commands, rules, guidelines, and contexts
+appear under the connector dropdown.
+
+### Cursor
+
+`~/.cursor/mcp.json` (or `<repo>/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "agent-config": {
+      "command": "/absolute/path/to/agent-config/.venv-mcp/bin/python",
+      "args": ["-m", "scripts.mcp_server"],
+      "cwd": "/absolute/path/to/agent-config"
+    }
+  }
+}
+```
+
+### Zed
+
+`~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "agent-config": {
+      "command": {
+        "path": "/absolute/path/to/agent-config/.venv-mcp/bin/python",
+        "args": ["-m", "scripts.mcp_server"]
+      },
+      "settings": {}
+    }
+  }
+}
+```
+
+### Continue (`continue.dev`)
+
+`~/.continue/config.yaml`:
+
+```yaml
+mcpServers:
+  - name: agent-config
+    command: /absolute/path/to/agent-config/.venv-mcp/bin/python
+    args: ["-m", "scripts.mcp_server"]
+    cwd: /absolute/path/to/agent-config
+```
+
+## Smoke test
+
+After configuring a client, run a manual stdio handshake to verify the server
+boots cleanly:
+
+```bash
+./agent-config mcp:run < /dev/null
+# Expect stderr: "mcp-server: loaded N prompts (0 warnings)" and
+#                "mcp-server: loaded 160 resources (0 warnings)"
+```
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Client shows no prompts | Confirm the `cwd` points at the repo root (where `.agent-src/` lives), not at `scripts/`. |
+| `ModuleNotFoundError: mcp` | Re-run `task mcp:setup`. The MCP runtime is isolated in `.venv-mcp/` — the project's base Python 3.9 deliberately does not see it. |
+| Stale prompts after editing | Hot-reload triggers on mtime; touch the file or reissue `resources/list`. |
+| Client refuses to start the server | Check the client's log for the full command. Most clients require **absolute** paths in `command` and `cwd`. |
+
+## Scope
+
+- **In scope:** read-only prompts + resources, pagination, hot-reload, stdio
+  transport, free-tier client compatibility.
+- **Out of scope (Phase 4+):** `tools/*` primitive, SSE / HTTP transport,
+  cloud distribution, signed payloads. Tracked in
+  [`agents/roadmaps/road-to-mcp-server.md`](../agents/roadmaps/road-to-mcp-server.md).
+
+← [Architecture](architecture.md) · [MCP config generation (consumer side)](mcp.md)

package/docs/setup/mcp-server-docker.md

@@ -0,0 +1,97 @@
+# MCP server — Docker (stdio bundle)
+
+Phase-6 F3 ships `docker/mcp-server/Dockerfile`: a stdio-only image of
+the agent-config MCP server, pinned to the same `mcp` + `PyYAML`
+versions the test suite runs against. No HTTP / SSE transport — that
+lives in [`road-to-mcp-distribution.md`](../../agents/roadmaps/road-to-mcp-distribution.md)
+under its own A0 amendment.
+
+## Build
+
+Build context is the **repo root**, not `docker/mcp-server/` — the
+`COPY` lines reference paths relative to the project root.
+
+```bash
+docker build -f docker/mcp-server/Dockerfile -t agent-config-mcp:local .
+```
+
+Tag conventions:
+
+- `:local` — your machine, current working tree
+- `:vX.Y.Z` — pinned to `package.json::version` at release time
+- `:latest` — most recent release (avoid in MCP client configs; pin)
+
+## Run (stdio)
+
+The image speaks MCP over **stdin / stdout**. `docker run` must be
+invoked with `-i` (interactive stdin) — without it the server has
+nothing to read and exits silently.
+
+```bash
+docker run --rm -i agent-config-mcp:local
+```
+
+You should see, on **stderr**:
+
+```
+mcp-server: loaded 278 prompts (0 warnings)
+mcp-server: loaded 160 resources (0 warnings)
+mcp-server: registered 2 tools: ['chat_history_append', 'lint_skills']
+mcp-server: identity serverVersion=0.1.0 packageVersion=1.36.1 skillSetSignature=<12-hex>
+```
+
+The fourth line is the F1 identity surface — see
+[`mcp-phase-1-scope.md § Phase 6`](../contracts/mcp-phase-1-scope.md)
+for semantics.
+
+## Wire into an MCP client
+
+```jsonc
+// .mcp.json (or your client's equivalent)
+{
+  "mcpServers": {
+    "agent-config": {
+      "command": "docker",
+      "args": ["run", "--rm", "-i", "agent-config-mcp:vX.Y.Z"]
+    }
+  }
+}
+```
+
+## Volume mounts (`chat_history_append`)
+
+The `chat_history_append` tool writes to
+`agents/.agent-chat-history` **inside the container**. For writes to
+survive container lifecycle, mount the host directory:
+
+```bash
+docker run --rm -i \
+  -v "$(pwd)/agents/.agent-chat-history:/app/agents/.agent-chat-history" \
+  agent-config-mcp:local
+```
+
+Without the mount the tool still succeeds (path-scope check passes
+inside the container), but the appended JSONL evaporates when the
+container exits. The `lint_skills` tool is read-only and needs no
+mount.
+
+## Security posture
+
+The image inherits the A0 contract verbatim — see
+[`mcp-phase-1-scope.md`](../contracts/mcp-phase-1-scope.md):
+
+- No `subprocess`, `os.system`, `requests`, `httpx`, or `urllib`
+  imports anywhere on the MCP wire surface (enforced by
+  `test_no_unsafe_imports_in_*` tests).
+- Tools allowlist is hardcoded in `scripts/mcp_server/tools.py`. The
+  container cannot grow new tools at runtime.
+- Image runs as a non-root user (`mcp:mcp`). Mounted host paths must
+  be writable by uid/gid `999` or you'll see permission errors.
+- No HTTP listener — there is no network attack surface. Stdin/stdout
+  only.
+
+## Size
+
+The runtime stage is `python:3.11-slim` + the pinned deps + the
+`.agent-src/` content. Expect ~150-200 MB; the builder stage is
+discarded.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.36.0",
+    "version": "1.37.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/agent-config

@@ -44,6 +44,10 @@ Commands:
   mcp:render                 Render mcp.json → .cursor/mcp.json, .windsurf/mcp.json
                              (pass --claude-desktop to also write user-scope config)
   mcp:check                  Dry-run mcp:render; exit non-zero if targets are stale
+  mcp:setup                  Create .venv-mcp/ and install the mcp SDK
+                             (one-line MCP server onboarding; idempotent)
+  mcp:run                    Run the built-in MCP server over stdio
+                             (requires `mcp:setup` first; see docs/mcp-server.md)
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
   hooks:install              Install the pre-commit roadmap-progress hook
@@ -97,6 +101,8 @@ Examples:
   ./agent-config mcp:render
   ./agent-config mcp:render --claude-desktop
   ./agent-config mcp:check
+  ./agent-config mcp:setup
+  ./agent-config mcp:run
   ./agent-config roadmap:progress
   ./agent-config hooks:install
   ./agent-config keys:install-anthropic
@@ -198,6 +204,27 @@ cmd_mcp_check() {
   exec python3 "$script" --check "$@"
 }
 
+cmd_mcp_setup() {
+  local script
+  script="$(resolve_script "scripts/mcp_setup.sh")" || return 1
+  exec bash "$script" "$@"
+}
+
+# Run the built-in stdio MCP server. The server module ships inside the
+# package (PACKAGE_ROOT/scripts/mcp_server/), but the venv is created by
+# `mcp_setup.sh` at CWD — keeping consumer projects in control of where
+# the SDK install lives. PYTHONPATH points at PACKAGE_ROOT so the
+# `scripts.mcp_server` import resolves regardless of CWD.
+cmd_mcp_run() {
+  local venv_py="$CONSUMER_ROOT/.venv-mcp/bin/python"
+  if [[ ! -x "$venv_py" ]]; then
+    echo "❌  agent-config: .venv-mcp/ not found at $CONSUMER_ROOT/.venv-mcp" >&2
+    echo "    Run \`./agent-config mcp:setup\` first to create it." >&2
+    exit 1
+  fi
+  exec env PYTHONPATH="$PACKAGE_ROOT" "$venv_py" -m scripts.mcp_server "$@"
+}
+
 cmd_roadmap_progress() {
   require_python3
   local script
@@ -484,6 +511,8 @@ main() {
   case "$cmd" in
     mcp:render)              cmd_mcp_render "$@" ;;
     mcp:check)               cmd_mcp_check "$@" ;;
+    mcp:setup)               cmd_mcp_setup "$@" ;;
+    mcp:run)                 cmd_mcp_run "$@" ;;
     roadmap:progress)        cmd_roadmap_progress "$@" ;;
     roadmap:progress-check)  cmd_roadmap_progress_check "$@" ;;
     hooks:install)           cmd_hooks_install "$@" ;;