hyperroute-mcp 0.1.0__py3-none-any.whl

hyperroute_mcp/__init__.py

@@ -0,0 +1,13 @@
+"""HyperRoute MCP — a Model Context Protocol server that exposes the HyperRoute router
+(register, login, recommend, describe, onboard, execute, report_outcome, HyperFeed, …) as MCP
+tools, so a coordinator agent (Claude Code, Codex, Goose, Cursor, …) can drive the whole product
+end-to-end in one conversation.
+
+It talks to the router only over its public HTTP API and holds no product logic of its own.
+"""
+
+__version__ = "0.1.0"
+
+from .server import mcp
+
+__all__ = ["mcp", "__version__"]

hyperroute_mcp/__main__.py

@@ -0,0 +1,13 @@
+"""`python -m hyperroute_mcp` — run the HyperRoute MCP server over stdio (the transport MCP
+clients launch it with). Point it at a router with HYPERROUTE_BASE_URL; see config.py for the
+full set of environment variables."""
+
+from .server import mcp
+
+
+def main() -> None:
+    mcp.run()  # stdio transport by default
+
+
+if __name__ == "__main__":
+    main()

hyperroute_mcp/client.py

@@ -0,0 +1,188 @@
+"""Thin async HTTP client over the HyperRoute router's public API.
+
+One method per endpoint this server touches. No product logic lives here — the client only
+knows how to (a) carry the session bearer token, and (b) turn the router's responses into
+plain dicts, surfacing its structured `detail` error bodies instead of raising, so the MCP
+tools can hand a coordinator an actionable object (e.g. `needs_onboard` + signup instructions)
+rather than a stack trace.
+
+One endpoint answers in text rather than JSON: `recommend` with `format=text` returns the
+compact tabular coordinator wire, so `_request(..., as_text=True)` returns a `str`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class Session:
+    """The MCP process's login state: the active bearer token and the resolved user_id.
+
+    Mutated in place by `register` / `login` so every later recommend/onboard/execute call
+    is authenticated as the same user for the life of the MCP connection.
+    """
+
+    def __init__(self, api_key: str | None = None) -> None:
+        self.api_key = api_key
+        self.user_id: str | None = None
+        self.email: str | None = None
+        self.env_managed = False   # token came from HYPERROUTE_API_KEY — don't read/write the cache
+
+    @property
+    def logged_in(self) -> bool:
+        return bool(self.api_key)
+
+
+def _unwrap(r: httpx.Response) -> Any:
+    """Router response -> dict. Success bodies pass through; error bodies are normalized to
+    `{"_error": True, "_http_status": <code>, ...}` with the server's `detail` merged in."""
+    try:
+        body = r.json()
+    except ValueError:
+        body = {"raw": r.text}
+    if r.is_success:
+        return body
+    detail = body.get("detail") if isinstance(body, dict) else None
+    base = {"_error": True, "_http_status": r.status_code}
+    if isinstance(detail, dict):
+        return {**base, **detail}
+    if detail is not None:
+        return {**base, "message": detail}
+    return {**base, "body": body}
+
+
+class HyperRouteClient:
+    """Stateless-per-call HTTP client bound to a mutable `Session` for auth."""
+
+    def __init__(self, base_url: str, session: Session, timeout: float = 30.0) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.session = session
+        self._timeout = timeout
+
+    def _headers(self, auth: bool) -> dict[str, str]:
+        h = {"content-type": "application/json"}
+        if auth and self.session.api_key:
+            h["authorization"] = f"Bearer {self.session.api_key}"
+        return h
+
+    async def _request(self, method: str, path: str, *, auth: bool = False,
+                       json: dict | None = None, params: dict | None = None,
+                       as_text: bool = False) -> Any:
+        if json is not None:  # drop None fields so router defaults apply
+            json = {k: v for k, v in json.items() if v is not None}
+        if params is not None:
+            params = {k: v for k, v in params.items() if v is not None}
+        try:
+            async with httpx.AsyncClient(timeout=self._timeout) as c:
+                r = await c.request(method, f"{self.base_url}{path}",
+                                    headers=self._headers(auth), json=json, params=params)
+        except httpx.RequestError as e:
+            return {"_error": True, "message": f"could not reach router at {self.base_url}: {e}"}
+        if as_text and r.is_success:
+            return r.text
+        return _unwrap(r)
+
+    # -- surfaces -----------------------------------------------------------
+    async def health(self) -> Any:
+        return await self._request("GET", "/health")
+
+    async def register(self, email: str, password: str, display_name: str | None) -> Any:
+        return await self._request("POST", "/auth/register",
+                                   json={"email": email, "password": password,
+                                         "display_name": display_name})
+
+    async def verify(self, email: str, code: str) -> Any:
+        return await self._request("POST", "/auth/verify", json={"email": email, "code": code})
+
+    async def login(self, email: str, password: str) -> Any:
+        return await self._request("POST", "/auth/login", json={"email": email, "password": password})
+
+    async def request_login_code(self, email: str) -> Any:
+        return await self._request("POST", "/auth/login/request-code", json={"email": email})
+
+    async def login_with_code(self, email: str, code: str) -> Any:
+        return await self._request("POST", "/auth/login/code", json={"email": email, "code": code})
+
+    async def forgot_password(self, email: str) -> Any:
+        return await self._request("POST", "/auth/password/forgot", json={"email": email})
+
+    async def whoami(self) -> Any:
+        return await self._request("POST", "/auth/whoami", auth=True)
+
+    async def recommend_text(self, payload: dict) -> Any:
+        """The coordinator wire: `detail=min` + `format=text` → compact tabular text (a `str`),
+        or the usual error dict. Depth is pulled per-tool afterwards via `describe`."""
+        return await self._request("POST", "/recommend", auth=True,
+                                   json={**payload, "detail": "min", "format": "text"},
+                                   as_text=True)
+
+    async def describe(self, payload: dict) -> Any:
+        return await self._request("POST", "/describe", auth=True, json=payload)
+
+    async def catalog(self) -> Any:
+        """The router's tool catalog (id + kind + auth + capabilities). Public; used to resolve
+        which coordinator ids exist before declaring the native baseline."""
+        return await self._request("GET", "/console", params={"view": "tools", "format": "json"})
+
+    async def onboard_info(self, tool_id: str) -> Any:
+        return await self._request("GET", f"/onboard/{tool_id}", auth=True)
+
+    async def onboard(self, tool_id: str, api_key: str, label: str | None) -> Any:
+        return await self._request("POST", "/onboard", auth=True,
+                                   json={"tool_id": tool_id, "api_key": api_key, "label": label})
+
+    async def execute(self, tool_id: str, query: str) -> Any:
+        return await self._request("POST", "/execute", auth=True,
+                                   json={"tool_id": tool_id, "query": query})
+
+    async def read_result(self, ref: str, op: str, offset: int, limit: int,
+                          path: list | None, query: str | None) -> Any:
+        return await self._request("POST", f"/result/{ref}/read", auth=True,
+                                   json={"op": op, "offset": offset, "limit": limit,
+                                         "path": path, "query": query})
+
+    async def list_credentials(self, user_id: str) -> Any:
+        return await self._request("GET", "/credentials", auth=True, params={"user_id": user_id})
+
+    async def report_outcome(self, payload: dict) -> Any:
+        return await self._request("POST", "/report_outcome", json=payload)
+
+    async def report_narrative(self, payload: dict) -> Any:
+        return await self._request("POST", "/report_narrative", json=payload)
+
+    async def console(self, view: str, user_id: str) -> Any:
+        return await self._request("GET", "/console", auth=True,
+                                   params={"view": view, "format": "json", "user_id": user_id})
+
+    async def facets_catalog(self) -> Any:
+        return await self._request("GET", "/facets/catalog")
+
+    async def get_preferences(self, project_id: str | None = None) -> Any:
+        return await self._request("GET", "/preferences", auth=True,
+                                   params={"project_id": project_id})
+
+    async def set_preferences(self, facets: dict, project_id: str | None = None) -> Any:
+        return await self._request("PUT", "/preferences", auth=True,
+                                   json={"facets": facets, "project_id": project_id})
+
+    # -- HyperFeed ----------------------------------------------------------
+    async def feed(self, stream: str | None = None, since: str | None = None,
+                   limit: int = 50) -> Any:
+        return await self._request("GET", "/feed",
+                                   params={"stream": stream, "since": since, "limit": limit})
+
+    async def feed_streams(self) -> Any:
+        return await self._request("GET", "/feed/streams")
+
+    async def feed_digest(self, since: str | None = None, limit: int = 20) -> Any:
+        return await self._request("GET", "/feed/digest", auth=True,
+                                   params={"since": since, "limit": limit})
+
+    async def feed_subscribe(self, payload: dict) -> Any:
+        return await self._request("POST", "/feed/subscribe", auth=True, json=payload)
+
+    async def feed_react(self, item_id: str, action: str) -> Any:
+        return await self._request("POST", "/feed/react", auth=True,
+                                   json={"item_id": item_id, "action": action})

