@event4u/agent-config 6.1.0 → 7.0.0

package/src/scripts/mcp_render.py

@@ -1,173 +0,0 @@
-#!/usr/bin/env python3
-"""
-MCP config renderer — one ``mcp.json`` → per-tool output files.
-
-Reads ``mcp.json`` at repo root (``{ "servers": { <name>: { command, args,
-env, cwd } } }``), substitutes ``${env:VAR}`` placeholders from the
-environment, and writes each target tool's concrete config format.
-
-Targets:
-    .cursor/mcp.json                                       (in-project)
-    .windsurf/mcp.json                                     (in-project)
-    ~/.config/claude-desktop/claude_desktop_config.json    (user, opt-in)
-
-All targets use the same ``mcpServers`` top-level key. The source file
-uses ``servers`` to keep our internal schema stable if a downstream
-format ever diverges.
-
-Failure mode: unresolved ``${env:VAR}`` placeholders are collected first,
-then reported together and a non-zero exit is raised. No target file is
-written when any placeholder is missing.
-
-See docs/mcp.md for schema, usage, and worked examples.
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import re
-import sys
-from pathlib import Path
-from typing import Any
-
-ENV_PLACEHOLDER = re.compile(r"\$\{env:([^}]+)\}")
-
-# Project root defaults to the current working directory so the renderer
-# works both for package maintainers (running from the package root via
-# Taskfile) and for consumer projects (running via `./agent-config
-# mcp:render` from their own repo root). Override with --project-root.
-def default_project_root() -> Path:
-    return Path.cwd().resolve()
-
-
-def in_project_targets(project_root: Path) -> dict[str, Path]:
-    return {
-        "cursor": project_root / ".cursor" / "mcp.json",
-        "windsurf": project_root / ".windsurf" / "mcp.json",
-    }
-
-
-CLAUDE_DESKTOP_TARGET = Path.home() / ".config" / "claude-desktop" / "claude_desktop_config.json"
-
-
-def substitute(value: Any, path: str, missing: list[tuple[str, str]]) -> Any:
-    """Recursively substitute ${env:VAR} in strings.
-
-    Missing variables are appended to ``missing`` as ``(var_name, json_path)``
-    instead of raising, so a single run surfaces *all* gaps at once.
-    """
-    if isinstance(value, str):
-        def repl(match: re.Match[str]) -> str:
-            name = match.group(1)
-            env_value = os.environ.get(name)
-            if env_value is None:
-                missing.append((name, path))
-                return match.group(0)
-            return env_value
-        return ENV_PLACEHOLDER.sub(repl, value)
-    if isinstance(value, dict):
-        return {k: substitute(v, f"{path}.{k}", missing) for k, v in value.items()}
-    if isinstance(value, list):
-        return [substitute(v, f"{path}[{i}]", missing) for i, v in enumerate(value)]
-    return value
-
-
-def load_source(source: Path) -> dict[str, Any]:
-    if not source.exists():
-        raise SystemExit(f"❌  Source file not found: {source}")
-    try:
-        data = json.loads(source.read_text(encoding="utf-8"))
-    except json.JSONDecodeError as exc:
-        raise SystemExit(f"❌  Invalid JSON in {source}: {exc}") from exc
-    if not isinstance(data, dict) or "servers" not in data or not isinstance(data["servers"], dict):
-        raise SystemExit(f"❌  {source} must contain a top-level 'servers' object.")
-    return data
-
-
-def render(data: dict[str, Any]) -> tuple[dict[str, Any], list[tuple[str, str]]]:
-    """Return (rendered, missing). Caller decides what to do on missing."""
-    missing: list[tuple[str, str]] = []
-    resolved_servers = substitute(data["servers"], "servers", missing)
-    return {"mcpServers": resolved_servers}, missing
-
-
-def format_missing_report(missing: list[tuple[str, str]]) -> str:
-    grouped: dict[str, list[str]] = {}
-    for name, path in missing:
-        grouped.setdefault(name, []).append(path)
-    lines = [f"❌  Unresolved ${{env:VAR}} placeholders ({len(grouped)} variable(s)):"]
-    for name in sorted(grouped):
-        lines.append(f"  - {name}  used at:")
-        for path in grouped[name]:
-            lines.append(f"      {path}")
-    lines.append("\nSet the variable(s) in your environment and re-run.")
-    return "\n".join(lines)
-
-
-def write_target(path: Path, content: dict[str, Any]) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    serialized = json.dumps(content, indent=2, sort_keys=True) + "\n"
-    path.write_text(serialized, encoding="utf-8")
-
-
-def collect_targets(project_root: Path, include_claude_desktop: bool) -> dict[str, Path]:
-    targets = dict(in_project_targets(project_root))
-    if include_claude_desktop:
-        targets["claude-desktop"] = CLAUDE_DESKTOP_TARGET
-    return targets
-
-
-def resolve_source(args: argparse.Namespace, project_root: Path) -> Path:
-    return Path(args.source) if args.source else project_root / "mcp.json"
-
-
-def cmd_render(args: argparse.Namespace) -> int:
-    project_root = Path(args.project_root).resolve() if args.project_root else default_project_root()
-    data = load_source(resolve_source(args, project_root))
-    rendered, missing = render(data)
-    if missing:
-        print(format_missing_report(missing), file=sys.stderr)
-        return 1
-    targets = collect_targets(project_root, args.claude_desktop)
-    for name, path in targets.items():
-        write_target(path, rendered)
-        print(f"✅  {name:16} → {path}")
-    return 0
-
-
-def cmd_check(args: argparse.Namespace) -> int:
-    project_root = Path(args.project_root).resolve() if args.project_root else default_project_root()
-    data = load_source(resolve_source(args, project_root))
-    rendered, missing = render(data)
-    if missing:
-        print(format_missing_report(missing), file=sys.stderr)
-        return 1
-    serialized = json.dumps(rendered, indent=2, sort_keys=True) + "\n"
-    targets = collect_targets(project_root, args.claude_desktop)
-    diffs = []
-    for name, path in targets.items():
-        actual = path.read_text(encoding="utf-8") if path.exists() else ""
-        if actual != serialized:
-            diffs.append((name, path))
-    if diffs:
-        print("❌  Targets out of date (run `./agent-config mcp:render`):", file=sys.stderr)
-        for name, path in diffs:
-            print(f"  - {name}: {path}", file=sys.stderr)
-        return 1
-    print("✅  All MCP targets match source.")
-    return 0
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(description="Render mcp.json → per-tool config files.")
-    parser.add_argument("--source", default=None, help="Source mcp.json (default: <project-root>/mcp.json)")
-    parser.add_argument("--project-root", default=None, help="Project root for resolving source and targets (default: CWD)")
-    parser.add_argument("--claude-desktop", action="store_true", help="Also write Claude Desktop user-scope config")
-    parser.add_argument("--check", action="store_true", help="Dry-run; exit non-zero if targets are stale")
-    args = parser.parse_args(argv)
-    return cmd_check(args) if args.check else cmd_render(args)
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/src/scripts/mcp_server/__init__.py

@@ -1,19 +0,0 @@
-"""MCP server for agent-config — Phase 1 MVP.
-
-mcp_scope: full — local stdio access can be extended to tool execution
-under the Phase 7 wake-up triggers in `docs/contracts/mcp-cloud-scope.md`.
-The hosted Worker (`internal/workers/mcp/`) is `mcp_scope: lite` and is
-intentionally narrower.
-
-Exposes a hand-picked subset of `dist/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`.
-Promotion to beta gated on `docs/contracts/mcp-beta-criteria.md`.
-"""
-from __future__ import annotations
-
-__version__ = "0.1.0"
-SERVER_NAME = "agent-config"

package/src/scripts/mcp_server/__main__.py

@@ -1,12 +0,0 @@
-"""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/src/scripts/mcp_server/catalog.py

