hypermind 0.11.0__py3-none-any.whl

hypermind/mcp/client.py

@@ -0,0 +1,142 @@
+"""MCP client — JSON-RPC 2.0 caller with CapToken provenance signing."""
+
+from __future__ import annotations
+
+import asyncio
+import itertools
+from typing import Any
+
+from hypermind.crypto.signing import Keypair
+from hypermind.mcp.provenance import (
+    Provenance,
+    ProvenanceError,
+    sign_provenance,
+)
+from hypermind.mcp.transport import MCPTransport
+
+
+class MCPRpcError(Exception):
+    """Raised when the server returns a JSON-RPC error envelope."""
+
+    def __init__(self, code: int, message: str) -> None:
+        super().__init__(f"[{code}] {message}")
+        self.code = code
+        self.message = message
+
+
+class MCPClient:
+    """Async JSON-RPC 2.0 client over an :class:`MCPTransport`.
+
+    Concurrency model: a single background task drains incoming frames
+    and routes them to per-request :class:`asyncio.Future` slots keyed
+    by ``id``. ``call`` is therefore safe to invoke concurrently from
+    multiple coroutines on the same client.
+    """
+
+    def __init__(self, transport: MCPTransport) -> None:
+        self._transport = transport
+        self._counter = itertools.count(1)
+        self._pending: dict[int, asyncio.Future[Any]] = {}
+        self._reader_task: asyncio.Task | None = None
+        self._closed = False
+
+    async def __aenter__(self) -> MCPClient:
+        await self.start()
+        return self
+
+    async def __aexit__(self, *_exc: Any) -> None:
+        await self.close()
+
+    async def start(self) -> None:
+        if self._reader_task is None:
+            self._reader_task = asyncio.create_task(self._reader_loop())
+
+    async def _reader_loop(self) -> None:
+        try:
+            while not self._closed:
+                msg = await self._transport.recv()
+                msg_id = msg.get("id")
+                if not isinstance(msg_id, int):
+                    continue
+                fut = self._pending.pop(msg_id, None)
+                if fut is None or fut.done():
+                    continue
+                if "error" in msg:
+                    err = msg["error"]
+                    fut.set_exception(
+                        MCPRpcError(int(err.get("code", 0)), str(err.get("message", "")))
+                    )
+                else:
+                    fut.set_result(msg.get("result"))
+        except (ConnectionError, asyncio.CancelledError):
+            pass
+        finally:
+            for fut in self._pending.values():
+                if not fut.done():
+                    fut.set_exception(ConnectionError("MCP transport closed"))
+            self._pending.clear()
+
+    async def call(self, method: str, params: dict[str, Any] | None = None) -> Any:
+        """Issue a JSON-RPC request and await the response."""
+        if self._reader_task is None:
+            await self.start()
+        msg_id = next(self._counter)
+        fut: asyncio.Future[Any] = asyncio.get_event_loop().create_future()
+        self._pending[msg_id] = fut
+        await self._transport.send(
+            {"jsonrpc": "2.0", "id": msg_id, "method": method, "params": params or {}}
+        )
+        return await fut
+
+    async def initialize(self) -> dict[str, Any]:
+        return await self.call("initialize", {})
+
+    async def list_tools(self) -> list[dict[str, Any]]:
+        result = await self.call("tools/list", {})
+        return list(result.get("tools", []))
+
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any],
+        *,
+        signing_keypair: Keypair,
+        cap_token_root: bytes,
+        provenance_override: Provenance | None = None,
+    ) -> Any:
+        """Call ``tools/call`` with a CapToken-bound provenance header.
+
+        ``provenance_override`` is an escape hatch for negative tests
+        that want to inject a forged provenance object — production
+        callers should never pass it.
+        """
+        params: dict[str, Any] = {"name": name, "arguments": arguments}
+        if provenance_override is not None:
+            provenance = provenance_override
+        else:
+            provenance = sign_provenance(
+                keypair=signing_keypair,
+                method="tools/call",
+                params=params,
+                cap_token_root=cap_token_root,
+            )
+        params_with_prov = dict(params)
+        params_with_prov["provenance"] = provenance.to_dict()
+        return await self.call("tools/call", params_with_prov)
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        if self._reader_task is not None:
+            self._reader_task.cancel()
+            try:
+                await self._reader_task
+            except (asyncio.CancelledError, Exception):
+                pass
+        await self._transport.close()
+
+
+# Re-export ProvenanceError so callers handling the negative path do
+# not need to import it from hypermind.mcp.provenance directly.
+__all__ = ["MCPClient", "MCPRpcError", "ProvenanceError"]

