接入 MCP 工具
通過 MCP 服務把自己的工具提供給 EvoX。本頁完成一個只讀接入:讓 Agent 讀取固定項目的 npm 腳本,驗證工具發現、調用和錯誤處理。連接管理與憑證表單見MCP 服務器;向其他 Agent 提供 Evolver 經驗工具見Evolver Proxy 與 MCP。
定義工具的作用範圍
本地示例只用於運行賬號控制的項目目錄及父目錄;其他用戶不得替換這些目錄或在調用期間修改文件。服務拒絕符號鏈接、核對已打開文件的身份,並從同一描述符最多讀取 64 KiB 加一個溢出檢測字節;共享惡意文件系統的隔離由系統賬號與權限負責。
示例工具 read_project_scripts 只讀取啓動時指定項目的 package.json,返回 scripts,不執行腳本、不寫文件、不訪問網絡。項目路徑由服務啓動參數指定,不接受 Agent 隨意傳入文件路徑。
| 契約 | 本例的決定 |
|---|---|
| 輸入 | 空對象 {};拒絕額外字段 |
| 輸出 | 文本內容中的 JSON 對象,包含 scripts |
| 資源 | 固定項目的普通 package.json,上限 64 KiB |
| 錯誤 | 無效參數返回協議錯誤;文件讀取失敗返回 isError: true |
| 副作用 | 無文件寫入與命令執行 |
創建 stdio 服務
將以下代碼保存為項目之外的 read-project-scripts.mjs。它使用 Node.js 內置模塊,標準輸出只寫 MCP 協議消息。實際服務還需要按部署方式補充會話管理、資源限制與訪問控制。
import { createInterface } from "node:readline";
import { realpathSync, lstatSync, openSync, fstatSync, readSync, closeSync, constants } from "node:fs";
import { join } from "node:path";
const root = realpathSync(process.argv[2]);
const file = join(root, "package.json");
const tool = {
name: "read_project_scripts",
description: "Read npm scripts from the configured project without executing them.",
inputSchema: { type: "object", properties: {}, additionalProperties: false }
};
const send = (id, result) => process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n");
const fail = (id, code, message) => process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }) + "\n");
const protocolVersion = "2024-11-05";
let phase = "new";
const input = createInterface({ input: process.stdin });
input.on("line", (line) => {
let request;
try { request = JSON.parse(line); }
catch { fail(null, -32700, "Invalid JSON"); return; }
if (!request || typeof request !== "object" || Array.isArray(request)) {
fail(null, -32600, "Invalid request"); return;
}
const { id, method } = request;
if (id !== undefined && typeof id !== "string" && !(typeof id === "number" && Number.isFinite(id))) {
fail(null, -32600, "Invalid request ID"); return;
}
if (request.jsonrpc !== "2.0" || typeof method !== "string") {
fail(id ?? null, -32600, "Invalid request"); return;
}
if (request.params !== undefined && (!request.params || typeof request.params !== "object" || Array.isArray(request.params))) {
if (id !== undefined) fail(id, -32602, "Invalid params");
return;
}
const params = request.params ?? {};
if (id === undefined) {
if (method === "notifications/initialized" && phase === "negotiated") phase = "ready";
return;
}
if (method === "initialize") {
const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
if (phase !== "new" || typeof params.protocolVersion !== "string" || !params.protocolVersion ||
!object(params.capabilities) || !object(params.clientInfo) ||
typeof params.clientInfo.name !== "string" || !params.clientInfo.name ||
typeof params.clientInfo.version !== "string" || !params.clientInfo.version) {
fail(id, -32602, "Invalid or repeated initialization"); return;
}
phase = "negotiated";
send(id, { protocolVersion, capabilities: { tools: {} }, serverInfo: { name: "project-scripts", version: "1.0.0" } });
} else if (method === "ping") {
send(id, {});
} else if (phase !== "ready") {
fail(id, -32002, "Complete initialization before using tools");
} else if (method === "tools/list") {
send(id, { tools: [tool] });
} else if (method === "tools/call") {
const args = params.arguments === undefined ? {} : params.arguments;
if (params.name !== tool.name || !args || typeof args !== "object" || Array.isArray(args) || Object.keys(args).length) {
fail(id, -32602, "Unknown tool or invalid arguments"); return;
}
try {
if (realpathSync(file) !== file) throw new Error("Linked file rejected");
const before = lstatSync(file, { bigint: true });
if (!before.isFile() || before.ino === 0n || before.size > 65536n) throw new Error("File rejected");
const fd = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
let text;
try {
const opened = fstatSync(fd, { bigint: true });
if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino) throw new Error("File changed");
const buffer = Buffer.alloc(65537);
let size = 0, count;
while (size < buffer.length && (count = readSync(fd, buffer, size, buffer.length - size, null)) > 0) size += count;
if (size > 65536) throw new Error("File too large");
text = buffer.toString("utf8", 0, size);
} finally { closeSync(fd); }
const pkg = JSON.parse(text);
const scripts = pkg.scripts ?? {};
if (!scripts || typeof scripts !== "object" || Array.isArray(scripts) || Object.values(scripts).some(v => typeof v !== "string")) throw new Error("Invalid scripts");
send(id, { content: [{ type: "text", text: JSON.stringify({ scripts }) }] });
} catch {
send(id, { isError: true, content: [{ type: "text", text: "Cannot read a regular package.json with valid scripts within 64 KiB." }] });
}
} else {
fail(id, -32601, "Method not found");
}
});
這是驗證單個只讀工具的最小服務。輸入按 JSON-RPC 單行消息處理,不提供 HTTP 端點、批量請求或完整生產服務治理;它也不提供操作系統沙箱。服務進程仍擁有啓動用戶的系統權限。
在 EvoX 中添加並驗證
在擴展的 MCP 入口添加手動連接,選擇 stdio,並分別填寫:
| 字段 | 示例 |
|---|---|
| 名稱 | project-scripts |
| 命令 | Node.js 可執行文件的絕對路徑 |
| 參數 | read-project-scripts.mjs 的絕對路徑,以及目標項目的絕對路徑;作為兩個獨立參數 |
保存後檢查連接和工具發現結果。向 Agent 發送:
使用 project-scripts 的 read_project_scripts 读取这个项目的 npm 脚本。
列出脚本名称和对应命令,不执行任何脚本。
把返回結果與目標項目的 package.json 對照。保存成功、進程啓動、工具發現和實際調用分別確認;只看到服務名稱不能證明工具可用。
檢查協議與錯誤
下面是工具調用消息;連接建立時還需由 MCP 客户端完成 initialize 與 initialized 握手。
initialize 請求提供 protocolVersion、capabilities 對象,以及包含 name 和 version 字符串的 clientInfo。服務端支持協議 2024-11-05,協商時返回該版本;客户端不支持時斷開連接。initialize 與 notifications/initialized 完成前拒絕工具發現和調用;ping 可在初始化前使用。
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"read_project_scripts","arguments":{}}}
| 驗證項 | 應得到的結果 |
|---|---|
| 普通項目 | 返回與文件相同的腳本,不執行腳本 |
添加 path 參數 | 返回無效參數錯誤,不讀取其他文件 |
| 項目沒有 package.json | 工具返回讀取錯誤,不偽造空項目結果 |
| 文件超出限制或為符號鏈接 | 拒絕讀取 |
| 服務進程退出 | 連接報錯,恢復服務後重新驗證發現與調用 |
擴展為寫入工具
寫入使用獨立工具名和 schema,明確資源標識、修改內容、預覽、授權與冪等行為。服務端驗證範圍和賬號權限,不能依賴模型遵守工具描述。超時後查詢真實操作結果,避免重試導致重複寫入。
升級時比較工具名稱、schema、錯誤和副作用,並重跑相同接入用例。停止 MCP 連接後,遠程服務的賬號授權和憑證仍需在提供方撤銷。