hyperroute_mcp/config.py

@@ -0,0 +1,58 @@
+"""Runtime configuration — everything is environment-driven, so the same package runs against
+the hosted router, a self-hosted one, or a local dev instance with no code change.
+
+  HYPERROUTE_BASE_URL      base URL of the router (default https://hyperroute.io)
+  HYPERROUTE_API_KEY       optional hyr_… personal access token to start already logged in
+  HYPERROUTE_TIMEOUT       per-request timeout in seconds (default 30)
+  HYPERROUTE_TOKEN_FILE    where the login token is cached (default ~/.hyperroute/token.json)
+
+  HYPERROUTE_COORDINATOR   which coordinator this server runs inside — "claude_code", "codex",
+                           or "none" to disable the declaration entirely. Unset = auto-detect
+                           from the MCP client's identity (see native.py).
+  HYPERROUTE_NATIVE_TOOLS  explicit, comma-separated coordinator tool ids to declare instead of
+                           auto-detecting (e.g. "claude_code_sonnet_quick" to pin one model).
+  HYPERROUTE_HELD          comma-separated plan groups the user already pays for
+                           (e.g. "anthropic_max_5x"), so those tools price at $0.
+"""
+
+from __future__ import annotations
+
+import os
+
+DEFAULT_BASE_URL = "https://hyperroute.io"
+DEFAULT_TIMEOUT = 30.0
+
+
+def base_url() -> str:
+    return os.environ.get("HYPERROUTE_BASE_URL", DEFAULT_BASE_URL).rstrip("/")
+
+
+def preset_api_key() -> str | None:
+    return os.environ.get("HYPERROUTE_API_KEY") or None
+
+
+def timeout() -> float:
+    try:
+        return float(os.environ.get("HYPERROUTE_TIMEOUT", DEFAULT_TIMEOUT))
+    except ValueError:
+        return DEFAULT_TIMEOUT
+
+
+def _csv(name: str) -> list[str]:
+    return [p.strip() for p in (os.environ.get(name) or "").split(",") if p.strip()]
+
+
+def coordinator() -> str | None:
+    """The coordinator product to declare, or None to auto-detect. "none"/"off" disables it."""
+    v = (os.environ.get("HYPERROUTE_COORDINATOR") or "").strip().lower()
+    return v or None
+
+
+def native_tools() -> list[str]:
+    """Explicit coordinator tool ids to declare, bypassing detection."""
+    return _csv("HYPERROUTE_NATIVE_TOOLS")
+
+
+def held_plans() -> list[str]:
+    """Plan groups the user holds — a held plan makes that tool free to them."""
+    return _csv("HYPERROUTE_HELD")

