@event4u/agent-config 1.39.0 → 1.41.0

package/scripts/mcp_parity_smoke.py

@@ -29,8 +29,10 @@ from typing import Any
 _SCRIPTS = Path(__file__).resolve().parent
 sys.path.insert(0, str(_SCRIPTS))
 
+from mcp_server.catalog import load_catalog  # noqa: E402
 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
+from mcp_server.tools import ALLOWLIST  # noqa: E402
 
 PAGE_SIZE = 50
 
@@ -96,6 +98,21 @@ def _normalize_resources(payload: dict[str, Any]) -> list[dict[str, Any]]:
     return sorted(out, key=lambda x: x["uri"])
 
 
+def _local_tools_list() -> dict[str, Any]:
+    """Tools catalog + allowlist as the stdio server publishes them."""
+    catalog_names = [c.name for c in load_catalog()]
+    allowlist_names = list(ALLOWLIST.keys())
+    return {"tools": [{"name": n} for n in sorted(set(catalog_names + allowlist_names))]}
+
+
+def _normalize_tools(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    """Compare on `name` only — descriptions / schemas drift acceptably."""
+    return sorted(
+        [{"name": t["name"]} for t in payload.get("tools", [])],
+        key=lambda x: x["name"],
+    )
+
+
 def _diff(label: str, local: list[Any], remote: list[Any]) -> int:
     if local == remote:
         print(f"✅  {label}: {len(local)} entries match")
@@ -129,8 +146,9 @@ def main() -> int:
     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)")
+        local_t = _normalize_tools(_local_tools_list())
+        remote_t = _normalize_tools(_rpc(args.target, "tools/list"))
+        failed += _diff("tools/list", local_t, remote_t)
     except Exception as e:
         print(f"❌  tools/list: {e}")
         failed += 1

package/scripts/mcp_server/catalog.py

