@event4u/agent-config 1.36.0 → 1.37.0

package/scripts/mcp_server/server.py

@@ -0,0 +1,269 @@
+"""MCP Server — registers `prompts/*` + `resources/*` over stdio.
+
+Phase 3 boundary (A0 Hard Contract still holds): read-only. No
+`tools/*`, no filesystem writes. New in Phase 3:
+
+- **C1/C2** `resources/list` + `resources/read` for rules,
+  guidelines, contexts via `ResourceCache`.
+- **C3** cursor-based pagination on `resources/list` (same shape as
+  prompts/list).
+- **C4** hot-reload — `ResourceCache` re-scans on mtime change before
+  each `resources/list` response.
+
+Carried over from Phase 2:
+
+- **B1/B2** full skills + commands coverage via `PromptCache`.
+- **B4** cursor-based pagination on `prompts/list`.
+- **B5** hot-reload — `PromptCache` re-scans on mtime change before
+  each `prompts/list` response.
+
+`build_server` still accepts a plain `list[SkillPrompt]` so the
+Phase-1 contract tests keep passing without touching their fixtures.
+"""
+from __future__ import annotations
+
+import asyncio
+import sys
+from typing import Callable, Iterable, Union
+
+import mcp.types as types
+from mcp.server import NotificationOptions, Server
+from mcp.server.lowlevel.helper_types import ReadResourceContents
+from mcp.server.models import InitializationOptions
+from mcp.server.stdio import stdio_server
+from pydantic import AnyUrl
+
+from . import SERVER_NAME, __version__
+from .metadata import (
+    boot_log_line as identity_boot_log_line,
+    compute_skill_set_signature,
+    read_package_version,
+)
+from .prompts import (
+    PromptCache,
+    SkillPrompt,
+    _project_root,
+    to_mcp_prompt_meta,
+)
+from .resources import (
+    Resource,
+    ResourceCache,
+    to_mcp_resource_meta,
+)
+from .tools import (
+    ToolCache,
+    boot_log_line as tools_boot_log_line,
+    to_mcp_tool_meta,
+)
+
+# Page size for cursor-based pagination. Conservative default —
+# Claude Desktop and Zed handle larger pages, but small pages keep
+# wire payloads under typical stdio frame limits.
+DEFAULT_PAGE_SIZE = 100
+
+PromptsSource = Union[
+    list[SkillPrompt],
+    Callable[[], tuple[list[SkillPrompt], list[str]]],
+]
+ResourcesSource = Union[
+    list[Resource],
+    Callable[[], tuple[list[Resource], list[str]]],
+]
+
+
+def _make_loader(
+    source: PromptsSource,
+) -> Callable[[], tuple[list[SkillPrompt], list[str]]]:
+    """Normalise to a callable returning `(prompts, errors)`."""
+    if callable(source):
+        return source
+    static = list(source)
+    return lambda: (static, [])
+
+
+def _make_resource_loader(
+    source: ResourcesSource,
+) -> Callable[[], tuple[list[Resource], list[str]]]:
+    """Normalise to a callable returning `(resources, errors)`."""
+    if callable(source):
+        return source
+    static = list(source)
+    return lambda: (static, [])
+
+
+def _decode_cursor(cursor: str | None, total: int) -> int:
+    """Cursor is a stringified integer offset. Invalid → start at 0."""
+    if cursor is None:
+        return 0
+    try:
+        offset = int(cursor)
+    except (TypeError, ValueError):
+        return 0
+    if offset < 0 or offset > total:
+        return 0
+    return offset
+
+
+def build_server(
+    source: PromptsSource,
+    *,
+    page_size: int = DEFAULT_PAGE_SIZE,
+    resources: ResourcesSource | None = None,
+    tools: ToolCache | None = None,
+) -> Server:
+    """Construct the MCP Server with the new-style paginated handlers.
+
+    Pure factory — no I/O. Tests pass a static list; the stdio
+    entrypoint passes a `PromptCache.get` callable for hot-reload.
+    When `resources` is omitted, resources/* handlers are still
+    registered but return an empty list — clients can probe the
+    capability without seeing a protocol error.
+    """
+    loader = _make_loader(source)
+    resource_loader = _make_resource_loader(resources or [])
+    server: Server = Server(
+        name=SERVER_NAME,
+        version=__version__,
+        instructions=(
+            "agent-config MCP server (Phase 3, experimental). Exposes "
+            "all skills + commands as instructional prompts, plus "
+            "rules + guidelines + contexts as read-only resources."
+        ),
+    )
+
+    @server.list_prompts()
+    async def _list_prompts(
+        req: types.ListPromptsRequest,
+    ) -> types.ListPromptsResult:
+        prompts, _errors = loader()
+        cursor = req.params.cursor if req.params else None
+        start = _decode_cursor(cursor, len(prompts))
+        end = start + page_size
+        page = prompts[start:end]
+        next_cursor: str | None = str(end) if end < len(prompts) else None
+        return types.ListPromptsResult(
+            prompts=[types.Prompt(**to_mcp_prompt_meta(p)) for p in page],
+            nextCursor=next_cursor,
+        )
+
+    @server.get_prompt()
+    async def _get_prompt(
+        name: str,
+        arguments: dict[str, str] | None = None,
+    ) -> types.GetPromptResult:
+        prompts, _errors = loader()
+        index = {to_mcp_prompt_meta(p)["name"]: p for p in prompts}
+        prompt = index.get(name)
+        if prompt is None:
+            raise ValueError(f"Unknown prompt: {name}")
+        return types.GetPromptResult(
+            description=prompt.description,
+            messages=[
+                types.PromptMessage(
+                    role="user",
+                    content=types.TextContent(
+                        type="text",
+                        text=prompt.body,
+                    ),
+                ),
+            ],
+        )
+
+    @server.list_resources()
+    async def _list_resources(
+        req: types.ListResourcesRequest,
+    ) -> types.ListResourcesResult:
+        items, _errors = resource_loader()
+        cursor = req.params.cursor if req.params else None
+        start = _decode_cursor(cursor, len(items))
+        end = start + page_size
+        page = items[start:end]
+        next_cursor: str | None = str(end) if end < len(items) else None
+        return types.ListResourcesResult(
+            resources=[types.Resource(**to_mcp_resource_meta(r)) for r in page],
+            nextCursor=next_cursor,
+        )
+
+    @server.read_resource()
+    async def _read_resource(uri: AnyUrl) -> Iterable[ReadResourceContents]:
+        items, _errors = resource_loader()
+        index = {r.uri: r for r in items}
+        resource = index.get(str(uri))
+        if resource is None:
+            raise ValueError(f"Unknown resource: {uri}")
+        return [
+            ReadResourceContents(content=resource.body, mime_type=resource.mime_type),
+        ]
+
+    if tools is not None:
+        tool_cache = tools
+
+        @server.list_tools()
+        async def _list_tools() -> list[types.Tool]:
+            return [types.Tool(**to_mcp_tool_meta(t)) for t in tool_cache.list()]
+
+        @server.call_tool()
+        async def _call_tool(
+            name: str,
+            arguments: dict[str, object],
+        ) -> dict[str, object]:
+            return await tool_cache.dispatch(name, arguments or {})
+
+    return server
+
+
+async def run_stdio() -> None:
+    """Entrypoint — load prompts + resources via caches, run server over stdio."""
+    cache = PromptCache()
+    prompts, errors = cache.get()
+    for line in errors:
+        print(f"mcp-server: warn: {line}", file=sys.stderr)
+    print(
+        f"mcp-server: loaded {len(prompts)} prompts "
+        f"({len(errors)} warnings)",
+        file=sys.stderr,
+    )
+    resource_cache = ResourceCache()
+    resources_list, resource_errors = resource_cache.get()
+    for line in resource_errors:
+        print(f"mcp-server: warn: {line}", file=sys.stderr)
+    print(
+        f"mcp-server: loaded {len(resources_list)} resources "
+        f"({len(resource_errors)} warnings)",
+        file=sys.stderr,
+    )
+    tool_cache = ToolCache()
+    print(tools_boot_log_line(tool_cache), file=sys.stderr)
+    package_version = read_package_version(_project_root())
+    skill_set_signature = compute_skill_set_signature(
+        cache.signature,
+        resource_cache.signature,
+    )
+    print(
+        identity_boot_log_line(
+            server_version=__version__,
+            package_version=package_version,
+            skill_set_signature=skill_set_signature,
+        ),
+        file=sys.stderr,
+    )
+    server = build_server(
+        cache.get,
+        resources=resource_cache.get,
+        tools=tool_cache,
+    )
+    init_options = InitializationOptions(
+        server_name=SERVER_NAME,
+        server_version=__version__,
+        capabilities=server.get_capabilities(
+            notification_options=NotificationOptions(),
+            experimental_capabilities={},
+        ),
+    )
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, init_options)
+
+
+def main() -> None:
+    """Sync wrapper for `python -m scripts.mcp_server`."""
+    asyncio.run(run_stdio())

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}"
+