mcp-tool-search 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaleb Teeter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,215 @@
+# MCP Tool Search
+
+[![npm version](https://img.shields.io/npm/v/mcp-tool-search.svg)](https://www.npmjs.com/package/mcp-tool-search)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node.js 20+](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
+[![Tests](https://img.shields.io/badge/tests-36%2F36-brightgreen.svg)](src/__tests__)
+
+**Reduce MCP tool-definition context overhead by ~85–96%.**
+
+MCP Tool Search is a proxy server that replaces dozens of MCP tool schemas in your model's context window with just 4 lightweight tools. Instead of loading every tool definition upfront, the model searches for tools on-demand and calls them through the proxy.
+
+```
+Before: 50 tool schemas loaded → ~10,000 context tokens consumed every turn
+After:  4 proxy tools loaded   →    ~600 context tokens (constant)
+```
+
+## Problem
+
+Every MCP server you add dumps its full tool schemas into the model's context window. With 5+ servers and 40+ tools, that's **8,000–20,000+ tokens** of schema definitions the model must process on every single turn — even when it doesn't use any of them.
+
+## Solution
+
+MCP Tool Search sits between your MCP client and your backend servers:
+
+1. **Catalog Builder** pre-scans all your MCP servers and snapshots their tool definitions to a local JSON file
+2. **Proxy Server** exposes only 4 tools — the model searches, inspects, and calls tools through the proxy
+3. **Lazy Connections** — backend servers are spawned on first use and kept alive for 5 minutes
+
+```
+MCP Client ←→ MCP Tool Search Proxy ←→ Backend MCP Servers
+                     ↓                    (lazily spawned)
+               catalog.json             Context7, GitHub, etc.
+               (pre-built snapshot)
+```
+
+## The 4 Proxy Tools
+
+| Tool | Purpose |
+|------|---------|
+| `search_tools` | Fuzzy-search across all backend tools by keyword or capability |
+| `get_tool_schema` | Retrieve the full input schema for a specific tool |
+| `call_tool` | Execute a tool on its backend server through the proxy |
+| `list_servers` | List all cataloged servers and their connection status |
+
+## Quick Start
+
+```bash
+npx mcp-tool-search --help
+# Or: npm install -g mcp-tool-search && mcp-build-catalog && mcp-tool-search
+```
+
+## Installation
+
+### Option A: npm (recommended)
+
+```bash
+npm install -g mcp-tool-search
+```
+
+### Option B: From source
+
+```bash
+git clone https://github.com/kteeter0405/mcp-tool-search.git
+cd mcp-tool-search
+npm install
+npm run build
+```
+
+## Setup
+
+### 1. Configure backend servers
+
+MCP Tool Search reads your MCP client's server configuration to discover backend tools. It uses the same `.mcp.json` format as Claude Code.
+
+### 2. Build the tool catalog
+
+```bash
+# If installed globally:
+mcp-build-catalog
+
+# If from source:
+npm run catalog
+```
+
+This connects to each configured MCP server, snapshots their tool definitions, and writes `catalog.json`. The proxy itself is automatically excluded from the catalog.
+
+### 3. Add the proxy to your MCP client
+
+Add to your `.mcp.json` (or equivalent config):
+
+```json
+{
+  "mcpServers": {
+    "mcp-tool-search": {
+      "command": "npx",
+      "args": ["-y", "mcp-tool-search"]
+    }
+  }
+}
+```
+
+Or if installed from source:
+
+```json
+{
+  "mcpServers": {
+    "mcp-tool-search": {
+      "command": "node",
+      "args": ["/path/to/mcp-tool-search/dist/index.js"]
+    }
+  }
+}
+```
+
+### 4. Disable direct backend servers
+
+Remove or disable your other MCP server entries in `.mcp.json` — the proxy handles all tool calls to them now.
+
+## Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `MCP_TOOL_SEARCH_CATALOG` | `./catalog.json` | Path to the catalog file |
+| `MCP_TOOL_SEARCH_METRICS` | *(none)* | Path to write JSON metrics (for monitoring dashboards) |
+
+## Token Savings
+
+The proxy's token footprint is **constant** — 4 tools regardless of how many backend servers exist.
+
+| Backend Tools | Direct Tokens | Proxy Tokens | Savings |
+|---|---|---|---|
+| 10 | ~2,000 | ~600 | 70% |
+| 25 | ~5,000 | ~600 | 88% |
+| 50 | ~10,000 | ~600 | 94% |
+| 100 | ~20,000 | ~600 | 97% |
+| 200 | ~40,000 | ~600 | 99% |
+
+See [BENCHMARKS.md](BENCHMARKS.md) for detailed methodology and measurements.
+
+## Security
+
+MCP Tool Search uses an **allowlist-based environment filter** when spawning backend servers. Only explicitly safe environment variables (PATH, HOME, NODE_PATH, etc.) are forwarded to child processes. API keys, tokens, and secrets from your shell environment are **never** leaked to backend servers unless explicitly configured in the catalog's per-server `env` block.
+
+Additional security measures:
+
+- **Connection cap**: Max 20 concurrent server connections (oldest idle connection evicted when limit reached)
+- **Connect timeout**: 15-second timeout on server spawn
+- **Idle cleanup**: Connections auto-close after 5 minutes of inactivity
+- **No shell execution**: Server commands passed as arrays to `child_process.spawn()`, never through shell interpretation
+- **TypeScript strict mode**: Full type safety with no `any` casts in core logic
+- **Minimal dependencies**: Only 2 runtime deps (`@modelcontextprotocol/sdk`, `zod`)
+
+> **Note:** `catalog.json` stores per-server env vars from your MCP config (including API tokens that backend servers need to function). Treat this file as sensitive — it is excluded from git (`.gitignore`) and npm publishing (`.npmignore` + `"files"` allowlist) by default. Do not share or commit it.
+
+## Trade-offs
+
+- **Latency**: Each tool call requires a search + schema lookup step (~2 extra LLM turns for first use of a tool)
+- **Discovery**: The model must search for tools instead of seeing them all upfront — minor overhead for small catalogs
+- **Connection startup**: Servers are lazily spawned, so first calls to a new server have connection overhead
+
+### When to use the proxy
+
+- **Use it** when you have 5+ MCP servers or 20+ total tools
+- **Skip it** when you have 1–2 servers with few tools
+
+## Compatibility
+
+Tested with:
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (primary target)
+- [Claude Desktop](https://claude.ai/download)
+- [Cursor](https://cursor.sh/)
+- [Windsurf](https://codeium.com/windsurf)
+
+Should work with any MCP client that supports the stdio transport.
+
+## Project Structure
+
+```
+mcp-tool-search/
+├── src/
+│   ├── types.ts          # Shared type definitions
+│   ├── catalog.ts        # Catalog loader + fuzzy search engine
+│   ├── pool.ts           # Lazy server connection pool with timeouts
+│   ├── index.ts          # Main proxy MCP server
+│   └── build-catalog.ts  # Catalog builder CLI
+├── dist/                 # Compiled JavaScript (after build)
+├── catalog.json          # Generated tool catalog (git-ignored)
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Run tests
+npm test
+
+# Watch mode
+npm run dev
+
+# Rebuild catalog
+npm run catalog
+```
+
+## License
+
+[MIT](LICENSE) — Copyright (c) 2026 Kaleb Teeter

package/dist/build-catalog.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * MCP Tool Search — Catalog Builder
+ *
+ * Connects to each MCP server defined in Claude Code's settings,
+ * discovers all available tools, and saves them to catalog.json.
+ *
+ * Usage: npm run catalog
+ *
+ * The catalog is a snapshot — rebuild it when you add/remove MCP servers.
+ */
+export {};
+//# sourceMappingURL=build-catalog.d.ts.map

package/dist/build-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-catalog.d.ts","sourceRoot":"","sources":["../src/build-catalog.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG"}

package/dist/build-catalog.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * MCP Tool Search — Catalog Builder
+ *
+ * Connects to each MCP server defined in Claude Code's settings,
+ * discovers all available tools, and saves them to catalog.json.
+ *
+ * Usage: npm run catalog
+ *
+ * The catalog is a snapshot — rebuild it when you add/remove MCP servers.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolveCommand, buildSafeEnv } from "./utils.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const OUTPUT_PATH = resolve(__dirname, "..", "catalog.json");
+// Timeout for connecting to each server (ms)
+const CONNECT_TIMEOUT = 15_000;
+/** Find and load MCP server configs from Claude settings */
+async function loadMcpConfigs() {
+    // Check multiple possible config locations
+    const candidates = [
+        // Claude Code project-level
+        resolve(process.cwd(), ".mcp.json"),
+        // Claude Code user-level
+        resolve(homedir(), ".claude", "settings.json"),
+        // Claude Desktop
+        resolve(homedir(), "AppData", "Roaming", "Claude", "claude_desktop_config.json"),
+        // macOS Claude Desktop
+        resolve(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json"),
+    ];
+    const allConfigs = {};
+    for (const path of candidates) {
+        if (!existsSync(path))
+            continue;
+        try {
+            const raw = JSON.parse(await readFile(path, "utf-8"));
+            // .mcp.json format: { "mcpServers": { ... } }
+            // settings.json format: { "mcpServers": { ... } }
+            // claude_desktop_config.json format: { "mcpServers": { ... } }
+            const servers = raw.mcpServers || raw.MCP_SERVERS || {};
+            for (const [name, config] of Object.entries(servers)) {
+                // Fix 1: Skip disabled servers
+                if (config.disabled === true) {
+                    process.stderr.write(`  Skipped: ${name} (disabled)\n`);
+                    continue;
+                }
+                if (!allConfigs[name]) {
+                    allConfigs[name] = config;
+                    process.stderr.write(`  Found: ${name} (from ${path})\n`);
+                }
+            }
+        }
+        catch (err) {
+            process.stderr.write(`  Warning: Could not parse ${path}: ${err}\n`);
+        }
+    }
+    return allConfigs;
+}
+/** Connect to a server and discover its tools */
+async function discoverTools(name, config) {
+    const transport = new StdioClientTransport({
+        command: resolveCommand(config.command),
+        args: config.args || [],
+        env: buildSafeEnv(config.env),
+    });
+    const client = new Client({ name: "mcp-catalog-builder", version: "2.0.0" }, { capabilities: {} });
+    try {
+        // Connect with timeout
+        await Promise.race([
+            client.connect(transport),
+            new Promise((_, reject) => setTimeout(() => reject(new Error("Connection timeout")), CONNECT_TIMEOUT)),
+        ]);
+        // List all tools
+        const response = await client.listTools();
+        const tools = (response.tools || []).map((t) => ({
+            name: t.name,
+            description: t.description || "",
+            inputSchema: t.inputSchema || {},
+        }));
+        await client.close();
+        return {
+            command: config.command,
+            args: config.args || [],
+            env: config.env,
+            tools,
+        };
+    }
+    catch (err) {
+        process.stderr.write(`  ✗ ${name}: ${err.message}\n`);
+        try {
+            await client.close();
+        }
+        catch {
+            // Ignore
+        }
+        return null;
+    }
+}
+async function main() {
+    process.stderr.write("╔══════════════════════════════════════╗\n");
+    process.stderr.write("║  MCP Tool Search — Catalog Builder   ║\n");
+    process.stderr.write("╚══════════════════════════════════════╝\n\n");
+    // Step 1: Find MCP server configs
+    process.stderr.write("[1/3] Scanning for MCP server configurations...\n");
+    const configs = await loadMcpConfigs();
+    const serverNames = Object.keys(configs);
+    if (serverNames.length === 0) {
+        process.stderr.write("\nNo MCP servers found. Make sure you have:\n" +
+            "  - .mcp.json in your project root, OR\n" +
+            "  - ~/.claude/settings.json with mcpServers, OR\n" +
+            "  - Claude Desktop config with mcpServers\n");
+        process.exit(1);
+    }
+    // Fix 3: Parse --only and --skip CLI flags to filter servers
+    const onlyArg = process.argv.find((a) => a.startsWith("--only="));
+    const skipArg = process.argv.find((a) => a.startsWith("--skip="));
+    if (onlyArg && skipArg) {
+        process.stderr.write("\nError: Cannot use --only and --skip together. Pick one.\n");
+        process.exit(1);
+    }
+    // Self-skip: never try to spawn ourselves during catalog build
+    let filteredNames = serverNames.filter((n) => n !== "mcp-tool-search");
+    if (onlyArg) {
+        const onlySet = new Set(onlyArg.replace("--only=", "").split(",").map((s) => s.trim()));
+        filteredNames = filteredNames.filter((n) => onlySet.has(n));
+        process.stderr.write(`  --only filter: ${filteredNames.length}/${serverNames.length} servers selected\n`);
+    }
+    if (skipArg) {
+        const skipSet = new Set(skipArg.replace("--skip=", "").split(",").map((s) => s.trim()));
+        filteredNames = filteredNames.filter((n) => !skipSet.has(n));
+        process.stderr.write(`  --skip filter: ${filteredNames.length}/${serverNames.length} servers selected\n`);
+    }
+    process.stderr.write(`\nFound ${filteredNames.length} servers.\n\n`);
+    // Step 2: Connect and discover tools
+    process.stderr.write("[2/3] Discovering tools from each server...\n");
+    const catalog = {
+        version: "2.0.0",
+        generated: new Date().toISOString(),
+        servers: {},
+    };
+    let totalTools = 0;
+    let failedServers = 0;
+    // Parallel discovery — all servers spawn simultaneously
+    const discoveryResults = await Promise.allSettled(filteredNames.map(async (name) => {
+        process.stderr.write(`  → ${name}...\n`);
+        const server = await discoverTools(name, configs[name]);
+        return { name, server };
+    }));
+    for (const result of discoveryResults) {
+        if (result.status === "fulfilled" && result.value.server) {
+            catalog.servers[result.value.name] = result.value.server;
+            totalTools += result.value.server.tools.length;
+            process.stderr.write(`  ✓ ${result.value.name}: ${result.value.server.tools.length} tools\n`);
+        }
+        else if (result.status === "rejected") {
+            failedServers++;
+            process.stderr.write(`  ✗ ${result.reason}\n`);
+        }
+        else if (result.status === "fulfilled" && !result.value.server) {
+            failedServers++;
+        }
+    }
+    // Step 3: Save catalog
+    process.stderr.write(`\n[3/3] Saving catalog to ${OUTPUT_PATH}...\n`);
+    await writeFile(OUTPUT_PATH, JSON.stringify(catalog, null, 2), "utf-8");
+    process.stderr.write("\n══════════════════════════════════════\n");
+    process.stderr.write(`  Catalog built: ${Object.keys(catalog.servers).length} servers, ${totalTools} tools\n`);
+    if (failedServers > 0) {
+        process.stderr.write(`  ⚠ ${failedServers} server(s) failed to connect\n`);
+    }
+    process.stderr.write("══════════════════════════════════════\n");
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal: ${err}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=build-catalog.js.map

package/dist/build-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-catalog.js","sourceRoot":"","sources":["../src/build-catalog.ts"],"names":[],"mappings":"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"}

package/dist/catalog.d.ts

@@ -0,0 +1,39 @@
+/**
+ * MCP Tool Search — Catalog Manager
+ *
+ * Loads the tool catalog (catalog.json) and provides fuzzy search.
+ * The catalog is pre-built by build-catalog.ts which connects to
+ * each backend MCP server and snapshots its tool definitions.
+ */
+import type { CatalogData, CatalogServer, SearchResult } from "./types.js";
+export declare class Catalog {
+    private readonly path;
+    private data;
+    private searchIndex;
+    constructor(path: string);
+    /** Load catalog from disk */
+    load(): Promise<void>;
+    /** Load catalog from data directly (for testing without filesystem) */
+    loadFromData(data: CatalogData): void;
+    /** Validate catalog shape to prevent cryptic runtime crashes */
+    private validateCatalog;
+    /** Build search index from catalog data */
+    private buildIndex;
+    /** Tokenize a string for fuzzy matching — splits on spaces, underscores, and hyphens */
+    private tokenize;
+    /** Fuzzy search across all tools */
+    search(query: string, maxResults?: number): SearchResult[];
+    /** Get a specific server's config */
+    getServer(name: string): CatalogServer | undefined;
+    /** Get a specific tool's full schema */
+    getToolSchema(serverName: string, toolName: string): Record<string, unknown> | undefined;
+    /** Total number of servers in catalog */
+    get totalServers(): number;
+    /** Total number of tools across all servers */
+    get totalTools(): number;
+    /** List all server names */
+    get serverNames(): string[];
+    /** Get tool count per server */
+    serverToolCounts(): Record<string, number>;
+}
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAsC3E,qBAAa,OAAO;IASN,OAAO,CAAC,QAAQ,CAAC,IAAI;IARjC,OAAO,CAAC,IAAI,CAA4B;IACxC,OAAO,CAAC,WAAW,CAKX;gBAEqB,IAAI,EAAE,MAAM;IAEzC,6BAA6B;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B,uEAAuE;IACvE,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAMrC,gEAAgE;IAChE,OAAO,CAAC,eAAe;IAwBvB,2CAA2C;IAC3C,OAAO,CAAC,UAAU;IAmBlB,wFAAwF;IACxF,OAAO,CAAC,QAAQ;IAQhB,oCAAoC;IACpC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,GAAE,MAAW,GAAG,YAAY,EAAE;IAkE9D,qCAAqC;IACrC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAIlD,wCAAwC;IACxC,aAAa,CACX,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAOtC,yCAAyC;IACzC,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,+CAA+C;IAC/C,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,4BAA4B;IAC5B,IAAI,WAAW,IAAI,MAAM,EAAE,CAE1B;IAED,gCAAgC;IAChC,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAQ3C"}