npm package: @jorgemf/mcp-filter-tools
Description: A TypeScript MCP proxy server that filters upstream tools using allowlist patterns to reduce token consumption
Author: Jorge MF
Latest version: 0.1.1

# @jorgemf/mcp-filter-tools

A TypeScript MCP (Model Context Protocol) proxy server that filters upstream tools using allowlist patterns to dramatically reduce token consumption.

## Features

- 🎯 **Allowlist Filtering**: Expose only the tools you need using exact names or regex patterns
- 🔌 **Multi-Transport Support**: Works with stdio, SSE, and HTTP transports
- 📉 **Token Reduction**: Reduce context token usage by 70-90% by filtering unnecessary tools
- 🛠️ **Easy CLI**: Simple command-line interface for quick configuration
- 📦 **TypeScript**: Fully typed for better developer experience

## Installation

```bash
npm install @jorgemf/mcp-filter-tools
```

Or use directly with npx:

```bash
npx @jorgemf/mcp-filter-tools [options]
```

## Usage

### Basic Example (stdio transport)

Filter a local MCP server to expose only specific tools:

```bash
npx @jorgemf/mcp-filter-tools \
  --transport stdio \
  --stdio-command npx \
  --stdio-arg -y \
  --stdio-arg @modelcontextprotocol/server-filesystem@latest \
  --allow-tool read_file \
  --allow-tool list_directory
```

### Example with Regex Patterns

Allow tools matching patterns:

```bash
npx @jorgemf/mcp-filter-tools \
  --transport stdio \
  --stdio-command npx \
  --stdio-arg -y \
  --stdio-arg @supabase/mcp-server-supabase@latest \
  --allow-pattern "^execute_" \
  --allow-pattern "^list_" \
  --allow-tool get_project
```

### Example with HTTP/SSE Transport

Filter a remote MCP server:

```bash
npx @jorgemf/mcp-filter-tools \
  --transport sse \
  --http-url http://localhost:3000/sse \
  --allow-tool tool1 \
  --allow-tool tool2
```

## CLI Options

| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--transport <type>` | `-t` | Transport type: `stdio`, `sse`, or `http` | `stdio` |
| `--stdio-command <cmd>` | | Command to execute for stdio transport | |
| `--stdio-arg <arg>` | | Arguments for stdio command (can be repeated) | `[]` |
| `--http-url <url>` | | URL for HTTP/SSE transport | |
| `--allow-tool <name>` | `-a` | Exact tool name to allow (can be repeated) | `[]` |
| `--allow-pattern <regex>` | | Regex pattern for tool names (can be repeated) | `[]` |

**Note**: At least one `--allow-tool` or `--allow-pattern` must be specified.

## Configuration in MCP Clients

### Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "filtered-filesystem": {
      "command": "npx",
      "args": [
        "@jorgemf/mcp-filter-tools",
        "--transport", "stdio",
        "--stdio-command", "npx",
        "--stdio-arg", "-y",
        "--stdio-arg", "@modelcontextprotocol/server-filesystem@latest",
        "--allow-tool", "read_file",
        "--allow-tool", "write_file",
        "--allow-pattern", "^list_"
      ]
    }
  }
}
```

**Note**: Claude Desktop may display `capabilities: none` for this server. This is **normal and expected** - it means the server has no additional capabilities beyond tools (no prompts, resources, etc.). Your filtered tools will still be available and functional. See [CLAUDE_DESKTOP.md](CLAUDE_DESKTOP.md) for details.

### Cline/Continue Configuration

Similar configuration in your MCP settings file.

## How It Works

1. **Proxy Architecture**: Acts as a transparent proxy between MCP clients and upstream servers
2. **Tool Filtering**: Intercepts `tools/list` requests and filters tools based on allowlist
3. **Request Forwarding**: Forwards `tools/call` requests to upstream (only for allowed tools)
4. **Token Savings**: By exposing fewer tools, dramatically reduces context window usage

## Examples

### Filtering Supabase MCP Server

Reduce 29 tools (~20.8k tokens) to 3 tools (~1.9k tokens) - **91% reduction**:

```bash
npx @jorgemf/mcp-filter-tools \
  --transport stdio \
  --stdio-command npx \
  --stdio-arg -y \
  --stdio-arg @supabase/mcp-server-supabase@latest \
  --stdio-arg --access-token \
  --stdio-arg YOUR_TOKEN \
  --allow-tool execute_sql \
  --allow-tool list_tables \
  --allow-tool get_project
```

### Filtering Filesystem Server

Expose only read operations:

```bash
npx @jorgemf/mcp-filter-tools \
  --transport stdio \
  --stdio-command npx \
  --stdio-arg -y \
  --stdio-arg @modelcontextprotocol/server-filesystem@latest \
  --allow-pattern "^read_" \
  --allow-pattern "^list_"
```

## Programmatic Usage

You can also use the library programmatically:

```typescript
import { MCPFilterProxy } from '@jorgemf/mcp-filter-tools';

const proxy = new MCPFilterProxy({
  transport: {
    type: 'stdio',
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-filesystem@latest'],
  },
  filter: {
    allowTools: ['read_file', 'write_file'],
    allowPatterns: ['^list_'],
  },
});

await proxy.start();
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Run tests (watch mode)
npm test

# Run tests (single run)
npm run test:ci

# Run only unit tests
npm run test:unit

# Run integration tests
npm run test:integration

# Run E2E tests
npm run test:e2e

# Run all tests
npm run test:all

# Generate coverage report
npm run test:coverage

# Lint
npm run lint

# Format
npm run format
```

See [TEST_GUIDE.md](TEST_GUIDE.md) for detailed testing documentation.

## Comparison with Other Tools

| Feature | @jorgemf/mcp-filter-tools | mcp-filter (Python) | @respawn-app/tool-filter-mcp |
|---------|---------------------------|---------------------|------------------------------|
| Language | TypeScript | Python | TypeScript |
| Allowlist | ✅ | ✅ | ❌ |
| Denylist | ❌ | ✅ | ✅ |
| stdio transport | ✅ | ✅ | ❌ |
| HTTP/SSE transport | ✅ | ✅ | ✅ |
| Regex patterns | ✅ | ✅ | ✅ |
| Tool prefixing | ❌ | ✅ | ❌ |
| Health check | ❌ | ✅ | ❌ |

## License

MIT

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

## Credits

Inspired by:
- [mcp-filter](https://github.com/pro-vi/mcp-filter) - Python MCP filter proxy
- [@respawn-app/tool-filter-mcp](https://www.npmjs.com/package/@respawn-app/tool-filter-mcp) - TypeScript tool filter