@event4u/agent-config 1.37.0 → 1.39.0

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

@@ -0,0 +1,109 @@
+# 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 ~112 Python scripts (linters, audits, `task ci`,
+work-engine hooks) — requires the local install. 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
+`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

@@ -0,0 +1,99 @@
+# 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.

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

@@ -0,0 +1,152 @@
+# Cloudflare MCP — Operator Setup
+
+One-stop landing for onboarding a Cloudflare account to host the
+`agent-config-mcp` Worker. Combines bucket bootstrap, DNS, GitHub
+secrets, and troubleshooting in one place.
+
+Governed by [`docs/contracts/mcp-cloud-scope.md`](../contracts/mcp-cloud-scope.md)
+(A0-cloud). Deploys run **only** in CI
+([`.github/workflows/deploy-mcp-worker.yml`](../../.github/workflows/deploy-mcp-worker.yml))
+— per A0-cloud invariant 7, never `wrangler deploy` from a developer
+machine.
+
+## TL;DR — the happy path
+
+```sh
+task mcp:cloud:login        # one-time, opens browser
+task mcp:cloud:setup        # check → r2-create → r2-verify → whoami
+# Copy account id from output → GitHub Secrets (see § GitHub Secrets)
+# Create scoped API token (see § API Token) → GitHub Secrets
+# Done. First `release: published` triggers the deploy.
+```
+
+## Prerequisites
+
+| Tool | Version | Install |
+|---|---|---|
+| Node.js | ≥ 20 | <https://nodejs.org/> or `nvm install 20` |
+| `npx`/`wrangler` | wrangler ≥ 4.0 (auto-fetched on first run) | bundled with Node |
+| `gh` CLI | latest | <https://cli.github.com/> (only for manual `deploy-dispatch`) |
+| Cloudflare account | any plan | <https://dash.cloudflare.com/sign-up> |
+
+Run `task mcp:cloud:check` to verify all four in one shot.
+
+## Step 1 — Cloudflare login
+
+```sh
+task mcp:cloud:login
+```
+
+Opens a browser to authorize wrangler against your Cloudflare account.
+One-time per developer machine; the token is stored in
+`~/Library/Preferences/.wrangler/` (macOS) or `~/.wrangler/` (Linux).
+
+## Step 2 — Enable R2
+
+Cloudflare requires a one-time plan activation before R2 buckets can
+be created. **You will hit error `code: 10042` on the first attempt
+if you skip this.**
+
+1. <https://dash.cloudflare.com/?to=/:account/r2/overview>
+2. Click **Purchase R2 Plan**
+3. Select **Free Tier** — 10 GB storage / 1 M Class-A / 10 M Class-B
+   ops per month at **$0** (credit card required, $0 within quota,
+   $0 egress)
+4. Confirm; wait ~30 s for activation
+
+## Step 3 — Create the R2 bucket
+
+```sh
+task mcp:cloud:r2-create     # idempotent — safe to re-run
+task mcp:cloud:r2-verify     # ✅ if present
+```
+
+The bucket is named `agent-config-mcp` and configured per
+[`docs/setup/mcp-r2-bootstrap.md`](mcp-r2-bootstrap.md) (private,
+indefinite retention, Worker reads via binding).
+
+`task mcp:cloud:setup` chains steps 1, 3, and the account-id readout
+in one shot.
+
+## Step 4 — API Token
+
+The CI deploy pipeline needs a **scoped** token — never reuse the
+Global API Key or a production-tenant token.
+
+Dashboard → **My Profile → API Tokens → Create Token → Custom token**:
+
+| Permission | Resource | Access |
+|---|---|---|
+| Account · Workers Scripts | your account | Edit |
+| Account · Workers R2 Storage | your account | Edit |
+| User · User Details | — | Read |
+
+If you uncomment the `routes` block in `workers/mcp/wrangler.toml`
+(custom domain cutover, Phase 5.2), add **Zone · DNS · Edit** on the
+relevant zone.
+
+Copy the generated token immediately — Cloudflare shows it once.
+
+## Step 5 — GitHub Secrets
+
+Repository → **Settings → Secrets and variables → Actions → New
+repository secret**:
+
+| Secret | Value | Source |
+|---|---|---|
+| `CLOUDFLARE_API_TOKEN` | scoped token from Step 4 | dashboard |
+| `CLOUDFLARE_ACCOUNT_ID` | account id | `task mcp:cloud:whoami` |
+
+Set them in **Actions** secrets, not **Codespaces** or **Dependabot**
+scopes.
+
+## Step 6 — Validate
+
+Trigger the deploy workflow manually against an existing tag — no
+release event needed:
+
+```sh
+task mcp:cloud:deploy-dispatch TAG=v1.37.0
+gh run watch
+```
+
+Green smoke step → `latest.txt` repoints → release is live on
+`*.workers.dev`. A red smoke step leaves `latest.txt` on the previous
+release.
+
+## Step 7 — DNS (optional, Phase 5.2)
+
+Custom domain `mcp.<your-domain>` setup lives in
+[`docs/setup/mcp-cloud-endpoints.md`](mcp-cloud-endpoints.md) § DNS
+setup. Until cutover, the Worker serves on the free
+`agent-config-mcp.<account>.workers.dev` URL.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `code: 10042` on bucket create | R2 not enabled on account | Step 2 — Enable R2 |
+| `wrangler whoami` shows no Account ID | not logged in | `task mcp:cloud:login` |
+| Workflow fails on `wrangler deploy` with auth error | secret missing/wrong scope | re-check Step 4 token permissions |
+| Smoke step red after deploy | bundle vs. SDK mismatch | check `compatibility_date` in `wrangler.toml` |
+| Bucket create returns `already exists` | bucket present | not an error — `task mcp:cloud:r2-verify` to confirm |
+
+## Available tasks
+
+| Task | Purpose |
+|---|---|
+| `task mcp:cloud:check` | Preflight — tools + login status |
+| `task mcp:cloud:login` | Interactive wrangler login |
+| `task mcp:cloud:whoami` | Print account id for GitHub Secret |
+| `task mcp:cloud:r2-create` | Create R2 bucket (idempotent) |
+| `task mcp:cloud:r2-verify` | Verify R2 bucket exists |
+| `task mcp:cloud:setup` | Full chain — check → r2 → whoami |
+| `task mcp:cloud:dev` | Local `wrangler dev` on :8787 |
+| `task mcp:cloud:deploy-dispatch TAG=v…` | Manual workflow trigger |
+
+## See also
+
+- [`docs/contracts/mcp-cloud-scope.md`](../contracts/mcp-cloud-scope.md) — A0-cloud contract
+- [`docs/setup/mcp-r2-bootstrap.md`](mcp-r2-bootstrap.md) — R2 layout & break-glass
+- [`docs/setup/mcp-cloud-endpoints.md`](mcp-cloud-endpoints.md) — URL shapes & DNS
+- [`workers/mcp/README.md`](../../workers/mcp/README.md) — Worker source overview

package/docs/setup/mcp-r2-bootstrap.md

@@ -0,0 +1,82 @@
+# R2 Bootstrap — agent-config MCP
+
+One-time setup for the R2 bucket that holds the Worker's release archive.
+Owned by `mcp-cloud-scope.md` §3.3 and consumed by the deploy pipeline
+(`.github/workflows/deploy-mcp-worker.yml`).
+
+## Bucket
+
+| Field | Value |
+|---|---|
+| Bucket name | `agent-config-mcp` |
+| Location hint | `auto` (Cloudflare-chosen) |
+| Public access | **off** — Worker reads via binding, never via signed URL |
+| Object retention | indefinite — every release stays for forensics |
+
+## Layout
+
+```
+agent-config-mcp/
+├─ releases/
+│  ├─ v<X.Y.Z>-<sha>/
+│  │  ├─ content.json.gz    # gzipped content blob (R2 archival copy)
+│  │  └─ manifest.json      # uncompressed manifest sidecar
+│  └─ latest.txt            # one-line: v<X.Y.Z>-<sha>
+└─ (no other prefixes)
+```
+
+`latest.txt` is the only mutable object. Every `releases/v*/` directory
+is **immutable** once written; the pipeline refuses to overwrite an
+existing release prefix.
+
+## Bootstrap — one-time
+
+Requires `wrangler` ≥ 4.0 and a Cloudflare API token with R2 admin scope.
+
+```sh
+# 1. Authenticate (interactive, opens browser).
+npx wrangler login
+
+# 2. Create the bucket.
+npx wrangler r2 bucket create agent-config-mcp
+
+# 3. Verify.
+npx wrangler r2 bucket list | grep agent-config-mcp
+```
+
+The Worker binding is declared in `workers/mcp/wrangler.toml` under
+`[[r2_buckets]]`. The pipeline reads/writes via the wrangler CLI in CI,
+not via the Worker — A0-cloud invariant 2 forbids the Worker from
+issuing R2 writes.
+
+## Secrets in CI
+
+The deploy pipeline needs two GitHub secrets:
+
+| Secret | Scope |
+|---|---|
+| `CLOUDFLARE_API_TOKEN` | `Workers Scripts:Edit` + `Workers R2 Storage:Edit` |
+| `CLOUDFLARE_ACCOUNT_ID` | account id (not a token) |
+
+The token must be scoped to **this account only**; do not reuse a
+production-tenant token.
+
+## Manual fixes — break-glass
+
+If `latest.txt` ends up pointing to a broken release, the recovery is to
+repoint it manually:
+
+```sh
+# Repoint latest to a known-good release.
+echo -n "v1.36.0-abc1234" | \
+  npx wrangler r2 object put agent-config-mcp/releases/latest.txt --pipe
+```
+
+Past `releases/v*/` directories are not deleted in recovery — leave the
+forensics intact.
+
+## Terraform note
+
+The repo does not yet manage CF resources via Terraform. When TF lands,
+this bucket should move into a `cloudflare_r2_bucket` resource and this
+doc shrinks to a pointer.

package/package.json

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

package/scripts/_lib/agent_settings.py

@@ -0,0 +1,168 @@
+"""Centralized loader for ``.agent-settings.yml`` with user-global fallback.
+
+Phase 1 of road-to-portable-dev-preferences. Single source of truth for
+how scripts read agent settings — replaces ~15 ad-hoc loaders in P3.
+
+Resolution order (project wins, user-global fills gaps for whitelisted
+keys only):
+
+  1. Project ``./.agent-settings.yml``                  (full file, all keys)
+  2. ``~/.config/agent-config/agent-settings.yml``      (whitelist only)
+  3. Built-in defaults                                  (currently empty)
+
+Whitelisted keys (``MERGEABLE_KEYS``) are exact dotted paths. A
+non-whitelisted key in the user-global file is silently ignored — the
+``verbose=True`` flag surfaces ignored paths via ``logging.info`` for
+debugging.
+
+Contract — pure, read-only, tolerant:
+
+* Lazy PyYAML import; no yaml installed → defaults returned.
+* Missing project file → user-global + defaults.
+* Missing user-global file → project + defaults.
+* Both missing → defaults.
+* Malformed YAML / unreadable file → defaults, logged at WARNING.
+* No file is ever created or written by this module.
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_PROJECT_FILE = ".agent-settings.yml"
+DEFAULT_USER_GLOBAL_FILE = (
+    Path.home() / ".config" / "agent-config" / "agent-settings.yml"
+)
+
+#: Exact dotted paths allowed to cascade from user-global into the merged
+#: settings. Anything not listed here is silently ignored when present in
+#: the user-global file. Adding a key requires an ADR — see
+#: ``agents/roadmaps/road-to-portable-dev-preferences.md``.
+MERGEABLE_KEYS: tuple[str, ...] = (
+    "name",
+    "ide",
+    "cost_profile",
+    "personal.bot_icon",
+    "personal.autonomy",
+    "caveman.speak_scope",
+)
+
+_DEFAULTS: dict[str, Any] = {}
+
+
+def load_agent_settings(
+    project_path: Path | str | None = None,
+    user_global_path: Path | str | None = None,
+    verbose: bool = False,
+) -> dict[str, Any]:
+    """Return the merged settings dict.
+
+    ``project_path`` defaults to ``./.agent-settings.yml`` (CWD-relative).
+    ``user_global_path`` defaults to
+    ``~/.config/agent-config/agent-settings.yml``. Both arguments accept
+    ``Path`` or ``str``. Pass ``verbose=True`` to log keys present in
+    user-global that are not on the whitelist.
+    """
+    project = _read_yaml(
+        Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE),
+    ) or {}
+    user_global_raw = _read_yaml(
+        Path(user_global_path) if user_global_path else DEFAULT_USER_GLOBAL_FILE,
+    ) or {}
+
+    user_global_filtered, ignored = _filter_whitelist(
+        user_global_raw, MERGEABLE_KEYS,
+    )
+    if verbose and ignored:
+        logger.info(
+            "agent_settings: ignored non-whitelisted user-global keys: %s",
+            sorted(ignored),
+        )
+
+    merged: dict[str, Any] = _deep_copy_defaults(_DEFAULTS)
+    _deep_merge(merged, user_global_filtered)
+    _deep_merge(merged, project)
+    return merged
+
+
+def _read_yaml(path: Path) -> dict[str, Any] | None:
+    """Best-effort YAML read; never raises. Returns ``None`` on any failure."""
+    if not path.is_file():
+        return None
+    try:
+        import yaml  # type: ignore[import-untyped]
+    except ImportError:
+        return None
+    try:
+        with path.open(encoding="utf-8") as fh:
+            data = yaml.safe_load(fh) or {}
+    except (OSError, yaml.YAMLError):
+        logger.warning("agent_settings: unreadable or malformed YAML at %s", path)
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _filter_whitelist(
+    raw: dict[str, Any], allowed: tuple[str, ...],
+) -> tuple[dict[str, Any], list[str]]:
+    """Return ``(filtered_dict, ignored_paths)`` from a user-global blob."""
+    filtered: dict[str, Any] = {}
+    for dotted in allowed:
+        value = _get_dotted(raw, dotted)
+        if value is not None:
+            _set_dotted(filtered, dotted, value)
+    ignored = [p for p in _leaf_paths(raw) if p not in allowed]
+    return filtered, ignored
+
+
+def _get_dotted(data: dict[str, Any], dotted: str) -> Any:
+    cursor: Any = data
+    for part in dotted.split("."):
+        if not isinstance(cursor, dict) or part not in cursor:
+            return None
+        cursor = cursor[part]
+    return cursor
+
+
+def _set_dotted(target: dict[str, Any], dotted: str, value: Any) -> None:
+    parts = dotted.split(".")
+    cursor = target
+    for part in parts[:-1]:
+        nxt = cursor.setdefault(part, {})
+        if not isinstance(nxt, dict):
+            nxt = {}
+            cursor[part] = nxt
+        cursor = nxt
+    cursor[parts[-1]] = value
+
+
+def _leaf_paths(data: dict[str, Any], prefix: str = "") -> list[str]:
+    paths: list[str] = []
+    for key, value in data.items():
+        path = f"{prefix}.{key}" if prefix else key
+        if isinstance(value, dict) and value:
+            paths.extend(_leaf_paths(value, path))
+        else:
+            paths.append(path)
+    return paths
+
+
+def _deep_merge(dst: dict[str, Any], src: dict[str, Any]) -> None:
+    """Merge ``src`` into ``dst`` in-place; nested dicts are merged recursively."""
+    for key, value in src.items():
+        if (
+            isinstance(value, dict)
+            and isinstance(dst.get(key), dict)
+        ):
+            _deep_merge(dst[key], value)
+        else:
+            dst[key] = value
+
+
+def _deep_copy_defaults(src: dict[str, Any]) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    _deep_merge(out, src)
+    return out