@event4u/agent-config 1.36.1 → 1.38.0

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 "$@" ;;

package/scripts/mcp_parity_smoke.py

@@ -0,0 +1,146 @@
+"""Live-replay parity smoke — local stdio kernel vs deployed Worker URL.
+
+Replays a fixed set of JSON-RPC calls against:
+
+1. The local Python loaders (`prompts.py` / `resources.py`) — the
+   source-of-truth wire surface.
+2. An HTTP target (typically `wrangler dev` locally, or the deployed
+   Cloudflare Worker URL in CI / post-deploy).
+
+Diffs the two on a normalised view (signature + release_key + content
+hashes stripped). Exit 0 = parity, 1 = drift.
+
+Usage:
+    python scripts/mcp_parity_smoke.py --target http://127.0.0.1:8787
+    python scripts/mcp_parity_smoke.py --target https://mcp.example.com
+
+Phase 5.1 of `road-to-cloudflare-mcp-hosting.md`. Governed by
+`docs/contracts/mcp-cloud-scope.md` §A0-cloud.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+_SCRIPTS = Path(__file__).resolve().parent
+sys.path.insert(0, str(_SCRIPTS))
+
+from mcp_server.prompts import load_all_prompts, to_mcp_prompt_meta  # noqa: E402
+from mcp_server.resources import load_all_resources, to_mcp_resource_meta  # noqa: E402
+
+PAGE_SIZE = 50
+
+
+def _local_prompts_list() -> dict[str, Any]:
+    prompts, _ = load_all_prompts()
+    metas = [to_mcp_prompt_meta(p) for p in prompts]
+    page = metas[:PAGE_SIZE]
+    out: dict[str, Any] = {"prompts": page}
+    if len(metas) > PAGE_SIZE:
+        out["nextCursor"] = page[-1]["name"]
+    return out
+
+
+def _local_resources_list() -> dict[str, Any]:
+    resources, _ = load_all_resources()
+    metas = [to_mcp_resource_meta(r) for r in resources]
+    page = metas[:PAGE_SIZE]
+    out: dict[str, Any] = {"resources": page}
+    if len(metas) > PAGE_SIZE:
+        out["nextCursor"] = page[-1]["uri"]
+    return out
+
+
+def _rpc(target: str, method: str, params: dict[str, Any] | None = None) -> Any:
+    body = json.dumps(
+        {"jsonrpc": "2.0", "id": 1, "method": method, "params": params or {}}
+    ).encode("utf-8")
+    req = urllib.request.Request(
+        target,
+        data=body,
+        headers={"content-type": "application/json"},
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=10) as r:  # noqa: S310
+        resp = json.loads(r.read().decode("utf-8"))
+    if "error" in resp:
+        raise RuntimeError(f"{method}: {resp['error']}")
+    return resp["result"]
+
+
+def _normalize_prompts(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    out = []
+    for p in payload.get("prompts", []):
+        out.append({
+            "name": p["name"],
+            "description": p["description"],
+            "kind": p.get("_meta", {}).get("kind"),
+        })
+    return sorted(out, key=lambda x: x["name"])
+
+
+def _normalize_resources(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    out = []
+    for r in payload.get("resources", []):
+        out.append({
+            "uri": r["uri"],
+            "name": r["name"],
+            "description": r["description"],
+            "mimeType": r["mimeType"],
+            "kind": r.get("_meta", {}).get("kind"),
+        })
+    return sorted(out, key=lambda x: x["uri"])
+
+
+def _diff(label: str, local: list[Any], remote: list[Any]) -> int:
+    if local == remote:
+        print(f"✅  {label}: {len(local)} entries match")
+        return 0
+    print(f"❌  {label}: drift ({len(local)} local vs {len(remote)} remote)")
+    local_set = {json.dumps(x, sort_keys=True) for x in local}
+    remote_set = {json.dumps(x, sort_keys=True) for x in remote}
+    only_local = local_set - remote_set
+    only_remote = remote_set - local_set
+    for s in sorted(only_local)[:5]:
+        print(f"    local-only: {s}")
+    for s in sorted(only_remote)[:5]:
+        print(f"    remote-only: {s}")
+    if len(only_local) > 5 or len(only_remote) > 5:
+        print(f"    (+{len(only_local) - 5} local, +{len(only_remote) - 5} remote more)")
+    return 1
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--target", required=True, help="HTTP URL of the Worker.")
+    args = ap.parse_args()
+
+    failed = 0
+    local_p = _normalize_prompts(_local_prompts_list())
+    remote_p = _normalize_prompts(_rpc(args.target, "prompts/list"))
+    failed += _diff("prompts/list", local_p, remote_p)
+
+    local_r = _normalize_resources(_local_resources_list())
+    remote_r = _normalize_resources(_rpc(args.target, "resources/list"))
+    failed += _diff("resources/list", local_r, remote_r)
+
+    try:
+        _ = _rpc(args.target, "tools/list")
+        print("✅  tools/list: round-trips (stub list — content not parity-checked)")
+    except Exception as e:
+        print(f"❌  tools/list: {e}")
+        failed += 1
+
+    if failed:
+        print(f"\n{failed} surface(s) drifted between local stdio and {args.target}")
+        return 1
+    print(f"\nparity OK against {args.target}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/mcp_server/__init__.py

@@ -0,0 +1,13 @@
+"""MCP server for agent-config — Phase 1 MVP.
+
+Exposes a hand-picked subset of `.agent-src/skills/` as MCP `prompts`
+over stdio. Read-only and instructional per the A0 execution-safety
+boundary in `agents/roadmaps/road-to-mcp-server.md`. No `tools`
+primitive, no engine spawn, no shell execution.
+
+Stability: experimental. Contract: `docs/contracts/mcp-phase-1-scope.md`.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+SERVER_NAME = "agent-config"