@@ -0,0 +1,125 @@
+"""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 (`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/scripts/mcp_server/consumer_tool_catalog.json

@@ -0,0 +1,275 @@
+{
+  "schema_version": 1,
+  "description": "Source-of-truth catalog of consumer-relevant MCP tools. Read by the stdio server (scripts/mcp_server/) and packed into the Cloud Worker bundle (workers/mcp/). Phase 1 of road-to-mcp-full-coverage: tools without 'implemented' transports return the 'not_implemented' envelope defined in docs/contracts/mcp-tool-stub-envelope.md. The 'implemented_on' field lists transports where the real handler is wired; everything else is a discovery stub. See agents/roadmaps/road-to-mcp-full-coverage.md.",
+  "install_hint_stdio": "pip install agent-config[mcp] && ./agent-config mcp:run",
+  "tools": [
+    {
+      "name": "lint_skills",
+      "description": "Lint skill / rule / command / guideline / persona markdown files. Returns the same JSON payload as `scripts/skill_linter.py --format json`. Read-only — never writes or spawns git. Pass `paths` to lint a subset, omit for a full tree scan.",
+      "side_effect": "ro",
+      "implemented_on": ["stdio"],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "paths": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "Repo-relative paths to lint. Empty / missing → full tree scan."
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "chat_history_append",
+      "description": "Append one entry to the consumer's chat-history JSONL (`agents/.agent-chat-history`). Path-scoped — writes outside the allowlist raise ValueError. Use `dry_run` to preview the payload without touching the filesystem.",
+      "side_effect": "fs-write",
+      "implemented_on": ["stdio"],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "text": {"type": "string"},
+          "entry_type": {"type": "string", "description": "Short `t` tag (e.g. note, decision). Defaults to `note`."},
+          "path": {"type": "string", "description": "Optional path override. Must resolve to `agents/.agent-chat-history` or `.agent-chat-history` under consumer_root."},
+          "session": {"type": "string"},
+          "dry_run": {"type": "boolean", "default": false},
+          "min_schema_version": {"type": "integer"}
+        },
+        "required": ["text"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "chat_history_read",
+      "description": "Read recent chat-history entries from `agents/.agent-chat-history`. Filter by session, limit, or entry-type. Read-only.",
+      "side_effect": "ro",
+      "implemented_on": ["stdio"],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "last": {"type": "integer", "description": "Return only the last N entries.", "minimum": 1},
+          "session": {"type": "string", "description": "Filter by 16-char session id."},
+          "entry_type": {"type": "string", "description": "Filter by `t` field."},
+          "path": {"type": "string"}
+        },
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "memory_lookup",
+      "description": "Hybrid memory retrieval over `agents/memory/<type>/*.yml` and `agents/memory/intake/*.jsonl`. Read-only.",
+      "side_effect": "ro",
+      "implemented_on": ["stdio"],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "types": {"type": "array", "items": {"type": "string"}, "description": "Memory types to scan (e.g. ownership, historical-patterns)."},
+          "keys": {"type": "array", "items": {"type": "string"}, "description": "Path / glob keys to match."},
+          "limit": {"type": "integer", "minimum": 1, "default": 5}
+        },
+        "required": ["types"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "memory_signal",
+      "description": "Append an engineering-memory signal to `agents/memory/intake/signals-YYYY-MM.jsonl`. Rate-limited per `(type, path)` within a rolling window.",
+      "side_effect": "fs-write",
+      "implemented_on": [],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "type": {"type": "string", "description": "Memory type (historical-patterns, incident-learnings, ownership, ...)."},
+          "path": {"type": "string", "description": "Anchor path the signal is about."},
+          "body": {"type": "string", "description": "Free-form signal body."}
+        },
+        "required": ["type", "path", "body"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "memory_status",
+      "description": "Report whether the optional `@event4u/agent-memory` package is reachable, and surface its routing metadata. Read-only.",
+      "side_effect": "ro",
+      "implemented_on": ["stdio"],
+      "input_schema": {"type": "object", "properties": {}, "additionalProperties": false}
+    },
+    {
+      "name": "skill_trigger_eval",
+      "description": "Score a user message against the compiled router and return the matching skills with their trigger reasons. Read-only.",
+      "side_effect": "ro",
+      "implemented_on": [],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "message": {"type": "string"},
+          "context": {"type": "string", "description": "Optional recent-turn context."},
+          "limit": {"type": "integer", "minimum": 1, "default": 5}
+        },
+        "required": ["message"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "suggest_command",
+      "description": "Run the command-suggestion engine: score commands against a user message + context and return the numbered options block. Read-only, deterministic.",
+      "side_effect": "ro",
+      "implemented_on": [],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "message": {"type": "string"},
+          "context": {"type": "string"}
+        },
+        "required": ["message"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "suggest_skill_for_task",
+      "description": "Match a free-form task description to the most relevant skills with frontmatter triggers. Read-only.",
+      "side_effect": "ro",
+      "implemented_on": [],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "task": {"type": "string"},
+          "limit": {"type": "integer", "minimum": 1, "default": 5}
+        },
+        "required": ["task"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "mine_session",
+      "description": "Extract patterns, decisions, and learnings from a chat-history session JSONL. Read-only.",
+      "side_effect": "ro",
+      "implemented_on": [],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "session": {"type": "string", "description": "Session id to mine."},
+          "path": {"type": "string", "description": "Optional path to a chat-history JSONL."}
+        },
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "update_form_request_messages",
+      "description": "Sync the `messages()` method of a Laravel FormRequest class — add missing entries, link to language keys, drop stale ones.",
+      "side_effect": "fs-write",
+      "implemented_on": [],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "request_class": {"type": "string", "description": "Fully-qualified FormRequest class FQN or repo-relative file path."},
+          "dry_run": {"type": "boolean", "default": false}
+        },
+        "required": ["request_class"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "sync_gitignore",
+      "description": "Synchronise the `event4u/agent-config` block in the consumer project's `.gitignore` — adds missing entries, preserves user-added lines.",
+      "side_effect": "fs-write",
+      "implemented_on": [],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "dry_run": {"type": "boolean", "default": false}
+        },
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "sync_agent_settings",
+      "description": "Synchronise `.agent-settings.yml` against the current template + profile — adds new sections/keys, preserves user values.",
+      "side_effect": "fs-write",
+      "implemented_on": [],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "profile": {"type": "string", "description": "Override the profile pinned in the settings file."},
+          "dry_run": {"type": "boolean", "default": false}
+        },
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "run_tests",
+      "description": "Execute the consumer project's test suite via the project's standard test runner. Returns the exit code, runner name, and a structured tail of the output.",
+      "side_effect": "shell",
+      "implemented_on": [],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "filter": {"type": "string", "description": "Restrict to tests matching this pattern."},
+          "path": {"type": "string", "description": "Restrict to tests under this directory."}
+        },
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "run_quality_checks",
+      "description": "Run the configured quality gate (PHPStan / Rector / ECS / equivalent) and return a structured per-tool result.",
+      "side_effect": "shell",
+      "implemented_on": [],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "tool": {"type": "string", "description": "Restrict to a single tool name."}
+        },
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "list_skills",
+      "description": "Enumerate every skill currently exposed as a prompt, with name + description + source. Read-only manifest view.",
+      "side_effect": "ro",
+      "implemented_on": ["stdio"],
+      "input_schema": {"type": "object", "properties": {}, "additionalProperties": false}
+    },
+    {
+      "name": "list_commands",
+      "description": "Enumerate every slash command currently exposed as a prompt. Read-only manifest view.",
+      "side_effect": "ro",
+      "implemented_on": ["stdio"],
+      "input_schema": {"type": "object", "properties": {}, "additionalProperties": false}
+    },
+    {
+      "name": "list_rules",
+      "description": "Enumerate every rule currently exposed as a resource. Read-only manifest view.",
+      "side_effect": "ro",
+      "implemented_on": ["stdio"],
+      "input_schema": {"type": "object", "properties": {}, "additionalProperties": false}
+    },
+    {
+      "name": "compile_router",
+      "description": "Regenerate the compiled router (`router.compiled.json`) from the current rule / skill / command frontmatter. Shell-bound — wraps `scripts/compile_router.py`.",
+      "side_effect": "shell",
+      "implemented_on": [],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "dry_run": {"type": "boolean", "default": false}
+        },
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "read_resource_body",
+      "description": "Fetch the rendered body of any resource URI (rule, guideline, context) without going through `resources/read`. Convenience for clients that want to inline content into a tool call result.",
+      "side_effect": "ro",
+      "implemented_on": ["stdio"],
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "uri": {"type": "string", "description": "Resource URI like `rule://commit-policy`."}
+        },
+        "required": ["uri"],
+        "additionalProperties": false
+      }
+    }
+  ]
+}

package/scripts/mcp_server/telemetry.py

@@ -0,0 +1,128 @@
+"""MCP telemetry sink — Phase 1 J4 instrumentation.
+
+Per ``agents/roadmaps/road-to-mcp-full-coverage.md`` §Phase 1 J4 +
+``docs/contracts/mcp-tool-stub-envelope.md``, both transports log every
+``tools/call`` with ``{tool_name, client_id_hash, ts, transport,
+outcome}``. Payload bodies are never logged; the client identifier is
+hashed at the server boundary so the queryable store never sees raw
+identity.
+
+Outcomes:
+
+- ``implemented`` — real handler ran (no envelope returned).
+- ``stub`` — catalog entry missing this transport; ``not_implemented``
+  envelope returned.
+- ``latent_demand`` — caller asked for a tool not in the catalog.
+
+The sink writes JSONL to ``agents/.mcp-telemetry/calls.jsonl`` under the
+consumer root. Failure to write must not break the wire surface: the
+``record_call`` helper swallows OSError + ValueError and emits a single
+warning to stderr.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Literal
+
+Outcome = Literal["implemented", "stub", "latent_demand"]
+
+# Stable file location relative to consumer_root. Phase 2 K1 routes
+# this into a queryable store; Phase 1 only needs the file to exist.
+TELEMETRY_REL_DIR = "agents/.mcp-telemetry"
+TELEMETRY_FILENAME = "calls.jsonl"
+
+# Truncation length for the client_id hash. 12 hex chars = 48 bits of
+# entropy — enough to distinguish hundreds of consumers without
+# becoming a re-identification vector.
+_HASH_LEN = 12
+
+
+def _client_id_seed() -> str:
+    """Identity components that together pin a consumer install.
+
+    USER + machine hostname + repo path is a stable triple that survives
+    sessions without leaking PII into the log. The hash never reverses.
+    """
+    user = os.environ.get("USER") or os.environ.get("USERNAME") or "unknown"
+    host = os.environ.get("HOSTNAME")
+    if not host and hasattr(os, "uname"):
+        host = os.uname().nodename
+    host = host or "unknown"
+    cwd = str(Path.cwd().resolve())
+    return f"{user}|{host}|{cwd}"
+
+
+def hash_client_id(seed: str | None = None) -> str:
+    """SHA-256(seed) truncated to 12 hex chars. Boundary-only call."""
+    raw = seed if seed is not None else _client_id_seed()
+    digest = hashlib.sha256(raw.encode("utf-8")).hexdigest()
+    return digest[:_HASH_LEN]
+
+
+def _resolve_log_path(consumer_root: Path | None = None) -> Path:
+    """Pick the JSONL location. Defaults to CWD when no override given."""
+    root = (consumer_root or Path.cwd()).resolve()
+    return root / TELEMETRY_REL_DIR / TELEMETRY_FILENAME
+
+
+def _now_iso() -> str:
+    """ISO-8601 UTC timestamp, seconds precision."""
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def build_record(
+    *,
+    tool_name: str,
+    outcome: Outcome,
+    transport: str,
+    client_id_hash_value: str | None = None,
+    ts: str | None = None,
+) -> dict[str, object]:
+    """Pure helper — assemble the record without touching the filesystem."""
+    return {
+        "tool_name": tool_name,
+        "client_id_hash": client_id_hash_value or hash_client_id(),
+        "ts": ts or _now_iso(),
+        "transport": transport,
+        "outcome": outcome,
+    }
+
+
+def record_call(
+    *,
+    tool_name: str,
+    outcome: Outcome,
+    transport: str,
+    consumer_root: Path | None = None,
+    client_id_hash_value: str | None = None,
+) -> dict[str, object] | None:
+    """Append one JSONL record. Returns the record or None on failure.
+
+    Failures are swallowed: telemetry must never break the wire surface.
+    A single ``mcp-server: warn: telemetry`` line is emitted to stderr
+    so silent-failure windows show up in the boot log and the J6
+    healthcheck can detect them.
+    """
+    record = build_record(
+        tool_name=tool_name,
+        outcome=outcome,
+        transport=transport,
+        client_id_hash_value=client_id_hash_value,
+    )
+    target = _resolve_log_path(consumer_root)
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        with target.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(record, separators=(",", ":")) + "\n")
+    except (OSError, ValueError) as exc:
+        print(
+            f"mcp-server: warn: telemetry write failed: {exc}",
+            file=sys.stderr,
+        )
+        return None
+    return record