@miller-tech/uap 1.40.0 → 1.41.0

package/docs/integrations/MCP_ROUTER.md

@@ -0,0 +1,147 @@
+# MCP Router
+
+`v1.40.0` · `src/mcp-router/`
+
+The MCP Router is a hierarchical Model Context Protocol server that sits in
+front of all of your downstream MCP servers and dramatically reduces the tokens
+the model spends on tool definitions and tool output. It is the mechanism behind
+UAP's "up to 98% savings on large tool calls."
+
+For where it fits in the wider system, see
+[../architecture/OVERVIEW.md](../architecture/OVERVIEW.md#mcp-router-srcmcp-router).
+
+---
+
+## Why it exists
+
+A normal MCP setup exposes every tool from every server directly to the model.
+With a dozen servers that is easily 150+ tool schemas at roughly ~500 tokens
+each — tens of thousands of tokens of context burned before the agent does any
+work. On top of that, tools like file readers and shell wrappers return large
+outputs that flood the context window.
+
+The router fixes both:
+
+1. **Tool hiding.** It exposes just three meta-tools instead of every
+   downstream tool. The documented design target is ~75,000 tokens of tool
+   definitions collapsed to ~700 (`src/mcp-router/index.ts`,
+   `src/mcp-router/server.ts`).
+2. **Output compression.** Large tool results are indexed into an in-memory
+   SQLite **FTS5** table and only the most relevant snippets are returned
+   (`src/mcp-router/output-compressor.ts`).
+
+---
+
+## How it works
+
+### The three meta-tools
+
+Instead of N downstream tools, the model sees:
+
+| Meta-tool | What it does |
+|-----------|--------------|
+| `discover_tools` | Natural-language query → matching downstream tool paths |
+| `execute_tool`   | Run a tool by `path` with `args` (+ optional `intent`) |
+| `deliver`        | Run the `uap deliver` convergence loop |
+
+Downstream tools are loaded into an in-memory fuzzy search index at startup and
+are never surfaced as definitions. The agent's flow is:
+
+```
+discover_tools("read the auth config")
+        │  → [ "filesystem.read_file", ... ]
+        ▼
+execute_tool({ path: "filesystem.read_file",
+               args: { path: "src/auth.ts" },
+               intent: "csrf token validation" })
+        │
+        ▼
+  ┌──────────── output compressor ────────────┐
+  │ small result → passthrough                 │
+  │ large result → FTS5 index + BM25(intent)   │
+  │   → top snippets + searchable-vocab footer │
+  │ huge / no intent → head+tail truncation    │
+  └────────────────────────────────────────────┘
+```
+
+The `intent` string on `execute_tool` is what drives the BM25 query — provide a
+focused intent to get focused snippets. The model can then issue a follow-up
+`execute_tool` with a refined intent using the vocabulary footer.
+
+---
+
+## Setup
+
+### One command, all harnesses
+
+```bash
+uap mcp-setup
+```
+
+`uap mcp-setup` (`src/cli/setup-mcp-router.ts`) configures the MCP Router as the
+single MCP server across your AI harnesses. It writes a `mcpServers.router`
+entry pointing at the router and migrates/backs up any existing servers
+(prompts unless `--force`), then validates the result with `uap mcp-router list`.
+
+Harnesses configured (global `~/` config paths):
+
+| Harness | Config file |
+|---------|-------------|
+| Claude Code | `~/.claude/settings.json` |
+| Factory.AI | `~/.factory/mcp.json` |
+| VSCode | `~/.vscode/mcp.json` (skipped if absent) |
+| Cursor | `~/.cursor/settings.json` |
+
+The router entry it writes looks like:
+
+```json
+{
+  "mcpServers": {
+    "router": {
+      "command": "npx",
+      "args": ["uap", "mcp-router", "start"]
+    }
+  }
+}
+```
+
+### Running and inspecting the router
+
+`uap mcp-router <action>` (`src/cli/mcp-router.ts`) drives the router directly:
+
+```bash
+uap mcp-router start      # run the stdio MCP server (what harnesses launch)
+uap mcp-router list       # list discovered downstream tools
+uap mcp-router discover   # try a natural-language tool discovery query
+uap mcp-router stats      # token-savings stats
+```
+
+`uap mcp-router start` is the command harnesses invoke via the generated config;
+you normally don't run it by hand.
+
+---
+
+## Verifying it works
+
+```bash
+uap mcp-router list       # should enumerate tools from your downstream servers
+uap mcp-router stats      # shows tool-hiding savings + per-output compression
+uap hooks doctor          # confirms gate/router wiring across harnesses
+```
+
+If `list` is empty, the router found no downstream MCP configs — confirm your
+harness still has its original MCP servers defined (they are migrated into the
+router's view, not deleted) and re-run `uap mcp-setup`.
+
+---
+
+## Notes
+
+- The router reads downstream MCP configs from Claude Desktop, Cursor, VSCode,
+  Claude Code CLI, Factory.AI, and a local `mcp.json`, expands `~`/env vars,
+  skips disabled servers, and refuses to reference itself.
+- The 98% / 75k→700 figures are the documented design target for tool hiding;
+  per-output FTS5 savings are computed live for each call and reported by
+  `uap mcp-router stats`.
+- Pair the router with **RTK** for CLI-output savings — see
+  [RTK.md](RTK.md). The two are complementary (tool definitions + CLI output).

package/docs/integrations/RTK.md

@@ -0,0 +1,102 @@
+# RTK — Rust Token Killer
+
+`v1.40.0` · `src/cli/rtk.ts`
+
+RTK (Rust Token Killer) is a fast CLI proxy that compresses and filters the
+output of command-line tools — `git status`, test runs, file reads, and similar
+heavy commands — to cut the tokens your agent spends echoing terminal output.
+Source positions it at **60–90% token savings on CLI command output**.
+
+RTK is a separate, open-source tool (`https://github.com/rtk-ai/rtk`,
+docs at `https://www.rtk-ai.app`). UAP integrates with it but does not bundle
+it; `uap rtk` manages installation and wiring.
+
+---
+
+## Why RTK + the MCP Router
+
+The two integrations target different sources of token waste and stack:
+
+| Layer | Tool | Saves on |
+|-------|------|----------|
+| MCP tool definitions + tool output | [MCP Router](MCP_ROUTER.md) | ~98% of tool-definition tokens |
+| Raw CLI command output | **RTK** | 60–90% of CLI-output tokens |
+
+Source describes the combination as **95%+ total token reduction**
+(`src/cli/rtk.ts`).
+
+---
+
+## How UAP integrates RTK
+
+`uap rtk <command>` (`src/cli/rtk.ts`):
+
+```bash
+uap rtk install     # install RTK, auto-detecting the best method
+uap rtk status      # check install + hook wiring + recent savings
+uap rtk help        # usage
+```
+
+### `uap rtk install`
+
+Auto-detects the best install method (Homebrew → Cargo → pre-built binary via
+curl) and runs it. Override with flags:
+
+```bash
+uap rtk install --method homebrew     # force a method: homebrew | cargo | curl
+uap rtk install --force               # reinstall
+```
+
+Equivalent manual installs:
+
+```bash
+brew install rtk                                          # Homebrew
+cargo install --git https://github.com/rtk-ai/rtk        # Cargo
+# or download a release binary from:
+#   https://github.com/rtk-ai/rtk/releases
+```
+
+After install, initialize and verify:
+
+```bash
+rtk init --global    # set up the global rewrite hook
+rtk gain             # show token savings analytics
+```
+
+### `uap rtk status`
+
+Reports whether the `rtk` binary is installed, whether the rewrite hook
+(`~/.claude/hooks/rtk-rewrite.sh`) is wired in, and recent savings from
+`rtk gain`.
+
+---
+
+## How it works in practice
+
+Once the rewrite hook is installed, heavy CLI commands are transparently routed
+through RTK (e.g. `git status` is rewritten to `rtk git status`) with zero
+extra tokens of overhead — the agent issues normal commands and RTK compresses
+the output before it reaches the model.
+
+UAP can nudge agents to route heavy CLIs through RTK via the `rtk_wrap.py`
+policy enforcer (`src/policies/enforcers/rtk_wrap.py`).
+
+Useful RTK meta-commands:
+
+```bash
+rtk gain              # token savings analytics
+rtk gain --history    # command usage history with savings
+rtk discover          # find missed savings opportunities
+rtk --version         # verify the install
+```
+
+---
+
+## Combined analytics
+
+`uap rtk` can surface unified analytics combining MCP Router and RTK savings
+(`showUnifiedAnalytics` in `src/cli/rtk.ts`), so you can see total context
+reduction from both layers at once.
+
+See also: [MCP_ROUTER.md](MCP_ROUTER.md) ·
+[../architecture/OVERVIEW.md](../architecture/OVERVIEW.md)