extensible-mcp 0.3.4__py3-none-any.whl

extensible_mcp/__init__.py

@@ -0,0 +1,97 @@
+# Copyright (c) 2026 Matthew Fuchs
+# SPDX-License-Identifier: Apache-2.0
+
+"""MCP proxy that replaces tool definitions with semantic search."""
+
+from .augment import BundleAugmenter
+from .bundle import PolicyBundle
+from .didweb import (
+    DidResolutionError,
+    DidWebResolver,
+    did_web_to_url,
+    ed25519_jwk_from_document,
+)
+from .fetchplan import FetchContext, FetchError, FetchExecutor, WalletLookup
+from .filters import CallFilter, ResponseFilter, ServerLoadFilter, ToolFilter
+from .guidance import render_denial
+from .replay import (
+    InMemorySpentStore,
+    SingleUseEvidenceFilter,
+    SpentStore,
+    wallet_bundle_jti,
+)
+from .issuer import IssuerRegistry
+from .routing import BundleRouter
+from .selection import (
+    LayeredBundleSelector,
+    RegoClassifier,
+    SelectionResult,
+    provenance_descriptor,
+)
+from .types import (
+    CallFilterResult,
+    CallRequest,
+    CallResponse,
+    LocalTool,
+    ResponseFilterResult,
+    SearchResult,
+    ServerLoadRequest,
+    ServerLoadResult,
+    ToolRecord,
+)
+from .wallet_bundle import AdaptedCall, WalletBundleAdapter, WalletBundleError, make_membership_lookup
+from .wasm_filter import VCPolicyFilter, WasmPolicyFilter, policy_deny_reason
+from .wasm_policy import (
+    HostBuiltinError,
+    OpaWasmPolicy,
+    PolicyEvaluationError,
+    default_builtins,
+)
+
+__all__ = [
+    "BundleAugmenter",
+    "BundleRouter",
+    "CallFilter",
+    "CallFilterResult",
+    "CallRequest",
+    "CallResponse",
+    "DidResolutionError",
+    "DidWebResolver",
+    "FetchContext",
+    "FetchError",
+    "FetchExecutor",
+    "HostBuiltinError",
+    "IssuerRegistry",
+    "LayeredBundleSelector",
+    "LocalTool",
+    "OpaWasmPolicy",
+    "PolicyBundle",
+    "PolicyEvaluationError",
+    "RegoClassifier",
+    "ResponseFilter",
+    "ResponseFilterResult",
+    "SearchResult",
+    "SelectionResult",
+    "ServerLoadFilter",
+    "ServerLoadRequest",
+    "ServerLoadResult",
+    "ToolFilter",
+    "ToolRecord",
+    "AdaptedCall",
+    "VCPolicyFilter",
+    "WalletBundleAdapter",
+    "WalletBundleError",
+    "WalletLookup",
+    "WasmPolicyFilter",
+    "default_builtins",
+    "did_web_to_url",
+    "ed25519_jwk_from_document",
+    "make_membership_lookup",
+    "policy_deny_reason",
+    "provenance_descriptor",
+    "render_denial",
+    "InMemorySpentStore",
+    "SingleUseEvidenceFilter",
+    "SpentStore",
+    "wallet_bundle_jti",
+]

extensible_mcp/__main__.py

@@ -0,0 +1,6 @@
+# Copyright (c) 2026 Matthew Fuchs
+# SPDX-License-Identifier: Apache-2.0
+
+from extensible_mcp.server import main
+
+main()

extensible_mcp/admin.py

