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 文檔 · 開發者 · 經驗與協議集成