{
  "markdown": "# agent-discover\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20.11-brightgreen)](https://nodejs.org/)\n[![Tests](https://img.shields.io/badge/tests-209%20passing-brightgreen)]()\n[![MCP Tools](https://img.shields.io/badge/MCP%20tools-1-purple)]()\n[![Registry Actions](https://img.shields.io/badge/registry%20actions-11-blueviolet)]()\n[![REST Endpoints](https://img.shields.io/badge/REST-33%20endpoints-orange)]()\n\n**MCP server registry and marketplace.** Discover, install, activate, and manage MCP tools on demand. Acts as a dynamic proxy -- activated servers have their tools merged into the registry's own tool list, so agents can use them without restarting.\n\n> **Every MCP client today — Claude Code, Cursor, Codex CLI, Aider, Continue, plain MCP clients — requires a full agent-session restart to pick up a newly registered MCP server.** The tool catalog is frozen at startup. agent-discover is the only path to register a new server and have it become discoverable in the same running session. This is the one differentiator that survives against every host, even those with their own built-in deferred-tool loaders.\n\nSearch spans the **official MCP registry**, **npm**, and **PyPI** in one query, so popular servers that aren't in the official index (Microsoft `@playwright/mcp`, `@modelcontextprotocol/server-*`, `mcp-server-fetch`, `mcp-server-git`, …) all show up.\n\nBuilt for AI coding agents (Claude Code, Codex CLI, Gemini CLI, Aider) but works equally well with any MCP client, REST consumer, or WebSocket listener.\n\n---\n\n| Light Theme                                | Dark Theme                               |\n| ------------------------------------------ | ---------------------------------------- |\n| ![Light Theme](docs/screenshots/light.png) | ![Dark Theme](docs/screenshots/dark.png) |\n\n---\n\n## Why\n\nStatic MCP configs mean every server is always running, even when unused. Adding a new server requires editing config files and restarting. There is no way to browse what is available or install new tools at runtime.\n\n|                  | Without agent-discover            | With agent-discover                                        |\n| ---------------- | --------------------------------- | ---------------------------------------------------------- |\n| **Discovery**    | Must know server names in advance | Browse the official MCP registry, search by keyword        |\n| **Installation** | Edit config files, restart agent  | One tool call installs and registers                       |\n| **Activation**   | All servers always running        | Activate/deactivate on demand, tools appear/disappear live |\n| **Secrets**      | API keys in config files or env   | Per-server secret storage, auto-injected on activation     |\n| **Monitoring**   | No visibility into server health  | Health checks, per-tool metrics, error counts              |\n| **Management**   | Manual config edits               | Dashboard + REST API for config, tags                      |\n\n---\n\n## Features\n\n- **Single-call tool discovery (`find_tool`)** — hybrid BM25 + semantic ranking returns the top match with a confidence label, compact `required_args`, and 4 ranked alternatives. Auto-activates the owning child server so the agent can call the proxied tool immediately on the next turn. Replaces the multi-step `search → list → activate` dance with one round-trip.\n- **Batch discovery (`find_tools`)** — pass an array of intents to discover N tools in a single round-trip for multi-step tasks.\n- **Indirect invocation (`proxy_call`)** — call a discovered tool **through** agent-discover without exposing it to the host catalog. Keeps the host MCP surface at exactly 5 actions regardless of how many tools the registered child servers expose — critical for very large catalogs where flooding the host with thousands of schemas would blow the model's context budget.\n- **Pluggable embeddings (`AGENT_DISCOVER_EMBEDDING_PROVIDER`)** — semantic search is opt-in via `none` (default, BM25 only) / `local` (Xenova/all-MiniLM-L6-v2 via `@huggingface/transformers`) / `openai` (`text-embedding-3-small`). Provider failures fall back to BM25 cleanly. Mirrors agent-knowledge's pattern so the same model can be reused.\n- **`did_you_mean` recovery** — when a proxied tool call fails, the proxy attaches BM25-ranked similar-tool suggestions to the error response so the agent can correct in one extra turn instead of giving up.\n- **Local registry** -- register MCP servers in a SQLite database with name, command, args, env, tags\n- **Federated marketplace search** -- a single query hits the official MCP registry, npm, and PyPI in parallel, dedupes by `<source>:<name>`, and collapses version duplicates\n- **PyPI integration** -- curated list of well-known Python MCP servers (`mcp-server-fetch`, `mcp-server-git`, `mcp-server-time`, `mcp-server-postgres`, `mcp-server-sqlite`, `mcp-proxy`, …) plus live metadata via the PyPI JSON API; Python entries install via `uvx`\n- **npm fallback** -- two parallel npm searches (`keywords:mcp` and `<query> mcp`) catch packages that didn't tag themselves (e.g. Microsoft `@playwright/mcp`)\n- **Prereqs probe** -- `GET /api/prereqs` reports which package managers (`npx`, `uvx`, `docker`, `uv`) are available on the host; the dashboard surfaces a banner when something needed for an install is missing\n- **Cross-process activation** -- the `active` flag is the source of truth in SQLite; every fresh agent-discover process hydrates its in-memory proxy from the DB on startup, so tools activated in one process show up in others\n- **On-demand activation** -- activate/deactivate servers at runtime; their tools appear and disappear dynamically with `tools/list_changed` notifications\n- **Tool proxying** -- activated server tools are namespaced as `serverName__toolName` and merged into the tool list\n- **Multi-transport** -- stdio, SSE, and streamable-http transports for connecting to child servers\n- **Secret management** -- store API keys and tokens per server, automatically injected as env vars (stdio) or HTTP headers (SSE/streamable-http) on activation; CRLF-validated to prevent header injection\n- **Health checks** -- connect/disconnect probes for inactive servers, tool-list checks for active ones, with error count tracking\n- **Per-tool metrics** -- call counts, error counts, and average latency recorded automatically on every proxied tool call\n- **Full-text search** -- FTS5 search across server names, descriptions, and tags + cross-server tool index for `find_tool`\n- **Pre-download** -- fire-and-forget `npm cache add` (npx servers) or `uv tool install` (uvx servers) on registration, plus a dedicated `/preinstall` endpoint\n- **Real-time dashboard** -- web UI at http://localhost:3424 with Servers and Browse tabs, dark/light theme, WebSocket updates\n- **MCP Inspector-grade Test panel** -- every active server card grows a Test drawer with seven subtabs (Tools / Info / Resources / Prompts / Events / Export / Diagnostics). Schema-driven form renderer, Pretty/Raw JSON/cURL result modes, live notification + progress streaming, localStorage presets, pop-out floating panel for side-by-side debugging, and a `Test ad-hoc` button that spins up a throwaway (never-registered) server with a 15-minute TTL. Covers the same surface as upstream `@modelcontextprotocol/inspector` without a second process or second port.\n- **3 transport layers** -- MCP (stdio), REST API (HTTP), WebSocket (real-time events)\n- **Declarative setup file** -- set `AGENT_DISCOVER_SETUP_FILE` to a JSON file listing servers to ensure-registered on startup. Idempotent (skips existing). Supports `auto_activate`, env var secret refs (`$VAR`), and tags. Automatically also reads a `.local.json` variant (e.g. `discover-setup.local.json`) for machine-specific servers with secrets. New `registry({ action: \"sync\" })` MCP action and `POST /api/sync` REST endpoint for on-demand re-read.\n- **Bench harness** -- under `bench/`, comparing eager tool loading vs deferred discovery against real OpenCode + gpt-5-mini. Reproducible structural result: discover's first-turn input tokens are flat in N (~20.8k across N ∈ {10, 100, 1000, 3000}); eager's grow linearly (20.9k → 32.4k → 160.9k → context overflow at N=3000). End-to-end accuracy and multi-turn cost numbers are noisier and model-dependent — see [`bench/README.md`](bench/README.md) for what reproduces and what doesn't.\n\n---\n\n## Quick Start\n\n### Install from npm\n\n```bash\nnpm install -g agent-discover\n```\n\n### Or run directly with npx\n\n```bash\nnpx agent-discover\n```\n\n### Or clone from source\n\n```bash\ngit clone https://github.com/keshrath/agent-discover.git\ncd agent-discover\nnpm install\nnpm run build\n```\n\n### Option 1: MCP server (for AI agents)\n\nAdd to your MCP client config (Claude Code, Cline, Cursor, Windsurf, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-discover\": {\n      \"command\": \"npx\",\n      \"args\": [\"agent-discover\"]\n    }\n  }\n}\n```\n\nThe dashboard auto-starts at http://localhost:3424 on the first MCP connection.\n\n### Option 2: Standalone server (for REST/WebSocket clients)\n\n```bash\nnode dist/server.js --port 3424\n```\n\n---\n\n## MCP Tools (1)\n\nA single action-based tool handles every operation via the `action` parameter — this keeps the prompt-overhead cost minimal regardless of how many child servers are registered.\n\n| Action       | Purpose                                                                                                                                                               |\n| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `find_tool`  | **Single-call discovery.** Hybrid BM25 + semantic search → top match + confidence label + compact `required_args` + 4 alternatives. Auto-activates the owning server. |\n| `find_tools` | **Batch discovery.** Pass `intents: [...]` to discover N tools in one round-trip. Use for multi-step tasks.                                                           |\n| `get_schema` | Full `input_schema` for a discovered tool. Only needed when the compact `required_args` summary isn't enough (conditional / polymorphic args).                        |\n| `proxy_call` | Invoke a discovered tool **through** agent-discover without exposing it to the host catalog. Pair with `find_tool({auto_activate: false})` for huge catalogs.         |\n| `list`       | Search the local registry by server (FTS5).                                                                                                                           |\n| `install`    | Add a server from the marketplace or via manual config (command + args + env).                                                                                        |\n| `uninstall`  | Remove a server.                                                                                                                                                      |\n| `activate`   | Start a server, discover its tools, expose them to the host as `serverName__toolName`.                                                                                |\n| `deactivate` | Stop a server, hide its tools.                                                                                                                                        |\n| `browse`     | Federated search across the official MCP registry, npm, and PyPI.                                                                                                     |\n| `status`     | Active servers summary (names, tool counts, tool lists).                                                                                                              |\n\nActivated servers expose their tools through agent-discover, namespaced as `serverName__toolName`. For example, activating a server named `filesystem` that exposes `read_file` makes it available as `filesystem__read_file`.\n\nWhen `find_tool` is called with `auto_activate: false` (recommended for catalogs above ~1k tools), the proxy connection is opened silently and tools must be invoked via `proxy_call` instead of being added to the host's catalog. This keeps the host MCP surface area constant regardless of how many tools the registered child servers expose.\n\n---\n\n## REST API (33 endpoints)\n\nAll endpoints return JSON. CORS enabled.\n\n```\nGET    /health                            Version, uptime\nGET    /api/prereqs                       Probe host for npx/uvx/docker/uv availability\nGET    /api/servers                       List servers (?query=, ?source=, ?installed=)\nGET    /api/servers/:id                   Server details + tools\nPOST   /api/servers                       Register new server\nPUT    /api/servers/:id                   Update server config (description, command, args, env, tags)\nDELETE /api/servers/:id                   Unregister (deactivates first if active)\nPOST   /api/servers/:id/activate          Activate -- start server, discover tools, begin proxying\nPOST   /api/servers/:id/deactivate        Deactivate -- stop server, remove tools\nPOST   /api/servers/:id/preinstall        Pre-download package (npm cache add for npx, uv tool install for uvx)\nGET    /api/servers/:id/secrets           List secrets (masked values)\nPUT    /api/servers/:id/secrets/:key      Set a secret (upsert)\nDELETE /api/servers/:id/secrets/:key      Delete a secret\nPOST   /api/servers/:id/health            Run health check (connect/disconnect probe)\nGET    /api/servers/:id/metrics           Per-tool metrics for a server (call count, errors, latency)\nGET    /api/metrics                       Metrics overview across all servers\nGET    /api/browse                        Federated search: official registry + npm + PyPI (?query=, ?limit=, ?cursor=)\nGET    /api/npm-check                     Check if an npm package exists (?package=)\nGET    /api/status                        Active servers summary (names, tool counts, tool lists)\n\nTester surface (MCP Inspector parity — localhost-only unless AGENT_DISCOVER_ALLOW_REMOTE_TEST=1):\nGET    /api/servers/:id/info               Server name, version, capabilities, instructions\nGET    /api/servers/:id/tools               Live tools (bypasses activation cache)\nPOST   /api/servers/:id/call                Call a tool\nGET    /api/servers/:id/resources           List resources (?cursor=...)\nGET    /api/servers/:id/resource-templates  List resource templates\nPOST   /api/servers/:id/resource/read       Read a resource\nPOST   /api/servers/:id/resource/subscribe  Subscribe to resource updates\nPOST   /api/servers/:id/resource/unsubscribe  Unsubscribe\nGET    /api/servers/:id/prompts             List prompts (?cursor=...)\nPOST   /api/servers/:id/prompt/get          Get a prompt with args\nPOST   /api/servers/:id/ping                Ping — returns { ok, rtt_ms }\nPOST   /api/servers/:id/logging-level       Set server logging level\nGET    /api/servers/:id/export              Export config (?format=mcp-json|claude-code|cursor|agent-discover)\nPOST   /api/transient                        Activate an ad-hoc server (returns { handle, ... })\nDELETE /api/transient/:handle                Release transient server\nGET    /api/transient/:handle/*              Same tester surface, keyed by handle\nGET    /api/roots                            Configured client roots (AGENT_DISCOVER_ROOTS)\nGET    /api/logs/notifications               Notification log entries\nGET    /api/logs/progress                    Progress log entries\n```\n\n---\n\n## Dashboard\n\nThe web dashboard auto-starts at **http://localhost:3424** and provides two views:\n\n**Servers tab** -- all registered servers as cards showing health dots, error counts, active/inactive status, description, tags, tools list, and expandable Secrets/Metrics/Config sections. Action buttons for activate, deactivate, health check, and delete.\n\n**Browse tab** -- federated search across the official MCP registry, npm, and PyPI. Each card shows the runtime tag (`node`, `python`, `streamable-http`, …), version, description, and an install button that picks the right command (`npx`, `uvx`, or remote URL) automatically. A prereq banner at the top of the tab warns when a required package manager (`npx`, `uvx`, `docker`) is missing on the host.\n\nReal-time updates via WebSocket with 2-second database polling. Dark and light themes with persistent preference.\n\n---\n\n## Testing\n\n```bash\nnpm test              # 179 tests across 12 files\nnpm run test:watch    # Watch mode\nnpm run test:coverage # Coverage report\nnpm run check         # Full CI: typecheck + lint + format + test\nnpm run test:e2e:ui   # Playwright dashboard smoke tests\n```\n\n---\n\n## Environment Variables\n\n### Core\n\n| Variable                           | Default                       | Description                                                                                                 |\n| ---------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------- |\n| `AGENT_DISCOVER_PORT`              | `3424`                        | Dashboard HTTP port                                                                                         |\n| `AGENT_DISCOVER_DB`                | `~/.claude/agent-discover.db` | SQLite database path                                                                                        |\n| `AGENT_DISCOVER_ROOTS`             | —                             | Comma-separated root URIs advertised to child servers (e.g. `file:///Users/me/repo,file:///Users/me/data`)  |\n| `AGENT_DISCOVER_ALLOW_REMOTE_TEST` | `0`                           | Set to `1` to allow the Test panel endpoints from non-loopback origins. **Not recommended** — see Security. |\n\n### Embeddings (semantic search for `find_tool`)\n\nEmbeddings are **opt-in**. The default is `none`, which means `find_tool` ranks by BM25 + verb synonyms only. Setting a provider enables hybrid BM25 + cosine retrieval, which closes the natural-language gap (e.g. \"billing arrangement\" → \"subscription\") that BM25 alone misses.\n\n| Variable                                | Default | Description                                                             |\n| --------------------------------------- | ------- | ----------------------------------------------------------------------- |\n| `AGENT_DISCOVER_EMBEDDING_PROVIDER`     | `none`  | `none` \\| `local` \\| `openai`                                           |\n| `AGENT_DISCOVER_EMBEDDING_MODEL`        | —       | Override the default model id for the chosen provider                   |\n| `AGENT_DISCOVER_EMBEDDING_THREADS`      | `1`     | Local provider only — onnx runtime thread count                         |\n| `AGENT_DISCOVER_EMBEDDING_IDLE_TIMEOUT` | `60`    | Local provider only — seconds before unloading the model from RAM       |\n| `AGENT_DISCOVER_OPENAI_API_KEY`         | —       | OpenAI API key for embeddings (falls back to `OPENAI_API_KEY` if unset) |\n\n**Local provider** uses `Xenova/all-MiniLM-L6-v2` (384 dims) via `@huggingface/transformers`. Install the optional peer dependency with `npm install @huggingface/transformers` if you want to use it. No network calls, no API key.\n\n**OpenAI provider** uses `text-embedding-3-small` (1536 dims). Same model as agent-knowledge so the two servers can share an embedding key.\n\n### Host package manager prerequisites\n\nagent-discover spawns child MCP servers via the host's installed package managers. Install whatever you intend to use; missing tools are reported by `GET /api/prereqs` and surfaced as a banner in the Browse tab.\n\n| Tool     | Used for                        | Install hint                                          |\n| -------- | ------------------------------- | ----------------------------------------------------- |\n| `npx`    | npm-published MCP servers       | ships with [Node.js](https://nodejs.org/)             |\n| `uvx`    | PyPI-published MCP servers      | install [uv](https://docs.astral.sh/uv/)              |\n| `docker` | Docker-image MCP servers (rare) | install [Docker](https://docs.docker.com/get-docker/) |\n\n---\n\n## Documentation\n\n- [User Manual](docs/USER-MANUAL.md) -- comprehensive guide covering all tools, REST API, dashboard, and troubleshooting\n- [API Reference](docs/API.md) -- all MCP tools and REST endpoints\n- [Architecture](docs/ARCHITECTURE.md) -- source structure, design principles, database schema\n- [Dashboard](docs/DASHBOARD.md) -- web UI views and features\n- [Setup Guide](docs/SETUP.md) -- installation, client setup (Claude Code, Cursor, Windsurf)\n- [Changelog](CHANGELOG.md)\n\n---\n\n## License\n\nMIT -- see [LICENSE](LICENSE)\n",
  "bytes": 20771,
  "sha": "7022e6ca06ffe4e5d6723b260cf4c3cbf43175a1f33966a101ffd2a83519f998",
  "repo_slug": "keshrath/agent-discover",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_keshrath_agent_discover_63217582/readme"
}