plugin-scanner 2.0.1022__tar.gz → 2.0.1024__tar.gz

plugin_scanner-2.0.1024/.pr-body.md

@@ -0,0 +1,55 @@
+# feat: local stdio MCP server implementing guard-mcp.v1
+
+## Summary
+
+Adds a read-only MCP server to `hol-guard` that serves three tools over stdio transport: `search`, `fetch`, and `get_guard_status`. This is the local component of the guard-mcp.v1 contract — it works offline and needs no cloud account.
+
+## Contract
+
+All tools implement `guard-mcp.v1`:
+
+- **search**: input `{query: string}`, returns max 20 sanitized results
+- **fetch**: input `{id: string}`, returns max 32 KiB sanitized text
+- **get_guard_status**: input `{}`, reports local CLI availability and data freshness
+
+All results include `contractVersion`, `source: local`, `generatedAt`, and `freshness: real-time`.
+
+## Security
+
+- IDs are SHA-256-hashed opaque namespaced values (`receipt:`, `artifact:`, `inventory:`, `device:`) that reveal no internal database keys, paths, or user identifiers
+- Default-deny sanitizers strip all fields except an explicit allowlist per result kind
+- Sensitive fields (`raw_command_text`, `approval_request_id`, `artifact_hash`, `source_scope`, `capabilities_summary`, `diff_summary`) are never included in MCP output
+- All tools are read-only, non-destructive, idempotent with `openWorldHint=false`
+- No mutation, checkout, admin, or widget tools exist
+- Stdout is MCP-protocol-only; diagnostics go to stderr
+
+## CLI
+
+New subcommand: `hol-guard mcp serve --stdio`
+
+## Tests
+
+40 contract and security tests verify:
+- Tool inventory and input schemas match contract exactly
+- Contract envelope fields present in all responses
+- Canary sanitization (tokens, paths, commands, secrets, identifiers)
+- Output allowlists and forbidden field exclusion
+- Uniform not-found behavior for missing, malformed, unauthorized IDs
+- Offline operation (no network access required)
+- Output size caps (search max 20, fetch max 32 KiB)
+- No mutation tools in tool list
+
+## Dependency
+
+`mcp>=1.27.0,<2` (MIT license, Python >=3.10)
+
+## Files Changed
+
+- `pyproject.toml` — added `mcp` dependency
+- `src/codex_plugin_scanner/guard/mcp/` — new module (6 files: `__init__`, `schemas`, `sanitizers`, `adapters`, `tools`, `server`)
+- `src/codex_plugin_scanner/guard/cli/commands_dispatch_local.py` — added `_run_guard_mcp_command` handler
+- `src/codex_plugin_scanner/guard/cli/commands_parser.py` — added `mcp` to metavar
+- `src/codex_plugin_scanner/guard/cli/commands_parser_cloud.py` — added `mcp` subparser with `serve` subcommand
+- `src/codex_plugin_scanner/guard/cli/commands_router.py` — added `mcp` to early handlers
+- `tests/test_guard_mcp_contract.py` — 23 contract tests
+- `tests/test_guard_mcp_sanitization.py` — 17 security tests

{plugin_scanner-2.0.1022 → plugin_scanner-2.0.1024}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.1022
+Version: 2.0.1024
 Summary: Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, OpenCode, and Pi.
 Project-URL: Homepage, https://github.com/hashgraph-online/hol-guard
 Project-URL: Repository, https://github.com/hashgraph-online/hol-guard
@@ -25,6 +25,7 @@ Requires-Python: >=3.10
 Requires-Dist: cisco-ai-skill-scanner~=2.0.11; python_version < '3.14'
 Requires-Dist: cryptography>=49.0.0
 Requires-Dist: keyring>=25.0
+Requires-Dist: mcp<2,>=1.27.0; python_version >= '3.10'
 Requires-Dist: packaging>=24.0
 Requires-Dist: requests<3,>=2.32
 Requires-Dist: rich<15,>=14.0

{plugin_scanner-2.0.1022 → plugin_scanner-2.0.1024}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plugin-scanner"
-version = "2.0.1022"
+version = "2.0.1024"
 description = "Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, OpenCode, and Pi."
 readme = "README.md"
 license = "Apache-2.0"
@@ -35,6 +35,7 @@ dependencies = [
     "requests>=2.32,<3",
     "tomli>=2.0; python_version < '3.11'",
     "cisco-ai-skill-scanner~=2.0.11; python_version < '3.14'",
+    "mcp>=1.27.0,<2; python_version >= '3.10'",
 ]
 
 [project.optional-dependencies]

