• 產品
  • 價格
  • 能力市集
返回 EvoMap
登入註冊
概覽
實踐案例
功能
配置
開發者
編寫技能接入 MCP 工具Hooks
架構與源碼倉庫
安全
管理
概覽
實踐案例
功能
配置
開發者
編寫技能接入 MCP 工具Hooks
架構與源碼倉庫
安全
管理
EvoX 文件/Build with EvoX/接入 MCP 工具

接入 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 協議消息。實際服務還需要按部署方式補充會話管理、資源限制與訪問控制。

javascript
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 發送:

text
使用 project-scripts 的 read_project_scripts 读取这个项目的 npm 脚本。
列出脚本名称和对应命令,不执行任何脚本。

把返回結果與目標項目的 package.json 對照。保存成功、進程啓動、工具發現和實際調用分別確認;只看到服務名稱不能證明工具可用。

檢查協議與錯誤

下面是工具調用消息;連接建立時還需由 MCP 客户端完成 initialize 與 initialized 握手。

initialize 請求提供 protocolVersion、capabilities 對象,以及包含 name 和 version 字符串的 clientInfo。服務端支持協議 2024-11-05,協商時返回該版本;客户端不支持時斷開連接。initialize 與 notifications/initialized 完成前拒絕工具發現和調用;ping 可在初始化前使用。

json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"read_project_scripts","arguments":{}}}
驗證項應得到的結果
普通項目返回與文件相同的腳本,不執行腳本
添加 path 參數返回無效參數錯誤,不讀取其他文件
項目沒有 package.json工具返回讀取錯誤,不偽造空項目結果
文件超出限制或為符號鏈接拒絕讀取
服務進程退出連接報錯,恢復服務後重新驗證發現與調用

擴展為寫入工具

寫入使用獨立工具名和 schema,明確資源標識、修改內容、預覽、授權與冪等行為。服務端驗證範圍和賬號權限,不能依賴模型遵守工具描述。超時後查詢真實操作結果,避免重試導致重複寫入。

升級時比較工具名稱、schema、錯誤和副作用,並重跑相同接入用例。停止 MCP 連接後,遠程服務的賬號授權和憑證仍需在提供方撤銷。

上一篇編寫技能下一篇Hooks