autorouter-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Webb Ventures
+
+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.

package/README.md

@@ -0,0 +1,393 @@
+# autorouter
+
+[![CI](https://github.com/Webb-Ventures/autorouter/actions/workflows/ci.yml/badge.svg)](https://github.com/Webb-Ventures/autorouter/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/autorouter-mcp.svg)](https://www.npmjs.com/package/autorouter-mcp)
+[![licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
+
+One tool instead of every tool.
+
+Every MCP server you register injects its full tool list — names, descriptions,
+JSON schemas — into the system prompt on every single turn. Five servers and a
+handful of skills is routinely 20–30k tokens of permanent overhead, paid whether
+or not the task touches any of them. It also makes tool selection _worse_: more
+candidates means more mis-picks.
+
+autorouter is an MCP server that exposes ~4 stable tools and hides everything
+else behind a search. The model asks for what it needs in natural language, gets
+back a few ranked candidates, reads one schema, and calls it through the router.
+
+```
+find_capabilities({ query: "why did my deploy fail" })
+  → mcp:railway/get_deployment_logs   (tool)
+  → mcp:datadog/search_datadog_logs   (tool)
+  → skill:incident-triage             (skill)
+
+describe_capability({ id: "mcp:railway/get_deployment_logs" })
+call_capability({ id: "mcp:railway/get_deployment_logs", arguments: { lines: 50 } })
+```
+
+## Install
+
+```sh
+npm install -g @webb-ventures/autorouter-mcp        # or: npx autorouter-mcp <command>
+autorouter init --target claude      # claude | codex | cursor | vscode
+autorouter adopt --target claude     # ← the step that actually saves context
+```
+
+**`adopt` is not optional.** Registering the router alongside your existing
+servers is a net _increase_: their schemas are still loaded and the router adds
+four more tools. `adopt` moves the downstream entries out of the harness config
+and into the router's own, so the harness loads one server and the router still
+reaches all of them.
+
+MCP servers are not the whole bill. Skills and plugins load through entirely
+separate mechanisms — every `SKILL.md` contributes its name and description to
+the system prompt, and an enabled plugin contributes its own skills, commands
+_and_ servers just by being installed. On Claude Code, `adopt` handles those too,
+using the only two levers the harness exposes:
+
+| what    | how                                            | effect                                                  |
+| ------- | ---------------------------------------------- | ------------------------------------------------------- |
+| skills  | `skillOverrides[name] = "user-invocable-only"` | out of the model's context; `/name` still works for you |
+| plugins | `enabledPlugins[id] = false`                   | plugin's skills, commands and servers all stop loading  |
+
+The router still finds all of them — it reads `~/.claude/skills` and
+`installed_plugins.json` directly, which record _installation_, not what the
+harness has enabled. That is what makes disabling a plugin a move rather than a
+deletion.
+
+Two things are refused rather than done quietly. A plugin whose MCP servers the
+router cannot reach (usually OAuth, where the harness holds the token and the
+router does not) stays enabled — disabling it would take away a server that
+currently works. So does a plugin whose servers the router never learned about,
+which happens if you drop `"plugins"` from `import`. Both are reported as `skip`
+lines with the reason.
+
+Use `--servers-only` to keep the old behaviour, `--skill-mode off` to remove the
+slash command as well, and `--keep-skill` / `--keep-plugin` to exempt individual
+ones. Codex, Cursor and VS Code have no skill or plugin concept, so there is
+nothing extra to do there.
+
+Run `autorouter doctor` to see the difference:
+
+```
+## Context cost
+  exposing everything: ~23,172 tokens
+  router surface:      ~700 tokens
+  still loaded direct: ~20,115 tokens (18,657 servers + 1,458 skills)
+  actually saved:      ~2,357 tokens per request (10%)
+
+## Not yet adopted
+  claude
+    servers: datadog:mcp, semble, railway, pencil, gemini
+    plugins: frontend-design
+    skills: lavish, react-doctor, find-skills, use-railway
+    → autorouter adopt --target claude
+```
+
+That "still loaded direct" line is what adoption removes. Every removal is backed
+up verbatim to `~/.autorouter/adopted/` before anything is written;
+`autorouter restore --target claude` puts it back byte for byte.
+
+## How it finds things
+
+Retrieve, then rerank.
+
+1. **BM25** over every capability, always on, no dependencies. The tokenizer
+   splits camelCase and snake_case (`execute_sql` → `execute`, `sql`, `executesql`)
+   and boosts fields: name ×3, keywords ×2, description ×1, schema ×0.5.
+2. **Embeddings**, optional. Voyage or OpenAI; scores are min-max normalized and
+   fused `0.5 × bm25 + 0.5 × cosine`. An absent or unreachable provider is not an
+   error — it degrades to pure lexical.
+3. **A selector model** reranks the shortlist. It should be the cheapest model in
+   whichever harness you are using, so `init` asks which one when it cannot infer
+   it, and stores the answer in that harness's own server entry.
+
+### The selector backend
+
+Three ways to reach a model, tried in this order under `"mode": "auto"`:
+
+| backend    | how                                         | when it fires                                                   |
+| ---------- | ------------------------------------------- | --------------------------------------------------------------- |
+| `sampling` | `sampling/createMessage` back to the host   | the host declares the capability — few do; Claude Code does not |
+| `api`      | direct HTTPS to Anthropic / OpenAI / Ollama | `selector.apiKeyEnv` names a variable that is actually set      |
+| `cli`      | `claude -p` or `codex exec`, headless       | a harness CLI is on `PATH`                                      |
+
+The CLI backend is the one that usually fires, and it exists because the other two
+usually cannot. Sampling is the protocol's own answer and almost nothing
+implements it. The API backend then asks for an `ANTHROPIC_API_KEY` that a Claude
+Code subscriber has no reason to own — they logged in, they did not buy a key — so
+the router would degrade to raw index order while telling them to go purchase
+access to a model they are already paying for. Meanwhile `claude` is sitting on
+`PATH`, already authenticated. Shelling out to it reuses that login with nothing
+to configure and no second bill.
+
+What it costs is process startup: 3-5s for a 30-candidate list against
+`claude -p --model haiku`, against roughly 1s for a direct HTTPS request. That is
+why a configured API key still outranks it. Selections are memoized per query and
+candidate set for the life of the process, so the price is paid once per distinct
+search, not once per turn.
+
+Getting there took stripping the harness back to a reranker. Out of the box the
+same call took 22s, because a headless agent boots hooks, LSP, plugin sync and
+`CLAUDE.md` discovery it has no use for, and then spends 6,223 output tokens
+thinking about a list it could rank in 168 — and returns a _worse_ answer for the
+deliberation. So the subprocess runs with `--bare --tools "" --setting-sources ""`
+and `MAX_THINKING_TOKENS=0` (Codex: `--ephemeral -s read-only`). The empty tool
+list is a correctness property before it is a saving: a selector that could edit
+files would be a different program.
+
+```jsonc
+"selector": {
+  "mode": "auto",          // auto | sampling | cli | api | off
+  "provider": "cli",
+  "cliCommand": "claude",  // only needed if the binary is not under its usual name
+  "model": "haiku",
+  "candidates": 30,
+  "maxResults": 8,
+  "timeoutMs": 20000       // raised automatically to the backend's own floor
+}
+```
+
+It is also started with an empty MCP config (`--strict-mcp-config`,
+`mcp_servers={}`) — inheriting the router's own wiring would load the exact
+catalog the router exists to keep out of context, and on a bad day recurse into
+the router itself.
+
+`model` is passed through only when you set it. Codex rejects model names an
+account's plan does not carry, so the account default is what it gets otherwise.
+
+`mode: "off"` skips reranking entirely and returns raw index order, which is
+fast, free, and noticeably worse.
+
+Downstream servers are **not** spawned at startup. The catalog is built once and
+persisted to `~/.cache/autorouter/catalog.json`; a server is cold-started only
+when one of its capabilities is first called.
+
+## What it indexes
+
+| kind                         | source                                                          |
+| ---------------------------- | --------------------------------------------------------------- |
+| `tool`, `prompt`, `resource` | every configured MCP server (following `nextCursor` pagination) |
+| `skill`                      | `**/SKILL.md` under your skill paths and plugin `skills/` dirs  |
+| `command`, `agent`           | plugin `commands/*.md` and `agents/*.md`                        |
+
+Skills, commands and agents are also republished as [slash commands](#slash-commands).
+
+Harness configs are imported rather than duplicated: `~/.claude.json` (global and
+per-project) and `.mcp.json`, `~/.codex/config.toml`, `~/.cursor/mcp.json`,
+`~/.vscode/mcp.json`, and installed Claude Code plugins.
+
+## Configuration
+
+`autorouter.json` — looked up at `$AUTOROUTER_CONFIG`, `./.autorouter.json`,
+`./autorouter.json`, `~/.config/autorouter/config.json`, `~/.autorouter.json`.
+
+```jsonc
+{
+  "import": ["claude", "codex", "cursor", "plugins"],
+  "servers": { "custom": { "command": "…", "args": [] } },
+  "skillPaths": ["~/.claude/skills", ".claude/skills"],
+  "exclude": ["gemini.generate_video"], // never surfaced at all
+  "alwaysExpose": ["semble.search"], // stays first-class, never adopted
+  "confirm": ["supabase.execute_sql"], // first call is rejected, must re-issue
+  "selector": { "mode": "auto", "model": "claude-haiku-4-5-20251001" },
+  "embeddings": {
+    "provider": "voyage",
+    "model": "voyage-3-lite",
+    "apiKeyEnv": "VOYAGE_API_KEY",
+  },
+}
+```
+
+Env overrides (`AUTOROUTER_IMPORT`, `AUTOROUTER_SELECTOR_MODEL`,
+`AUTOROUTER_SELECTOR_MODE`, `AUTOROUTER_EMBEDDINGS_PROVIDER`, …) let each harness
+pin its own behaviour without a shared global file. `AUTOROUTER_HOME` redirects
+every home-relative path, for tests and containers.
+
+## Slash commands
+
+Adopting a plugin into the router would otherwise cost you its slash commands:
+Claude Code reads `commands/*.md` off disk, and nothing over MCP can add to that
+list. What it _does_ surface as slash commands are MCP prompts, so every skill,
+plugin command and subagent in the catalog is republished as one:
+
+```
+/mcp__autorouter__find <what you want to do>
+/mcp__autorouter__datadog_ddviz
+/mcp__autorouter__supabase_supabase
+```
+
+Bodies are substituted the way the native loader substitutes them — `$ARGUMENTS`
+for everything you typed, `$1`..`$9` positionally — so a command file written for
+Claude Code behaves identically through the router. `argument-hint` frontmatter
+is passed through as the argument description. Names are prefixed with the owning
+plugin, so two plugins shipping a `setup` command both stay reachable rather than
+one silently shadowing the other.
+
+Tools are deliberately not published here. A prompt returns text for the model to
+act on and cannot return a tool result, so a slash command for `execute_sql` would
+look callable and do nothing. Tools reach the model through search instead.
+
+## Harness support
+
+Searching returns a tool with its **full description and input schema**, not a
+summary — the same information a native tool listing carries, because a truncated
+description leaves the model guessing argument names, and a guessed argument is
+the whole difference between roughly reliable and reliable.
+
+Better still, where the client honours `notifications/tools/list_changed`,
+`find_capabilities` **promotes** what it matched to real first-class tools. The
+model then makes an ordinary tool call: the host validates arguments against the
+real schema, the permission prompt names the real tool rather than
+`call_capability`, and the router is not in the execution path at all. It becomes
+a loader that decides what is in your tool list, not a middleman on every call.
+
+| supports `listChanged`                          | proxy only                                       |
+| ----------------------------------------------- | ------------------------------------------------ |
+| Claude Code ≥ 2.1.232, GitHub Copilot, opencode | Codex, Gemini CLI, Claude Desktop, Vercel AI SDK |
+
+Where it is unsupported the schema travels inline in the search result instead,
+and `activate_capabilities` is never advertised, so the model is never told about
+a tool it cannot use. Override the detection with `AUTOROUTER_DYNAMIC=on|off|auto`.
+A tool registered mid-turn may not be callable until the next turn on Claude Code,
+so `call_capability` always remains as the same-turn fallback and returns an
+identical result.
+
+## Token budgets
+
+A router that leaks context is just a slower way of loading everything, so the
+three surfaces that persist or accumulate are each bounded in **tokens**, not in
+item count. Counting items looks like a bound and is not one: tool definitions in
+a real catalog range from 199 to 1,748 tokens, so "15 tools" is anywhere between
+3k and 26k depending only on what the model happened to search for.
+
+| surface                   | budget                            | lifetime   |
+| ------------------------- | --------------------------------- | ---------- |
+| promoted tool list        | 3,000 tok, LRU eviction           | session    |
+| inline schemas per search | 700 tok, spent top-down           | one result |
+| prompt list               | descriptions clamped to 180 chars | session    |
+
+Tools promoted by the search in flight are never evicted — a tool that vanishes
+between being offered and being called is worse than one never offered.
+
+Schemas are **compacted** everywhere they are repeated: `$schema`, `title` and
+`examples` are dropped, and prose is trimmed, more aggressively the deeper it
+sits. Every structural field survives untouched — names, types, enums, `required`,
+nesting, and `additionalProperties: false` — because dropping one of those turns a
+valid call into a guessed one. On this machine that is a 31% cut across the
+catalog and 3× on the worst offenders, with no effect on what is callable.
+`describe_capability` is the exception and returns the schema verbatim: it exists
+precisely to recover anything a budgeted result had to leave out.
+
+## CLI
+
+For agents that have a shell but no MCP, the same engine is directly usable:
+
+```sh
+autorouter search "chart a csv"
+autorouter search "query postgres" --raw --limit 5
+autorouter describe skill:dataviz
+autorouter call mcp:railway/get_logs --args '{"lines":50}'
+autorouter list --kind skill
+autorouter doctor
+autorouter reindex
+
+autorouter adopt --target claude --dry-run          # preview, change nothing
+autorouter adopt --target claude --servers-only     # skip skills and plugins
+autorouter adopt --target claude --keep supabase --keep-plugin datadog
+autorouter restore --target claude                  # undo the most recent adopt
+
+autorouter login                                    # which servers need a grant
+autorouter login datadog:mcp                        # authorize one (opens a browser)
+autorouter logout datadog:mcp                       # forget a stored grant
+```
+
+## OAuth servers
+
+Several of the heaviest MCP servers — Datadog, Supabase, Linear — carry no
+credentials in their config at all. Datadog's headers expand to `""`, Supabase's
+are only `X-Source-*`. The working token is an OAuth grant your harness obtained
+and keeps in its own credential store, and it was issued to that harness.
+
+The router does not read it. It runs its own authorization-code flow and holds
+its own grant, which means it also works under Codex and Cursor, neither of which
+has a token to borrow:
+
+```sh
+autorouter login datadog:mcp
+autorouter login supabase:supabase
+autorouter reindex
+```
+
+Registration is RFC 7591 dynamic client registration, so there is no app to
+create first. Tokens live in `~/.autorouter/oauth/<server>.json` at `0600` and
+are refreshed automatically; `logout` deletes them. The loopback redirect uses a
+fixed port (33418, `--port` or `$AUTOROUTER_OAUTH_PORT` to change it) because the
+redirect URI is baked into the registration a provider stores — a grant obtained
+on one port cannot be refreshed from another.
+
+### Choosing permissions
+
+A dynamically registered client defaults to every scope the provider advertises,
+which for Supabase includes `database:write` and `edge_functions:write` — a token
+able to drop tables, held on behalf of a search tool. Scopes are the only
+restriction that survives a prompt injection, so pick them deliberately:
+
+```sh
+autorouter login supabase --list-scopes   # what this server offers
+autorouter login supabase --read-only     # 8 of 13, no write scopes
+autorouter login supabase --scopes "projects:read,database:read"
+```
+
+`--read-only` keeps the scopes whose names do not grant mutation. It is a
+heuristic over naming conventions (`:write`, `admin`, `manage`, `all`) and it
+cannot see through an opaque name like GitHub's `repo`, which grants write while
+reading as neutral — `--scopes` is the exact lever when it guesses wrong. Where a
+provider offers no read-only subset at all, `--read-only` fails loudly rather than
+requesting an empty scope, which most providers read as "give the default".
+
+Scopes are fixed when the grant is issued, so narrowing an existing one means
+`--force` and a fresh authorization. A re-login inherits the previous narrowing
+unless you pass a new one, and `autorouter login` with no argument prints what
+each stored grant actually covers.
+
+Until a server has a grant, `adopt` refuses to move it or to disable the plugin
+that supplies it. Moving a server the router cannot reach would delete a working
+capability, so `doctor` and `adopt` both print the exact `login` command instead.
+
+## The trade-off, stated plainly
+
+Routing means your host's permission prompt sees `call_capability`, not
+`supabase.execute_sql`. That is a real loss of granularity and this tool does not
+pretend otherwise. Three mitigations: `exclude` means a capability is never
+surfaced; `confirm` rejects the first attempt with the resolved target spelled
+out and requires the model to re-issue with `confirm: true`; and every result is
+prefixed with the resolved `server/tool` so the transcript stays auditable.
+
+Adopting skills and plugins edits `~/.claude/settings.json`, a file you also edit
+by hand. The whole file is backed up verbatim alongside the server moves and
+`restore` rewrites it byte for byte, but it is a shared file and worth knowing
+about. Hidden skills default to `user-invocable-only` rather than `off` for the
+same reason: `/name` keeps working, so the capability is relocated, not removed.
+
+## Development
+
+```sh
+bun install
+bun test
+bun run src/cli.ts doctor
+bun run build          # bun build src/cli.ts --target=node --outfile dist/cli.js
+```
+
+The build targets Node so `npx` works for people who do not have Bun.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the invariants worth knowing before
+changing anything — chiefly that nothing is spawned at startup, that every write
+`adopt` makes has to restore byte for byte, and that the selector subprocess runs
+with no tools by design.
+
+## Licence
+
+[MIT](LICENSE). Security reports go through [SECURITY.md](SECURITY.md), not the
+public issue tracker.