agent-discover

agent-discover

在任何 MCP 宿主中，于会话期间查找、安装并启用 MCP 服务。 agent-discover 是一个本地守护进程，可搜索官方 MCP Registry、npm 和 PyPI；你批准确切的命令及其来源后，它会安装服务，并将其工具提供给宿主，无需修改配置或重启。它还会保护安装过程：固定工具定义，并隔离工具发生变化的服务；机密信息存储在操作系统密钥链中，且每项操作都会经过审计。

---

为什么需要它

当前的宿主（Claude Code、Codex、Anthropic 和 OpenAI API）都有自己的工具搜索功能，因此 agent-discover 现在的主要目的已不再是节省提示词令牌。宿主的工具搜索无法处理尚未安装的服务。添加新的 MCP 服务仍然需要编辑宿主配置并重启会话。agent-discover 消除了这一步：

• 发现。 一次查询即可搜索已安装服务的工具索引和公共注册表（官方 MCP Registry 的本地镜像，以及 npm 和 PyPI）。
• 经同意后安装。 install_server 会显示确切的命令或 URL、环境变量和标头名称、固定版本以及来源检查（注册表命名空间、npm mcpName、PyPI、OCI 标签）。只有你接受后才会运行。
• 运行时启用和禁用，包括一分钟前才安装的服务。启用时会在需要的情况下先为服务编制索引。
• 接入宿主自身的工具搜索。 在 native 模式（默认）下，每个已启用服务的工具都会以 <server>__<tool> 的形式列出；每次发生变化时，agent-discover 都会发送 notifications/tools/list_changed，因此宿主原生的工具搜索、权限提示和 alwaysLoad 设置仍可正常使用。在 proxy 模式下，只会列出八个元工具，所有操作都通过 call_tool 进行，适用于工具搜索功能较弱或不具备该功能的宿主。
• 保持掌控。 请参阅信任层。

	静态 MCP 配置	使用 agent-discover
发现	提前知道服务名称	按需搜索注册表，并查看来源信息
安装	编辑配置，重启会话	调用一次工具，由你批准确切的命令
启用	所有已配置的服务始终加载	在会话期间启用和禁用；索引仍可搜索
机密信息	密钥存储在配置文件或环境变量中	存储在操作系统密钥链（或加密文件）中，并在连接时注入
工具变更	无提示	固定哈希；发生漂移时会隔离服务，直到你批准
可见性	各宿主的日志	/discover 面板、运行状况、各工具指标、审计日志、OTel

---

快速开始

Claude Code

安装该插件。它会将 stdio shim 作为 MCP 服务运行，添加 find 和 install 技能，以及带管理界面的 Claude Code mod（函数钩子）：

claude plugin marketplace add keshrath/agent-discover
claude plugin install agent-discover@agent-discover

如果你还不熟悉该窗格，教程通过截图逐步介绍了使用方法。

• /discover 会打开 agent-discover 窗格（全屏布局下停靠在对话记录旁，否则位于提示词上方；也可在桌面版 Code 标签页和 VS Code 中使用）。按键 1-4 可切换标签页，焦点会落在下一个步骤上（批准、启用、搜索字段、缺少的密钥、安装）。服务：显示每个已安装服务及其状态；打开某个服务可查看其配置（命令或 URL、标签、来源和注册表状态、软件包；仅显示环境变量和标头的密钥名称）、密钥编辑器（可设置或删除，绝不显示密钥值）、工具及其输入架构和每个工具的指标、健康检查和错误重置、隔离差异（可批准 / 保持禁用）、OAuth 登录（授权 URL 作为链接），以及启用 / 禁用 / 重新索引 / 卸载操作。浏览：搜索注册表、查看安装计划（确切的命令或 URL、来源、警告、必需密钥及其输入框），然后安装。日志（近期代理调用）和审计（按服务和操作筛选，分页显示）。上游服务提出的问题（征询）会显示在最上方。
• /discover <你需要的内容> 会打开显示搜索结果的“浏览”页。
• 状态栏会显示 MCP 2/6 enabled · 1 to review（已启用数量 / 已安装数量，以及需要查看的服务数量）；服务被隔离、健康状态异常或提出问题时会弹出提示；当有事项需要你处理且窗格关闭时，提示词上方会显示横幅。
• 每次对话开始时，都会有一个上下文块告知模型哪些服务已启用，并提示它在声称缺少某项功能前先调用 search_tools。
• 此 mod 需要 Claude Code 2.1.289 或更高版本。较旧版本仍可使用这些技能和工具。
• 从 ~/.claude.json 中移除任何手动编写的 agent-discover 条目，以免工具重复显示。

