Metadata-Version: 2.4
Name: mcpfind
Version: 0.2.1
Summary: Context-efficient MCP tool proxy with semantic search
License: # PolyForm Noncommercial License 1.0.0
        
        <https://polyformproject.org/licenses/noncommercial/1.0.0>
        
        ## Acceptance
        
        In order to get any license under these terms, you must agree
        to them as both strict obligations and conditions to all
        your licenses.
        
        ## Copyright License
        
        The licensor grants you a copyright license for the
        software to do everything you might do with the software
        that would otherwise infringe the licensor's copyright
        in it for any permitted purpose under these terms,
        other than distributing the software or making changes
        or new works based on the software.
        
        ## Distribution License
        
        The licensor grants you an additional copyright license
        to distribute copies of the software. Your license
        to distribute covers distributing the software with
        changes and new works permitted by [Changes and New
        Works License](#changes-and-new-works-license).
        
        ## Notices
        
        You must ensure that anyone who gets a copy of any part
        of the software from you also gets a copy of these terms
        or the URL for them above, as well as copies of any
        plain-text lines beginning with `Required Notice:` that
        the licensor provided with the software. For example:
        
        > Required Notice: Copyright Jerry Chang (https://github.com/jcgs2503)
        
        ## Changes and New Works License
        
        The licensor grants you an additional copyright license
        to make changes and new works based on the software for
        any permitted purpose.
        
        ## Patent License
        
        The licensor grants you a patent license for the software
        that covers patent claims the licensor can license, or
        becomes able to license, that you would infringe by using
        the software.
        
        ## Noncommercial Purposes
        
        Any noncommercial purpose is a permitted purpose.
        
        ## Personal Uses
        
        Personal use for research, experiment, and testing for
        the benefit of public knowledge, personal study, private
        entertainment, hobby projects, amateur pursuits, or
        religious observance, without any anticipated commercial
        application, is use for a permitted purpose.
        
        ## Noncommercial Organizations
        
        Use by any charitable organization, educational
        institution, public research organization, public safety
        or health organization, environmental protection
        organization, or government institution is use for a
        permitted purpose regardless of the source of funding or
        obligations resulting from the funding.
        
        ## Fair Use
        
        You may have "fair use" rights for the software under the
        law. These terms do not limit them.
        
        ## No Other Rights
        
        These terms do not allow you to sublicense or transfer any
        of your licenses to anyone else, or prevent the licensor
        from granting licenses to anyone else. These terms do not
        imply any other licenses.
        
        ## Patent Defense
        
        If you make any written claim that the software infringes
        or contributes to infringement of any patent, your patent
        license for the software granted under these terms ends
        immediately. If your company makes such a claim, your
        patent license ends immediately for work on behalf of your
        company.
        
        ## Violations
        
        The first time you are notified in writing that you have
        violated any of these terms, or done anything with the
        software not covered by your licenses, your licenses can
        nonetheless continue if you come into full compliance with
        these terms, and take practical steps to correct past
        violations, within 32 days of receiving notice. Otherwise,
        all your licenses end immediately.
        
        ## No Liability
        
        ***As far as the law allows, the software comes as is,
        without any warranty or condition, and the licensor will
        not be liable to you for any damages arising out of these
        terms or the use or nature of the software, under any kind
        of legal claim.***
        
        ## Definitions
        
        The **licensor** is the individual or entity offering these
        terms, and the **software** is the software the licensor
        makes available under these terms.
        
        **You** refers to the individual or entity agreeing to these
        terms.
        
        **Your company** is any legal entity, sole proprietorship,
        or other kind of organization that you work for, plus all
        organizations that have control over, are under the control
        of, or are under common control with that organization.
        **Control** means ownership of substantially all the assets
        of an entity, or the power to direct its management and
        policies by vote, contract, or otherwise. Control can be
        direct or indirect.
        
        **Your licenses** are all the licenses granted to you for
        the software under these terms.
        
        **Use** means anything you do with the software requiring
        one of your licenses.
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: click
Requires-Dist: fastembed
Requires-Dist: mcp>=1.0
Requires-Dist: numpy
Requires-Dist: tomli
Provides-Extra: openai
Requires-Dist: openai; extra == 'openai'
Description-Content-Type: text/markdown

# MCPFind

[![License: PolyForm Noncommercial](https://img.shields.io/badge/license-PolyForm%20Noncommercial%201.0.0-blue)](LICENSE)

Context-efficient MCP tool proxy with semantic search. MCPFind sits between any MCP client and your backend MCP servers, replacing hundreds of tool schemas in the agent's context with just 3 meta-tools (~500 tokens).

```
Agent (Claude Desktop, Cursor, Claude Code, etc.)
  │  Sees only: list_servers, search_tools, get_tool_schema, call_tool
  ▼
MCPFind Proxy
  ├── Vector search over all tool descriptions
  ├── Per-agent MFU cache for personalized ranking
  └── Routes calls to the correct backend server
  │
  ├──▶ Gmail MCP Server
  ├──▶ GitHub MCP Server
  ├──▶ Slack MCP Server
  └──▶ ... N servers
```

## Why

As MCP toolspaces grow, every tool schema gets dumped into the agent's context:

| Tools | Context tokens | Effect |
|-------|---------------|--------|
| 10 | ~2K | Fine |
| 50 | ~10K | Manageable |
| 200 | ~40K | Agent picks wrong tools |
| 1000 | ~200K | Unusable |

MCPFind keeps context at ~500 tokens regardless of how many tools exist behind it. Agents discover tools via semantic search, pull schemas on demand, and call tools through the proxy.

## Install

```bash
# With uv (recommended)
uv tool install mcpfind

# With pip
pip install mcpfind
```

No API key needed — MCPFind uses local embeddings by default.

## Quick Start

### 1. Configure your servers

```bash
mcpfind setup
```

The setup wizard walks you through choosing an embedding provider and adding MCP servers (GitHub, Slack, Filesystem, PostgreSQL, Brave Search, Playwright, and more). Config is saved to `~/.config/mcpfind/mcpfind.toml`.

### 2. Register with your MCP client

```bash
mcpfind install claude-code
mcpfind install cursor
mcpfind install claude-desktop
```

Pick the client you use. That's it — mcpfind is now available as an MCP server.

### 3. Verify (optional)

```bash
# List all tools discovered from your backend servers
mcpfind list-tools

# Test semantic search
mcpfind search "create a pull request"
```

## How It Works

MCPFind exposes 4 tools to the agent:

1. **`list_servers`** — List all connected MCP servers and their tool counts. Use this to see what's available.

2. **`search_tools`** — Find relevant tools by natural language query (e.g., "send an email"). Returns tool names, servers, and descriptions ranked by semantic similarity + usage frequency. Optionally filter to a specific server.

3. **`get_tool_schema`** — Pull the full input schema for a specific tool before calling it. Keeps schemas out of context until actually needed.

4. **`call_tool`** — Execute a tool on a backend server. MCPFind validates and routes the call to the correct server.

### Agent workflow

```
Agent: list_servers()
  → [{"server": "gmail", "tool_count": 5}, {"server": "github", "tool_count": 12}, ...]

Agent: search_tools("create issue", server="github")
  → [{"server": "github", "name": "create_issue", "score": 0.97}, ...]

Agent: get_tool_schema(server="github", tool="create_issue")
  → {"type": "object", "properties": {"repo": ..., "title": ..., "body": ...}}

Agent: call_tool(server="github", tool="create_issue", arguments={...})
  → "Issue created!"
```

### MFU Cache

MCPFind tracks which tools each agent uses most frequently. Frequently used tools get a ranking boost in search results via `mfu_boost_weight` (default: 0.15 — 85% semantic similarity, 15% usage frequency). Set `mfu_persist = true` to save usage data across restarts.

## Project-Specific Servers

Add servers that only apply to the current project:

```bash
cd your-project
mcpfind init
```

This creates a local `mcpfind.toml` in the project directory. When mcpfind starts, it merges global + local configs:

- **Global** (`~/.config/mcpfind/mcpfind.toml`) — your always-available servers and settings
- **Local** (`./mcpfind.toml`) — project-specific servers, merged on top

A local server with the same name as a global one overrides it. Proxy settings (embedding model, MFU weight, etc.) fall back to global if not set locally.

## Configuration Reference

### File locations

| Config | Path | Created by |
|--------|------|------------|
| Global | `~/.config/mcpfind/mcpfind.toml` | `mcpfind setup` |
| Local | `./mcpfind.toml` | `mcpfind init` |

### Format

```toml
[proxy]
embedding_provider = "local"                # "local" (default) or "openai"
embedding_model = "all-MiniLM-L6-v2"        # Model name (provider-specific)
mfu_boost_weight = 0.15                     # Frequency boost weight (0.0-1.0)
mfu_persist = true                          # Persist usage data to SQLite
default_max_results = 5                     # Default number of search results

[[servers]]
name = "github"                  # Required: unique identifier
command = "npx"                  # Required: executable to launch
args = ["-y", "@modelcontextprotocol/server-github"]  # Optional: command arguments
env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }             # Optional: env vars (${VAR} expansion)
```

### Using `--config`

All commands default to layered config (global + local). To use a specific config file instead:

```bash
mcpfind serve --config /path/to/mcpfind.toml
mcpfind list-tools --config /path/to/mcpfind.toml
mcpfind search "query" --config /path/to/mcpfind.toml
```

## CLI Reference

| Command | Description |
|---------|-------------|
| `mcpfind setup` | Interactive wizard — configure global config |
| `mcpfind init` | Create project-local `mcpfind.toml` |
| `mcpfind install <client>` | Register mcpfind with an MCP client (`claude-code`, `cursor`, `claude-desktop`) |
| `mcpfind serve` | Start the proxy server (stdio MCP transport) |
| `mcpfind list-tools` | List all discovered tools from backend servers |
| `mcpfind search "<query>"` | Test semantic search against discovered tools |

## Development

```bash
# Clone and install
git clone https://github.com/jcgs2503/mcpfind.git
cd mcpfind
uv sync

# Run tests
uv run pytest -v

# Lint and format
uv run ruff check .
uv run ruff format --check .
```
