hyperroute-mcp 0.1.0__tar.gz

hyperroute_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HyperRouteAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hyperroute_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: hyperroute-mcp
+Version: 0.1.0
+Summary: MCP server for HyperRoute — routes each task to the best external tool and runs it for your coordinator agent.
+Author: HyperRouteAI
+License-Expression: MIT
+Project-URL: Homepage, https://hyperroute.io
+Project-URL: Repository, https://github.com/HyperRouteAI/hyperroute-mcp
+Project-URL: Issues, https://github.com/HyperRouteAI/hyperroute-mcp/issues
+Keywords: mcp,model-context-protocol,hyperroute,agents,tool-routing,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# hyperroute-mcp
+
+The official [Model Context Protocol](https://modelcontextprotocol.io) server for
+**[HyperRoute](https://hyperroute.io)**.
+
+HyperRoute is a router for AI agents. Give it a task and it picks the best external tool for
+*that* task — measured, not advertised — then runs the tool for you with your own key held
+server-side, and learns from how it went. This MCP server is how a coordinator agent (Claude
+Code, Codex, Goose, Cursor, LangGraph, …) drives it:
+
+> recommend → onboard a key → execute the tool server-side → report the outcome
+
+It talks to the router only over its public HTTP API and holds no product logic of its own.
+
+## Why route at all
+
+An agent with 100 tools bolted on has a context problem and a quality problem. HyperRoute
+replaces both with one verb: your agent learns `recommend`, and HyperRoute decides which of
+hundreds of tools actually answers this task, whether you can already do it better yourself,
+and what it will cost.
+
+- **Measured, not advertised.** Every capability score is backed by real graded probes you can
+  inspect (`describe(tool_id, ["evidence"])`).
+- **Your keys never leave the server.** You connect a key once; HyperRoute runs the tool with it
+  and returns only the result. The key is never sent to your agent, never logged.
+- **It tells you when NOT to route.** If nothing beats what your coordinator already does, the
+  verdict is `use_native` — do it yourself. That only works if the server knows which coordinator
+  it runs inside; see [Declaring your coordinator](#declaring-your-coordinator).
+
+## Install
+
+Not on PyPI yet — install from source:
+
+```bash
+git clone https://github.com/HyperRouteAI/hyperroute-mcp
+cd hyperroute-mcp
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+Or straight from GitHub, without cloning:
+
+```bash
+pip install git+https://github.com/HyperRouteAI/hyperroute-mcp
+```
+
+Either way you get the `hyperroute-mcp` command on your PATH. Requires Python ≥ 3.10.
+
+## Add it to your coordinator
+
+**Claude Code**
+
+```bash
+claude mcp add hyperroute -- hyperroute-mcp
+```
+
+If you installed into a venv, `hyperroute-mcp` is only on your PATH while that venv is active — MCP
+clients launch the server themselves, outside your shell. Give them the absolute path instead
+(`/path/to/.venv/bin/hyperroute-mcp`), or install with [`pipx`](https://pipx.pypa.io) so the command
+is always available.
+
+**OpenCode** — copy [`opencode.json`](opencode.json) into your project. OpenCode is bring-your-own-model,
+so the server can't infer what you're running from the client name alone: set `HYPERROUTE_COORDINATOR`
+(or `HYPERROUTE_NATIVE_TOOLS`) to match the model you actually point it at, or HyperRoute will have no
+baseline for you. [`AGENTS.md`](AGENTS.md) carries the operating loop and the methodology — drop it in
+so the agent can both act correctly and explain how the routing works.
+
+**Any MCP client** (`mcp.json` / `claude_desktop_config.json` / equivalent):
+
+```json
+{
+  "mcpServers": {
+    "hyperroute": {
+      "command": "hyperroute-mcp",
+      "env": { "HYPERROUTE_BASE_URL": "https://hyperroute.io" }
+    }
+  }
+}
+```
+
+Then just ask: *"Use HyperRoute to find the best tool for searching recent papers, connect my
+key, and run it."* The agent calls `recommend` → `connect_info` → `onboard` → `execute` on its
+own.
+
+## Authenticate once
+
+`recommend` and browsing are public — no account. Connecting keys and running tools need one.
+
+Preferred: mint a personal access token at [hyperroute.io](https://hyperroute.io) and hand it to
+the `use_token` tool (or set `HYPERROUTE_API_KEY`). Your password never enters the conversation.
+
+The token is then **cached on disk** (`~/.hyperroute/token.json`, mode `0600`, keyed by router
+URL), so every new MCP session restores your login silently. You are asked to authenticate again
+only if the router invalidates the token. A full inline `register` → `verify` email-code flow is
+also available for headless use.
+
+## Declaring your coordinator
+
+HyperRoute compares external tools against *what you can already do*. That baseline is the set of
+coordinators that are free to you — and it is **empty by default**, because the router never
+assumes you have one. An MCP server that does not declare itself gets an external tool
+recommended for every task, including tasks the coordinator does better itself.
+
+This server declares it for you. It reads the MCP client identity your coordinator sends on
+connect and maps it to the coordinator HyperRoute models (`claude-code` → `claude_code`, …).
+Check what it resolved with the `session_info` tool: if `native_tools` is empty, set it yourself.
+
+```jsonc
+"env": {
+  "HYPERROUTE_COORDINATOR": "claude_code",       // or codex / cursor / goose / …; "none" disables
+  "HYPERROUTE_HELD": "anthropic_max_5x"          // subscriptions you already pay for → priced at $0
+}
+```
+
+`HYPERROUTE_NATIVE_TOOLS` takes exact tool ids if you want to pin one model variant instead of the
+whole product family.
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `HYPERROUTE_BASE_URL` | `https://hyperroute.io` | Which router to talk to. Override to point at a different instance. |
+| `HYPERROUTE_API_KEY` | — | `hyr_…` token to start already logged in. Externally managed: used, never cached. |
+| `HYPERROUTE_TIMEOUT` | `30` | Per-request timeout, seconds. |
+| `HYPERROUTE_TOKEN_FILE` | `~/.hyperroute/token.json` | Where the cached login lives. |
+| `HYPERROUTE_COORDINATOR` | auto-detect | Which coordinator this runs inside; `none` disables the declaration. |
+| `HYPERROUTE_NATIVE_TOOLS` | — | Exact coordinator tool ids, overriding detection. |
+| `HYPERROUTE_HELD` | — | Comma-separated plan groups you hold, e.g. `anthropic_max_5x`. |
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `session_info` | Base URL, login state, and the coordinator this server declares. Call first. |
+| `health` | Router readiness + the loaded model bundle. |
+| `recommend` | **The main verb.** Task → ranked tools as a compact table + how to act. Public. |
+| `describe` | Pull ONE tool's depth on demand: `about` · `price` · `facets` · `evidence`. |
+| `facets_catalog` | Every facet a tool can be judged on, with defaults. Fetch once. |
+| `get_preferences` / `set_preferences` | Your standing constraints, applied to every future route. |
+| `connect_info` | A tool's onboarding process: signup URL, steps, whether you're connected. |
+| `onboard` | Save + test one tool API key under your account. Stored encrypted, reused forever. |
+| `list_credentials` | Your connected tools (keys masked). |
+| `execute` | Run the chosen tool server-side with your held key; returns only the result. |
+| `fetch_result` | Page through a result too large to inline. |
+| `report_outcome` | Per-call feedback — the signal that sharpens future routing. |
+| `report_narrative` | Open-ended feedback about a whole run. |
+| `console` | Human-readable management view: history, tools, keys, stats. |
+| `use_token` / `register` / `verify` / `login` / `login_link` / `verify_login` / `forgot_password` / `whoami` | Account lifecycle. |
+| `hyperfeed` / `hyperfeed_digest` / `hyperfeed_subscribe` / `hyperfeed_react` | HyperFeed: curated agentic-AI news, agent releases, and SF events — plus your agent's personalized daily brief. |
+
+### The wire is deliberately lean
+
+`recommend` answers with a compact table, not a catalog dump:
+
+```
+session: s-6d6c5a95f9f84d9a
+verdict: interpose
+refine:  freshness, cited_references, source_quality
+
+  tool              name                        price  use        why
+→ opencitations     OpenCitations Index         free   ready      highest-ranked: capability 0.81 …
+  semantic_scholar  Semantic Scholar Graph API  free   needs_key  lower capability (0.75 vs 0.81).
+
+confidence: med (on the pick)
+act: execute('opencitations', <query>)
+```
+
+Everything else — descriptions, per-plan pricing, per-facet breakdowns, the probe evidence behind
+a score — is pulled for the one tool that matters via `describe`. That keeps a route roughly an
+order of magnitude cheaper in tokens than shipping the full object on every call.
+
+The `use` column is the whole auth story: `ready` (run it) · `needs_key` (connect first) ·
+`native` (do it yourself) · `soon` (not runnable server-side yet).
+
+### Two-pass refinement
+
+Pass 1 always returns a usable ranking. The `refine:` line names the unset preferences that would
+reorder *these* candidates; fill the relevant ones and call `recommend` again with `facets` for a
+personalized result. Durable constraints (GDPR, a budget cap) belong in `set_preferences`
+instead — stored once, applied to every future route.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+The suite is fully offline — the router is faked, so no network and no real account are touched.
+Set `HYPERROUTE_BASE_URL` to try it against a different router instance.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

hyperroute_mcp-0.1.0/README.md

@@ -0,0 +1,195 @@
+# hyperroute-mcp
+
+The official [Model Context Protocol](https://modelcontextprotocol.io) server for
+**[HyperRoute](https://hyperroute.io)**.
+
+HyperRoute is a router for AI agents. Give it a task and it picks the best external tool for
+*that* task — measured, not advertised — then runs the tool for you with your own key held
+server-side, and learns from how it went. This MCP server is how a coordinator agent (Claude
+Code, Codex, Goose, Cursor, LangGraph, …) drives it:
+
+> recommend → onboard a key → execute the tool server-side → report the outcome
+
+It talks to the router only over its public HTTP API and holds no product logic of its own.
+
+## Why route at all
+
+An agent with 100 tools bolted on has a context problem and a quality problem. HyperRoute
+replaces both with one verb: your agent learns `recommend`, and HyperRoute decides which of
+hundreds of tools actually answers this task, whether you can already do it better yourself,
+and what it will cost.
+
+- **Measured, not advertised.** Every capability score is backed by real graded probes you can
+  inspect (`describe(tool_id, ["evidence"])`).
+- **Your keys never leave the server.** You connect a key once; HyperRoute runs the tool with it
+  and returns only the result. The key is never sent to your agent, never logged.
+- **It tells you when NOT to route.** If nothing beats what your coordinator already does, the
+  verdict is `use_native` — do it yourself. That only works if the server knows which coordinator
+  it runs inside; see [Declaring your coordinator](#declaring-your-coordinator).
+
+## Install
+
+Not on PyPI yet — install from source:
+
+```bash
+git clone https://github.com/HyperRouteAI/hyperroute-mcp
+cd hyperroute-mcp
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+Or straight from GitHub, without cloning:
+
+```bash
+pip install git+https://github.com/HyperRouteAI/hyperroute-mcp
+```
+
+Either way you get the `hyperroute-mcp` command on your PATH. Requires Python ≥ 3.10.
+
+## Add it to your coordinator
+
+**Claude Code**
+
+```bash
+claude mcp add hyperroute -- hyperroute-mcp
+```
+
+If you installed into a venv, `hyperroute-mcp` is only on your PATH while that venv is active — MCP
+clients launch the server themselves, outside your shell. Give them the absolute path instead
+(`/path/to/.venv/bin/hyperroute-mcp`), or install with [`pipx`](https://pipx.pypa.io) so the command
+is always available.
+
+**OpenCode** — copy [`opencode.json`](opencode.json) into your project. OpenCode is bring-your-own-model,
+so the server can't infer what you're running from the client name alone: set `HYPERROUTE_COORDINATOR`
+(or `HYPERROUTE_NATIVE_TOOLS`) to match the model you actually point it at, or HyperRoute will have no
+baseline for you. [`AGENTS.md`](AGENTS.md) carries the operating loop and the methodology — drop it in
+so the agent can both act correctly and explain how the routing works.
+
+**Any MCP client** (`mcp.json` / `claude_desktop_config.json` / equivalent):
+
+```json
+{
+  "mcpServers": {
+    "hyperroute": {
+      "command": "hyperroute-mcp",
+      "env": { "HYPERROUTE_BASE_URL": "https://hyperroute.io" }
+    }
+  }
+}
+```
+
+Then just ask: *"Use HyperRoute to find the best tool for searching recent papers, connect my
+key, and run it."* The agent calls `recommend` → `connect_info` → `onboard` → `execute` on its
+own.
+
+## Authenticate once
+
+`recommend` and browsing are public — no account. Connecting keys and running tools need one.
+
+Preferred: mint a personal access token at [hyperroute.io](https://hyperroute.io) and hand it to
+the `use_token` tool (or set `HYPERROUTE_API_KEY`). Your password never enters the conversation.
+
+The token is then **cached on disk** (`~/.hyperroute/token.json`, mode `0600`, keyed by router
+URL), so every new MCP session restores your login silently. You are asked to authenticate again
+only if the router invalidates the token. A full inline `register` → `verify` email-code flow is
+also available for headless use.
+
+## Declaring your coordinator
+
+HyperRoute compares external tools against *what you can already do*. That baseline is the set of
+coordinators that are free to you — and it is **empty by default**, because the router never
+assumes you have one. An MCP server that does not declare itself gets an external tool
+recommended for every task, including tasks the coordinator does better itself.
+
+This server declares it for you. It reads the MCP client identity your coordinator sends on
+connect and maps it to the coordinator HyperRoute models (`claude-code` → `claude_code`, …).
+Check what it resolved with the `session_info` tool: if `native_tools` is empty, set it yourself.
+
+```jsonc
+"env": {
+  "HYPERROUTE_COORDINATOR": "claude_code",       // or codex / cursor / goose / …; "none" disables
+  "HYPERROUTE_HELD": "anthropic_max_5x"          // subscriptions you already pay for → priced at $0
+}
+```
+
+`HYPERROUTE_NATIVE_TOOLS` takes exact tool ids if you want to pin one model variant instead of the
+whole product family.
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `HYPERROUTE_BASE_URL` | `https://hyperroute.io` | Which router to talk to. Override to point at a different instance. |
+| `HYPERROUTE_API_KEY` | — | `hyr_…` token to start already logged in. Externally managed: used, never cached. |
+| `HYPERROUTE_TIMEOUT` | `30` | Per-request timeout, seconds. |
+| `HYPERROUTE_TOKEN_FILE` | `~/.hyperroute/token.json` | Where the cached login lives. |
+| `HYPERROUTE_COORDINATOR` | auto-detect | Which coordinator this runs inside; `none` disables the declaration. |
+| `HYPERROUTE_NATIVE_TOOLS` | — | Exact coordinator tool ids, overriding detection. |
+| `HYPERROUTE_HELD` | — | Comma-separated plan groups you hold, e.g. `anthropic_max_5x`. |
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `session_info` | Base URL, login state, and the coordinator this server declares. Call first. |
+| `health` | Router readiness + the loaded model bundle. |
+| `recommend` | **The main verb.** Task → ranked tools as a compact table + how to act. Public. |
+| `describe` | Pull ONE tool's depth on demand: `about` · `price` · `facets` · `evidence`. |
+| `facets_catalog` | Every facet a tool can be judged on, with defaults. Fetch once. |
+| `get_preferences` / `set_preferences` | Your standing constraints, applied to every future route. |
+| `connect_info` | A tool's onboarding process: signup URL, steps, whether you're connected. |
+| `onboard` | Save + test one tool API key under your account. Stored encrypted, reused forever. |
+| `list_credentials` | Your connected tools (keys masked). |
+| `execute` | Run the chosen tool server-side with your held key; returns only the result. |
+| `fetch_result` | Page through a result too large to inline. |
+| `report_outcome` | Per-call feedback — the signal that sharpens future routing. |
+| `report_narrative` | Open-ended feedback about a whole run. |
+| `console` | Human-readable management view: history, tools, keys, stats. |
+| `use_token` / `register` / `verify` / `login` / `login_link` / `verify_login` / `forgot_password` / `whoami` | Account lifecycle. |
+| `hyperfeed` / `hyperfeed_digest` / `hyperfeed_subscribe` / `hyperfeed_react` | HyperFeed: curated agentic-AI news, agent releases, and SF events — plus your agent's personalized daily brief. |
+
+### The wire is deliberately lean
+
+`recommend` answers with a compact table, not a catalog dump:
+
+```
+session: s-6d6c5a95f9f84d9a
+verdict: interpose
+refine:  freshness, cited_references, source_quality
+
+  tool              name                        price  use        why
+→ opencitations     OpenCitations Index         free   ready      highest-ranked: capability 0.81 …
+  semantic_scholar  Semantic Scholar Graph API  free   needs_key  lower capability (0.75 vs 0.81).
+
+confidence: med (on the pick)
+act: execute('opencitations', <query>)
+```
+
+Everything else — descriptions, per-plan pricing, per-facet breakdowns, the probe evidence behind
+a score — is pulled for the one tool that matters via `describe`. That keeps a route roughly an
+order of magnitude cheaper in tokens than shipping the full object on every call.
+
+The `use` column is the whole auth story: `ready` (run it) · `needs_key` (connect first) ·
+`native` (do it yourself) · `soon` (not runnable server-side yet).
+
+### Two-pass refinement
+
+Pass 1 always returns a usable ranking. The `refine:` line names the unset preferences that would
+reorder *these* candidates; fill the relevant ones and call `recommend` again with `facets` for a
+personalized result. Durable constraints (GDPR, a budget cap) belong in `set_preferences`
+instead — stored once, applied to every future route.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+The suite is fully offline — the router is faked, so no network and no real account are touched.
+Set `HYPERROUTE_BASE_URL` to try it against a different router instance.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

hyperroute_mcp-0.1.0/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-0.1.0/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-0.1.0/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})