mcp-filter 1.0.1 → 1.1.0

package/README.md

@@ -19,159 +19,198 @@
 
 ## Why mcp-filter?
 
-MCP servers expose tools, resources, and prompts to AI agents — but you don't always want agents to have access to everything. `mcp-filter` sits between your MCP client and upstream server, filtering what gets through:
+[GitHub MCP Server](https://github.com/github/github-mcp-server) exposes 79 tools — **~52,000 tokens** of context window per request. A PR review agent needs maybe 10 of them. The other 69 (gists, stars, security advisories, dependabot, discussions...) are noise that costs tokens and confuses tool selection.
 
-- **Security** — Block destructive operations (`delete_*`, `admin_*`) before they reach the agent
-- **Focus** — Whitelist only the tools an agent needs for its specific task
-- **Cost** — Fewer tools in context means fewer tokens consumed per request
-- **Flexibility** — Works with any MCP server, any MCP client, any transport
+`mcp-filter` sits between your MCP client and upstream server, filtering what gets through:
 
-## Quick Start
+- **Cost** — 79 tools → 10 tools = ~80% fewer tokens per request
+- **Focus** — Fewer tools means better tool selection by the model
+- **Security** — Block destructive operations (`delete_*`, `push_*`) before they reach the agent
+- **Future-proof** — `--include` whitelists are immune to upstream adding new tools
 
-```bash
-npm install -g mcp-filter
-# or use directly with npx (no install needed)
-```
+## Quick Start
 
-```bash
-# Filter a local MCP server (stdio)
-npx mcp-filter --exclude "browser_close" --exclude "browser_evaluate" -- npx @playwright/mcp
+Add mcp-filter to your MCP client config. No install needed — `npx` downloads it automatically.
 
-# Filter a remote MCP server (HTTP)
-npx mcp-filter --exclude "delete_*" --upstream-url https://mcp.notion.com/mcp
+**Local server** — filter tools from a stdio MCP server:
 
-# Whitelist mode — only allow specific tools
-npx mcp-filter --include "browser_navigate" --include "browser_screenshot" -- npx @playwright/mcp
+```json
+{
+  "mcpServers": {
+    "playwright-safe": {
+      "command": "npx",
+      "args": [
+        "mcp-filter",
+        "--exclude", "browser_close",
+        "--exclude", "browser_evaluate",
+        "--include", "browser_*",
+        "--",
+        "npx", "@playwright/mcp@latest"
+      ]
+    }
+  }
+}
 ```
 
-## Supported Transports
+**Remote server** — filter tools from an HTTP MCP server:
 
-mcp-filter connects to upstream MCP servers via three transport types:
+```json
+{
+  "mcpServers": {
+    "stripe-safe": {
+      "command": "npx",
+      "args": [
+        "mcp-filter",
+        "--exclude", "create_refund",
+        "--exclude", "delete_*",
+        "--upstream-url", "https://mcp.stripe.com"
+      ]
+    }
+  }
+}
+```
 
-| Transport | Flag | Use Case | Status |
-|-----------|------|----------|--------|
-| **Stdio** | `-- <command>` | Local servers spawned as subprocesses | Stable |
-| **HTTP** | `--upstream-url <url>` | Remote servers via Streamable HTTP | Stable |
-| **SSE** | `--transport sse --upstream-url <url>` | Legacy remote servers via Server-Sent Events | Deprecated |
+**Remote server with authentication:**
 
-Transport is auto-detected: `--upstream-url` selects HTTP by default, `-- <command>` selects stdio. Override with `--transport`.
+```json
+{
+  "mcpServers": {
+    "api-readonly": {
+      "command": "npx",
+      "args": [
+        "mcp-filter",
+        "--exclude", "write_*",
+        "--exclude", "delete_*",
+        "--upstream-url", "https://api.example.com/mcp",
+        "--authorization", "Bearer your-oauth-token"
+      ]
+    }
+  }
+}
+```
 
-## Usage
+For additional headers, use `--header "Key: Value"` (repeatable).
 
-### Local Servers (Stdio)
+This JSON format works with Cursor (`.cursor/mcp.json`), VS Code (`.vscode/mcp.json`), Claude Desktop (`claude_desktop_config.json`), and any MCP client that supports stdio servers.
 
-```bash
-# Exclude specific tools
-npx mcp-filter --exclude "playwright*" -- npx @playwright/mcp
+## Examples: GitHub MCP Server
 
-# Include only specific tools (whitelist)
-npx mcp-filter --include "browser_navigate" --include "browser_screenshot" -- npx @playwright/mcp
+The [GitHub MCP Server](https://github.com/github/github-mcp-server) is a good example of a large server that benefits from filtering. All examples below work with any MCP client that supports the JSON config format.
 
-# Rsync-style: exclude exceptions, then include category
-npx mcp-filter --exclude "browser_close" --include "browser_*" -- npx @playwright/mcp
+**PR review agent** — whitelist only what's needed (79 → ~10 tools):
 
-# Works with any local MCP server
-npx mcp-filter --exclude "debug*" -- node my-mcp-server.js
+```json
+{
+  "mcpServers": {
+    "github-pr-review": {
+      "command": "npx",
+      "args": [
+        "mcp-filter",
+        "--include", "pull_request_*",
+        "--include", "issue_*",
+        "--include", "get_file_contents",
+        "--include", "list_commits",
+        "--include", "search_code",
+        "--",
+        "github-mcp-server", "stdio"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "<your-token>"
+      }
+    }
+  }
+}
 ```
 
-### Remote Servers (HTTP)
-
-```bash
-# Filter a remote HTTP MCP server
-npx mcp-filter --exclude "delete_*" --upstream-url https://mcp.notion.com/mcp
-
-# With authentication headers
-npx mcp-filter --exclude "admin_*" \
-  --upstream-url https://api.example.com/mcp \
-  --header "Authorization: Bearer your-token-here"
-
-# Multiple headers
-npx mcp-filter --exclude "write_*" \
-  --upstream-url https://api.example.com/mcp \
-  --header "Authorization: Bearer token" \
-  --header "X-Team-Id: engineering"
-```
+When GitHub adds new tools tomorrow, they won't leak through — only `pull_request_*`, `issue_*`, and the explicitly listed tools are visible.
 
-### Legacy SSE Servers
+**Read-only agent** — exclude all mutations, keep all reads:
 
-```bash
-# SSE transport (deprecated — prefer HTTP for new deployments)
-npx mcp-filter --transport sse \
-  --upstream-url https://mcp.example.com/sse \
-  --exclude "dangerous_*"
+```json
+{
+  "mcpServers": {
+    "github-readonly": {
+      "command": "npx",
+      "args": [
+        "mcp-filter",
+        "--exclude", "create_*",
+        "--exclude", "update_*",
+        "--exclude", "delete_*",
+        "--exclude", "push_*",
+        "--exclude", "merge_*",
+        "--exclude", "fork_*",
+        "--exclude", "*_write",
+        "--",
+        "github-mcp-server", "stdio"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "<your-token>"
+      }
+    }
+  }
+}
 ```
 
-## CLI Reference
+**PR tools without merge** — rsync-style, first match wins:
 
+```json
+{
+  "mcpServers": {
+    "github-pr-safe": {
+      "command": "npx",
+      "args": [
+        "mcp-filter",
+        "--exclude", "merge_pull_request",
+        "--include", "pull_request_*",
+        "--include", "list_pull_requests",
+        "--include", "search_pull_requests",
+        "--",
+        "github-mcp-server", "stdio"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "<your-token>"
+      }
+    }
+  }
+}
 ```
-mcp-filter [options] -- <upstream-command>
-mcp-filter [options] --upstream-url <url>
-```
-
-### Filtering Options
-
-| Flag | Description |
-|------|-------------|
-| `--exclude <pattern>` | Exclude items matching glob pattern (repeatable) |
-| `--include <pattern>` | Include only items matching glob pattern (repeatable) |
-
-### Transport Options
-
-| Flag | Description |
-|------|-------------|
-| `--upstream-url <url>` | Connect to remote HTTP/SSE server |
-| `--transport <type>` | Transport type: `stdio`, `http`, `sse` (auto-detected) |
-| `--header <header>` | HTTP header as `"Key: Value"` (repeatable, HTTP/SSE only) |
-| `--` | Separates mcp-filter options from upstream command (stdio only) |
-
-### Other Options
-
-| Flag | Description |
-|------|-------------|
-| `--help` | Show help message |
-| `--version` | Show version number |
 
-> **Note**: `--upstream-url` and `-- <command>` are mutually exclusive.
+`merge_pull_request` matches `--exclude` first, so it's blocked. The remaining `pull_request_*` tools pass through.
 
-## Filtering Modes
-
-### Exclude Mode
+### Claude Code
 
-Block specific items, allow everything else:
+Claude Code uses `claude mcp add` instead of JSON:
 
 ```bash
-npx mcp-filter --exclude "browser_close" --exclude "browser_evaluate" -- npx @playwright/mcp
-```
-
-### Include Mode (Whitelist)
-
-Allow only specified items, block everything else:
+# Local server (two -- separators: first for Claude, second for mcp-filter)
+claude mcp add playwright-safe -- \
+  npx mcp-filter \
+    --exclude "browser_close" \
+    --exclude "browser_evaluate" \
+    --include "browser_*" \
+    -- npx @playwright/mcp@latest
 
-```bash
-npx mcp-filter --include "browser_navigate" --include "browser_screenshot" -- npx @playwright/mcp
+# Remote HTTP server (no second --)
+claude mcp add stripe-safe -- \
+  npx mcp-filter \
+    --exclude "create_refund" \
+    --exclude "delete_*" \
+    --upstream-url https://mcp.stripe.com
 ```
 
-### Rsync-Style Combination
-
-Patterns are evaluated **in order** — first match wins. This lets you combine `--include` and `--exclude` for fine-grained control:
+## Options
 
-```bash
-# Exclude specific tools, then include the rest of the category
-npx mcp-filter \
-  --exclude "browser_close" \
-  --exclude "browser_evaluate" \
-  --include "browser_*" \
-  -- npx @playwright/mcp
-
-# Evaluation:
-#   browser_close      → matches --exclude "browser_close"     → EXCLUDED
-#   browser_evaluate   → matches --exclude "browser_evaluate"  → EXCLUDED
-#   browser_navigate   → matches --include "browser_*"         → included
-#   browser_screenshot → matches --include "browser_*"         → included
-#   some_other_tool    → no match, --include exists            → excluded (whitelist mode)
-```
+| Option | Description |
+|--------|-------------|
+| `--exclude <pattern>` | Exclude items matching glob pattern (repeatable) |
+| `--include <pattern>` | Include only items matching glob pattern (repeatable) |
+| `--upstream-url <url>` | Connect to remote HTTP/SSE server (mutually exclusive with `--`) |
+| `--transport <type>` | Transport type: `stdio`, `http`, `sse` (auto-detected) |
+| `--authorization <value>` | Set Authorization header (e.g. `"Bearer token"`, HTTP/SSE only) |
+| `--header <header>` | HTTP header as `"Key: Value"` (repeatable, HTTP/SSE only) |
+| `--` | Separates mcp-filter options from upstream command (stdio only) |
 
-> **Order matters!** `--exclude "browser_close" --include "browser_*"` excludes `browser_close` then includes the rest. Reversing the order would include `browser_close` (it matches `browser_*` first).
+## Filtering
 
 ### Pattern Syntax
 
@@ -185,7 +224,7 @@ Patterns use glob syntax via [minimatch](https://github.com/isaacs/minimatch):
 | `exact_name` | Exact match only |
 | `*` | Everything |
 
-### Default Behavior
+### Modes
 
 | Configuration | Unmatched items are... |
 |---------------|------------------------|
@@ -194,224 +233,41 @@ Patterns use glob syntax via [minimatch](https://github.com/isaacs/minimatch):
 | `--include` only | Excluded (whitelist mode) |
 | Mixed | Excluded if any `--include` exists |
 
-## MCP Spec Conformance
+### Rsync-Style Ordering
 
-mcp-filter is a fully conformant MCP proxy. It transparently forwards all MCP protocol features while applying filters only to list/call operations.
-
-### Filtered Operations
-
-| Operation | Behavior |
-|-----------|----------|
-| `tools/list` | Drains all pages, filters by name, returns filtered list |
-| `tools/call` | Blocks excluded tools with `-32602 InvalidParams` |
-| `resources/list` | Drains all pages, filters by name |
-| `resources/templates/list` | Drains all pages, filters by name |
-| `resources/read` | Forwarded (filtered resources won't appear in list) |
-| `resources/subscribe` | Forwarded to upstream |
-| `resources/unsubscribe` | Forwarded to upstream |
-| `prompts/list` | Drains all pages, filters by name |
-| `prompts/get` | Blocks excluded prompts with `-32602 InvalidParams` |
-| `completion/complete` | Blocks if referenced prompt is filtered; forwards resource completions |
-| `logging/setLevel` | Forwarded to upstream |
-
-### Forwarded Notifications
-
-| Direction | Notification | Description |
-|-----------|-------------|-------------|
-| Upstream → Downstream | `notifications/tools/list_changed` | Tool list changed |
-| Upstream → Downstream | `notifications/resources/list_changed` | Resource list changed |
-| Upstream → Downstream | `notifications/prompts/list_changed` | Prompt list changed |
-| Upstream → Downstream | `notifications/resources/updated` | Resource content updated |
-| Upstream → Downstream | `notifications/message` | Log messages |
-| Downstream → Upstream | `notifications/roots/list_changed` | Client roots changed |
-
-### Reverse-Direction Requests (Server → Client)
-
-| Request | Description |
-|---------|-------------|
-| `sampling/createMessage` | Forwarded from upstream to downstream client |
-| `roots/list` | Forwarded from upstream to downstream client |
-| `elicitation/create` | Forwarded from upstream to downstream client |
-
-### Protocol Features
-
-| Feature | Support |
-|---------|---------|
-| **Capability gating** | Only advertises capabilities the upstream server supports |
-| **Instructions forwarding** | Upstream server instructions passed through to downstream |
-| **Pagination** | Drains all pages before filtering (max 100 pages) |
-| **Progress notifications** | Forwarded on `tools/call`, `prompts/get`, `resources/read` |
-| **Cancellation propagation** | Downstream abort triggers upstream `notifications/cancelled` |
-| **Graceful shutdown** | SIGINT/SIGTERM cleanly close both transports |
-| **Connection timeout** | 30-second timeout prevents hang on unreachable servers |
-
-## Architecture
-
-```
-┌─────────────┐         ┌──────────────────────────────────────┐         ┌──────────────┐
-│  MCP Client │  stdio  │            mcp-filter                │ stdio/  │   Upstream    │
-│  (Claude,   │◄───────►│                                      │ HTTP/   │  MCP Server   │
-│   Cursor,   │         │  ┌────────┐  ┌────────┐  ┌────────┐ │  SSE    │  (Playwright, │
-│   etc.)     │         │  │ Server │→ │ Filter │→ │ Client │◄┼────────►│   Notion,     │
-│             │         │  └────────┘  └────────┘  └────────┘ │         │   etc.)       │
-└─────────────┘         └──────────────────────────────────────┘         └──────────────┘
-```
-
-**Four-layer design:**
-
-1. **CLI** (`src/cli.ts`) — Parses arguments into a typed `FilterConfig`
-2. **Transport Factory** (`src/transport.ts`) — Creates the appropriate client transport (stdio/HTTP/SSE)
-3. **Filter Engine** (`src/filter.ts`) — Glob pattern matching via minimatch
-4. **Proxy Server** (`src/proxy.ts`) — Dual-role MCP client + server with two-phase initialization
-
-## Integration Guides
-
-### Claude Code
-
-```bash
-# Add a filtered MCP server
-claude mcp add playwright-safe -- \
-  npx mcp-filter \
-    --exclude "browser_close" \
-    --exclude "browser_evaluate" \
-    --include "browser_*" \
-    -- npx @playwright/mcp@latest
-
-# Scopes: local (default), user (all projects), project (team-shared .mcp.json)
-claude mcp add --scope user playwright-safe -- \
-  npx mcp-filter --include "browser_*" -- npx @playwright/mcp@latest
-```
-
-**Command structure:** first `--` separates Claude options from mcp-filter; second `--` separates mcp-filter options from the upstream command.
-
-<details>
-<summary>More Claude Code examples</summary>
-
-**Read-only monitoring agent:**
-
-```bash
-claude mcp add browser-monitor -- \
-  npx mcp-filter \
-    --include "browser_navigate" \
-    --include "browser_snapshot" \
-    --include "browser_console_messages" \
-    --include "browser_network_requests" \
-    --include "browser_take_screenshot" \
-    -- npx @playwright/mcp@latest
-```
-
-**Testing agent (no destructive actions):**
-
-```bash
-claude mcp add browser-test -- \
-  npx mcp-filter \
-    --exclude "browser_close" \
-    --exclude "browser_tabs" \
-    --exclude "browser_evaluate" \
-    --include "browser_*" \
-    -- npx @playwright/mcp@latest
-```
-
-**Managing servers:**
-
-```bash
-claude mcp list                    # List all servers
-claude mcp get playwright-safe     # Show server details
-claude mcp remove playwright-safe  # Remove a server
-```
-
-</details>
-
-### Cursor IDE
-
-Add to `.cursor/mcp.json` or `~/.cursor/mcp.json`:
+Patterns are evaluated **in order** — first match wins. This lets you combine `--include` and `--exclude` for fine-grained control:
 
 ```json
-{
-  "mcpServers": {
-    "playwright-safe": {
-      "command": "npx",
-      "args": [
-        "mcp-filter",
-        "--exclude", "browser_close",
-        "--exclude", "browser_evaluate",
-        "--include", "browser_*",
-        "--",
-        "npx", "@playwright/mcp@latest"
-      ]
-    }
-  }
-}
+"args": [
+  "mcp-filter",
+  "--exclude", "merge_pull_request",
+  "--include", "pull_request_*",
+  "--include", "list_pull_requests",
+  "--",
+  "github-mcp-server", "stdio"
+]
 ```
 
-<details>
-<summary>More Cursor examples</summary>
-
-**Whitelist mode:**
-
-```json
-{
-  "mcpServers": {
-    "playwright-readonly": {
-      "command": "npx",
-      "args": [
-        "mcp-filter",
-        "--include", "browser_navigate",
-        "--include", "browser_screenshot",
-        "--include", "browser_snapshot",
-        "--",
-        "npx", "@playwright/mcp@latest"
-      ]
-    }
-  }
-}
 ```
-
-**Remote server with auth:**
-
-```json
-{
-  "mcpServers": {
-    "notion-safe": {
-      "command": "npx",
-      "args": [
-        "mcp-filter",
-        "--exclude", "delete_*",
-        "--exclude", "archive_*",
-        "--upstream-url", "https://mcp.notion.com/mcp",
-        "--header", "Authorization: Bearer your-token"
-      ]
-    }
-  }
-}
+merge_pull_request  → matches --exclude              → EXCLUDED
+pull_request_read   → matches --include              → included
+list_pull_requests  → matches --include              → included
+create_gist         → no match, --include exists     → excluded (whitelist mode)
 ```
 
-</details>
-
-### Any MCP Client
-
-mcp-filter works with any MCP client that supports stdio servers. The upstream server can be local (stdio) or remote (HTTP/SSE):
-
-```json
-{
-  "command": "npx",
-  "args": ["mcp-filter", "--exclude", "pattern", "--", "npx", "your-mcp-server"]
-}
-```
+> **Order matters!** `--exclude "merge_pull_request" --include "pull_request_*"` blocks merge then includes the rest. Reversing the order would include `merge_pull_request` (it matches `pull_request_*` first).
 
 ## Common Mistakes
 
 ### JSON args must be separate strings
 
-In JSON configs (Claude Desktop, Cursor, VS Code), each argument must be its own array element. The shell splits arguments for you — JSON doesn't.
+In JSON configs, each argument must be its own array element. The shell splits arguments for you — JSON doesn't.
 
-**WRONG:**
-```json
+```jsonc
+// WRONG
 "args": ["mcp-filter", "--include browser_*", "--", "npx", "server"]
-```
 
-**CORRECT:**
-```json
+// CORRECT
 "args": ["mcp-filter", "--include", "browser_*", "--", "npx", "server"]
 ```
 
@@ -424,11 +280,9 @@ Put `--exclude` patterns **before** `--include` to create exceptions. First matc
 ```bash
 # CORRECT: exclude first, then include the rest
 --exclude "browser_close" --include "browser_*"
-# Result: browser_close blocked, other browser_* allowed
 
-# WRONG order: include matches first, exclude never fires
+# WRONG: include matches first, exclude never fires
 --include "browser_*" --exclude "browser_close"
-# Result: ALL browser_* allowed including browser_close
 ```
 
 ### Two `--` separators in Claude Code
@@ -441,30 +295,13 @@ claude mcp add my-server -- npx mcp-filter --exclude "dangerous_*" -- npx upstre
 #                   Claude's --                              mcp-filter's --
 ```
 
-## Programmatic API
+## Transports
 
-mcp-filter exports its core modules for use in custom tooling:
-
-```typescript
-import { FilterEngine } from 'mcp-filter/filter';
-import { ProxyServer } from 'mcp-filter/proxy';
-import { createTransport } from 'mcp-filter/transport';
-import type { FilterConfig, TransportConfig } from 'mcp-filter/types';
-```
-
-## Testing
-
-187+ tests across 15 test suites covering unit tests, integration tests with real MCP servers, and full spec compliance validation.
-
-```bash
-pnpm test               # Run all tests
-pnpm test:coverage      # With coverage report
-pnpm test tests/unit/   # Unit tests only (fast)
-```
-
-Tests run on **Node 20, 22, and 24** via GitHub Actions CI.
-
-See [TESTING.md](TESTING.md) for the full testing guide.
+| Transport | Flag | Use Case | Status |
+|-----------|------|----------|--------|
+| **Stdio** | `-- <command>` | Local servers spawned as subprocesses | Stable |
+| **HTTP** | `--upstream-url <url>` | Remote servers via Streamable HTTP | Stable |
+| **SSE** | `--transport sse --upstream-url <url>` | Legacy remote servers via Server-Sent Events | Deprecated |
 
 ## Development
 
@@ -476,13 +313,15 @@ pnpm run build
 pnpm test
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and [TESTING.md](TESTING.md) for the testing guide.
 
 ## Links
 
 - [npm package](https://www.npmjs.com/package/mcp-filter)
 - [GitHub repository](https://github.com/baranovxyz/mcp-filter)
 - [Changelog](CHANGELOG.md)
+- [Spec conformance](docs/spec-conformance.md)
+- [Architecture decisions](docs/architecture-decisions.md)
 - [MCP specification](https://modelcontextprotocol.io)
 
 ## License

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,YAAY,EAGb,MAAM,YAAY,CAAC;AAwCpB,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,YAAY,CAoKtD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,YAAY,EAGb,MAAM,YAAY,CAAC;AAwCpB,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,YAAY,CA6KtD"}

package/dist/cli.js

@@ -98,6 +98,14 @@ export function parseArgs(args) {
             headers[key] = value;
             continue;
         }
+        if (arg === "--authorization") {
+            const value = args[++i];
+            if (!value) {
+                throw new Error("--authorization requires a value (e.g. 'Bearer token')");
+            }
+            headers["Authorization"] = value;
+            continue;
+        }
         if (arg === "--help" || arg === "-h") {
             throw new Error("help");
         }
@@ -150,7 +158,7 @@ export function parseArgs(args) {
             throw new Error(`--transport ${explicitTransport} requires --upstream-url. Use --transport stdio or omit --transport for command-based servers.`);
         }
         if (Object.keys(headers).length > 0) {
-            throw new Error("--header can only be used with --upstream-url");
+            throw new Error("--header/--authorization can only be used with --upstream-url");
         }
         transportConfig = {
             type: "stdio",