mcp-filter 1.1.0 → 1.1.2

package/README.md

@@ -1,9 +1,9 @@
 <p align="center">
   <h1 align="center">mcp-filter</h1>
   <p align="center">
-    MCP proxy that filters tools, resources, and prompts from upstream MCP servers using glob patterns.
+    MCP proxy that filters tools, resources, and prompts using glob patterns.
     <br />
-    Works with any MCP client. Supports local and remote servers.
+    Any MCP server. Any MCP client. Local or remote.
   </p>
 </p>
 
@@ -17,22 +17,17 @@
 
 ---
 
-## Why mcp-filter?
+## The Problem
 
-[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.
+[GitHub MCP Server](https://github.com/github/github-mcp-server) exposes 79 tools — **~52,000 tokens** of context window on every request. A PR review agent needs about 10 of them. The other 69 (gists, stars, security advisories, dependabot, discussions...) consume tokens and make tool selection harder for the model.
 
-`mcp-filter` sits between your MCP client and upstream server, filtering what gets through:
+Most MCP clients offer blacklists like `disabledTools` — you list what to block. This works until the upstream server adds a new tool. It silently appears in context because it's not in your blocklist. You find out when the agent calls a tool you didn't know existed.
 
-- **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
+Blacklists describe what you *don't* want. Whitelists describe what you *do* want — and they're immune to upstream changes.
 
-## Quick Start
+## The Solution
 
-Add mcp-filter to your MCP client config. No install needed — `npx` downloads it automatically.
-
-**Local server** — filter tools from a stdio MCP server:
+`mcp-filter` is an MCP proxy that sits between your client and server. It intercepts tool/resource/prompt lists, applies glob patterns, and only passes through what matches. Add it to your MCP client's JSON config:
 
 ```json
 {
@@ -52,7 +47,10 @@ Add mcp-filter to your MCP client config. No install needed — `npx` downloads
 }
 ```
 
-**Remote server** — filter tools from an HTTP MCP server:
+No install needed — `npx` downloads it automatically. This config format works with Cursor, VS Code, Claude Desktop, and any MCP client that supports stdio servers.
+
+<details>
+<summary>Remote server (HTTP)</summary>
 
 ```json
 {
@@ -70,7 +68,10 @@ Add mcp-filter to your MCP client config. No install needed — `npx` downloads
 }
 ```
 
-**Remote server with authentication:**
+</details>
+
+<details>
+<summary>Remote server with authentication</summary>
 
 ```json
 {
@@ -91,13 +92,84 @@ Add mcp-filter to your MCP client config. No install needed — `npx` downloads
 
 For additional headers, use `--header "Key: Value"` (repeatable).
 
-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.
+</details>
+
+<details>
+<summary>Claude Code</summary>
+
+Claude Code uses `claude mcp add` instead of JSON config:
+
+```bash
+# 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
+
+# Remote HTTP server (no second --)
+claude mcp add stripe-safe -- \
+  npx mcp-filter \
+    --exclude "create_refund" \
+    --exclude "delete_*" \
+    --upstream-url https://mcp.stripe.com
+```
+
+First `--` separates Claude's options from mcp-filter. Second `--` separates mcp-filter's options from the upstream command.
+
+</details>
+
+## How Filtering Works
+
+mcp-filter supports three filtering modes:
+
+**Exclude mode** blocks specific tools and allows everything else. Use `--exclude` when you trust most tools but want to remove a few dangerous ones: `--exclude "delete_*"` blocks all delete operations.
+
+**Include mode** (whitelist) allows only what you specify and blocks everything else. Use `--include` when you want a tight perimeter: `--include "pull_request_*"` passes through only PR tools. New tools added upstream are automatically blocked.
+
+**Combined mode** uses rsync-style ordering — patterns are evaluated in the order you write them, and the first match wins. This lets you create exceptions within a category:
 
-## Examples: GitHub MCP Server
+```
+--exclude "merge_pull_request" --include "pull_request_*"
+```
+
+Here, `merge_pull_request` hits the exclude rule first, so it's blocked. Other `pull_request_*` tools match the include rule and pass through. Anything that doesn't match any pattern is excluded (because `--include` exists).
+
+Reversing the order would break this: `--include "pull_request_*" --exclude "merge_pull_request"` — now `merge_pull_request` matches `pull_request_*` first and gets included.
 
-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.
+<details>
+<summary>Pattern syntax and default behavior</summary>
 
-**PR review agent** — whitelist only what's needed (79 → ~10 tools):
+Patterns use glob syntax via [minimatch](https://github.com/isaacs/minimatch):
+
+| Pattern | Matches |
+|---------|---------|
+| `browser_*` | All items starting with `browser_` |
+| `*_admin` | All items ending with `_admin` |
+| `test_*_debug` | Items like `test_foo_debug` |
+| `exact_name` | Exact match only |
+| `*` | Everything |
+
+Default behavior for unmatched items:
+
+| Configuration | Unmatched items are... |
+|---------------|------------------------|
+| No patterns | Allowed (passthrough) |
+| `--exclude` only | Allowed |
+| `--include` only | Excluded (whitelist mode) |
+| Mixed | Excluded if any `--include` exists |
+
+</details>
+
+## Real-World Examples
+
+The [GitHub MCP Server](https://github.com/github/github-mcp-server) exposes 79 tools across 19 toolsets. Here's how different agents can get exactly the slice they need.
+
+<details>
+<summary>PR review agent — whitelist (79 → ~10 tools)</summary>
+
+A code review agent only needs PRs, issues, file contents, and search. Everything else — gists, stars, notifications, security advisories — is noise.
 
 ```json
 {
@@ -122,9 +194,14 @@ The [GitHub MCP Server](https://github.com/github/github-mcp-server) is a good e
 }
 ```
 
-When GitHub adds new tools tomorrow, they won't leak through — only `pull_request_*`, `issue_*`, and the explicitly listed tools are visible.
+When GitHub adds new tools tomorrow, they won't leak through — only the patterns above are visible to the agent.
 
-**Read-only agent** — exclude all mutations, keep all reads:
+</details>
+
+<details>
+<summary>Read-only agent — exclude mutations</summary>
+
+An analytics agent that collects data for reports shouldn't be able to change anything. Exclude all write operations:
 
 ```json
 {
@@ -151,7 +228,14 @@ When GitHub adds new tools tomorrow, they won't leak through — only `pull_requ
 }
 ```
 
-**PR tools without merge** — rsync-style, first match wins:
+The agent can read anything but can't modify anything.
+
+</details>
+
+<details>
+<summary>PR tools without merge — rsync-style exceptions</summary>
+
+Allow all PR tools except the ability to merge. First match wins:
 
 ```json
 {
@@ -175,28 +259,9 @@ When GitHub adds new tools tomorrow, they won't leak through — only `pull_requ
 }
 ```
 
-`merge_pull_request` matches `--exclude` first, so it's blocked. The remaining `pull_request_*` tools pass through.
+`merge_pull_request` hits the `--exclude` first and gets blocked. The remaining PR tools match `--include` and pass through.
 
-### Claude Code
-
-Claude Code uses `claude mcp add` instead of JSON:
-
-```bash
-# 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
-
-# Remote HTTP server (no second --)
-claude mcp add stripe-safe -- \
-  npx mcp-filter \
-    --exclude "create_refund" \
-    --exclude "delete_*" \
-    --upstream-url https://mcp.stripe.com
-```
+</details>
 
 ## Options
 
@@ -210,58 +275,12 @@ claude mcp add stripe-safe -- \
 | `--header <header>` | HTTP header as `"Key: Value"` (repeatable, HTTP/SSE only) |
 | `--` | Separates mcp-filter options from upstream command (stdio only) |
 
-## Filtering
-
-### Pattern Syntax
+Transport is auto-detected: `--upstream-url` selects HTTP, `-- <command>` selects stdio.
 
-Patterns use glob syntax via [minimatch](https://github.com/isaacs/minimatch):
+<details>
+<summary>Common mistakes</summary>
 
-| Pattern | Matches |
-|---------|---------|
-| `browser_*` | All items starting with `browser_` |
-| `*_admin` | All items ending with `_admin` |
-| `test_*_debug` | Items like `test_foo_debug` |
-| `exact_name` | Exact match only |
-| `*` | Everything |
-
-### Modes
-
-| Configuration | Unmatched items are... |
-|---------------|------------------------|
-| No patterns | Allowed (passthrough) |
-| `--exclude` only | Allowed |
-| `--include` only | Excluded (whitelist mode) |
-| Mixed | Excluded if any `--include` exists |
-
-### Rsync-Style Ordering
-
-Patterns are evaluated **in order** — first match wins. This lets you combine `--include` and `--exclude` for fine-grained control:
-
-```json
-"args": [
-  "mcp-filter",
-  "--exclude", "merge_pull_request",
-  "--include", "pull_request_*",
-  "--include", "list_pull_requests",
-  "--",
-  "github-mcp-server", "stdio"
-]
-```
-
-```
-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)
-```
-
-> **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, each argument must be its own array element. The shell splits arguments for you — JSON doesn't.
+**JSON args must be separate strings.** In JSON configs, each argument must be its own array element:
 
 ```jsonc
 // WRONG
@@ -273,21 +292,14 @@ In JSON configs, each argument must be its own array element. The shell splits a
 
 mcp-filter detects this mistake and shows a corrective error message.
 
-### Pattern order matters
-
-Put `--exclude` patterns **before** `--include` to create exceptions. First match wins.
+**Pattern order matters.** Put `--exclude` before `--include` to create exceptions. First match wins:
 
-```bash
-# CORRECT: exclude first, then include the rest
---exclude "browser_close" --include "browser_*"
-
-# WRONG: include matches first, exclude never fires
---include "browser_*" --exclude "browser_close"
+```
+--exclude "browser_close" --include "browser_*"   (browser_close blocked)
+--include "browser_*" --exclude "browser_close"   (browser_close allowed!)
 ```
 
-### Two `--` separators in Claude Code
-
-When using `claude mcp add`, the first `--` separates Claude's options from the mcp-filter command. The second `--` separates mcp-filter's options from the upstream server command:
+**Two `--` in Claude Code.** First `--` separates Claude's options. Second `--` separates mcp-filter's options from the upstream command:
 
 ```bash
 claude mcp add my-server -- npx mcp-filter --exclude "dangerous_*" -- npx upstream-server
@@ -295,7 +307,10 @@ claude mcp add my-server -- npx mcp-filter --exclude "dangerous_*" -- npx upstre
 #                   Claude's --                              mcp-filter's --
 ```
 
-## Transports
+</details>
+
+<details>
+<summary>Transports</summary>
 
 | Transport | Flag | Use Case | Status |
 |-----------|------|----------|--------|
@@ -303,7 +318,10 @@ claude mcp add my-server -- npx mcp-filter --exclude "dangerous_*" -- npx upstre
 | **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
+</details>
+
+<details>
+<summary>Development</summary>
 
 ```bash
 git clone https://github.com/baranovxyz/mcp-filter.git
@@ -315,6 +333,8 @@ pnpm test
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and [TESTING.md](TESTING.md) for the testing guide.
 
+</details>
+
 ## Links
 
 - [npm package](https://www.npmjs.com/package/mcp-filter)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-filter",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "MCP server proxy to filter tools, resources, and prompts from upstream MCP servers",
   "type": "module",
   "bin": {