@crabeye-ai/crabeye-mcp-bridge 0.4.0 → 1.0.0

package/README.md

@@ -47,7 +47,13 @@ Say your MCP client config looks like this today:
 }
 ```
 
-To use the bridge, rename `mcpServers` to `upstreamMcpServers` and add the bridge as the only entry in `mcpServers`:
+First, store your secrets in the encrypted credential store:
+
+```bash
+crabeye-mcp-bridge credential set github-pat ghp_abc123
+```
+
+Then rename `mcpServers` to `upstreamMcpServers`, add the bridge, and replace hardcoded tokens with `${credential:key}` references:
 
 ```json
 {
@@ -66,7 +72,7 @@ To use the bridge, rename `mcpServers` to `upstreamMcpServers` and add the bridg
       "command": "npx",
       "args": ["-y", "@anthropic/github-mcp-server"],
       "env": {
-        "GITHUB_TOKEN": "ghp_..."
+        "GITHUB_TOKEN": "${credential:github-pat}"
       }
     }
   }
@@ -75,7 +81,7 @@ To use the bridge, rename `mcpServers` to `upstreamMcpServers` and add the bridg
 
 That's it. Your AI assistant now has access to all tools from all configured servers through a single connection. The bridge automatically excludes itself from `mcpServers` to avoid recursion, so pointing `--config` at the same file is safe.
 
-The bridge also reads `servers` (VS Code Copilot) and `context_servers` (Zed) as input keys. On duplicate names, earlier sources win: `upstreamMcpServers` > `servers` > `context_servers` > `mcpServers`. Self-exclusion applies to `mcpServers` and `context_servers`.
+The bridge also reads `upstreamServers` (shorthand), `servers` (VS Code Copilot), and `context_servers` (Zed) as input keys. On duplicate names, earlier sources win: `upstreamMcpServers` > `upstreamServers` > `servers` > `context_servers` > `mcpServers`. Self-exclusion applies to `mcpServers` and `context_servers`.
 
 Alternatively, you can add the bridge alongside your existing `mcpServers` entries without renaming anything:
 
@@ -94,7 +100,7 @@ Alternatively, you can add the bridge alongside your existing `mcpServers` entri
       "command": "npx",
       "args": ["-y", "@anthropic/github-mcp-server"],
       "env": {
-        "GITHUB_TOKEN": "ghp_..."
+        "GITHUB_TOKEN": "${credential:github-pat}"
       }
     }
   }
@@ -118,6 +124,25 @@ The AI assistant calls `search_tools` automatically when it detects a relevant i
 
 When `search_tools` is called, the assistant receives the matching tools and their input schemas. The bridge also directly exposes the searched tools to the assistant so they can be called natively. Some assistants don't refresh their tool list mid-session, so they may not see the newly exposed tools — but they can still call them through `run_tool` and the call is executed exactly as if made directly on the original tool.
 
+The bridge tracks how many tokens it saves compared to exposing all upstream tool definitions directly. Token savings are always logged to stderr after each search. To also include them in `search_tools` responses, pass `--stats`:
+
+```json
+{
+  "session_stats": {
+    "tokens_saved": 11200,
+    "baseline_tokens": 14200,
+    "bridge_tokens": 3000
+  },
+  "results": [...]
+}
+```
+
+- **`baseline_tokens`** — estimated tokens if all upstream tool definitions were injected into context without the bridge
+- **`bridge_tokens`** — cumulative tokens used by the bridge's two meta-tools plus all search results returned so far
+- **`tokens_saved`** — the difference (baseline − bridge)
+
+Token counts are estimated using a chars/4 heuristic.
+
 ## Examples
 
 ### Discovering providers