hypermind/mcp/provenance.py

@@ -0,0 +1,214 @@
+"""MCP tool-call provenance binding (T1-03).
+
+Every MCP ``tools/call`` request signed by the calling agent MUST
+carry a *provenance* triple in its protected header:
+
+    calling_agent_kid : bstr (32-byte Ed25519 pubkey half)
+    cap_token_root    : bstr (SHA-256 of the root CapToken authorising
+                              the call — for fast lookup against the
+                              namespace-scoped cap store)
+    request_kid       : bstr (SHA-256 of the canonical CBOR encoding of
+                              the request body, sans signature — used
+                              for idempotency)
+
+The triple is bound to the call by an Ed25519 signature over the
+canonical CBOR encoding of ``[method, params_without_provenance,
+calling_agent_kid, cap_token_root, request_kid]``. The MCP server
+verifies the signature *before* dispatching the tool, mirroring the
+A-ALG-BOUND discipline of :mod:`hypermind.wire`.
+
+Wire label
+----------
+The numeric label ``HM_MCP_PROVENANCE = -65627`` is reserved in
+:mod:`hypermind.wire` so every label allocation lives in one place.
+On JSON-RPC the field is named ``provenance`` (camelCase) inside the
+request ``params``; on a future COSE_Sign1 carrier the label numeric
+value is the same.
+
+Error codes (JSON-RPC 2.0 ``error.code``)
+-----------------------------------------
+- ``-32001`` MCP_PROVENANCE_MISSING — request lacked provenance
+- ``-32002`` MCP_PROVENANCE_INVALID — signature check failed
+- ``-32003`` MCP_PROVENANCE_UNKNOWN_CAP — cap_token_root not registered
+- ``-32004`` MCP_PROVENANCE_REQUEST_KID_MISMATCH — request_kid does not
+  match the canonical hash of the params
+
+Codes ``-32000..-32099`` are reserved for server errors by the
+JSON-RPC 2.0 specification (§5.1); we use the lower end of that range
+so custom codes do not collide with the library's pre-allocated
+``-32600..-32603`` (parse / invalid-request / method-not-found /
+invalid-params).
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from typing import Any
+
+import cbor2
+
+from hypermind.crypto.signing import Keypair, verify_ed25519
+
+#: JSON-RPC error codes for provenance failures.
+ERR_PROVENANCE_MISSING = -32001
+ERR_PROVENANCE_INVALID = -32002
+ERR_PROVENANCE_UNKNOWN_CAP = -32003
+ERR_PROVENANCE_REQUEST_KID_MISMATCH = -32004
+
+
+def _canon(obj: Any) -> bytes:
+    """RFC 8949 §4.2 deterministic CBOR encoding."""
+    return cbor2.dumps(obj, canonical=True)
+
+
+def compute_request_kid(method: str, params_without_provenance: dict[str, Any]) -> bytes:
+    """SHA-256 of canonical CBOR(method, params)."""
+    return hashlib.sha256(_canon([method, params_without_provenance])).digest()
+
+
+def compute_cap_token_root(cap_token_bytes: bytes) -> bytes:
+    """SHA-256 of the root CapToken's canonical bytes."""
+    return hashlib.sha256(cap_token_bytes).digest()
+
+
+@dataclass(frozen=True)
+class Provenance:
+    """Bound triple + signature attached to an MCP request."""
+
+    calling_agent_kid: bytes
+    cap_token_root: bytes
+    request_kid: bytes
+    signature: bytes
+
+    def to_dict(self) -> dict[str, str]:
+        """Serialise to a JSON-safe mapping (hex-encoded byte fields)."""
+        return {
+            "calling_agent_kid": self.calling_agent_kid.hex(),
+            "cap_token_root": self.cap_token_root.hex(),
+            "request_kid": self.request_kid.hex(),
+            "signature": self.signature.hex(),
+        }
+
+    @classmethod
+    def from_dict(cls, m: dict[str, Any]) -> Provenance:
+        try:
+            return cls(
+                calling_agent_kid=bytes.fromhex(m["calling_agent_kid"]),
+                cap_token_root=bytes.fromhex(m["cap_token_root"]),
+                request_kid=bytes.fromhex(m["request_kid"]),
+                signature=bytes.fromhex(m["signature"]),
+            )
+        except (KeyError, TypeError, ValueError) as e:
+            raise ProvenanceError(
+                ERR_PROVENANCE_INVALID, f"malformed provenance object: {e}"
+            ) from e
+
+
+class ProvenanceError(Exception):
+    """Raised by the MCP server when provenance verification fails."""
+
+    def __init__(self, code: int, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+def sign_provenance(
+    *,
+    keypair: Keypair,
+    method: str,
+    params: dict[str, Any],
+    cap_token_root: bytes,
+) -> Provenance:
+    """Build a provenance attestation for an outbound MCP request.
+
+    ``params`` must be the request params *without* a ``provenance``
+    field — the caller is signing the bare semantic payload.
+    """
+    if "provenance" in params:
+        raise ValueError("params must not yet contain a 'provenance' field")
+    request_kid = compute_request_kid(method, params)
+    sig_input = _canon(
+        [
+            "MCP/Provenance/v1",
+            method,
+            params,
+            keypair.kid,
+            cap_token_root,
+            request_kid,
+        ]
+    )
+    signature = keypair.sign(sig_input)
+    return Provenance(
+        calling_agent_kid=keypair.kid,
+        cap_token_root=cap_token_root,
+        request_kid=request_kid,
+        signature=signature,
+    )
+
+
+def check_provenance(headers: dict) -> None:
+    """Validate that *headers* contains the required MCP provenance fields.
+
+    This is the fast-path gate applied to inbound MCP tool-call envelopes
+    before cryptographic verification. It enforces spec §4.13.1: every
+    inbound call MUST carry ``cap_token_root`` (and, by extension, the full
+    provenance triple). Missing or ``None`` values raise immediately so the
+    server can return ``ERR_PROVENANCE_MISSING`` without attempting to parse
+    a broken envelope.
+
+    Parameters
+    ----------
+    headers:
+        The request headers / params dict received from the MCP client.
+        Typically the ``provenance`` sub-dict extracted from the JSON-RPC
+        ``params`` object.
+
+    Raises
+    ------
+    ValueError
+        ``"MCP-NO-CAP-ROOT"`` when ``cap_token_root`` is absent or ``None``.
+    ValueError
+        ``"MCP-NO-CALLING-AGENT-KID"`` when ``calling_agent_kid`` is absent.
+    ValueError
+        ``"MCP-NO-REQUEST-KID"`` when ``request_kid`` is absent.
+    """
+    if not headers.get("cap_token_root"):
+        raise ValueError("MCP-NO-CAP-ROOT")
+    if not headers.get("calling_agent_kid"):
+        raise ValueError("MCP-NO-CALLING-AGENT-KID")
+    if not headers.get("request_kid"):
+        raise ValueError("MCP-NO-REQUEST-KID")
+
+
+def verify_provenance(
+    *,
+    method: str,
+    params_without_provenance: dict[str, Any],
+    provenance: Provenance,
+) -> None:
+    """Verify the signature and request_kid binding.
+
+    Raises :class:`ProvenanceError` with a JSON-RPC error code on
+    failure. Does NOT verify that ``cap_token_root`` corresponds to a
+    known CapToken — the server does that in a second step.
+    """
+    expected_kid = compute_request_kid(method, params_without_provenance)
+    if expected_kid != provenance.request_kid:
+        raise ProvenanceError(
+            ERR_PROVENANCE_REQUEST_KID_MISMATCH,
+            "request_kid does not match canonical hash of params",
+        )
+    sig_input = _canon(
+        [
+            "MCP/Provenance/v1",
+            method,
+            params_without_provenance,
+            provenance.calling_agent_kid,
+            provenance.cap_token_root,
+            provenance.request_kid,
+        ]
+    )
+    if not verify_ed25519(provenance.calling_agent_kid, provenance.signature, sig_input):
+        raise ProvenanceError(ERR_PROVENANCE_INVALID, "provenance signature invalid")

hypermind/mcp/relata_tools.py

@@ -0,0 +1,152 @@
+"""RelataDB exposed to HyperMind agents as a research tool source (integration P2).
+
+Registers a curated set of Relata knowledge/memory tools and dispatches calls to
+Relata's MCP server via ``relata.McpClient``. This is the "agents research from
+the tools they have access to" surface: an agent mid-``consult`` / deliberation
+can recall memory, search the knowledge base, run a governed query, or traverse
+the entity graph — all sourced from Relata, all tenant-scoped.
+
+Two MCP layers, do not confuse them:
+  * HyperMind's own MCP (``src/hypermind/mcp/``) — agents expose/consume tools
+    per the HM protocol.
+  * This module — Relata offered as *one tool source* inside HM. They compose.
+
+**Access is CapToken-gated.** Pass an agent's ``cap_token`` to :meth:`call` and
+each dispatch is authorized against a ``Caveat.tool(...)`` scope (glob-subset
+match), so you can grant an agent ``relata.recall`` without ``relata.query_knowledge``.
+
+The ``relata`` SDK is imported lazily inside :meth:`open`; tests inject
+``mcp_factory``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+if False:  # TYPE_CHECKING — avoid importing capability at module load
+    from hypermind.capability import CapToken
+
+_PURPOSE = "agent_research"
+
+# slug → Relata MCP tool name + MCP tools/list descriptor.
+_RELATA_TOOLS: dict[str, dict[str, Any]] = {
+    "relata.recall": {
+        "mcp": "recall",
+        "description": "Recall memories relevant to a query, ranked by relevance/recency.",
+        "schema": {
+            "type": "object",
+            "properties": {"query": {"type": "string"}, "top_k": {"type": "integer"}},
+            "required": ["query"],
+        },
+    },
+    "relata.search_knowledge": {
+        "mcp": "search_knowledge",
+        "description": "Semantic + keyword search over the Relata knowledge base.",
+        "schema": {
+            "type": "object",
+            "properties": {"query": {"type": "string"}},
+            "required": ["query"],
+        },
+    },
+    "relata.query_knowledge": {
+        "mcp": "query_knowledge",
+        "description": "Run a governed, read-only SQL query against Relata.",
+        "schema": {
+            "type": "object",
+            "properties": {"sql": {"type": "string"}},
+            "required": ["sql"],
+        },
+    },
+    "relata.find_connections": {
+        "mcp": "find_connections",
+        "description": "Graph traversal: find entities connected to the given entity.",
+        "schema": {
+            "type": "object",
+            "properties": {"entity": {"type": "string"}, "limit": {"type": "integer"}},
+            "required": ["entity"],
+        },
+    },
+}
+
+McpFactory = Callable[[], Any]
+
+
+class RelataToolProvider:
+    """Adapts Relata's MCP tools into HyperMind's tool surface. One per (server, namespace)."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        namespace_id: str,
+        bearer_token: str | None = None,
+        purpose: str = _PURPOSE,
+        mcp_factory: McpFactory | None = None,
+    ) -> None:
+        self._url = base_url
+        self._ns = namespace_id
+        self._tok = bearer_token
+        self._purpose = purpose
+        self._factory = mcp_factory
+        self._mcp: Any = None
+
+    def open(self) -> None:
+        if self._mcp is not None:
+            return
+        if self._factory is not None:
+            self._mcp = self._factory()
+        else:  # pragma: no cover - requires the optional `relata` SDK + live server
+            from relata import RelataClient
+            from relata.mcp import McpClient
+
+            client = RelataClient(
+                self._url,
+                bearer_token=self._tok,
+                purpose=self._purpose,
+                tenant=self._ns,  # tenant isolation
+            )
+            self._mcp = McpClient.from_client(client)
+
+    def close(self) -> None:
+        if self._mcp is not None:
+            self._mcp.close()
+            self._mcp = None
+
+    def _require(self) -> Any:
+        if self._mcp is None:
+            raise RuntimeError("RelataToolProvider used before open()")
+        return self._mcp
+
+    def tool_defs(self) -> list[dict[str, Any]]:
+        """MCP ``tools/list``-shaped descriptors — mergeable into HM's tool view."""
+        return [
+            {"name": slug, "description": spec["description"], "inputSchema": spec["schema"]}
+            for slug, spec in _RELATA_TOOLS.items()
+        ]
+
+    def call(
+        self,
+        slug: str,
+        arguments: dict[str, Any],
+        *,
+        cap_token: CapToken | None = None,
+        **authorize_kwargs: Any,
+    ) -> dict[str, Any]:
+        """Dispatch a whitelisted Relata tool call.
+
+        When ``cap_token`` is provided, the call is authorized against a
+        ``Caveat.tool(slug)`` scope first (raising ``AuthError`` if not granted).
+        Extra keyword args flow to :meth:`CapToken.authorize` (e.g.
+        ``expected_root_issuer=``, ``revocation_store=``). Delegated tokens must
+        be chain-verified by the caller before use.
+        """
+        spec = _RELATA_TOOLS.get(slug)
+        if spec is None:
+            raise KeyError(f"unknown Relata tool {slug!r}; known: {sorted(_RELATA_TOOLS)}")
+        if cap_token is not None:
+            cap_token.authorize(action="tool_call", tool=slug, **authorize_kwargs)
+        # Relata's MCP tools expect a governance `purpose`; inject ours unless
+        # the caller overrides (mirrors relata.McpClient's typed methods).
+        args = {"purpose": self._purpose, **arguments}
+        return dict(self._require().call_tool(spec["mcp"], args))