npm package: @squadbase/mcp-bonsai
Description: MCP middleware proxy for filtering tools, resources, and prompts
Latest version: 0.0.1-build3

# @squadbase/mcp-bonsai

A middleware proxy for filtering tools, resources, and prompts from MCP (Model Context Protocol) servers.

## Overview

mcp-bonsai sits between LLM clients (like Claude Code) and MCP servers as a proxy.
It intercepts JSON-RPC messages and filters `tools/list`, `resources/list`, and `prompts/list` responses based on your configuration.

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ LLM Client  │ ──► │ mcp-bonsai  │ ──► │ MCP Server  │
│ (Claude)    │ ◄── │  (Proxy)    │ ◄── │             │
└─────────────┘     └─────────────┘     └─────────────┘
                          │
                    Filters based on
                    configuration
```

## Installation

```bash
npm install @squadbase/mcp-bonsai
```

## Usage

### CLI

```bash
npx mcp-bonsai --name <identifier> --command "<mcp-server-command>" [options]
```

### Options

| Option | Required | Description |
|--------|:--------:|-------------|
| `-n, --name <identifier>` | ✅ | Identifier for config lookup |
| `-c, --command <cmd>` | ✅ | MCP server command to spawn |
| `-f, --config <path>` | | Config file path or JSON string |
| `--debug` | | Enable debug logging to stderr |

### Examples

```bash
# Filter next-devtools-mcp
npx mcp-bonsai \
  --name next-devtools \
  --command "npx -y next-devtools-mcp@latest" \
  --config ./mcp-bonsai.json

# Pass config as JSON string
npx mcp-bonsai \
  --name myserver \
  --command "uvx some-mcp-server" \
  --config '{"myserver": {"tools": ["allowed_tool"]}}'
```

## Configuration

Configuration uses a whitelist approach to specify which tools, resources, and prompts are allowed.

### Supported Formats

- JSON (`.json`)
- YAML (`.yaml`, `.yml`)

### Schema

```json
{
  "<server-name>": {
    "tools": ["tool1", "tool2"],
    "resources": ["resource://*"],
    "prompts": ["prompt1"]
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `tools` | `string[]` | List of allowed tool names |
| `resources` | `string[]` | List of allowed resource URIs (supports wildcards) |
| `prompts` | `string[]` | List of allowed prompt names |

### Configuration Examples

#### Filtering next-devtools-mcp

```json
{
  "next-devtools": {
    "tools": [
      "init",
      "nextjs_docs",
      "nextjs_index",
      "nextjs_call"
    ],
    "resources": [],
    "prompts": []
  }
}
```

This configuration blocks `browser_eval`, `enable_cache_components`, and `upgrade_nextjs_16`.

#### YAML Format

```yaml
next-devtools:
  tools:
    - init
    - nextjs_docs
    - nextjs_index
  resources: []
  prompts: []
```

### Wildcards

Resource filtering supports wildcards (`*`).

```json
{
  "myserver": {
    "resources": [
      "file://*",
      "system_logs://*"
    ]
  }
}
```

## Usage with Claude Code

Register mcp-bonsai as an MCP server in `~/.claude/claude_code_config.json`:

```json
{
  "mcpServers": {
    "next-devtools-filtered": {
      "command": "npx",
      "args": [
        "mcp-bonsai",
        "--name", "next-devtools",
        "--command", "npx -y next-devtools-mcp@latest",
        "--config", "/path/to/mcp-bonsai.json"
      ]
    }
  }
}
```

## How It Works

1. **Startup**: Spawns the specified MCP server as a child process
2. **Passthrough**: Most messages are forwarded as-is
3. **Filtering**: Only `tools/list`, `resources/list`, and `prompts/list` responses are filtered based on configuration
4. **Execution**: `tools/call` and other execution requests are passed through without modification

## Debugging

Use the `--debug` option to output detailed logs to stderr:

```bash
npx mcp-bonsai \
  --name next-devtools \
  --command "npx -y next-devtools-mcp@latest" \
  --config ./mcp-bonsai.json \
  --debug
```

Debug logs show:
- Client requests received
- Server responses received
- Filtered tools/resources/prompts

## Development

```bash
# Build
npm run build

# Type check
npm run typecheck

# Unit tests
npm test

# Integration tests (requires network)
npm run test:integration

# Development mode (watch)
npm run dev
```

## License

MIT