package/scripts/mcp_server/__main__.py

@@ -0,0 +1,12 @@
+"""Entrypoint — `python -m scripts.mcp_server`.
+
+Required by Claude Desktop / Zed / Continue stdio-server config.
+The wrapper forwards to `server.main()`; keep this file flat so
+crash tracebacks point at server.py, not the bootstrap.
+"""
+from __future__ import annotations
+
+from .server import main
+
+if __name__ == "__main__":
+    main()

package/scripts/mcp_server/metadata.py

@@ -0,0 +1,75 @@
+"""Phase-6 F1 — server identity metadata.
+
+Three values surfaced at boot via stderr (`run_stdio` boot log):
+
+- **server version** — wire-surface SemVer in `__init__.py::__version__`.
+  Hand-bumped when the MCP-side surface (prompts/resources/tools shape,
+  protocol semantics) changes.
+- **package version** — read from `package.json::version` at boot.
+  Build-ID semantics; bumps with every release of the agent-config bundle.
+- **skill-set signature** — SHA-256 hex (first 12 chars) over the joined
+  `PromptCache._signature` + `ResourceCache._signature` tuples
+  (`(uri, mtime)` pairs, already sorted). Content fingerprint, not a
+  version — auto-derived, never hand-edited.
+
+Wire-surface caveat: the MCP SDK constructs `serverInfo.Implementation`
+internally with a fixed field set (`name`, `version`, `websiteUrl`,
+`icons`), so the package version and skill-set signature cannot be
+attached to `serverInfo._meta` without subclassing the session.
+Stderr is the canonical surface in Phase 6; a wire-surface lift can
+follow once the SDK supports it.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Sequence
+
+Signature = Sequence[tuple[str, float]]
+
+
+def read_package_version(root: Path) -> str:
+    """Return `package.json::version`, or `"unknown"` if unreadable."""
+    path = root / "package.json"
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return "unknown"
+    version = data.get("version")
+    if not isinstance(version, str) or not version:
+        return "unknown"
+    return version
+
+
+def compute_skill_set_signature(*signatures: Signature) -> str:
+    """SHA-256 hex (12 chars) over the concatenated `(uri, mtime)` tuples.
+
+    Deterministic across processes for identical inputs. Changes when
+    any tracked file's path-set or mtime changes. Inputs are taken as-is
+    (callers pass already-sorted cache signatures); the hash is taken
+    over the joined repr to keep the framing unambiguous.
+    """
+    hasher = hashlib.sha256()
+    for sig in signatures:
+        for uri, mtime in sig:
+            hasher.update(uri.encode("utf-8"))
+            hasher.update(b"\x00")
+            hasher.update(f"{mtime:.6f}".encode("ascii"))
+            hasher.update(b"\x1e")  # record separator
+        hasher.update(b"\x1d")  # group separator between caches
+    return hasher.hexdigest()[:12]
+
+
+def boot_log_line(
+    *,
+    server_version: str,
+    package_version: str,
+    skill_set_signature: str,
+) -> str:
+    """Single stderr line surfacing all three identity values at boot."""
+    return (
+        f"mcp-server: identity serverVersion={server_version} "
+        f"packageVersion={package_version} "
+        f"skillSetSignature={skill_set_signature}"
+    )

package/scripts/mcp_server/prompts.py

@@ -0,0 +1,305 @@
+"""Prompt loader — reads `.agent-src/skills/` and `.agent-src/commands/`.
+
+Phase 1 (A4) exposed 5 hand-picked, stack-agnostic skills. Phase 2
+(B1–B3) extends to the full set: every `SKILL.md` under
+`.agent-src/skills/` plus every `*.md` under `.agent-src/commands/`.
+
+Frontmatter `name` + `description` map to MCP prompt metadata; the
+body (frontmatter stripped) is the prompt content. Frontmatter
+`source:` is forwarded verbatim into the MCP `_meta` field so clients
+can filter package-vs-project entries on the wire.
+
+Project-overrides resolution: `.agent-src/` is the already-merged
+view at sync time; the runtime loader does not re-merge.
+
+Frontmatter validation (B3): entries missing `name` or `description`
+are skipped and surfaced in the second tuple element of `scan_*`
+helpers (caller decides whether to log).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+# Phase 1 hand-picked skills — kept for the Phase-1 entrypoint
+# (`load_phase_1_prompts`) and as the contract-test fixture set. The
+# roadmap originally listed `verify-before-complete`, which lives as
+# a rule, not a skill; its skill counterpart is
+# `verify-completion-evidence` (same evidence-gate obligation).
+PHASE_1_SKILLS: tuple[str, ...] = (
+    "verify-completion-evidence",
+    "systematic-debugging",
+    "test-driven-development",
+    "refine-ticket",
+    "conventional-commits-writing",
+)
+
+PromptKind = Literal["skill", "command"]
+
+
+@dataclass(frozen=True)
+class SkillPrompt:
+    """Resolved Markdown prompt ready for MCP exposure.
+
+    `kind` distinguishes the two Phase-2 source families. The name
+    field is the frontmatter `name:` value verbatim (e.g.
+    `test-driven-development` or `research:report`); MCP wire names
+    are derived in `to_mcp_prompt_meta` with `kind`-aware prefixing.
+    """
+
+    name: str
+    description: str
+    body: str
+    source: str
+    kind: PromptKind = "skill"
+
+
+def _project_root() -> Path:
+    """Walk up from this file to the repo root (parent of `scripts/`)."""
+    return Path(__file__).resolve().parent.parent.parent
+
+
+def _strip_frontmatter(text: str) -> tuple[dict[str, str], str]:
+    """Split a Markdown file with `---` frontmatter into (meta, body).
+
+    Tiny YAML-ish parser sufficient for our flat key/value frontmatter.
+    Avoids a `pyyaml` dependency for Phase 1; the frontmatter shape is
+    enforced by `task lint-skills` upstream.
+    """
+    if not text.startswith("---\n"):
+        return {}, text
+    try:
+        _, fm, body = text.split("---\n", 2)
+    except ValueError:
+        return {}, text
+    meta: dict[str, str] = {}
+    for line in fm.splitlines():
+        if not line.strip() or line.startswith("#"):
+            continue
+        if ":" not in line:
+            continue
+        key, _, value = line.partition(":")
+        meta[key.strip()] = value.strip().strip('"').strip("'")
+    return meta, body.lstrip("\n")
+
+
+def load_skill(name: str, root: Path | None = None) -> SkillPrompt:
+    """Load a single skill by name. Raises FileNotFoundError if missing."""
+    base = root or _project_root()
+    path = base / ".agent-src" / "skills" / name / "SKILL.md"
+    if not path.exists():
+        raise FileNotFoundError(f"SKILL.md not found: {path}")
+    return _load_file(path, kind="skill", fallback_name=name)
+
+
+def _load_file(
+    path: Path,
+    *,
+    kind: PromptKind,
+    fallback_name: str,
+) -> SkillPrompt:
+    text = path.read_text(encoding="utf-8")
+    meta, body = _strip_frontmatter(text)
+    return SkillPrompt(
+        name=meta.get("name", fallback_name),
+        description=meta.get("description", "").strip(),
+        body=body.rstrip() + "\n",
+        source=meta.get("source", "package"),
+        kind=kind,
+    )
+
+
+def load_phase_1_prompts(root: Path | None = None) -> list[SkillPrompt]:
+    """Load every skill listed in PHASE_1_SKILLS.
+
+    Kept for backward compatibility with Phase-1 tests and as a
+    minimal smoke path. Production entrypoint is `load_all_prompts`.
+    """
+    prompts: list[SkillPrompt] = []
+    errors: list[str] = []
+    for name in PHASE_1_SKILLS:
+        try:
+            prompts.append(load_skill(name, root=root))
+        except FileNotFoundError as exc:
+            errors.append(str(exc))
+    if errors and not prompts:
+        raise RuntimeError(
+            "No Phase 1 skills loaded. Errors:\n  - "
+            + "\n  - ".join(errors)
+        )
+    return prompts
+
+
+def scan_skills(
+    root: Path | None = None,
+) -> tuple[list[SkillPrompt], list[str]]:
+    """Enumerate every `.agent-src/skills/*/SKILL.md`.
+
+    Returns `(prompts, errors)`. Files missing `name` or
+    `description` frontmatter are skipped with a one-line reason in
+    `errors`. Files that fail to read are surfaced the same way.
+    """
+    base = root or _project_root()
+    skills_root = base / ".agent-src" / "skills"
+    prompts: list[SkillPrompt] = []
+    errors: list[str] = []
+    if not skills_root.is_dir():
+        return prompts, errors
+    for skill_dir in sorted(skills_root.iterdir()):
+        path = skill_dir / "SKILL.md"
+        if not path.is_file():
+            continue
+        try:
+            prompt = _load_file(path, kind="skill", fallback_name=skill_dir.name)
+        except OSError as exc:
+            errors.append(f"{path}: read failed ({exc})")
+            continue
+        if not prompt.description:
+            errors.append(f"{path}: missing frontmatter description")
+            continue
+        prompts.append(prompt)
+    return prompts, errors
+
+
+def scan_commands(
+    root: Path | None = None,
+) -> tuple[list[SkillPrompt], list[str]]:
+    """Enumerate every `.agent-src/commands/**/*.md`.
+
+    Same return contract as `scan_skills`. Command frontmatter `name:`
+    values use `:` as cluster/sub separator (e.g. `research:report`);
+    the value is preserved verbatim and translated to MCP wire form
+    in `to_mcp_prompt_meta`.
+    """
+    base = root or _project_root()
+    cmd_root = base / ".agent-src" / "commands"
+    prompts: list[SkillPrompt] = []
+    errors: list[str] = []
+    if not cmd_root.is_dir():
+        return prompts, errors
+    for path in sorted(cmd_root.rglob("*.md")):
+        if not path.is_file():
+            continue
+        rel = path.relative_to(cmd_root).with_suffix("")
+        fallback = str(rel).replace("/", ":")
+        try:
+            prompt = _load_file(path, kind="command", fallback_name=fallback)
+        except OSError as exc:
+            errors.append(f"{path}: read failed ({exc})")
+            continue
+        if not prompt.description:
+            errors.append(f"{path}: missing frontmatter description")
+            continue
+        prompts.append(prompt)
+    return prompts, errors
+
+
+def load_all_prompts(
+    root: Path | None = None,
+) -> tuple[list[SkillPrompt], list[str]]:
+    """Phase 2 entrypoint — all skills + all commands.
+
+    Result is sorted by MCP wire name (deterministic across boots)
+    and de-duplicated: if the same wire name appears in both lists
+    (should not happen in a clean tree) the skill copy wins and the
+    duplicate is reported in `errors`.
+    """
+    skills, skill_errors = scan_skills(root)
+    commands, command_errors = scan_commands(root)
+    errors = list(skill_errors) + list(command_errors)
+    seen: dict[str, SkillPrompt] = {}
+    for prompt in skills + commands:
+        wire = to_mcp_prompt_meta(prompt)["name"]
+        if wire in seen:
+            errors.append(
+                f"duplicate MCP name {wire!r}: keeping {seen[wire].kind}, "
+                f"skipping {prompt.kind}"
+            )
+            continue
+        seen[wire] = prompt
+    merged = sorted(seen.values(), key=lambda p: to_mcp_prompt_meta(p)["name"])
+    return merged, errors
+
+
+def to_mcp_prompt_meta(prompt: SkillPrompt) -> dict[str, Any]:
+    """Project a SkillPrompt into MCP `Prompt` constructor kwargs.
+
+    Wire-name shape:
+        skill.<frontmatter-name>            (skills)
+        command.<frontmatter-name with : → .>  (commands)
+    Colons in command names (e.g. `research:report`) become `.` so
+    the wire identifier is a single-segment dotted path that survives
+    every MCP client we have tested.
+    """
+    if prompt.kind == "command":
+        wire = f"command.{prompt.name.replace(':', '.')}"
+    else:
+        wire = f"skill.{prompt.name}"
+    return {
+        "name": wire,
+        "title": prompt.name,
+        "description": prompt.description,
+        "arguments": [],
+        "_meta": {"source": prompt.source, "kind": prompt.kind},
+    }
+
+
+class PromptCache:
+    """In-memory cache with mtime-based invalidation (B5 hot-reload).
+
+    `get()` re-scans `.agent-src/skills/` and `.agent-src/commands/`
+    when any tracked SKILL.md / command file has changed mtime since
+    the previous scan. New / removed files also trigger a refresh
+    (the set of tracked paths is part of the staleness key).
+
+    The cache is intentionally simple: no inotify, no debounce, no
+    background thread. The server calls `get()` once per
+    `prompts/list` request, which is the natural rate-limiter.
+    """
+
+    def __init__(self, root: Path | None = None) -> None:
+        self._root = root or _project_root()
+        self._prompts: list[SkillPrompt] = []
+        self._errors: list[str] = []
+        self._signature: tuple[tuple[str, float], ...] = ()
+        self._index: dict[str, SkillPrompt] = {}
+
+    def _current_signature(self) -> tuple[tuple[str, float], ...]:
+        entries: list[tuple[str, float]] = []
+        skills_root = self._root / ".agent-src" / "skills"
+        if skills_root.is_dir():
+            for skill_dir in sorted(skills_root.iterdir()):
+                path = skill_dir / "SKILL.md"
+                if path.is_file():
+                    entries.append((str(path), path.stat().st_mtime))
+        cmd_root = self._root / ".agent-src" / "commands"
+        if cmd_root.is_dir():
+            for path in sorted(cmd_root.rglob("*.md")):
+                if path.is_file():
+                    entries.append((str(path), path.stat().st_mtime))
+        return tuple(entries)
+
+    def _refresh(self) -> None:
+        prompts, errors = load_all_prompts(self._root)
+        self._prompts = prompts
+        self._errors = errors
+        self._index = {to_mcp_prompt_meta(p)["name"]: p for p in prompts}
+
+    def get(self) -> tuple[list[SkillPrompt], list[str]]:
+        """Return cached prompts + errors, refreshing on mtime change."""
+        signature = self._current_signature()
+        if signature != self._signature:
+            self._signature = signature
+            self._refresh()
+        return self._prompts, self._errors
+
+    @property
+    def signature(self) -> tuple[tuple[str, float], ...]:
+        """Cached `(path, mtime)` tuples (Phase-6 F1 input). Call `get()` first."""
+        return self._signature
+
+    def lookup(self, wire_name: str) -> SkillPrompt | None:
+        """Resolve an MCP wire name to its SkillPrompt, refreshing first."""
+        self.get()
+        return self._index.get(wire_name)

package/scripts/mcp_server/requirements.txt

@@ -0,0 +1,4 @@
+# MCP server runtime — pinned to the versions the test suite ran against.
+# Mirror upstream when bumping; keep this lean (no dev/test deps).
+mcp==1.27.1
+PyYAML==6.0.3