{plugin_scanner-2.0.1022 → plugin_scanner-2.0.1024}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.1022"
+version = "2.0.1024"
 description = "Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, OpenCode, and Pi."
 readme = "README.md"
 license = "Apache-2.0"
@@ -35,6 +35,7 @@ dependencies = [
     "requests>=2.32,<3",
     "tomli>=2.0; python_version < '3.11'",
     "cisco-ai-skill-scanner~=2.0.11; python_version < '3.14'",
+    "mcp>=1.27.0,<2; python_version >= '3.10'",
 ]
 
 [project.optional-dependencies]

{plugin_scanner-2.0.1022 → plugin_scanner-2.0.1024}/src/codex_plugin_scanner/guard/cli/commands_dispatch_local.py

@@ -363,6 +363,32 @@ def _run_guard_install_command(
     _emit("install", payload, getattr(args, "json", False))
     return 0
 
+
+def _run_guard_mcp_command(
+    args: argparse.Namespace,
+    *,
+    input_text: str | None = None,
+    output_stream: object | None = None,
+) -> int:
+    """Start the local Guard MCP server over stdio transport.
+
+    This is an early handler: it resolves its own guard_home and manages
+    its own GuardStore lifecycle. Stdout is protocol-only; diagnostics
+    go to stderr.
+    """
+    from codex_plugin_scanner.guard.mcp.server import GuardMCPServer
+
+    home_override = getattr(args, "home", None)
+    guard_home = resolve_guard_home(getattr(args, "guard_home", None) or home_override)
+
+    mcp_command = getattr(args, "mcp_command", None)
+    if mcp_command != "serve":
+        print("Error: only 'serve' subcommand is supported", file=sys.stderr)
+        return 2
+
+    server = GuardMCPServer(guard_home=guard_home)
+    return server.run_stdio()
+
 __all__ = [
     "_run_guard_apps_command",
     "_run_guard_bootstrap_command",
@@ -370,6 +396,7 @@ __all__ = [
     "_run_guard_detect_command",
     "_run_guard_init_command",
     "_run_guard_install_command",
+    "_run_guard_mcp_command",
     "_run_guard_preflight_command",
     "_run_guard_protect_command",
     "_run_guard_scan_command",

{plugin_scanner-2.0.1022 → plugin_scanner-2.0.1024}/src/codex_plugin_scanner/guard/cli/commands_parser.py

@@ -54,7 +54,7 @@ def _configure_guard_parser(guard_parser: argparse.ArgumentParser) -> None:
             "test-eval,"
             "receipts,inventory,abom,aibom,approvals,explain,allow,deny,policies,trust,exceptions,advisories,events,doctor,connect,"
             "remote-pair,disconnect,"
-            "login,sync,device,commands,bridge}"
+            "login,sync,device,commands,bridge,mcp}"
         ),
     )
     _configure_guard_local_parsers(guard_subparsers)

{plugin_scanner-2.0.1022 → plugin_scanner-2.0.1024}/src/codex_plugin_scanner/guard/cli/commands_parser_cloud.py

@@ -375,6 +375,22 @@ def _configure_guard_cloud_parsers(
     _add_guard_common_args(hermes_mcp_proxy_parser)
     hermes_mcp_proxy_parser.add_argument("--server", required=True)
     hermes_mcp_proxy_parser.add_argument("--stdio", action="store_true")
+
+    mcp_parser = guard_subparsers.add_parser(
+        "mcp",
+        help="Serve the local Guard MCP server (guard-mcp.v1)",
+    )
+    mcp_subparsers = mcp_parser.add_subparsers(
+        dest="mcp_command",
+        required=True,
+        parser_class=FriendlyArgumentParser,
+    )
+    mcp_serve_parser = mcp_subparsers.add_parser(
+        "serve",
+        help="Start the MCP server over stdio transport",
+    )
+    _add_guard_common_args(mcp_serve_parser)
+    mcp_serve_parser.add_argument("--stdio", action="store_true", default=True)
     hidden_commands = {
         "admin",
         "hook",

{plugin_scanner-2.0.1022 → plugin_scanner-2.0.1024}/src/codex_plugin_scanner/guard/cli/commands_router.py

@@ -18,6 +18,7 @@ from .commands_parser_helpers import *
 _EARLY_HANDLERS = {
     "scan": "_run_guard_scan_command",
     "preflight": "_run_guard_preflight_command",
+    "mcp": "_run_guard_mcp_command",
 }
 
 _PRESTORE_HANDLERS = {

plugin_scanner-2.0.1024/src/codex_plugin_scanner/guard/mcp/__init__.py

@@ -0,0 +1,13 @@
+"""HOL Guard local MCP server implementing guard-mcp.v1.
+
+Modules:
+- schemas: contract constants, ID namespaces, output envelopes
+- sanitizers: default-deny field sanitization per result kind
+- adapters: bridge GuardStore queries to MCP-safe result dicts
+- tools: search, fetch, get_guard_status implementations
+- server: GuardMCPServer wrapping FastMCP, stdio entry point
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

plugin_scanner-2.0.1024/src/codex_plugin_scanner/guard/mcp/adapters.py

@@ -0,0 +1,152 @@
+"""Adapters bridging GuardStore queries to MCP-safe result dicts.
+
+These adapters call bounded GuardStore methods and produce raw dicts
+that the sanitizers will clean before returning to the MCP client.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .schemas import (
+    DEFAULT_SEARCH_LIMIT,
+    MAX_SEARCH_LIMIT,
+    make_opaque_id,
+)
+
+if TYPE_CHECKING:
+    from codex_plugin_scanner.guard.store import GuardStore
+
+_FETCH_SCAN_LIMIT = 200
+
+
+def search_receipts(store: GuardStore, query: str, limit: int = DEFAULT_SEARCH_LIMIT) -> list[dict[str, object]]:
+    bounded_limit = min(max(limit, 1), MAX_SEARCH_LIMIT)
+    receipts = store.list_receipts(limit=bounded_limit)
+    results: list[dict[str, object]] = []
+    q = query.lower().strip() if query else ""
+    for r in receipts:
+        artifact_name = str(r.get("artifact_name") or "")
+        harness = str(r.get("harness") or "")
+        decision = str(r.get("policy_decision") or "")
+        if q and q not in f"{artifact_name} {harness} {decision}".lower():
+            continue
+        results.append(_receipt_to_search_result(r))
+    return results[:bounded_limit]
+
+
+def fetch_receipt(store: GuardStore, opaque_id: str) -> dict[str, object] | None:
+    """Resolve a hash-based opaque ID back to a receipt."""
+    receipts = store.list_receipts(limit=_FETCH_SCAN_LIMIT)
+    for r in receipts:
+        rid = str(r.get("receipt_id") or "")
+        if make_opaque_id("receipt", rid) == opaque_id:
+            return _receipt_to_fetch_result(r)
+    return None
+
+
+def search_inventory(store: GuardStore, query: str, limit: int = DEFAULT_SEARCH_LIMIT) -> list[dict[str, object]]:
+    bounded_limit = min(max(limit, 1), MAX_SEARCH_LIMIT)
+    items = store.list_inventory()
+    results: list[dict[str, object]] = []
+    q = query.lower().strip() if query else ""
+    for item in items:
+        name = str(item.get("artifact_name") or "")
+        harness = str(item.get("harness") or "")
+        if q and q not in f"{name} {harness}".lower():
+            continue
+        results.append(_inventory_to_search_result(item))
+    return results[:bounded_limit]
+
+
+def fetch_inventory(store: GuardStore, opaque_id: str) -> dict[str, object] | None:
+    """Resolve a hash-based opaque ID back to an inventory item.
+
+    Accepts inventory:, artifact:, and device: prefixed IDs.
+    """
+    items = store.list_inventory()
+    for item in items:
+        aid = str(item.get("artifact_id") or "")
+        if make_opaque_id("inventory", aid) == opaque_id:
+            return _inventory_to_fetch_result(item)
+        if make_opaque_id("artifact", aid) == opaque_id:
+            return _inventory_to_fetch_result(item)
+        if make_opaque_id("device", aid) == opaque_id:
+            return _inventory_to_fetch_result(item)
+    return None
+
+
+def get_status(store: GuardStore) -> dict[str, object]:
+    try:
+        receipt_count = store.count_receipts()
+    except Exception:
+        receipt_count = 0
+    try:
+        inventory = store.list_inventory()
+        inventory_count = len(inventory)
+    except Exception:
+        inventory_count = 0
+    return {
+        "cliAvailable": True,
+        "receiptCount": receipt_count,
+        "inventoryCount": inventory_count,
+    }
+
+
+def _receipt_to_search_result(r: dict[str, object]) -> dict[str, object]:
+    return {
+        "id": make_opaque_id("receipt", str(r.get("receipt_id") or "")),
+        "title": str(r.get("artifact_name") or "Guard receipt"),
+        "kind": "receipt",
+        "harness": str(r.get("harness") or ""),
+        "decision": str(r.get("policy_decision") or ""),
+        "changedSinceLastApproval": bool(r.get("changed_capabilities")),
+    }
+
+
+def _receipt_to_fetch_result(r: dict[str, object]) -> dict[str, object]:
+    text = (
+        f"Decision: {r.get('policy_decision', 'unknown')}\n"
+        f"Harness: {r.get('harness', 'unknown')}\n"
+        f"Artifact: {r.get('artifact_name', 'unknown')}"
+    )
+    return {
+        "id": make_opaque_id("receipt", str(r.get("receipt_id") or "")),
+        "title": str(r.get("artifact_name") or "Guard receipt"),
+        "kind": "receipt",
+        "harness": str(r.get("harness") or ""),
+        "decision": str(r.get("policy_decision") or ""),
+        "text": text,
+        "truncated": False,
+        "changedSinceLastApproval": bool(r.get("changed_capabilities")),
+    }
+
+
+def _inventory_to_search_result(item: dict[str, object]) -> dict[str, object]:
+    return {
+        "id": make_opaque_id("inventory", str(item.get("artifact_id") or "")),
+        "title": str(item.get("artifact_name") or "Inventory item"),
+        "kind": "inventory",
+        "harness": str(item.get("harness") or ""),
+        "decision": str(item.get("last_policy_action") or "unknown"),
+        "changedSinceLastApproval": item.get("last_changed_at") != item.get("last_approved_at"),
+    }
+
+
+def _inventory_to_fetch_result(item: dict[str, object]) -> dict[str, object]:
+    text = (
+        f"Artifact: {item.get('artifact_name', 'unknown')}\n"
+        f"Harness: {item.get('harness', 'unknown')}\n"
+        f"Type: {item.get('artifact_type', 'unknown')}\n"
+        f"Present: {item.get('present', 'unknown')}"
+    )
+    return {
+        "id": make_opaque_id("inventory", str(item.get("artifact_id") or "")),
+        "title": str(item.get("artifact_name") or "Inventory item"),
+        "kind": "inventory",
+        "harness": str(item.get("harness") or ""),
+        "decision": str(item.get("last_policy_action") or "unknown"),
+        "text": text,
+        "truncated": False,
+        "changedSinceLastApproval": item.get("last_changed_at") != item.get("last_approved_at"),
+    }

plugin_scanner-2.0.1024/src/codex_plugin_scanner/guard/mcp/sanitizers.py

@@ -0,0 +1,101 @@
+"""Default-deny sanitizers for guard-mcp.v1 MCP output.
+
+Every field not in the explicit allowlist is dropped. All values are
+length-capped, control-characters removed, Unicode normalized, and
+enum-validated before being included in any MCP response.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from typing import Any
+
+from .schemas import (
+    MAX_FETCH_TEXT_BYTES,
+    VALID_DECISIONS,
+    VALID_HARNESSES,
+    VALID_KINDS,
+)
+
+_MAX_FIELD_LENGTH = 1024
+_MAX_TITLE_LENGTH = 256
+_MAX_SUMMARY_LENGTH = 4096
+
+_CONTROL_CHARS = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]")
+
+
+def _normalize_text(value: Any, max_length: int) -> str:
+    if value is None:
+        return ""
+    text = str(value)
+    text = unicodedata.normalize("NFKC", text)
+    text = _CONTROL_CHARS.sub("", text)
+    return text[:max_length]
+
+
+def sanitize_search_result(raw: dict[str, object]) -> dict[str, object]:
+    allowed: dict[str, object] = {}
+
+    raw_id = _normalize_text(raw.get("id"), 256)
+    if raw_id:
+        allowed["id"] = raw_id
+
+    allowed["title"] = _normalize_text(raw.get("title"), _MAX_TITLE_LENGTH)
+    allowed["kind"] = _validate_enum(raw.get("kind"), VALID_KINDS, "receipt")
+    allowed["harness"] = _validate_enum(raw.get("harness"), VALID_HARNESSES, "")
+    allowed["decision"] = _validate_enum(raw.get("decision"), VALID_DECISIONS, "unknown")
+
+    changed = raw.get("changedSinceLastApproval")
+    if isinstance(changed, bool):
+        allowed["changedSinceLastApproval"] = changed
+
+    return allowed
+
+
+def sanitize_fetch_result(raw: dict[str, object]) -> dict[str, object]:
+    allowed: dict[str, object] = {}
+
+    raw_id = _normalize_text(raw.get("id"), 256)
+    if raw_id:
+        allowed["id"] = raw_id
+
+    allowed["title"] = _normalize_text(raw.get("title"), _MAX_TITLE_LENGTH)
+    allowed["kind"] = _validate_enum(raw.get("kind"), VALID_KINDS, "receipt")
+    allowed["harness"] = _validate_enum(raw.get("harness"), VALID_HARNESSES, "")
+    allowed["decision"] = _validate_enum(raw.get("decision"), VALID_DECISIONS, "unknown")
+
+    changed = raw.get("changedSinceLastApproval")
+    if isinstance(changed, bool):
+        allowed["changedSinceLastApproval"] = changed
+
+    text = _normalize_text(raw.get("text"), MAX_FETCH_TEXT_BYTES)
+    allowed["text"] = text
+    allowed["truncated"] = bool(raw.get("truncated", False))
+
+    return allowed
+
+
+def sanitize_status_result(raw: dict[str, object]) -> dict[str, object]:
+    allowed: dict[str, object] = {}
+
+    allowed["cliAvailable"] = bool(raw.get("cliAvailable", True))
+    receipt_count = raw.get("receiptCount")
+    allowed["receiptCount"] = int(receipt_count) if isinstance(receipt_count, (int, float)) else 0
+    inventory_count = raw.get("inventoryCount")
+    allowed["inventoryCount"] = int(inventory_count) if isinstance(inventory_count, (int, float)) else 0
+
+    version = _normalize_text(raw.get("cliVersion"), _MAX_FIELD_LENGTH)
+    if version:
+        allowed["cliVersion"] = version
+
+    return allowed
+
+
+def _validate_enum(value: Any, valid: frozenset[str], default: str) -> str:
+    if value is None:
+        return default
+    text = str(value)
+    if text in valid:
+        return text
+    return default

plugin_scanner-2.0.1024/src/codex_plugin_scanner/guard/mcp/schemas.py

@@ -0,0 +1,63 @@
+"""Contract constants and schema definitions for guard-mcp.v1."""
+
+from __future__ import annotations
+
+import re
+from enum import Enum
+
+CONTRACT_VERSION = "guard-mcp.v1"
+SOURCE_LOCAL = "local"
+
+DEFAULT_SEARCH_LIMIT = 10
+MAX_SEARCH_LIMIT = 20
+MAX_FETCH_TEXT_BYTES = 32768  # 32 KiB
+
+ID_NAMESPACES = ("receipt:", "artifact:", "inventory:", "device:")
+
+
+class ResultKind(str, Enum):
+    RECEIPT = "receipt"
+    ARTIFACT = "artifact"
+    INVENTORY = "inventory"
+    DEVICE = "device"
+
+
+class DecisionCategory(str, Enum):
+    ALLOW = "allow"
+    DENY = "deny"
+    WARN = "warn"
+    BLOCK = "block"
+    UNKNOWN = "unknown"
+
+
+class HarnessName(str, Enum):
+    CODEX = "codex"
+    CLAUDE = "claude"
+    CURSOR = "cursor"
+    COPILOT = "copilot"
+    OPENCODE = "opencode"
+    GEMINI = "gemini"
+    HERMES = "hermes"
+    OPENCLAW = "openclaw"
+    ANTIGRAVITY = "antigravity"
+    PI = "pi"
+
+
+VALID_HARNESSES = frozenset(h.value for h in HarnessName)
+VALID_DECISIONS = frozenset(d.value for d in DecisionCategory)
+VALID_KINDS = frozenset(k.value for k in ResultKind)
+
+_ID_PATTERN = re.compile(r"^(receipt|artifact|inventory|device):[a-zA-Z0-9_-]+$")
+
+
+def is_valid_id(raw: str) -> bool:
+    if not raw or len(raw) > 256:
+        return False
+    return bool(_ID_PATTERN.match(raw))
+
+
+def make_opaque_id(kind: str, internal_id: str) -> str:
+    import hashlib
+
+    digest = hashlib.sha256(f"{kind}:{internal_id}".encode()).hexdigest()[:24]
+    return f"{kind}:{digest}"

plugin_scanner-2.0.1024/src/codex_plugin_scanner/guard/mcp/server.py

@@ -0,0 +1,164 @@
+"""GuardMCPServer: local stdio MCP server for guard-mcp.v1.
+
+Wraps FastMCP with sync call_tool/list_tools methods for testability.
+The stdio entry point keeps stdout protocol-only; diagnostics go to stderr.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from .tools import execute_fetch, execute_get_guard_status, execute_search
+
+logger = logging.getLogger(__name__)
+
+_TOOL_DEFINITIONS = [
+    {
+        "name": "search",
+        "description": (
+            "Search local Guard receipts and inventory. Returns at most 20 "
+            "sanitized results. The query matches artifact names, harness "
+            "names, and policy decisions."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Free-text search query.",
+                },
+            },
+            "required": ["query"],
+        },
+    },
+    {
+        "name": "fetch",
+        "description": (
+            "Fetch a single Guard receipt or inventory item by its opaque "
+            "namespaced ID. Returns at most 32 KiB of sanitized text."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "description": "Opaque namespaced ID (receipt:, artifact:, inventory:, device:).",
+                },
+            },
+            "required": ["id"],
+        },
+    },
+    {
+        "name": "get_guard_status",
+        "description": ("Report whether local Guard data is available and how fresh it is. Takes no input."),
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+        },
+    },
+]
+
+
+def _create_annotations() -> Any:
+    from mcp import types
+
+    return types.ToolAnnotations(
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+
+
+class GuardMCPServer:
+    """Local MCP server implementing guard-mcp.v1 over stdio.
+
+    Provides synchronous call_tool/list_tools for direct testing and
+    a run_stdio() method for protocol-level stdio transport.
+    """
+
+    def __init__(self, guard_home: Path) -> None:
+        self.guard_home = guard_home
+        self._store: Any = None
+
+    @property
+    def store(self) -> Any:
+        if self._store is None:
+            from codex_plugin_scanner.guard.store import GuardStore
+
+            self._store = GuardStore(self.guard_home)
+        return self._store
+
+    def list_tools(self) -> list[Any]:
+        from typing import cast
+
+        from mcp import types
+
+        annotations = _create_annotations()
+        return [
+            types.Tool(
+                name=str(td["name"]),
+                description=str(td["description"]),
+                inputSchema=cast(dict[str, Any], td["inputSchema"]),
+                annotations=annotations,
+            )
+            for td in _TOOL_DEFINITIONS
+        ]
+
+    def call_tool(self, name: str, arguments: dict[str, Any]) -> Any:
+        from mcp import types
+
+        store = self.store
+        if name == "search":
+            query = str(arguments.get("query", ""))
+            text = execute_search(store, query)
+        elif name == "fetch":
+            item_id = str(arguments.get("id", ""))
+            text = execute_fetch(store, item_id)
+        elif name == "get_guard_status":
+            text = execute_get_guard_status(store)
+        else:
+            from .tools import _envelope
+
+            text = _envelope({"error": f"Unknown tool: {name}"})
+        return types.TextContent(type="text", text=text)
+
+    def run_stdio(self) -> int:
+        """Run the MCP server over stdio transport."""
+        from mcp.server.fastmcp import FastMCP
+
+        mcp = FastMCP("hol-guard")
+        annotations = _create_annotations()
+
+        search_desc = _TOOL_DEFINITIONS[0]["description"]
+        fetch_desc = _TOOL_DEFINITIONS[1]["description"]
+        status_desc = _TOOL_DEFINITIONS[2]["description"]
+
+        @mcp.tool(
+            name="search",
+            description=str(search_desc),
+            annotations=annotations,
+        )
+        def search(query: str) -> str:
+            return execute_search(self.store, query)
+
+        @mcp.tool(
+            name="fetch",
+            description=str(fetch_desc),
+            annotations=annotations,
+        )
+        def fetch(id: str) -> str:  # noqa: A002
+            return execute_fetch(self.store, id)
+
+        @mcp.tool(
+            name="get_guard_status",
+            description=str(status_desc),
+            annotations=annotations,
+        )
+        def get_guard_status() -> str:
+            return execute_get_guard_status(self.store)
+
+        mcp.run(transport="stdio")
+        return 0