@event4u/agent-config 1.36.1 → 1.38.0

package/scripts/mcp_server/tools.py

@@ -0,0 +1,363 @@
+"""MCP Server — Phase 4 tools layer.
+
+A0 contract amendment: Phase 4 lifts the read-only line for exactly the
+tools listed in ``ALLOWLIST`` (`lint_skills` + `chat_history_append`).
+Every other tool name is unreachable — `tools/call` against an unknown
+name raises ``ValueError``, not just "unlisted".
+
+Path-scoping is mandatory for any tool that writes: the resolved target
+path must stay under ``<consumer_root>`` and within the allowlist of
+filenames (`.agent-chat-history`, `agents/.agent-chat-history`). Escape
+attempts surface as ``ValueError`` before the underlying writer runs.
+
+This module deliberately does **not** import the ``subprocess`` module
+or ``os``-level shell-execution helpers directly. It imports project
+modules (``skill_linter``, ``chat_history``) that internally use them;
+the wire surface exposes no shell execution.
+
+Tools return ``dict`` from their handlers — the SDK wraps that in a
+``TextContent`` block with the JSON-serialized payload, so MCP clients
+can render structured output.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Awaitable, Callable
+
+# Allowlisted directories (relative to consumer_root) where tool writes
+# are permitted. ``chat_history_append`` resolves its path through this
+# guard before the underlying writer touches the filesystem.
+_ALLOWED_WRITE_REL_PATHS: frozenset[str] = frozenset(
+    {
+        "agents/.agent-chat-history",
+        ".agent-chat-history",
+    }
+)
+
+
+ToolHandler = Callable[[dict[str, Any], Path], Awaitable[dict[str, Any]]]
+
+
+@dataclass(frozen=True)
+class BuiltinTool:
+    """Static registration record for an allowlisted MCP tool.
+
+    ``input_schema`` is a JSON-Schema dict the SDK validates against on
+    each ``tools/call``. ``handler`` is an async function that receives
+    the validated arguments + the resolved ``consumer_root`` Path.
+    """
+
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    handler: ToolHandler
+
+
+def _resolve_consumer_root(override: Path | None = None) -> Path:
+    """Pick the consumer-project root.
+
+    Default: the current working directory. Tests pass an explicit
+    override; the stdio entrypoint relies on the CWD set by the
+    ``./agent-config mcp:run`` wrapper.
+    """
+    if override is not None:
+        return override.resolve()
+    return Path.cwd().resolve()
+
+
+def _validate_in_tree_path(raw: str | None, consumer_root: Path) -> Path:
+    """Resolve ``raw`` under ``consumer_root`` and assert it stays in tree.
+
+    Returns the resolved target path. Raises ``ValueError`` when the
+    path escapes the root or is not in the write allowlist. ``None``
+    falls back to the default chat-history location.
+    """
+    root = consumer_root.resolve()
+    if raw is None or raw == "":
+        target = root / "agents" / ".agent-chat-history"
+    else:
+        candidate = Path(raw)
+        if candidate.is_absolute():
+            target = candidate.resolve()
+        else:
+            target = (root / candidate).resolve()
+    try:
+        rel = target.relative_to(root)
+    except ValueError as exc:
+        raise ValueError(
+            f"path escapes consumer_root: {target} not under {root}"
+        ) from exc
+    rel_str = rel.as_posix()
+    if rel_str not in _ALLOWED_WRITE_REL_PATHS:
+        raise ValueError(
+            f"path not in write allowlist: {rel_str!r} "
+            f"(allowed: {sorted(_ALLOWED_WRITE_REL_PATHS)})"
+        )
+    return target
+
+
+async def _lint_skills_handler(
+    arguments: dict[str, Any],
+    consumer_root: Path,
+) -> dict[str, Any]:
+    """D2 — read-only wrapper around ``skill_linter.lint_file``.
+
+    Arguments:
+        paths: optional list of repo-relative paths to lint. Empty /
+            missing → lint the full ``.agent-src.uncompressed/`` tree
+            via ``gather_all_candidate_files``.
+
+    Never spawns ``git`` (no ``--changed`` mode); never writes; mirrors
+    the JSON output format of ``scripts/skill_linter.py --format json``.
+    """
+    # Import lazily so the loader-layer import-surface test stays clean.
+    from scripts.skill_linter import (  # noqa: PLC0415
+        format_json,
+        gather_all_candidate_files,
+        lint_file,
+    )
+
+    root = consumer_root.resolve()
+    requested = arguments.get("paths") or []
+    if not isinstance(requested, list):
+        raise ValueError("'paths' must be a list of strings")
+
+    paths: list[Path] = []
+    if requested:
+        for raw in requested:
+            if not isinstance(raw, str):
+                raise ValueError("'paths' entries must be strings")
+            candidate = Path(raw)
+            resolved = (
+                candidate.resolve()
+                if candidate.is_absolute()
+                else (root / candidate).resolve()
+            )
+            try:
+                resolved.relative_to(root)
+            except ValueError as exc:
+                raise ValueError(
+                    f"path escapes consumer_root: {resolved}"
+                ) from exc
+            if resolved.exists():
+                paths.append(resolved)
+    else:
+        paths = gather_all_candidate_files(root)
+
+    results = [lint_file(p, repo_root=root) for p in sorted(set(paths))]
+    payload = json.loads(format_json(results))
+    return payload
+
+
+async def _chat_history_append_handler(
+    arguments: dict[str, Any],
+    consumer_root: Path,
+) -> dict[str, Any]:
+    """D3 — append one entry to the consumer's chat-history JSONL.
+
+    Arguments:
+        text: free-form entry text. Stored under the ``text`` field.
+        entry_type: short ``t`` tag (e.g. ``note``, ``decision``).
+        path: optional override of the target file. Must resolve to one
+            of ``agents/.agent-chat-history`` / ``.agent-chat-history``
+            under ``consumer_root``.
+        session: optional 16-char session tag. Falls back to the most
+            recent body entry's ``s`` (see ``chat_history.append``).
+        dry_run: when true, validates the payload + path guard and
+            returns the entry that *would* be written without touching
+            the filesystem.
+        min_schema_version: when set, the call fails fast if the
+            chat-history schema version is below this number. Defaults
+            to ``None`` (no version check).
+
+    # TODO(phase-6): wrap the file write in ``fcntl.flock`` for SSE /
+    # multi-process safety. stdio is single-process so this is a moot
+    # concern in Phase 4.
+    """
+    from scripts.chat_history import (  # noqa: PLC0415
+        SCHEMA_VERSION,
+        append,
+        init,
+        read_header,
+    )
+
+    text = arguments.get("text")
+    if not isinstance(text, str) or not text.strip():
+        raise ValueError("'text' must be a non-empty string")
+    entry_type = arguments.get("entry_type") or "note"
+    if not isinstance(entry_type, str) or not entry_type.strip():
+        raise ValueError("'entry_type' must be a non-empty string")
+    if entry_type == "header":
+        raise ValueError("'entry_type' must not be 'header'")
+
+    session = arguments.get("session")
+    if session is not None and not isinstance(session, str):
+        raise ValueError("'session' must be a string when provided")
+
+    dry_run = bool(arguments.get("dry_run", False))
+
+    raw_path = arguments.get("path")
+    target = _validate_in_tree_path(raw_path, consumer_root)
+
+    min_schema = arguments.get("min_schema_version")
+    if min_schema is not None:
+        if not isinstance(min_schema, int):
+            raise ValueError("'min_schema_version' must be an integer")
+        existing_header = read_header(target) if target.exists() else None
+        observed = (
+            int(existing_header.get("v", 0))
+            if isinstance(existing_header, dict)
+            else SCHEMA_VERSION
+        )
+        if observed < min_schema:
+            raise ValueError(
+                f"chat-history schema {observed} below required "
+                f"{min_schema}"
+            )
+
+    entry: dict[str, Any] = {"t": entry_type, "text": text}
+
+    if dry_run:
+        return {
+            "dry_run": True,
+            "target_path": str(target),
+            "entry": entry,
+            "session": session,
+        }
+
+    # `append` requires the parent directory and a header line. Lazy-init
+    # the JSONL when the consumer hasn't run `agent-config chat:init` yet.
+    if not target.exists() or read_header(target) is None:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        init(path=target)
+    append(entry, path=target, session=session)
+    return {
+        "dry_run": False,
+        "target_path": str(target),
+        "entry": entry,
+        "session": session,
+    }
+
+
+# ---------------------------------------------------------------------
+# Allowlist — hardcoded per AI Council Q1-a verdict (2026-05-10).
+# Adding a tool here is a code-review event; settings cannot enable an
+# unlisted tool. Boot-time stderr log enumerates the registered set.
+# ---------------------------------------------------------------------
+
+ALLOWLIST: dict[str, BuiltinTool] = {
+    "lint_skills": BuiltinTool(
+        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."
+        ),
+        input_schema={
+            "type": "object",
+            "properties": {
+                "paths": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": (
+                        "Repo-relative paths to lint. Empty / missing → "
+                        "full tree scan via gather_all_candidate_files."
+                    ),
+                },
+            },
+            "additionalProperties": False,
+        },
+        handler=_lint_skills_handler,
+    ),
+    "chat_history_append": BuiltinTool(
+        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."
+        ),
+        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,
+        },
+        handler=_chat_history_append_handler,
+    ),
+}
+
+
+def to_mcp_tool_meta(tool: BuiltinTool) -> dict[str, Any]:
+    """Render a ``BuiltinTool`` as kwargs for ``mcp.types.Tool``."""
+    return {
+        "name": tool.name,
+        "description": tool.description,
+        "inputSchema": tool.input_schema,
+    }
+
+
+class ToolCache:
+    """Hardcoded registry view of ``ALLOWLIST`` with a stable interface.
+
+    Kept as a class for symmetry with ``PromptCache`` / ``ResourceCache``.
+    No mtime check needed — the allowlist lives in source and changes
+    require a deploy.
+    """
+
+    def __init__(self, registry: dict[str, BuiltinTool] | None = None) -> None:
+        self._registry: dict[str, BuiltinTool] = dict(
+            registry if registry is not None else ALLOWLIST
+        )
+
+    def names(self) -> list[str]:
+        return sorted(self._registry.keys())
+
+    def list(self) -> list[BuiltinTool]:
+        return [self._registry[name] for name in self.names()]
+
+    def get(self, name: str) -> BuiltinTool | None:
+        return self._registry.get(name)
+
+    async def dispatch(
+        self,
+        name: str,
+        arguments: dict[str, Any],
+        consumer_root: Path | None = None,
+    ) -> dict[str, Any]:
+        tool = self.get(name)
+        if tool is None:
+            raise ValueError(f"Unknown tool: {name}")
+        root = _resolve_consumer_root(consumer_root)
+        return await tool.handler(arguments or {}, root)
+
+
+def boot_log_line(cache: ToolCache) -> str:
+    """Single-line stderr enumeration of the registered tools."""
+    names = cache.names()
+    return f"mcp-server: registered {len(names)} tools: {names}"
+

package/scripts/mcp_setup.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# mcp_setup.sh — One-line MCP server onboarding.
+# Creates .venv-mcp/ (gitignored) and installs the `mcp` SDK.
+# Idempotent: safe to re-run; reuses an existing .venv-mcp/.
+
+set -euo pipefail
+
+VENV_DIR=".venv-mcp"
+
+log_ok()    { echo "✅  $*"; }
+log_warn()  { echo "⚠️  $*" >&2; }
+log_err()   { echo "❌  $*" >&2; }
+
+# --- Locate a Python ≥ 3.11 ---
+find_python() {
+  for cand in python3.13 python3.12 python3.11; do
+    if command -v "$cand" >/dev/null 2>&1; then
+      echo "$cand"
+      return 0
+    fi
+  done
+  if command -v python3 >/dev/null 2>&1; then
+    local ver
+    ver="$(python3 -c 'import sys; print("%d.%d" % sys.version_info[:2])')"
+    case "$ver" in
+      3.11|3.12|3.13|3.1[4-9]|3.[2-9][0-9]) echo "python3"; return 0 ;;
+    esac
+  fi
+  return 1
+}
+
+PY="$(find_python || true)"
+if [[ -z "${PY:-}" ]]; then
+  log_err "Python 3.11+ not found."
+  log_err "Install Python 3.11+ (e.g. via pyenv, asdf, brew, or apt) and re-run."
+  exit 1
+fi
+
+PY_VER="$("$PY" -c 'import sys; print("%d.%d.%d" % sys.version_info[:3])')"
+
+# --- Create or reuse venv ---
+if [[ -d "$VENV_DIR" ]]; then
+  log_ok "$VENV_DIR/ exists — reusing (Python $("$VENV_DIR/bin/python" --version 2>&1 | awk '{print $2}'))"
+else
+  "$PY" -m venv "$VENV_DIR"
+  log_ok "Created $VENV_DIR/ with $PY ($PY_VER)"
+fi
+
+# --- Install / upgrade mcp SDK ---
+"$VENV_DIR/bin/pip" install --quiet --upgrade pip
+"$VENV_DIR/bin/pip" install --quiet --upgrade mcp
+
+MCP_VER="$("$VENV_DIR/bin/python" -c 'import mcp, importlib.metadata as m; print(m.version("mcp"))' 2>/dev/null || echo "?")"
+log_ok "Installed mcp SDK ($MCP_VER) in $VENV_DIR/"
+
+# --- Smoke: import the server module ---
+if ! "$VENV_DIR/bin/python" -c 'import scripts.mcp_server' 2>/dev/null; then
+  log_warn "scripts.mcp_server import failed — check repository checkout."
+  exit 1
+fi
+log_ok "scripts.mcp_server import OK"
+
+# --- Print client config snippet ---
+ROOT="$(pwd)"
+PY_BIN="$ROOT/$VENV_DIR/bin/python"
+
+echo ""
+echo "──  MCP server ready  ─────────────────────────────────────────"
+echo ""
+echo "Run over stdio:"
+echo "  task mcp:run"
+echo ""
+echo "Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):"
+cat <<JSON
+  {
+    "mcpServers": {
+      "agent-config": {
+        "command": "$PY_BIN",
+        "args": ["-m", "scripts.mcp_server"],
+        "env": { "PYTHONPATH": "$ROOT" }
+      }
+    }
+  }
+JSON
+echo ""
+echo "After saving the config: ⌘Q Claude Desktop and restart."
+echo "──────────────────────────────────────────────────────────────"