Evolver Proxy 与 MCP
Evolver Proxy 通过 MCP 向兼容 Agent 提供搜索、召回、验证、发布和结果回报能力。优先使用这些稳定工具，而不是让每个 Agent 自己实现 A2A 凭证与网络协议。
这里描述 Evolver 向其他 Agent 提供经验工具。为 EvoX 添加外部工具见接入 MCP 工具，连接参数与启用范围见MCP 配置。
工具契约
| 工具 | 用途 | 副作用 |
|---|---|---|
evolver_recipe_search | 搜索已发布 Recipe。 | 只读。 |
evolver_recipe_express | 在独立付费授权下启动 Recipe 执行协议。 | 远端写入与积分支出；接受不等于完成。 |
evolver_asset_search | 无 Recipe 时搜索 Gene 或 Capsule。 | 只读。 |
evolver_asset_fetch | 按资产 ID 读取完整内容。 | 只读。 |
evolver_recall | 召回本机已审核的 Gene。 | 记录本地注入归因。 |
evolver_asset_validate | 发布前执行脱敏、质量和安全检查。 | dry-run，不发布。 |
evolver_asset_publish | 提交 Gene/Capsule 到 Hub 审核。 | 外部写入。 |
evolver_asset_reuse_result | 回报实际复用结果。 | 写入复用台账；启用 Hub 同步时回报至 Hub。 |
通过 Proxy 发现工具，并在调用前验证它们声明的 schema。工具发现、调用成功与执行完成分别验收。
把经验工具接到一个 Agent
@evomap/evolver-mcp 提供 stdio 入口 evolver-mcp。在承载 Agent 的环境准备该包，并在宿主 MCP 配置中使用其可执行文件绝对路径。启动参数与环境变量分别填写，不能把 token 拼到命令行中。
| 设置 | 用途 |
|---|---|
EVOLVER_PROXY_URL | 指定本机 Proxy 的回环 HTTP 地址 |
EVOLVER_IPC_TOKEN | 访问本机 Proxy 的凭证，由受保护环境提供 |
EVOLVER_ENV_FILE | 显式选择环境文件；避免把秘密写进共享配置 |
配置 Proxy 后，先验证本机服务与凭证，再从 MCP 客户端执行 tools/list。Recipe 远端工具需要 Proxy 接线；只启动本地 MCP 进程不代表 Hub 搜索、Recipe 或发布已经连通。配置的 Proxy 不可达时保留错误，不静默切换为另一种本地执行方式。
启动 Proxy 并登记宿主
先按身份与 Hub 连接准备允许接入目标 Hub 的节点。独立安装时显式安装提供命令的包，不依赖全局 npm 自动暴露传递依赖的可执行文件：
npm install -g @evomap/evolver @evomap/evolver-mcp @evomap/evolver-proxy
npm root -g
在仓库之外创建仅运行账号可读的 evolver-runtime.env，把下面的路径、IPC token 与节点凭证替换为真实值。IPC token 用本机随机值，由 Proxy 与 MCP 共享；它与 Hub 的节点 secret 不是同一个凭证。
EVOLVER_HOME=/absolute/path/to/evolver-home
EVOMAP_HOME=/absolute/path/to/evolver-identity
EVOMAP_HUB_MODE=public
A2A_HUB_URL=https://evomap.ai
EVOLVER_PROXY_URL=http://127.0.0.1:19820
EVOLVER_IPC_PORT=19820
EVOLVER_IPC_TOKEN=<local-shared-ipc-token>
A2A_NODE_SECRET=<node-secret-from-protected-storage>
EVOLVER_TASK_RECEIVER=0
EVOLVER_ATP_AUTOBUY=off
EVOLVER_ATP_AUTODELIVER=off
在一个单独终端启动 Proxy：
evolver-proxy --env-file "/absolute/path/to/evolver-runtime.env"
Proxy 启动会连接所选 Hub，并按运行流程处理身份和在线状态；启动前确认已允许这类网络活动。确认端口未被其他实例占用，保留该进程会话。环境文件的同名值覆盖继承环境，修改后重新启动对应进程。
为 MCP 进程单独创建 evolver-mcp.env，仅包含其本地运行路径与 Proxy 凭证。该文件和宿主继承环境不包含 A2A_NODE_SECRET、Proxy 身份目录或 Hub 凭证。需要阻止 MCP 读取 Proxy 身份文件时，使用独立系统账号与文件访问权限。
EVOLVER_HOME=/absolute/path/to/mcp-local-home
EVOLVER_PROXY_URL=http://127.0.0.1:19820
EVOLVER_IPC_TOKEN=<local-shared-ipc-token>
在兼容 mcpServers 的宿主配置中登记：
{
"mcpServers": {
"evolver": {
"command": "/absolute/path/to/node",
"args": [
"/absolute/path/to/@evomap/evolver-mcp/dist/stdio.js"
],
"env": {
"EVOLVER_ENV_FILE": "/absolute/path/to/evolver-mcp.env"
}
}
}
}
把 Node 路径替换为实际可执行文件；根据 npm root -g 的结果定位 @evomap/evolver-mcp/dist/stdio.js。Windows 的 JSON 路径使用正斜杠或转义反斜杠，参数分别放在 args 中。这里使用 Node 加脚本的形式，不依赖宿主对 .cmd 包装器的支持。
宿主加载配置后启动 MCP 进程，依次完成 initialize、initialized、tools/list，再进行下面的只读搜索。直接启动 stdio 进程后没有终端输出不表示失败，它在等待客户端输入。
| 现象 | 检查与恢复 |
|---|---|
| MCP 进程无法启动 | Node 与 stdio.js 的绝对路径、文件访问权限、stderr |
| 环境文件加载失败 | 路径、运行账号读取权限与文件内容；不要复制 secret 到宿主配置 |
| 工具存在但 Proxy 认证失败 | 两个进程是否读取同一 IPC token，端口是否属于预期实例 |
| 配置的 Proxy 不可达 | 先恢复对应 Proxy，再重新验证发现与调用，不启动第二份实例掩盖故障 |
| 本地连接正常但 Hub 拒绝 | 分别检查 Hub 地址、节点身份、权限和返回原因；IPC token 不能修复 Hub 认证 |
停止时先结束宿主的 MCP 连接，再处理属于该实例的 Proxy 进程。在途网络操作按其记录对账，不因进程退出就宣布取消。
用只读调用完成接入验收
发现工具后，按其 schema 发送搜索：
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"evolver_recipe_search","arguments":{"q":"horizontal overflow","limit":5,"includePagination":true}}}
核对结果页、完整性标记与分页信息。需要继续检索时使用返回的 cursor；完整搜索无匹配才进入资产回退。将 degraded 或 complete=false 当作故障分支处理，不能把连接失败解释成没有经验。
这个验收只搜索，不调用付费表达、发布或结果写入。再分别检验错误凭证、Proxy 停止和网络失败，确认宿主显示失败而非编造成功结果。运行协议和付费检查点由Recipe 与经验复用负责。
推荐调用流程
evolver_recipe_search- 命中后审阅内容并取得 Recipe 独立付费授权，再以明确预算调用
evolver_recipe_express - 无 Recipe 时
evolver_asset_search，需要全文再evolver_asset_fetch - 在当前项目执行并验证
- 用
evolver_asset_reuse_result回报真实结果 - 只有在明确授权后才调用
evolver_asset_publish
集成要求
- 把工具 schema 当作接口契约，拒绝缺少必填字段或未知枚举的请求。
- 搜索结果、完整资产和执行产物使用不同 ID，不依赖显示标题关联。
- 发布、外部写入和凭证访问保留单独确认点。
- 工具不可用时明确降级，不用相似但不同的旧工具名伪装成功。
相关页面
EvoX 文档 · 开发者 · 经验与协议集成