mcp-filter 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.0] - 2025-10-08
+
+### Fixed
+- Fixed connection failures caused by double-spawning upstream MCP server subprocess
+- Fixed "command not found" errors with `npx` by properly passing environment variables
+- Fixed stderr forwarding from upstream servers
+
+### Changed
+- Delegated subprocess management entirely to `StdioClientTransport` (breaking change in internal architecture)
+- Improved error forwarding by using `stderr: "inherit"` instead of `"pipe"`
+
+### Added
+- Comprehensive integration tests for subprocess management and real-world MCP server compatibility
+- Architecture validation tests to prevent regression of subprocess spawning anti-patterns
+- Debugging guide for common MCP communication issues in CLAUDE.md
+- ADR-003 documenting subprocess delegation pattern
+- Claude Code configuration with custom slash commands
+
+## [0.3.0] - 2025-01-XX
+
+### Added
+- Rsync-style pattern evaluation (first match wins)
+- Support for both `--include` and `--exclude` patterns
+
+### Changed
+- Pattern matching now evaluates in order with first-match-wins semantics
+
+## [0.2.0] - 2025-01-XX
+
+### Added
+- Comprehensive documentation updates
+- Testing infrastructure with Vitest
+
+## [0.1.0] - 2025-01-XX
+
+### Added
+- Initial release
+- Basic MCP proxy server with pattern-based filtering
+- Support for filtering tools, resources, and prompts
+- Glob pattern matching using minimatch

package/README.md

@@ -24,8 +24,8 @@ npx mcp-filter --exclude "playwright*" -- npx @playwright/mcp
 # Include mode: only allow specific tools
 npx mcp-filter --include "browser_navigate" --include "browser_screenshot" -- npx @playwright/mcp
 
-# Combination: include with exceptions
-npx mcp-filter --include "browser_*" --exclude "browser_close" -- npx @playwright/mcp
+# Combination: include with exceptions (order matters!)
+npx mcp-filter --exclude "browser_close" --include "browser_*" -- npx @playwright/mcp
 
 # Multiple patterns
 npx mcp-filter --exclude "playwright*" --exclude "unsafe_*" -- npx @playwright/mcp
@@ -68,18 +68,21 @@ npx mcp-filter --include "browser_navigate" --include "browser_screenshot" -- np
 
 **Rsync-style filtering**: patterns evaluated in order, first match wins.
 
+⚠️ **Common mistake**: Putting `--include` before `--exclude` means the exclude never applies!
+
 ```bash
-# Example 1: Include first, then exclude
+# Example 1: Include first, then exclude (DOES NOT WORK AS EXPECTED!)
 npx mcp-filter --include "browser_*" --exclude "browser_close" -- npx @playwright/mcp
 # Result: All browser_* tools are INCLUDED (browser_* matched first)
 # browser_close is also included because it matches browser_* first
+# The --exclude "browser_close" is never evaluated!
 
-# Example 2: Exclude first, then include (different result!)
+# Example 2: Exclude first, then include (CORRECT way to exclude exceptions!)
 npx mcp-filter --exclude "browser_close" --include "browser_*" -- npx @playwright/mcp
 # Result: browser_close is EXCLUDED (matched exclude first)
 # Other browser_* tools are included
 
-# Example 3: More specific patterns first
+# Example 3: Multiple exclusions, then broad include (recommended pattern)
 npx mcp-filter --exclude "browser_close" --exclude "browser_evaluate" --include "browser_*" -- npx @playwright/mcp
 # Result: browser_close and browser_evaluate excluded (matched first)
 # All other browser_* tools included
@@ -127,6 +130,139 @@ npx mcp-filter \
 # 4. other_tool doesn't match any pattern, but --include exists → excluded (whitelist mode)
 ```
 