其他 MCP 宿主

{
  "mcpServers": {
    "agent-discover": { "command": "npx", "args": ["-y", "agent-discover@^3"] }
  }
}

支持 Streamable HTTP 的宿主也可以在守护进程已运行时，指向 http://127.0.0.1:3424/mcp。Cursor、Codex、VS Code、Claude Desktop 等：docs/SETUP.md。

其他宿主通过 agent-discover 的 MCP 工具使用它（Markdown 结果；宿主支持渲染时显示 MCP Apps 小组件）。如需批准被隔离的服务，或在客户端不支持征询时进行安装，可在 Claude Code 的 /discover 窗格中操作，或由操作员设置 AGENT_DISCOVER_ALLOW_UNCONFIRMED_INSTALL=1。

从源代码构建

git clone https://github.com/keshrath/agent-discover.git
cd agent-discover
npm install
npm run build
node dist/index.js daemon

---

运行方式

每台机器运行一个守护进程：agent-discover daemon。它监听 127.0.0.1:3424，提供 REST API（/api/*，Claude Code 窗格通过它通信）和 MCP Streamable HTTP 服务（/mcp）。/mcp 在同一端点上支持 2026-07-28 协议和 2025 会话协议。

默认可执行文件 agent-discover 是一个精简的 stdio shim：它会检查 /api/health，如果守护进程未运行则启动它（由锁文件保护，以分离模式运行），并将 stdio 中继到 /mcp。所有宿主和会话共用同一个守护进程，因此连接和启用状态由同一个主体管理。如果 30 分钟内没有打开的 HTTP 交互，守护进程就会退出（AGENT_DISCOVER_IDLE_MS）。

详情：docs/ARCHITECTURE.md。

---

MCP 工具（8 个）

工具	用途
search_servers	已安装的服务，以及公共注册表 / npm / PyPI 中的匹配项，供查找尚未安装的服务。
install_server	根据准确的注册表、npm 或 PyPI 名称（固定版本）安装，或通过手动命令或 URL 安装。请你确认计划后，再进行索引。
enable_server	向宿主公开服务的工具。隔离中的服务会要求你先查看差异并重新批准。
disable_server	停止公开这些工具。服务仍保持安装状态，且可搜索。
server_status	已安装 / 已索引 / 已启用 / 已连接 / 已隔离状态、工具数量、已标记的工具、运行状况（check_health 会执行实时探测）。
search_tools	批量搜索（最多 10 个查询），覆盖所有已安装服务的工具索引，无论服务是否已启用。
get_tool	根据服务和名称获取一个已索引工具的完整定义。
call_tool	调用任意已索引工具，并原样返回上游结果。proxy 模式下使用此工具调用。

在会显示 MCP 提示词的宿主中，discover、install 和 status 提示词会显示为斜杠命令。除 call_tool 外，所有工具都声明了 outputSchema，并会返回 structuredContent 以及 Markdown 渲染内容。

MCP Apps 小组件。 工具结果包含 ui://agent-discover/app.html，这是一个用于渲染搜索结果、服务卡片、安装授权和工具测试器的小组件。Claude Desktop、claude.ai 和 VS Code 会渲染它。Claude Code 暂不支持渲染 MCP Apps，因此会显示 Markdown 内容。

完整模式：docs/API.md。

---

信任层

agent-discover 位于你的宿主与其未编写的 MCP 服务之间，因此会将这些服务的描述视为恶意内容。完整模型见：docs/SECURITY.md。

• 带来源信息的安装授权。 计划会显示确切的命令、固定版本以及注册表命名空间 / 包元数据检查。特意不提供由 Agent 提供的 confirm 参数。
• 工具固定与隔离。 首次为服务建立索引时，会固定每个工具的描述、输入模式和注释的哈希。之后任何更改、添加或移除都会导致服务被隔离，直到你查看易读的差异并重新批准（或工具恢复原状）。
• 描述清理。 剔除控制字符、零宽字符和双向文本字符，限制描述长度，并通过六种启发式规则标记可能的提示词注入。标记仅供参考；真正的控制手段是固定。
• 密钥存储在操作系统钥匙串中；若钥匙串不可用，则存储在 AES-256-GCM 文件中。绝不存入 SQLite，也绝不以未遮蔽的形式列出。
• 审计日志仅追加，可通过 GET /api/audit 查看。
• OpenTelemetry，通过 OTEL_EXPORTER_OTLP_ENDPOINT 或 AGENT_DISCOVER_OTEL=1 选择启用。
• 仅限回环连接。 设有 Host / Origin 允许列表、仅接受 JSON 正文，且每次启动都会为每个更改状态的 REST 调用生成令牌。
• 远程服务的 OAuth 2.1（发现、PKCE、刷新、iss 检查），登录时会向你提供 URL；agent-discover 绝不会自行打开该 URL。

未覆盖：上游 stdio 服务的沙盒隔离。这些服务会以你的用户权限运行。

---

搜索质量

search_tools 使用 SQLite FTS5 排序（Porter 词干提取，对名称、描述和参数名称执行字段化 BM25），并结合错别字修复、服务路由和少量使用频率先验。可选择启用本地或 OpenAI 嵌入提供方，以增加稠密分数。

在 bench/retrieval/ 中的检索基准上测得：50 个真实 MCP 服务、1674 个工具、468 条人工标注查询（改述、任务、跨服务、多步骤、错别字、德语和无法回答）。所有调优均使用开发集；以下数据来自留出测试集（269 条可回答查询）。

排序器	R@1	R@5	R@10	MRR
纯 BM25（与托管 BM25 工具搜索的表现大致相当）	0.305	0.522	0.618	0.430
agent-discover 1.x	0.307	0.561	0.642	0.446
agent-discover 2.0，零配置	0.338	0.576	0.661	0.474
2.0 + multilingual-e5-small（可选启用）	0.381	0.618	0.722	0.522

请客观看待这些结果：

• 相比纯 BM25，零配置带来的提升有限（R@10 提高 4 个百分点）。稠密检索选项还能再提高约 6 个百分点。
• 这仅涉及检索：没有大模型选择工具，语料也只是公开服务及其真实且质量参差不齐的描述。
• e5 这一行需要手动执行 npm install @huggingface/transformers（模型约 130 MB，在单线程上为 1674 个工具建索引约需 3 分钟），且不会在 CI 中运行。
• 对描述进行每个工具 5 条查询的大模型增强，离线 R@10 达到了 0.922，但这仅用于基准测试，并未随产品发布：它需要在建索引时使用大模型，而且标注查询也是由大模型编写的，因此应将其视为上限。
• 不设分数下限。没有任何信号能区分无法回答的查询和可回答的查询，因此 2.0 会返回最匹配的结果，而不会假装拒绝回答。

方法、分类结果及运行方式：bench/retrieval/README.md。CI 会运行 npm run bench:retrieval -- --check。

---

功能

• 本地注册表，存储于 SQLite：服务、已索引工具、每个服务的密钥和指标。索引与启用相互独立：安装时会探测一次服务，持久化其工具，然后断开连接。
• 官方 MCP Registry 镜像（v0.1 API），支持增量 updated_since 同步、已弃用和已删除状态跟踪，以及精确名称安装。注册表条目已删除的服务会在 server_status 中标记。
• 对注册表镜像、npm 和 PyPI 进行联邦搜索。
• 连接上游服务的传输方式：stdio、SSE、streamable HTTP，并自动协商两代协议。上游的 input_required 和 2025 年的 elicitation/create 请求会转发给你的客户端。
• 延迟建立连接并使用连接池，支持重连退避、空闲断开和真实健康探测。
• 三个 UI 界面：Claude Code /discover 面板、MCP Apps 小组件（Claude Desktop、claude.ai、VS Code），以及为其他所有宿主（OpenCode、Cursor、Codex 等）提供的 Markdown 结果。自 3.0 起不再提供 Web 控制面板。
• 声明式设置文件（AGENT_DISCOVER_SETUP_FILE），列出守护进程启动时需要确保已安装的服务。
• 每个工具的指标和调用日志。

---

环境变量

常用变量。完整列表请参阅 docs/API.md。

变量	默认值	描述
AGENT_DISCOVER_PORT	3424	守护进程端口
AGENT_DISCOVER_HOST	127.0.0.1	监听地址
AGENT_DISCOVER_DATA_DIR	平台数据目录	数据目录（参见从 1.x 升级）
AGENT_DISCOVER_DB	其中的 agent-discover.db	SQLite 文件路径
AGENT_DISCOVER_MODE	native	native 列出已启用服务的工具；proxy 仅列出元工具
AGENT_DISCOVER_IDLE_MS	1800000	守护进程空闲退出（0 = 永不退出）
AGENT_DISCOVER_SETUP_FILE	未设置	启动时同步的声明式服务列表
AGENT_DISCOVER_EMBEDDING_PROVIDER	none	local 或 openai 会添加语义排序
AGENT_DISCOVER_SECRETS	自动	keyring 或 file 强制使用相应的密钥后端

---

升级

从 2.x 升级： 3.0 移除了 3424 端口上的 Web 控制面板（以及其 WebSocket、测试器、预设和临时服务路由）和 agent-desk 支持。在 Claude Code 中使用 /discover 管理服务；其他宿主仍可使用 MCP 工具。宿主配置改为 agent-discover@^3。详情请参阅 CHANGELOG.md。

从 1.x 升级： 2.0 是一个不兼容的版本。单个 registry 工具被上方的八个工具取代，REST 路由已重命名，设置文件中的 auto_activate 键现为 enabled，密钥移至密钥链，默认可执行文件改为 shim。数据库会自动迁移，并在首次启动时从 ~/.claude 移至每用户数据目录（%LOCALAPPDATA%\agent-discover、~/Library/Application Support/agent-discover 或 $XDG_DATA_HOME/agent-discover / ~/.local/share/agent-discover；可通过 AGENT_DISCOVER_DATA_DIR 覆盖），因此请先停止任何正在运行的 1.x 进程。完整列表请参阅 CHANGELOG.md。

---

已知限制

• Claude Code 会将工具的 structuredContent 作为 JSON 文本而非 Markdown content 转发给模型（上游行为，anthropics/claude-code#55677 已关闭且不会计划处理，另请参阅 #15412）。其他宿主和小组件会使用 Markdown / UI。
• 尚未支持对 stdio 服务进行 Docker 沙箱隔离（已延期）。

---

测试

npm test              # 218 tests across 27 files (+9 e2e skipped unless AGENT_DISCOVER_E2E=1, +16 pane e2e)
npm run check         # typecheck + lint + format + test
npm run bench:retrieval
npm run plugin:check  # claude plugin validate + the pane's 9 plugin tests
npm run e2e:claude    # the /discover pane in the real Claude Code CLI (inline and docked), screenshots to ~/.claude/tmp/pane-shots

---

文档

• 教程：逐步介绍 /discover 面板，并附有截图
• 用户手册：日常使用
• 设置指南：安装和各客户端配置
• API 参考：MCP 工具、REST、环境
• 架构：进程模型、领域服务、架构、搜索
• 安全：信任模型
• 变更日志

---

许可证

MIT，详见 LICENSE