@crabeye-ai/crabeye-mcp-bridge 0.3.0 → 0.5.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}"
       }
     }
   }
@@ -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.
 
+Every `search_tools` response includes a `session_stats` object showing how many tokens the bridge is saving compared to exposing all upstream tool definitions directly:
+
+```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. Suppress this with `--no-stats`.
+
 ## 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,17 +470,62 @@ 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.
+
 ## 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 |
+| `--no-stats` | Suppress `session_stats` from `search_tools` responses |
 | `-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
+
+Use `--validate` to check your config file without starting the bridge:
+
+```
+$ npx @crabeye-ai/crabeye-mcp-bridge --config config.json --validate
+Config OK — 3 upstream servers
+  linear (stdio) [project management]
+  github (stdio)
+  sentry (streamable-http)
+```
+
+Exits with code 0 on success, code 1 on validation errors.
 
 ## License