@event4u/agent-config 9.8.0 → 9.10.0

package/docs/setup/mcp-client-config.md

@@ -1,358 +0,0 @@
-# MCP Client Config — agent-config
-
-Connect any MCP-capable client to the `agent-config` read-only content
-surface. Two entry points — a **local stdio** server (`agent-config
-mcp-server`, no account, no network) and a **self-hosted Cloudflare Worker**
-(a shared HTTP endpoint). See [§ Two ways to connect](#two-ways-to-connect--pick-one)
-to choose; both are read-only and identity-stable per release.
-
-The Worker sections below assume the self-hosted path (optional Bearer-token
-auth — see [§ Bearer auth](#bearer-auth)). For the local path jump straight to
-[§ Local stdio (turnkey)](#local-stdio-turnkey--no-worker-no-account).
-
-> **No public endpoint.** This package ships the Worker source under
-> `internal/workers/mcp/`, but does **not** operate a shared hosted MCP server.
-> Deploy your own per [`mcp-cloud-setup.md`](mcp-cloud-setup.md) — your
-> URL will be `https://agent-config-mcp.<your-account>.workers.dev`
-> (or a custom domain you wire up in Step 7).
->
-> In every snippet below, **replace `https://your-worker.workers.dev`
-> with your actual deployment URL**.
-
-For URL shapes (latest vs. pinned `/v<X.Y.Z>`) see
-[`mcp-cloud-endpoints.md`](mcp-cloud-endpoints.md). For operator
-setup of your own deployment see [`mcp-cloud-setup.md`](mcp-cloud-setup.md).
-
-## Two ways to connect — pick one
-
-There are **two distinct entry points**, and it is easy to confuse them.
-Pick the one that matches your situation; the per-client sections below
-cover the **remote Worker**, and [§ Local stdio (turnkey)](#local-stdio-turnkey--no-worker-no-account)
-covers the local one.
-
-| | **Local stdio (turnkey)** | **Remote Worker (self-hosted)** |
-|---|---|---|
-| Command | `agent-config mcp-server` | `npx -y mcp-remote https://your-worker…` |
-| Needs | the npm package installed | your own deployed Cloudflare Worker |
-| Network / account | none — fully local & offline | a Cloudflare account + a deployed Worker |
-| Surface | read-only content (skills / commands / rules / guidelines) | same read-only content |
-| Best for | end-users configuring an agent; offline; no account; a Worker-outage fallback | a shared team endpoint reachable from anywhere |
-
-> **Don't mix them up.** The local entry runs a **command** (`agent-config
-> mcp-server`); the remote entry points at a **URL**. If you installed the
-> npm package and just want the content locally, use the local-stdio path —
-> you do **not** need a Worker.
-
-## Transport note
-
-The Worker speaks JSON-RPC over HTTP POST. Clients that support
-HTTP transport natively (Claude Code, Cursor) talk to it directly.
-Clients that only support stdio (Claude Desktop, Zed) need the
-[`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge from
-npm — invoked via `npx`, no install required.
-
-The **local stdio** path is the opposite: it is natively stdio
-(`agent-config mcp-server`), so stdio-only clients need **no** bridge,
-and HTTP-native clients run it as a local command.
-
-## Where settings live — `.agent-settings.yml` vs. MCP config
-
-These are **two different files** for two different layers. Don't
-look for MCP server config inside `.agent-settings.yml`.
-
-| File | Where | Who reads it | Purpose |
-|---|---|---|---|
-| MCP client config (this page) | client-specific path per section above | the MCP client at startup | which MCP servers to talk to (name + URL / command) |
-| `.agent-settings.yml` | consumer project root (`<repo>/.agent-settings.yml`) | the agent at runtime (Claude / Cursor / …) | per-developer preferences: `name`, `ide`, `rule_loading_tier`, `personal.autonomy`, `pipelines.skill_improvement`, `telegraph.speak_scope`, … |
-
-The Worker is **stateless** and **project-agnostic** — it serves the
-same skill / rule / command catalog to every client. Personalization
-happens agent-side after the MCP delivers its content blob; the Worker
-itself does not read `.agent-settings.yml`.
-
-First-time setup of `.agent-settings.yml` runs through `/onboard`;
-template drift is handled by `/sync-agent-settings`.
-
-## Bearer auth
-
-If you set the `MCP-Token` secret on your Worker (via
-`task mcp:cloud:secret-put`), every POST request must carry the header
-`Authorization: Bearer <token>`. The `GET /` liveness probe stays
-unauthenticated.
-
-Add the header to each client below by appending the per-client header
-snippet shown in its section. Treat the token like any other secret —
-keep it out of repo files and shared dotfiles; prefer an env var
-(`MCP_TOKEN`) sourced from a password manager or shell init.
-
-If your Worker has **no** `MCP-Token` secret set, skip the header
-snippets — every POST is accepted as-is.
-
-## 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": "npx",
-      "args": ["-y", "mcp-remote", "https://your-worker.workers.dev"]
-    }
-  }
-}
-```
-
-With Bearer auth, add `--header`:
-
-```json
-{
-  "mcpServers": {
-    "agent-config": {
-      "command": "npx",
-      "args": [
-        "-y", "mcp-remote", "https://your-worker.workers.dev",
-        "--header", "Authorization: Bearer ${MCP_TOKEN}"
-      ],
-      "env": { "MCP_TOKEN": "paste-token-here" }
-    }
-  }
-}
-```
-
-Restart Claude Desktop. The connector appears in the dropdown.
-
-Newer builds also support **Settings → Connectors → Add Custom
-Connector** with the URL directly — no `mcp-remote` wrapper needed.
-
-## Claude Code
-
-Native HTTP transport — one command:
-
-```bash
-claude mcp add --transport http agent-config https://your-worker.workers.dev
-```
-
-With Bearer auth:
-
-```bash
-
-
-```
-
-Verify:
-
-```bash
-claude mcp list
-```
-
-## Cursor
-
-`~/.cursor/mcp.json` (global) or `<repo>/.cursor/mcp.json`
-(project-local):
-
-```json
-{
-  "mcpServers": {
-    "agent-config": {
-      "url": "https://your-worker.workers.dev",
-      "headers": { "Authorization": "Bearer paste-token-here" }
-    }
-  }
-}
-```
-
-(Omit the `headers` block if your Worker has no `MCP-Token` secret.)
-Reload Cursor (`Cmd+Shift+P → Reload Window`).
-
-## Zed
-
-`~/.config/zed/settings.json`:
-
-```json
-{
-  "context_servers": {
-    "agent-config": {
-      "source": "custom",
-      "command": "npx",
-      "args": [
-        "-y", "mcp-remote", "https://your-worker.workers.dev",
-        "--header", "Authorization: Bearer ${MCP_TOKEN}"
-      ],
-      "env": { "MCP_TOKEN": "paste-token-here" }
-    }
-  }
-}
-```
-
-Drop the `--header` / `env` pair when the Worker has no token set.
-Zed has no native remote-MCP transport yet, so the `mcp-remote`
-bridge is required.
-
-## Continue
-
-`~/.continue/config.yaml` (or `<repo>/.continue/config.yaml`):
-
-```yaml
-mcpServers:
-  - name: agent-config
-    command: npx
-    args:
-      - "-y"
-      - mcp-remote
-      - https://your-worker.workers.dev
-      - --header
-      - "Authorization: Bearer ${MCP_TOKEN}"
-    env:
-      MCP_TOKEN: paste-token-here
-```
-
-Drop the `--header` / `env` keys when the Worker has no token set.
-
-## Verify
-
-After reload, every client should:
-
-1. List `agent-config` under connectors / tools with a release-key
-   matching the live deploy. Probe the endpoint to see the current
-   release (the `GET /` liveness probe is always unauthenticated):
-
-   ```bash
-   curl https://your-worker.workers.dev
-   # → { "ok": true, "release_key": "v…", "signature": "…", … }
-   ```
-
-2. Expose skill + command prompts under URIs like `skill://…` and
-   `command://…`.
-3. Expose rule + guideline + context resources under `rule://…`,
-   `guideline://…`, `context://…`.
-
-With Bearer auth, a wrong/missing token returns HTTP 401 with body
-`{"jsonrpc":"2.0","id":null,"error":{"code":-32001,"message":"Unauthorized"}}` —
-quick way to confirm enforcement:
-
-```bash
-curl -X POST -H "content-type: application/json" \
-  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}' \
-  https://your-worker.workers.dev
-# → 401 Unauthorized
-
-curl -X POST -H "content-type: application/json" \
-  -H "Authorization: Bearer $MCP_TOKEN" \
-  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}' \
-  https://your-worker.workers.dev
-# → 200 { "jsonrpc":"2.0","id":1,"result":{} }
-```
-
-If the client shows the connector but no prompts / resources,
-re-probe the URL — a 5xx from the Worker indicates the deploy is
-mid-roll, retry after a minute.
-
-## Local stdio (turnkey) — no Worker, no account
-
-Install the package, then point your client at the **`agent-config
-mcp-server`** command. It serves the bundled content (skills / commands as
-prompts; rules / guidelines as resources) over stdio — **read-only**, fully
-local, no network, no Cloudflare account, no repo clone. This is the local
-counterpart to the remote-Worker snippets above; the Worker templates are
-unchanged.
-
-```bash
-npm install -g @event4u/agent-config   # provides the `agent-config` binary
-```
-
-In every snippet below, `agent-config` is the globally-installed binary. If
-you prefer not to install globally, replace
-`"command": "agent-config", "args": ["mcp-server"]` with
-`"command": "npx", "args": ["-y", "@event4u/agent-config", "mcp-server"]`.
-
-### Claude Desktop
-
-`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
-`%APPDATA%\Claude\claude_desktop_config.json` (Windows):
-
-```json
-{
-  "mcpServers": {
-    "agent-config": {
-      "command": "agent-config",
-      "args": ["mcp-server"]
-    }
-  }
-}
-```
-
-Restart Claude Desktop fully (Cmd+Q on macOS).
-
-### Claude Code
-
-Native stdio — one command (everything after `--` is the server command):
-
-```bash
-claude mcp add agent-config -- agent-config mcp-server
-claude mcp list
-```
-
-### Cursor
-
-`~/.cursor/mcp.json` (global) or `<repo>/.cursor/mcp.json` (project-local):
-
-```json
-{
-  "mcpServers": {
-    "agent-config": {
-      "command": "agent-config",
-      "args": ["mcp-server"]
-    }
-  }
-}
-```
-
-Reload Cursor (`Cmd+Shift+P → Reload Window`).
-
-### Zed
-
-`~/.config/zed/settings.json`:
-
-```json
-{
-  "context_servers": {
-    "agent-config": {
-      "source": "custom",
-      "command": "agent-config",
-      "args": ["mcp-server"]
-    }
-  }
-}
-```
-
-No `mcp-remote` bridge is needed — the local server is already stdio.
-
-### Verify the local server
-
-The server speaks the same wire surface; drive it directly to confirm:
-
-```bash
-printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
-  | agent-config mcp-server
-# → {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"…","serverInfo":{"name":"agent-config-mcp",…}}}
-```
-
-The readiness note (`[mcp-server] … ready — N entries, read-only`) is printed
-on **stderr**; stdout carries only JSON-RPC. `tools/list` is empty and
-`tools/call` returns a `not_implemented` envelope — the local surface is
-read-only by design (execution is deferred; see
-[`../decisions/ADR-085-mcp-stdio-end-user-distribution-shape.md`](../decisions/ADR-085-mcp-stdio-end-user-distribution-shape.md)).
-
-> **Contributor variant.** If you have the repo cloned and want the
-> execution-capable Python kernel under `scripts/mcp_server/` instead, run
-> `task mcp:setup` then `task mcp:run` — details in
-> [`../mcp-server.md`](../mcp-server.md). That path is for development, not
-> end-user packaging.
-
-## See also
-
-- URL shapes & DNS — [`mcp-cloud-endpoints.md`](mcp-cloud-endpoints.md)
-- Operator setup (your own deploy) — [`mcp-cloud-setup.md`](mcp-cloud-setup.md)
-- A0-cloud contract — [`../contracts/mcp-cloud-scope.md`](../contracts/mcp-cloud-scope.md)

package/docs/setup/mcp-cloud-endpoints.md

@@ -1,116 +0,0 @@
-# MCP Cloud Endpoints — URL shapes & DNS
-
-Public URL shapes for the hosted `agent-config-mcp` Worker. Governed
-by `docs/contracts/mcp-cloud-scope.md` (A0-cloud) and Phase 5.2 of
-`agents/roadmaps/road-to-cloudflare-mcp-hosting.md`.
-
-## Stability
-
-**Experimental.** Inherits the label from `mcp-phase-1-scope.md`. URL
-shapes below are pinned for the lifetime of the *experimental* window;
-breaking changes require a stability-label bump.
-
-## Scope — Lite surface
-
-The hosted endpoint exposes the **read-only governance surface**
-(skills, commands, rules, guidelines, contexts) as MCP prompts +
-resources. `tools/list` returns two **deprecated stubs**
-(`lint_skills`, `chat_history_append`) that point at their local-stdio
-successors; `tools/call` against either returns `isError=true`. No
-script execution, no FS access, no shell.
-
-Full power — the implemented tool surface (18 tools as of the 2026-07-07
-write/exec cut: memory, roadmap, capabilities, doctor/conformance,
-telemetry, council-estimate, and the vitest `run_tests` pilot) — requires
-the **local kernel server** (`agent-config mcp:run` on a repo checkout).
-`implemented_on` stays `["stdio"]` for every execution tool, permanently:
-the Worker has no kernel runtime endpoint — it serves a release-pinned
-content snapshot from R2, so there is no process that could run the
-handlers, and the A0-cloud contract's no-execution boundary is a design
-invariant, not a backlog item. See
-[`../contracts/mcp-cloud-scope.md`](../contracts/mcp-cloud-scope.md)
-for the execution-safety boundary and the Phase-7-DEFERRED gate that
-governs any future tool restoration.
-
-## URL shapes (pinned)
-
-Two surfaces, both serve identical wire contracts (JSON-RPC over POST,
-SSE on GET — A0-cloud invariant 1):
-
-| Shape | Resolves to | Use case |
-|---|---|---|
-| `https://mcp.<domain>/latest/sse` | the release currently pointed at by `releases/latest.txt` in R2 | client wants the rolling cutting-edge build |
-| `https://mcp.<domain>/v<X.Y.Z>/sse` | the immutable release `<X.Y.Z>` from the R2 archive | client wants a pinned, reproducible build |
-
-The `<domain>` placeholder is operator-configured; the package itself
-does not own DNS. Pin the chosen domain in your fork's
-`mcp-cloud-scope.md` § Bucket / DNS.
-
-For JSON-RPC, drop the `/sse` suffix:
-
-| JSON-RPC | SSE |
-|---|---|
-| `POST https://mcp.<domain>/latest` | `GET  https://mcp.<domain>/latest/sse` |
-| `POST https://mcp.<domain>/v1.37.0` | `GET  https://mcp.<domain>/v1.37.0/sse` |
-
-The Worker reads its bundled blob at module init (per A0-cloud
-invariant 2); the path prefix in MVP-1 is a routing artefact, not a
-content selector. Multi-version routing lands in MVP-2.
-
-## DNS setup (operator-side)
-
-One-time, requires Cloudflare account + zone access:
-
-```sh
-# 1. Add the Worker custom domain in Cloudflare dashboard:
-#    Workers & Pages → agent-config-mcp → Settings → Domains & Routes
-#    → Add Custom Domain → "mcp.<your-domain>"
-#
-# 2. Cloudflare creates the AAAA + A records automatically. No manual
-#    CNAME — Custom Domains is the supported path (not "Routes").
-#
-# 3. Verify:
-curl -s -X POST https://mcp.<your-domain>/ \
-  -H "content-type: application/json" \
-  -d '{"jsonrpc":"2.0","id":1,"method":"ping","params":{}}'
-```
-
-After DNS is live, uncomment the `routes` block in
-`internal/workers/mcp/wrangler.toml` and redeploy via `wrangler deploy` (or let
-the GitHub Action pick it up on the next release).
-
-The fallback `*.workers.dev` URL stays live for free; the custom
-domain is only the public stability promise.
-
-## Health probe
-
-Every URL accepts `GET /` with no body and returns release identity:
-
-```json
-{
-  "ok": true,
-  "name": "agent-config-mcp",
-  "release_key": "v1.37.0-2fc5084",
-  "package_version": "1.37.0",
-  "signature": "35bc3c5e8b83",
-  "schema_version": 1
-}
-```
-
-The `signature` field is the wire-surface `skillSetSignature` — same
-hash that MCP clients see under `_meta.skillSetSignature` on the
-identity surface.
-
-## Parity smoke
-
-Post-deploy CI runs `scripts/mcp_parity_smoke.py` against the new
-deployment with `--target https://mcp.<domain>`. A non-zero exit
-aborts the `latest.txt` repoint, so the previous release keeps
-serving on `/latest/`.
-
-## See also
-
-- Per-client config snippets: [`mcp-client-config.md`](mcp-client-config.md)
-- A0-cloud contract: `docs/contracts/mcp-cloud-scope.md`
-- R2 bootstrap: `docs/setup/mcp-r2-bootstrap.md`
-- Local stdio fallback: `scripts/mcp_server/` (unchanged)

package/docs/setup/mcp-cloud-registry-listing.md

@@ -1,99 +0,0 @@
-# MCP Registry Listing — submission package
-
-Single source of truth for every MCP-registry submission of the hosted
-`agent-config-mcp` Worker. Copy-paste sections from this file into the
-target registry's template; do not maintain per-registry forks.
-
-Phase 6.1 of `agents/roadmaps/road-to-cloudflare-mcp-hosting.md`.
-
-## One-liner
-
-> Read-only governance surface for AI coding agents — 174 skills, 104
-> commands, 60 rules, 100 guidelines + contexts. Hosted MCP bridge
-> over the `event4u/agent-config` package.
-
-## Endpoints
-
-| Shape | URL | Use |
-|---|---|---|
-| Rolling latest | `https://mcp.<operator-domain>/latest/sse` | clients tracking the live build |
-| Pinned release | `https://mcp.<operator-domain>/v<X.Y.Z>/sse` | clients pinning a reproducible version |
-| Liveness | `GET https://mcp.<operator-domain>/` | release identity + signature |
-
-The `<operator-domain>` placeholder reflects the package's design —
-every operator hosts their own Worker. The package upstream does not
-run a public reference deployment; consumers point their Worker at
-their own R2 bucket per `docs/setup/mcp-r2-bootstrap.md`.
-
-## Wire surface (MVP-1)
-
-| Method | Status |
-|---|---|
-| `initialize` | implemented |
-| `ping` | implemented |
-| `prompts/list`, `prompts/get` | implemented |
-| `resources/list`, `resources/read` | implemented |
-| `tools/list` | implemented (returns deprecated stubs only) |
-| `tools/call` | **not implemented** — returns `-32601 Method not found` |
-| `notifications/*` | not implemented |
-
-No mutation, no auth, no subrequests at runtime. Full contract:
-`docs/contracts/mcp-cloud-scope.md` § A0-cloud.
-
-## Stability
-
-**Experimental.** Wire surface, URL shapes, and the `_meta.signature`
-field are pinned for the lifetime of the *experimental* window.
-Breaking changes require a stability-label bump (see
-`docs/contracts/mcp-phase-1-scope.md`).
-
-## Identity & reproducibility
-
-Every response carries `_meta.skillSetSignature` — a 12-char SHA-256
-prefix over the sorted `(uri, body)` pairs of the bundled content.
-Identical content → identical signature, across machines and builds.
-R2 archives every release indefinitely under
-`releases/v<X.Y.Z>-<sha>/`.
-
-## Categories (for registry tagging)
-
-- `governance`
-- `meta-prompting`
-- `skills`
-- `agent-infrastructure`
-- `code-review`
-- `experimental`
-
-## License & contact
-
-| Field | Value |
-|---|---|
-| License | MIT |
-| Source | `https://github.com/event4u-app/agent-config` |
-| Maintainer | event4u-app (org) |
-| Contact | GitHub issues |
-
-## Links to upstream contracts
-
-- A0-cloud safety contract: `docs/contracts/mcp-cloud-scope.md`
-- Phase-1 scope (inherited): `docs/contracts/mcp-phase-1-scope.md`
-- URL shapes & DNS: `docs/setup/mcp-cloud-endpoints.md`
-- Local stdio kernel (predecessor): `scripts/mcp_server/`
-
-## Submission targets
-
-| Target | Status | Notes |
-|---|---|---|
-| [`awesome-mcp-servers`](https://github.com/punkpeye/awesome-mcp-servers) | ready for PR | low-friction listing, accepts experimental |
-| [`modelcontextprotocol.io` catalog](https://modelcontextprotocol.io/servers) | ready for PR after `awesome-mcp-servers` merges | needs evidence of community uptake |
-
-Both submissions reuse the **One-liner**, **Endpoints**, **Wire
-surface**, **Stability**, and **License & contact** sections verbatim
-from this file.
-
-## Out of scope for this roadmap
-
-npm-launcher listing (`npx @event4u/agent-config-mcp`) targets the
-**local stdio** server, not the hosted Worker. Different transport,
-different installation pattern, different audience — captured in
-`agents/roadmaps/road-to-mcp-server.md` if revived.