@@ -366,7 +391,46 @@ The assistant can then search by category: `{ "queries": [{ "category": "design"
 
 ### Authentication
 
-Static credentials (API keys, tokens) can be passed via `env` or `headers` in the server config. OAuth is not yet supported.
+Secrets belong in the encrypted credential store, not in config files. Store a secret once, then reference it with `${credential:key}` in `env` or `headers`:
+
+```bash
+# Store credentials
+crabeye-mcp-bridge credential set github-pat ghp_abc123
+crabeye-mcp-bridge credential set remote-api-key sk_live_xyz
+```
+
+```json
+{
+  "upstreamMcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/github-mcp-server"],
+      "env": { "GITHUB_TOKEN": "${credential:github-pat}" }
+    },
+    "remote-api": {
+      "url": "https://mcp.example.com/sse",
+      "type": "sse",
+      "headers": { "Authorization": "Bearer ${credential:remote-api-key}" }
+    }
+  }
+}
+```
+
+Templates are resolved on every connect and reconnect, so rotating a credential takes effect without restarting the bridge.
+
+**How it works:** Credentials are encrypted with AES-256-GCM. The master key is stored in your OS keychain (macOS Keychain, Linux secret-tool, Windows Credential Manager). Set `MCP_BRIDGE_MASTER_KEY` (64 hex chars) to use a static key instead.
+
+**CLI commands:**
+
+| Command | Description |
+|---------|-------------|
+| `credential set <key> [value]` | Store a plain string secret |
+| `credential set <key> --json '<json>'` | Store a typed credential (bearer/oauth2/secret) |
+| `credential get <key>` | Retrieve a credential (masked by default, `--show-secret` for full) |
+| `credential delete <key>` | Delete a stored credential |
+| `credential list` | List all stored credential keys |
+
+Pipe-friendly: `echo "ghp_abc123" | crabeye-mcp-bridge credential set github-pat`
 
 ### Tool policies
 
@@ -406,18 +470,61 @@ Policies cascade in this order (first match wins):
 
 In this example, all Linear tools require confirmation except `list_issues` (runs freely) and `delete_issue` (blocked). Tools from other servers use the global default (`"always"`).
 
+### Rate limiting
+
+Prevent the bridge from exceeding upstream API quotas by setting per-server rate limits. When the limit is hit, calls wait in a FIFO queue until the sliding window opens — the LLM just sees slightly higher latency instead of an error.
+
+```json
+{
+  "upstreamMcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/github-mcp-server"],
+      "_bridge": {
+        "rateLimit": {
+          "maxCalls": 30,
+          "windowSeconds": 60
+        }
+      }
+    }
+  }
+}
+```
+
+In this example, the bridge allows at most 30 tool calls to the `github` server per 60-second sliding window. If a 31st call arrives before the window slides, it waits until a slot opens. If the wait exceeds 30 seconds, the call fails with an error.
+
+Rate limit configuration is hot-reloadable — changes take effect without restarting the bridge.
+
+### Discovery mode
+
+Control how searched tools are surfaced to the assistant with `--discovery-mode`:
+
+- **`both`** (default) — Search results include tool names, descriptions, and full input schemas. Matching tools are also added to the MCP tools list so the assistant can call them directly.
+- **`search`** — Search results include full tool details, but tools are NOT added to the MCP tools list. The assistant must use `run_tool` to execute them. Use this when your client doesn't handle dynamic tool list changes well.
+- **`tools_list`** — Matching tools are added to the MCP tools list with full schemas, but search results omit `input_schema` to avoid duplication. The assistant calls discovered tools directly by their namespaced name, or via `run_tool`.
+
+```bash
+npx @crabeye-ai/crabeye-mcp-bridge --config config.json --discovery-mode search
+```
+
 ## CLI
 
 ```
 npx @crabeye-ai/crabeye-mcp-bridge --config <path>
 ```
 
-| Flag | Description |
-|------|-------------|
+| Flag / Subcommand | Description |
+|-------------------|-------------|
 | `-c, --config <path>` | Path to config file (required, or set `MCP_BRIDGE_CONFIG`) |
 | `--validate` | Validate config and list upstream servers, then exit |
+| `--stats` | Include `session_stats` in `search_tools` responses (always logged to stderr) |
+| `--discovery-mode <mode>` | How searched tools are surfaced: `search`, `tools_list`, or `both` (default) |
 | `-V, --version` | Print version |
 | `-h, --help` | Print help |
+| `credential set <key> [value]` | Store a credential (plain string, `--json` for typed, or pipe stdin) |
+| `credential get <key>` | Retrieve a credential (`--show-secret` to unmask) |
+| `credential delete <key>` | Delete a stored credential |
+| `credential list` | List all stored credential keys |
 
 ### Validating your config