@@ -1,125 +0,0 @@
-"""Consumer tool catalog — source of truth for Phase 1 discovery stubs.
-
-Loaded once at module import from ``consumer_tool_catalog.json``. Both
-the stdio server (``tools.py``) and the cloud pack
-(``scripts/pack_mcp_content.py``) read from this file so the manifest
-returned by ``tools/list`` on either transport is byte-identical apart
-from per-tool ``implemented_on`` metadata.
-
-Side-effect classification (``ro`` / ``fs-write`` / ``shell``) and the
-``not_implemented`` envelope contract live in
-``docs/contracts/mcp-tool-stub-envelope.md``.
-"""
-from __future__ import annotations
-
-import json
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Any
-
-_CATALOG_FILE = Path(__file__).resolve().parent / "consumer_tool_catalog.json"
-
-# Stable error code surfaced in the ``not_implemented`` envelope. The
-# Worker mirrors this string verbatim — keep them in sync via the
-# envelope contract.
-NOT_IMPLEMENTED_CODE = "not_implemented"
-
-
-@dataclass(frozen=True)
-class CatalogEntry:
-    """One row in ``consumer_tool_catalog.json``.
-
-    ``implemented_on`` lists transports where a real handler is wired
-    (``stdio`` / ``worker``); missing transports return the
-    ``not_implemented`` envelope.
-    """
-
-    name: str
-    description: str
-    side_effect: str
-    implemented_on: tuple[str, ...]
-    input_schema: dict[str, Any]
-
-
-def _validate(raw: dict[str, Any]) -> None:
-    """Refuse to boot on a malformed catalog. Boot-time errors only."""
-    if raw.get("schema_version") != 1:
-        raise ValueError(
-            f"catalog: unsupported schema_version="
-            f"{raw.get('schema_version')!r}; expected 1"
-        )
-    tools = raw.get("tools")
-    if not isinstance(tools, list) or not tools:
-        raise ValueError("catalog: 'tools' must be a non-empty list")
-    seen: set[str] = set()
-    for entry in tools:
-        if not isinstance(entry, dict):
-            raise ValueError("catalog: every tool entry must be an object")
-        for field in ("name", "description", "side_effect", "input_schema"):
-            if field not in entry:
-                raise ValueError(f"catalog: tool missing '{field}'")
-        if entry["side_effect"] not in ("ro", "fs-write", "shell"):
-            raise ValueError(
-                f"catalog: tool {entry['name']!r} has invalid side_effect "
-                f"{entry['side_effect']!r} (expected ro / fs-write / shell)"
-            )
-        name = entry["name"]
-        if name in seen:
-            raise ValueError(f"catalog: duplicate tool name {name!r}")
-        seen.add(name)
-
-
-def load_catalog(path: Path | None = None) -> list[CatalogEntry]:
-    """Parse and validate the catalog. Returns entries in file order."""
-    target = path or _CATALOG_FILE
-    raw = json.loads(target.read_text(encoding="utf-8"))
-    _validate(raw)
-    return [
-        CatalogEntry(
-            name=t["name"],
-            description=t["description"],
-            side_effect=t["side_effect"],
-            implemented_on=tuple(t.get("implemented_on") or ()),
-            input_schema=t["input_schema"],
-        )
-        for t in raw["tools"]
-    ]
-
-
-def load_raw(path: Path | None = None) -> dict[str, Any]:
-    """Return the raw parsed JSON. Used by the cloud packer."""
-    target = path or _CATALOG_FILE
-    raw = json.loads(target.read_text(encoding="utf-8"))
-    _validate(raw)
-    return raw
-
-
-def install_hint(raw: dict[str, Any] | None = None) -> str:
-    """Stable install-hint surfaced in the envelope."""
-    data = raw if raw is not None else load_raw()
-    return str(data.get("install_hint_stdio") or "")
-
-
-def not_implemented_envelope(
-    tool_name: str,
-    *,
-    transport: str,
-    install_hint_value: str,
-) -> dict[str, Any]:
-    """Wire-shape error envelope used when a stub is invoked.
-
-    Mirrored verbatim by the Cloud Worker (`internal/workers/mcp/src/stubs.ts`).
-    """
-    return {
-        "code": NOT_IMPLEMENTED_CODE,
-        "tool": tool_name,
-        "transport": transport,
-        "install_hint": install_hint_value,
-        "alternative": "stdio",
-        "message": (
-            f"Tool '{tool_name}' is in the discovery catalog but not "
-            f"implemented on the {transport} transport. See the install "
-            "hint to wire it up locally, or check "
-            "docs/contracts/mcp-tool-stub-envelope.md."
-        ),
-    }

package/src/scripts/mcp_server/metadata.py

@@ -1,75 +0,0 @@
-"""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}"
-    )