# mcp-compressor

MCP Compression Proxy service for PVE.

Wraps any existing MCP server and reduces tool-description token usage by exposing only a tiny discovery interface to the agent:

- `list_tools()` — compact list of `{name, brief_description}`
- `get_tool_schema(tool_name)` — full JSON schema + docs for one tool (cached)
- `invoke_tool(tool_name, arguments)` — execute and return result
- `get_server_info()` — metadata about connected upstream servers

Upstream tools are namespaced as `mcp__<server>__<tool>` to avoid collisions across servers.

## Quick start

### CLI / `uvx` mode (single upstream)

```bash
# stdio command upstream
uvx mcp-compressor "npx -y @modelcontextprotocol/server-filesystem /tmp"

# SSE URL upstream
uvx mcp-compressor "http://localhost:8080/sse" --server-name fetch --transport stdio
```

### Service mode (multi-upstream)

Create `config.yaml`:

```yaml
servers:
  - name: filesystem
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    cache_ttl: 300
    max_tools: 100

  - name: fetch
    url: http://localhost:8080/sse
    cache_ttl: 300
    max_tools: 50

cache_ttl: 300
max_tools: 100
log_level: INFO
host: 127.0.0.1
port: 8000
transport: sse
```

Run:

```bash
uvx mcp-compressor --config config.yaml --transport sse
```

Or install as a systemd service on PVE:

```bash
uv pip install -e .
mcp-compressor --config /etc/mcp-compressor.yaml --transport sse
```

## Configuration

| Option | Env / CLI | Default | Description |
|--------|-----------|---------|-------------|
| `servers` | `--config` | `[]` | List of upstream MCP servers |
| `cache_ttl` | `--cache-ttl` | `300` | Schema cache TTL in seconds |
| `max_tools` | `--max-tools` | `100` | Safety cap per upstream server |
| `transport` | `--transport` | `stdio` | `stdio`, `sse`, or `streamable-http` |
| `host` | `--host` | `127.0.0.1` | Bind host for SSE/HTTP |
| `port` | `--port` | `8000` | Bind port for SSE/HTTP |
| `log_level` | `--log-level` | `INFO` | Log level |

Each upstream server accepts either:

- `command` + `args` + optional `env` for stdio MCP servers
- `url` for SSE MCP servers

## Hermes / Bob `mcp.json` example

```json
{
  "mcpServers": {
    "compressor": {
      "command": "uvx",
      "args": [
        "mcp-compressor",
        "npx -y @modelcontextprotocol/server-filesystem /tmp"
      ]
    }
  }
}
```

For service mode:

```json
{
  "mcpServers": {
    "compressor": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}
```

## How it works

1. The proxy connects to every configured upstream MCP server on startup.
2. `list_tools` returns a short, stable list of namespaced names and one-line descriptions.
3. When the agent calls `get_tool_schema`, the proxy fetches the full schema for that single tool from the upstream server and caches it for `cache_ttl` seconds.
4. `invoke_tool` forwards the call to the correct upstream server with the original tool name and returns the result.

This keeps the agent context small while preserving the full MCP contract.

## Development

```bash
uv sync --extra dev
uv run pytest
uv run ruff check src tests
uv run mypy src
```

## License

MIT