@@ -0,0 +1,261 @@
+# Copyright (c) 2026 Matthew Fuchs
+# SPDX-License-Identifier: Apache-2.0
+
+"""Adding an authenticated server without handing the credential to the model.
+
+`load_mcp_server` lets the LLM name both a server and a URL, and a token is
+keyed by name — so a prompt-injected model could point a name that has a token
+at a host it controls and be handed the bearer. The proxy closed that by
+sending credentials only to URLs an operator configured, which also removed the
+documented "drop the token in the tokens file, then load at runtime" flow.
+
+This restores it from the other side. The distinction that makes it safe is
+*who possesses the credential*: the bug was the model referencing a secret it
+had never seen, and the proxy fetching it on the model's behalf. Here the
+operator passes the token in, so only a caller who already holds it can use it
+— and the model holds none.
+
+Note this is the opposite direction from moving *signed evidence* by handle
+rather than by value, and both are right. Evidence should travel by reference
+because the LLM is a lossy courier of bytes it legitimately carries; a
+downstream auth token should travel by value because the LLM must never be
+able to invoke one it cannot hold.
+
+Deliberately not an MCP tool. A `token` parameter on `load_mcp_server` would
+be safe from exfiltration — the model has nothing to pass — but it shares the
+endpoint the model drives, and any user who pasted a token into a chat to make
+it work would break the rule that tokens never transit the conversation.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+from dataclasses import dataclass
+from pathlib import Path
+
+from mcp import ClientSession
+from mcp.client.streamable_http import streamable_http_client
+
+PID_FILENAME = "extensible-mcp.pid"
+
+
+class AdminError(Exception):
+    """Something the operator needs to fix, reported without a traceback."""
+
+
+@dataclass
+class VerifiedServer:
+    name: str
+    url: str
+    tool_names: list[str]
+
+
+async def verify_server(name: str, url: str, token: str | None) -> VerifiedServer:
+    """Connect as an MCP client and list tools, so a bad URL or a wrong token
+    fails here rather than at the proxy's next start.
+
+    Verification is the point of the command: writing a token into a file is
+    trivial, and finding out hours later that it was wrong is the expensive
+    part.
+
+    Built to behave exactly as ``ClientManager`` will, which means **not**
+    following redirects. An earlier version did, and so accepted a URL the
+    proxy then could not use -- a `/mcp/` that 307s to `/mcp` verified here and
+    failed at the proxy, which is worse than not checking, because it reports
+    success for something broken. The runtime does not follow redirects either,
+    and should not: a redirect carrying an Authorization header is a way to
+    hand a bearer somewhere it was not meant to go.
+    """
+    import httpx
+
+    headers = {"Authorization": f"Bearer {token}"} if token else {}
+    try:
+        async with httpx.AsyncClient(headers=headers) as http:
+            async with streamable_http_client(url, http_client=http) as (r, w, _):
+                async with ClientSession(r, w) as session:
+                    await session.initialize()
+                    listed = await session.list_tools()
+    except Exception as e:  # noqa: BLE001 - every failure is the same advice
+        detail = _leaf(e)
+        hint = (
+            "Check the URL, that the server is running, and that the token is "
+            "the one it expects."
+        )
+        if "Redirect" in detail or "307" in detail or "308" in detail:
+            # Overwhelmingly a trailing slash, and the message httpx gives names
+            # the target, so point straight at it.
+            hint = (
+                "That URL redirects. Use the URL it redirects to -- usually this "
+                "is a trailing slash: try the form without one, or with one, to "
+                "match what the server serves. The proxy does not follow "
+                "redirects, so the exact URL matters."
+            )
+        raise AdminError(f"could not use {url} as an MCP server: {detail}\n{hint}") from e
+    return VerifiedServer(name=name, url=url, tool_names=[t.name for t in listed.tools])
+
+
+def _leaf(exc: BaseException) -> str:
+    """The innermost message. anyio task groups wrap the real failure."""
+    if isinstance(exc, BaseExceptionGroup):
+        return "; ".join(_leaf(e) for e in exc.exceptions)
+    return str(exc).strip() or type(exc).__name__
+
+
+def add_server_to_config(config_path: Path, name: str, url: str) -> None:
+    """Add ``name`` to the config's ``mcpServers``, refusing to redefine one.
+
+    Rewriting an existing entry is how a name could be re-pointed at another
+    host, which is the substitution the token binding exists to prevent -- so
+    it is an error here rather than an overwrite.
+    """
+    raw = json.loads(config_path.read_text())
+    servers = raw.setdefault("mcpServers", {})
+    if name in servers:
+        raise AdminError(
+            f"'{name}' is already in {config_path}. Remove it by hand if you "
+            "really mean to point that name somewhere else; this command will "
+            "not repoint an existing server."
+        )
+    servers[name] = {"url": url}
+    config_path.write_text(json.dumps(raw, indent=2) + "\n")
+
+
+def write_token(tokens_path: Path, name: str, token: str) -> None:
+    """Upsert ``name=token``, leaving every other line untouched.
+
+    Rewritten through a 0600 temp file and replaced atomically: a reader that
+    catches the file mid-write would see a truncated token and send it.
+    """
+    lines: list[str] = []
+    replaced = False
+    if tokens_path.exists():
+        for line in tokens_path.read_text().splitlines():
+            key = line.split("=", 1)[0].strip()
+            if key == name and not line.strip().startswith("#"):
+                lines.append(f"{name}={token}")
+                replaced = True
+            else:
+                lines.append(line)
+    if not replaced:
+        lines.append(f"{name}={token}")
+
+    tmp = tokens_path.with_name(tokens_path.name + ".tmp")
+    fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as fh:
+        fh.write("\n".join(lines) + "\n")
+    os.replace(tmp, tokens_path)
+    os.chmod(tokens_path, 0o600)
+
+
+def pid_file_for(config_path: Path) -> Path:
+    """Beside the config, so one proxy per config is the unit."""
+    return config_path.parent / PID_FILENAME
+
+
+def _is_locked(pid_file: Path) -> bool:
+    """Whether a live process holds the pid file's lock.
+
+    The pid alone is not safe to act on. Python does not run ``finally`` on
+    SIGTERM, which is how a daemon is normally stopped, so a stale pid file is
+    the common case rather than the exceptional one -- and pids get reused.
+    Signalling a recycled pid would send SIGHUP to an unrelated process, whose
+    default action is to terminate it.
+
+    An advisory lock answers the question the pid cannot: the running proxy
+    holds it for its whole life, and the kernel drops it when that process
+    dies, however it died. If we can take the lock, nobody is there.
+    """
+    try:
+        import fcntl
+    except ImportError:  # pragma: no cover - Windows
+        return True  # cannot tell; fall back to trusting the pid
+    try:
+        fd = os.open(str(pid_file), os.O_RDWR)
+    except OSError:
+        return False
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except OSError:
+        return True  # someone holds it: a live proxy
+    else:
+        fcntl.flock(fd, fcntl.LOCK_UN)
+        return False
+    finally:
+        os.close(fd)
+
+
+def signal_reload(config_path: Path) -> int | None:
+    """SIGHUP a proxy running against this config. Returns the pid, or None.
+
+    A stale pid file is normal, so it is reported rather than treated as a
+    failure: the config and token are already written, and the next start picks
+    them up.
+    """
+    pid_file = pid_file_for(config_path)
+    if not pid_file.exists():
+        return None
+    try:
+        pid = int(pid_file.read_text().strip())
+    except ValueError:
+        return None
+    if not hasattr(signal, "SIGHUP"):
+        return None
+    if not _is_locked(pid_file):
+        return None
+    try:
+        os.kill(pid, signal.SIGHUP)
+    except (ProcessLookupError, PermissionError):
+        return None
+    return pid
+
+
+# The running proxy's lock fd. Held for the process lifetime: closing it would
+# release the lock and make a live proxy look stale.
+_pid_lock_fd: int | None = None
+
+
+def write_pid_file(config_path: Path) -> Path:
+    """Record this process's pid and hold an advisory lock on the file."""
+    global _pid_lock_fd
+    path = pid_file_for(config_path)
+    # Open without O_TRUNC and truncate only after the lock is ours. O_TRUNC
+    # empties the file at open(), which happens before the lock is tested -- so
+    # a second proxy that is about to be refused would first wipe the running
+    # proxy's pid, leaving add-server unable to find it.
+    fd = os.open(str(path), os.O_WRONLY | os.O_CREAT, 0o644)
+    try:
+        import fcntl
+
+        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except ImportError:  # pragma: no cover - Windows
+        pass
+    except OSError as e:
+        os.close(fd)
+        raise AdminError(
+            f"another proxy is already running against {config_path} "
+            f"(see {path})"
+        ) from e
+    os.ftruncate(fd, 0)
+    os.write(fd, f"{os.getpid()}\n".encode())
+    _pid_lock_fd = fd
+    return path
+
+
+def remove_pid_file(path: Path) -> None:
+    """Best effort, on the graceful path only. The lock is what actually
+    tells a later ``add-server`` whether anyone is there, so a file left by a
+    SIGTERM is untidy rather than wrong."""
+    global _pid_lock_fd
+    if _pid_lock_fd is not None:
+        try:
+            os.close(_pid_lock_fd)
+        except OSError:
+            pass
+        _pid_lock_fd = None
+    try:
+        if int(path.read_text().strip()) == os.getpid():
+            path.unlink()
+    except (OSError, ValueError):
+        pass