hyperroute_mcp/native.py

@@ -0,0 +1,161 @@
+"""Declaring the native baseline — the coordinator this server runs inside.
+
+HyperRoute never assumes you have a coordinator. Its verdict for a task is one of:
+
+  * **interpose** — an external tool beats what you can already do, so route to it;
+  * **use_native** — nothing beats your own tools, so do it yourself.
+
+That comparison needs a baseline, and the baseline is the set of coordinators that are
+effectively free to the caller. An MCP server that does not say which coordinator it runs
+inside gives the router no baseline at all, so an external tool wins *every* time — including
+for tasks the coordinator does better itself. Declaring it is therefore not optional.
+
+Two independent ways to be effectively free, both sent on the `recommend` call's `context`:
+
+  * `native_tools` — **self-loopback**: the caller IS this coordinator. Zero marginal cost.
+  * `entitlements.held` — a **subscription** the user already pays for (e.g. `anthropic_max_5x`),
+    which also prices that tool at $0.
+
+Resolution order, first hit wins:
+
+  1. `HYPERROUTE_NATIVE_TOOLS` — explicit tool ids, e.g. to pin one model variant.
+  2. `HYPERROUTE_COORDINATOR` — a product name (`claude_code`, `codex`); `none`/`off` disables.
+  3. Auto-detect from the MCP client's own identity, sent on the protocol handshake.
+
+A product name resolves to concrete tool ids against the router's live catalog (fetched once
+per process, cached), so a new coordinator variant needs no release here. If detection finds
+nothing the declaration is simply omitted — routing still works, it just has no baseline.
+"""
+
+from __future__ import annotations
+
+from . import config
+
+# MCP client identity (as sent on the protocol handshake) -> the coordinator product it is.
+# Matched as a prefix on the lowercased, punctuation-normalized client name, longest first, so
+# "claude-code" wins over a bare "claude". Deliberately conservative: an unrecognized client
+# declares nothing rather than claiming capability it does not have.
+_CLIENT_PRODUCTS = {
+    "claude_code": "claude_code",
+    "codex": "codex",
+    "cursor": "cursor",
+    "goose": "goose",
+    "cline": "cline",
+    "opencode": "opencode",
+    "aider": "aider",
+}
+
+_DISABLED = {"none", "off", "no", "false", "0"}
+
+# Resolved once per process: product name -> the coordinator tool ids the router models for it.
+_catalog_cache: dict[str, list[str]] | None = None
+
+
+def normalize_client(name: str | None) -> str:
+    """`Claude Code`, `claude-code`, `claude_code/1.2` -> `claude_code`."""
+    if not name:
+        return ""
+    out = []
+    for ch in name.strip().lower():
+        out.append(ch if ch.isalnum() else "_")
+    return "".join(out).strip("_")
+
+
+def product_for_client(name: str | None) -> str | None:
+    """Which coordinator product an MCP client is, or None when we don't recognize it."""
+    norm = normalize_client(name)
+    if not norm:
+        return None
+    for key in sorted(_CLIENT_PRODUCTS, key=len, reverse=True):
+        if norm == key or norm.startswith(key + "_"):
+            return _CLIENT_PRODUCTS[key]
+    return None
+
+
+def _match(tool_id: str, product: str) -> bool:
+    return tool_id == product or tool_id.startswith(product + "_")
+
+
+async def coordinator_ids(client, product: str) -> list[str]:
+    """The router's tool ids for a coordinator product, read from its live catalog.
+
+    All of a product's variants are declared together: the coordinator can switch model or
+    depth mid-session, so the product — not one variant — is what the caller *is*. Pin a single
+    variant with `HYPERROUTE_NATIVE_TOOLS` when that matters.
+    """
+    global _catalog_cache
+    if _catalog_cache is None:
+        cat = await client.catalog()
+        tools = cat.get("tools") if isinstance(cat, dict) else None
+        if not tools:
+            return []                                    # unreachable/empty catalog: declare nothing
+        by_product: dict[str, list[str]] = {}
+        for t in tools:
+            if t.get("kind") != "coordinator_agent":
+                continue
+            tid = t.get("id") or ""
+            for prod in set(_CLIENT_PRODUCTS.values()):
+                if _match(tid, prod):
+                    by_product.setdefault(prod, []).append(tid)
+        _catalog_cache = by_product
+    return sorted(_catalog_cache.get(product, []))
+
+
+def reset_cache() -> None:
+    """Drop the cached catalog (tests; a router that swapped bundles mid-session)."""
+    global _catalog_cache
+    _catalog_cache = None
+
+
+async def declared_context(client, client_name: str | None) -> dict:
+    """The `context` fragment to merge into every route: what this caller already has.
+
+    Returns `{}` when nothing is known — no baseline, and the best external tool simply wins.
+    """
+    setting = config.coordinator()
+    if setting in _DISABLED:
+        return {}
+
+    ids = config.native_tools()
+    if not ids:
+        product = setting or product_for_client(client_name)
+        if product:
+            ids = await coordinator_ids(client, product)
+
+    out: dict = {}
+    if ids:
+        out["native_tools"] = ids
+    held = config.held_plans()
+    if held:
+        out["entitlements"] = {"held": held}
+    return out
+
+
+def merge_context(declared: dict, supplied: dict | None) -> dict | None:
+    """Merge the declaration UNDER a caller-supplied `context`.
+
+    `native_tools` and `entitlements.held` are **unioned, never dropped** — what the caller is, and
+    what it holds, are structural facts, so a per-call context adds to them rather than replacing
+    them. (Silently losing the declaration on a call that happened to pass a context is the exact
+    failure this whole module exists to prevent.) Every other key the caller passes wins outright.
+    To route with no baseline at all, disable the declaration itself: `HYPERROUTE_COORDINATOR=none`.
+    """
+    caller = dict(supplied or {})
+    if not declared and not caller:
+        return None
+
+    merged = {**caller}
+    native = _union(declared.get("native_tools"), caller.get("native_tools"))
+    if native:
+        merged["native_tools"] = native
+
+    caller_ent = dict(caller.get("entitlements") or {})
+    held = _union((declared.get("entitlements") or {}).get("held"), caller_ent.get("held"))
+    if held or caller_ent:
+        merged["entitlements"] = {**caller_ent, **({"held": held} if held else {})}
+    return merged or None
+
+
+def _union(*lists) -> list[str]:
+    """Order-preserving union — declaration first, caller's additions after."""
+    return list(dict.fromkeys([x for lst in lists for x in (lst or [])]))