Metadata-Version: 2.4
Name: shutup-mcp
Version: 0.3.0a1
Summary: Experimental MCP proxy for filtering large tool lists using hybrid semantic and keyword retrieval
Author-email: yuqiang <yuqiang@humanjudgment.org>
License: MIT
Project-URL: Homepage, https://github.com/hjs-spec/shutup-mcp
Project-URL: Repository, https://github.com/hjs-spec/shutup-mcp.git
Project-URL: Issues, https://github.com/hjs-spec/shutup-mcp/issues
Keywords: mcp,model-context-protocol,agent,tools,filter,ollama,embeddings,bm25,hybrid-search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE.md
Requires-Dist: mcp>=1.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: watchdog>=3.0.0
Provides-Extra: sentence-transformers
Requires-Dist: sentence-transformers>=2.2.0; extra == "sentence-transformers"
Provides-Extra: ollama
Requires-Dist: ollama>=0.1.0; extra == "ollama"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Dynamic: license-file

# shutup-mcp

> Experimental MCP tool-list filtering proxy for large tool catalogs.

`shutup-mcp` sits between an MCP client and one or more MCP servers. It aggregates tool definitions and exposes only the top-k tools that match the current intent.

This repository is an **alpha implementation seed**. It is useful for experimenting with tool-list compression, but it is not yet a full production MCP gateway.

---

## What It Does

- Reads a Claude Desktop-style MCP config.
- Discovers configured MCP servers.
- Fetches and prefixes upstream tools.
- Builds a hybrid retrieval index over tool names and descriptions.
- Filters `tools/list` results using:
  - explicit CLI intent;
  - a runtime `shutup__set_intent` tool;
  - fallback behavior when no intent is known.
- Routes `tools/call` to the correct upstream server.
- Supports local embedding backends:
  - `sentence-transformers`;
  - `ollama`.

---

## What It Does Not Yet Do

This alpha does not yet provide:

- full MCP request proxying for every capability;
- persistent upstream sessions for every server;
- guaranteed client-side dynamic intent detection across all MCP clients;
- production authentication or sandboxing;
- benchmark-backed token or latency claims.

Earlier README versions included strong reduction metrics. Those are removed until reproducible benchmarks are added.

---

## Install

```bash
pip install shutup-mcp
```

For local development:

```bash
pip install -e ".[dev]"
```

---

## CLI Usage

### One-shot tool filtering

```bash
shutup \
  --config ~/Library/Application\ Support/Claude/claude_desktop_config.json \
  --intent "read and write local files" \
  --top-k 5
```

This prints a JSON array of filtered tool definitions.

### Run as MCP proxy

```bash
shutup \
  --config ~/Library/Application\ Support/Claude/claude_desktop_config.json \
  --intent "work with GitHub issues" \
  --serve \
  --top-k 5
```

If `--intent` is supplied, `tools/list` returns only top-k tools matching that intent.

If no intent is supplied, the proxy exposes a small control tool:

```text
shutup__set_intent
```

Calling this tool updates the current intent, after which `tools/list` can be filtered.

---

## Claude Desktop Configuration

Example:

```json
{
  "mcpServers": {
    "shutup": {
      "command": "shutup",
      "args": [
        "--config",
        "/absolute/path/to/claude_desktop_config.json",
        "--serve",
        "--intent",
        "work with GitHub issues",
        "--top-k",
        "5"
      ]
    }
  }
}
```

---

## Example MCP Server Config

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

---

## Embedder Options

| Backend | Description | Privacy | Setup |
|---|---|---|---|
| `sentence-transformers` | Local model such as `all-MiniLM-L6-v2` | Local after download | Downloads model on first use |
| `ollama` | Ollama embedding model | Local | Requires Ollama running |
| `fake` | Deterministic lightweight test embedder | Local | For tests and CI only |

---

## Command Options

```text
shutup --config PATH [--intent TEXT] [--top-k K] [--embedder BACKEND] [--serve]
```

| Option | Description | Default |
|---|---|---|
| `--config` | Path to Claude Desktop MCP config | required |
| `--intent` | Current user task intent | none |
| `--top-k` | Number of tools to expose | 5 |
| `--embedder` | `sentence-transformers`, `ollama`, or `fake` | `sentence-transformers` |
| `--serve` | Run as an MCP stdio proxy | false |

---

## Runtime Intent Tool

The proxy exposes a control tool:

```text
shutup__set_intent
```

Input:

```json
{
  "intent": "create and triage GitHub issues"
}
```

Output:

```json
{
  "ok": true,
  "intent": "create and triage GitHub issues"
}
```

This provides an explicit client-controlled intent update path.

---

## Testing

```bash
pip install -e ".[dev]"
pytest -q
```

Tests use the lightweight `fake` embedder and do not download embedding models.

---

## Security Notes

`shutup-mcp` reads and launches MCP servers from a config file. Treat that config file as executable configuration.

Do not use untrusted server configs.

This project filters tool visibility; it does not enforce policy, authorization, sandboxing, or data-loss prevention.

---

## License

MIT