+## Using with Claude Code
+
+### Adding Filtered MCP Servers
+
+Add filtered MCP servers to Claude Code using the `claude mcp add` command:
+
+```bash
+# Basic syntax
+claude mcp add <name> -- npx mcp-filter [filter-options] -- <upstream-command>
+
+# Example: Safe Playwright with read-only browser access
+claude mcp add playwright-safe -- \
+  npx mcp-filter \
+    --include "browser_navigate" \
+    --include "browser_screenshot" \
+    --include "browser_snapshot" \
+    -- npx @playwright/mcp@latest
+
+# Example: Block dangerous operations
+claude mcp add playwright-filtered -- \
+  npx mcp-filter \
+    --exclude "browser_close" \
+    --exclude "browser_evaluate" \
+    -- npx @playwright/mcp@latest
+
+# Example: Include category with exceptions (rsync-style)
+claude mcp add playwright -- \
+  npx mcp-filter \
+    --exclude "browser_close" \
+    --exclude "browser_evaluate" \
+    --include "browser_*" \
+    -- npx @playwright/mcp@latest
+```
+
+**Understanding the command structure:**
+
+- First `--` separates Claude's options from the mcp-filter command
+- Second `--` separates mcp-filter options from the upstream MCP server command
+
+### Scope Options
+
+Choose where to store the configuration:
+
+```bash
+# Local scope (default): Only you, only this project
+claude mcp add playwright-safe -- npx mcp-filter --include "browser_*" -- npx @playwright/mcp@latest
+
+# User scope: Available across all your projects
+claude mcp add --scope user playwright-safe -- \
+  npx mcp-filter --include "browser_*" -- npx @playwright/mcp@latest
+
+# Project scope: Share with team via .mcp.json (checked into git)
+claude mcp add --scope project playwright-safe -- \
+  npx mcp-filter --include "browser_*" -- npx @playwright/mcp@latest
+```
+
+**Security Note**: Claude Code prompts for approval before using project-scoped servers from `.mcp.json` files. To reset approval choices, use `claude mcp reset-project-choices`.
+
+### Managing Filtered Servers
+
+```bash
+# List all configured servers
+claude mcp list
+
+# Get details for a specific server
+claude mcp get playwright-safe
+
+# Remove a server
+claude mcp remove playwright-safe
+
+# Check server status in Claude Code
+/mcp
+```
+
+### Practical Examples
+
+**Monitoring agent (read-only)**
+
+```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
+```
+
+Note: Exclude patterns must come BEFORE the include pattern to match first.
+
+**Production debugging (safe operations only)**
+
+```bash
+# Add as user-scoped for use across projects
+claude mcp add --scope user prod-debugger -- \
+  npx mcp-filter \
+    --exclude "browser_click" \
+    --exclude "browser_type" \
+    --exclude "browser_evaluate" \
+    --exclude "browser_fill_form" \
+    --include "browser_*" \
+    -- npx @playwright/mcp@latest
+```
+
+### Updating Server Configuration
+
+To update filter rules, remove and re-add the server:
+
+```bash
+# Remove existing configuration
+claude mcp remove playwright-safe
+
+# Add with new filter rules
+claude mcp add playwright-safe -- \
+  npx mcp-filter \
+    --include "browser_navigate" \
+    --include "browser_screenshot" \
+    -- npx @playwright/mcp@latest
+```
+
 ## Using with Cursor IDE
 
 Add to your `.cursor/mcp.json` or `~/.cursor/mcp.json`:

package/dist/index.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import { spawn } from "child_process";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { parseArgs } from "./cli.js";
@@ -28,8 +27,6 @@ async function main() {
     if (hasInclude && hasExclude) {
         console.error("Note: Using rsync-style filtering - patterns evaluated in order, first match wins.");
     }
-    // Spawn upstream server
-    const upstreamProcess = spawnUpstream(config.upstreamCommand);
     // Create filter
     const filter = new Filter(config.patterns);
     // Create proxy server
@@ -38,10 +35,12 @@ async function main() {
         version: "0.2.0",
     }, filter);
     // Connect client to upstream server via subprocess stdio
+    // StdioClientTransport spawns and manages the subprocess
     const clientTransport = new StdioClientTransport({
         command: config.upstreamCommand[0],
         args: config.upstreamCommand.slice(1),
-        stderr: "pipe",
+        env: process.env, // Pass current environment
+        stderr: "inherit", // Forward upstream stderr to our stderr
     });
     await proxy.getClient().connect(clientTransport);
     console.error("Connected to upstream server");
@@ -52,31 +51,11 @@ async function main() {
     // Handle cleanup
     const cleanup = () => {
         console.error("Shutting down...");
-        upstreamProcess.kill();
         process.exit(0);
     };
     process.on("SIGINT", cleanup);
     process.on("SIGTERM", cleanup);
 }
-function spawnUpstream(command) {
-    const [cmd, ...args] = command;
-    const proc = spawn(cmd, args, {
-        stdio: ["pipe", "pipe", "pipe"],
-    });
-    // Forward stderr to our stderr
-    proc.stderr.on("data", (data) => {
-        process.stderr.write(data);
-    });
-    proc.on("error", (error) => {
-        console.error(`Failed to start upstream server: ${error.message}`);
-        process.exit(1);
-    });
-    proc.on("exit", (code) => {
-        console.error(`Upstream server exited with code ${code}`);
-        process.exit(code || 0);
-    });
-    return proc;
-}
 main().catch((error) => {
     console.error("Fatal error:", error);
     process.exit(1);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-filter",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "MCP server proxy to filter tools, resources, and prompts from upstream MCP servers",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "keywords": [