extensible_mcp/augment.py

@@ -0,0 +1,189 @@
+# Copyright (c) 2026 Matthew Fuchs
+# SPDX-License-Identifier: Apache-2.0
+
+"""Search-side augmentation: tell the LLM which credentials a governed tool
+needs.
+
+When ``search_tools`` surfaces a tool governed by a policy bundle, the LLM must
+be told to supply the bundle's credential fields (e.g. ``requestVC``) — and
+*when*, since some are required only on certain paths (e.g. an authorization VC
+only above a spend threshold). :class:`BundleAugmenter` is a ``ToolFilter`` that,
+per result, looks up the governing bundle (via the :class:`BundleRouter` the call
+path already uses) and rewrites the surfaced tool definition:
+
+- injects each credential field into the tool's input schema, typed from the
+  bundle's manifest; an always-required credential is marked ``required``, a
+  conditional one is optional;
+- extends the description with a generated "what you need" note — the
+  *scaffolding* ("always / if … also", the dependency ordering) is the
+  proxy's; the *meaningful words* (the named-check sentences, issuer roles,
+  credential names) come from the bundle's ``guidance.json``.
+
+Credentials are listed in **dependency order** (a credential that signs over
+another comes after it), each annotated with its **issuer role** — the
+policy's enforced tag ("a parent must sign"), which the deployment's
+``IssuerRegistry`` maps to a concrete wallet. Roles and edges are fail-soft
+derivations from the bundle's own authoring toolchain: when a guidance file
+predates them the note is merely vaguer, never wrong.
+
+This is the proactive half of the message-is-the-interface design: the
+enforcement path re-checks everything regardless, so a tool that misreads this
+guidance is denied, not a security hole.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+from collections.abc import Callable
+
+from .bundle import PolicyBundle
+from .routing import BundleRouter
+from .types import SearchResult, ToolRecord
+
+
+def _vc_bundle_phrase(role: str | None) -> str:
+    wallet = f"the {role}'s wallet" if role else "the appropriate wallet"
+    return (
+        "A signed verifiable-credential bundle ({token, membership}) "
+        f"obtained from {wallet}."
+    )
+
+
+def _unqualified_action(tool_name: str) -> str:
+    return tool_name.split("__", 1)[1] if "__" in tool_name else tool_name
+
+
+class BundleAugmenter:
+    """A ``ToolFilter`` that surfaces a governed tool's required credentials.
+
+    ``tool_action`` must match the call filter's mapping (the policy's
+    ``input.tool``): the note tells the LLM the exact action identifier to
+    put in the signed request, because the policy binds on it and the LLM
+    cannot guess it — each wrong guess costs a human wallet approval.
+
+    ``wire_schemas`` (field → JSON Schema) overrides the injected schema for
+    a credential field. The manifest's shape is what the *policy* reads; when
+    the call path runs a translating adapter (e.g. ``WalletBundleAdapter``
+    turning ``{token, membership}`` into ``{jws, claims}``), the LLM must be
+    shown the **wire** shape it actually sends — advertising the policy shape
+    misleads it into "fixing" a working call.
+    """
+
+    def __init__(
+        self,
+        router: BundleRouter,
+        *,
+        tool_action: Callable[[str], str] = _unqualified_action,
+        wire_schemas: dict[str, dict[str, Any]] | None = None,
+    ) -> None:
+        self._router = router
+        self._tool_action = tool_action
+        self._wire_schemas = dict(wire_schemas or {})
+
+    def filter(self, results: list[SearchResult], query: str) -> list[SearchResult]:
+        out: list[SearchResult] = []
+        for r in results:
+            bundle = self._router.bundle_for(r.tool.server_name)
+            if bundle is None or not bundle.credential_fields():
+                out.append(r)
+                continue
+            out.append(SearchResult(tool=self._augment(r.tool, bundle), score=r.score))
+        return out
+
+    # -- augmentation ------------------------------------------------------- #
+
+    def _augment(self, tool: ToolRecord, bundle: PolicyBundle) -> ToolRecord:
+        schema = deepcopy(tool.input_schema) if tool.input_schema else {"type": "object"}
+        properties: dict[str, Any] = schema.setdefault("properties", {})
+        required: list[str] = schema.setdefault("required", [])
+
+        for field in self._dependency_order(bundle):
+            properties[field] = self._credential_schema(field, bundle)
+            if bundle.is_always_required(field) and field not in required:
+                required.append(field)
+
+        return ToolRecord(
+            name=tool.name,
+            qualified_name=tool.qualified_name,
+            description=self._augment_description(
+                tool.description, bundle, action=self._tool_action(tool.qualified_name)
+            ),
+            input_schema=schema,
+            server_name=tool.server_name,
+            # Keep the original embedding text: augmentation is presentation,
+            # it must not change how the tool is found.
+            embedding_text=tool.embedding_text,
+        )
+
+    def _dependency_order(self, bundle: PolicyBundle) -> list[str]:
+        """Credential fields with each one's dependencies before it (a
+        credential signs over what it depends on, so that must exist first).
+        Fail-soft: an edge to a non-credential field is ignored, and a cycle —
+        which a well-formed bundle's dependency edges should never contain —
+        degrades to the given order."""
+        fields = bundle.credential_fields()
+        ordered: list[str] = []
+        visiting: set[str] = set()
+
+        def visit(field: str) -> None:
+            if field in ordered or field in visiting:
+                return
+            visiting.add(field)
+            for dep in bundle.credential_dependencies(field):
+                if dep in fields:
+                    visit(dep)
+            visiting.discard(field)
+            ordered.append(field)
+
+        for field in fields:
+            visit(field)
+        return ordered
+
+    def _credential_schema(self, field: str, bundle: PolicyBundle) -> dict[str, Any]:
+        base = self._wire_schemas.get(field) or bundle.field_schema(field)
+        schema = deepcopy(base) if isinstance(base, dict) else {"type": "object"}
+        note = self._requirement_phrase(field, bundle)
+        existing = schema.get("description")
+        schema["description"] = f"{existing} {note}".strip() if existing else note
+        return schema
+
+    def _requirement_phrase(self, field: str, bundle: PolicyBundle) -> str:
+        phrase = _vc_bundle_phrase(bundle.issuer_role(field))
+        if bundle.is_always_required(field):
+            return f"Required: {phrase}"
+        deciding = bundle.deciding_sentences(field)
+        when = "; ".join(deciding) if deciding else "certain conditions hold"
+        return f"Required only when {when}. {phrase}"
+
+    def _augment_description(
+        self, description: str, bundle: PolicyBundle, *, action: str
+    ) -> str:
+        lines = ["", "This tool is policy-governed and requires signed credentials:"]
+        for field in self._dependency_order(bundle):
+            role = bundle.issuer_role(field)
+            signed = f", signed by the {role}," if role else ""
+            if bundle.is_always_required(field):
+                head = f"- Always provide `{field}`{signed}".rstrip(",")
+            else:
+                deciding = bundle.deciding_sentences(field)
+                when = "; ".join(deciding) if deciding else "the policy's conditions hold"
+                head = f"- Provide `{field}`{signed} when {when}"
+            deps = [d for d in bundle.credential_dependencies(field)
+                    if d in bundle.credential_fields()]
+            if deps:
+                listed = ", ".join(f"`{d}`" for d in deps)
+                head += f"; obtain {listed} first — this credential signs over it"
+            lines.append(head + ".")
+        lines.append(
+            f'The policy evaluates this tool\'s action as `"{action}"` — when '
+            "requesting a credential, name the action exactly so (the signed "
+            f'request\'s type/action field must equal `"{action}"`, not the '
+            "qualified tool name)."
+        )
+        lines.append(
+            "Calls missing a required credential are denied; the denial says "
+            "what is still needed."
+        )
+        return description + "\n".join(lines)