MCP、REST 与应用内 Agent

Eidograph 提供三条 Agent 路径，但它们最终调用同一组工具：

路径	适合场景	可用位置
应用内 Agent	直接用自然语言创建或修改当前项目	Windows 与 Android 应用
MCP Streamable HTTP	支持远程 HTTP MCP 的 Agent 平台	Windows 应用
JSON REST API	自动化脚本、工作流和自建 Agent	Windows 应用

工具修改脚本前会先编译候选内容。含编译错误或“命令被跳过”警告的修改会被拒绝，当前脚本保持不变；成功修改会立即保存、重绘并进入普通撤销历史。

启用原生服务

在已安装的应用中打开设置 › MCP / REST 服务器。
开启服务器，确认状态显示运行中。默认端口是 14159。
在工具列表中只启用客户端需要的权限。
在图形面板检查每个图形旁的暴露圆点：实心表示外部客户端可访问。
默认只监听本机；只有在可信网络中才开启 LAN 模式。

默认端点：

txt

MCP   http://127.0.0.1:14159/mcp
REST  http://127.0.0.1:14159/api/v1

DANGER

LAN 模式监听 0.0.0.0，也没有互联网中继。网络内的原生客户端可以调用你启用的工具，因此请先开启访问令牌再开启 LAN 模式，只在受信任网络使用，并在结束后关闭。

启用访问令牌

服务器默认不做身份验证。只监听本机时这是安全的：只有本机已在运行的程序才能访问。在设置 › MCP / REST 服务器 › 需要访问令牌中开启后（开启 LAN 模式之前务必先开启），Eidograph 会生成一个密钥，每个请求都必须携带：

txt

Authorization: Bearer <token>

缺少该头的请求返回 401。设置中会显示令牌并提供复制按钮，更换令牌可轮换密钥，关闭开关则清除它。两者都立即生效，请同步更新所有已配置的客户端。

让外部程序找到服务器

端口是一项设置，应用之外无法假定它的值。服务器运行期间 Eidograph 会写入一个发现文件，并在服务器停止或应用退出时删除它：

平台	路径
Windows	`%LOCALAPPDATA%\eidograph.metaphor.projects\server.json`
macOS	`~/Library/Application Support/eidograph.metaphor.projects/server.json`
Linux	`$XDG_DATA_HOME/eidograph.metaphor.projects/server.json`

json

{
  "version": "0.2.19",
  "pid": 24680,
  "updatedAt": 1757000000000,
  "bindAddress": "127.0.0.1",
  "port": 14159,
  "mcp": "http://127.0.0.1:14159/mcp",
  "api": "http://127.0.0.1:14159/api/v1",
  "token": "3f9c…",
  "lanAddresses": []
}

读取 mcp 或 api，并把 token 作为 bearer 令牌发送；不需要令牌时该字段为 null。即使在 LAN 模式下，文件中发布的 URL 也始终指向本机回环地址，因为读取这个文件的程序都在同一台机器上。设置 › MCP / REST 服务器会显示并复制确切路径。文件不存在就表示“服务器没有运行”，不要退回到猜测端口。

Claude Desktop

Claude Desktop 把 MCP 服务器安装为本地 stdio 进程，因此不能直接填入 HTTP URL。安装 eidograph-mcpb 扩展即可桥接两者——它无需配置，会自行找到端口和访问令牌，并在每次请求时重新读取。详细的安装步骤、截图，以及如何指向运行在另一台设备上的 Eidograph，见 Claude Desktop。

连接 MCP 平台

对于支持 Streamable HTTP 传输的客户端（例如应用内可直接复制配置所面向的 Trae / WorkBuddy），加入下面的服务器配置：

json

{
  "mcpServers": {
    "Eidograph": {
      "url": "http://127.0.0.1:14159/mcp",
      "transport": "streamable-http",
      "disabled": false
    }
  }
}

不同平台的配置文件位置和外层字段可能不同，但核心信息只有服务器名称、URL 和 Streamable HTTP 传输。若某个平台只支持本地 stdio MCP 进程，不能把 URL 直接填入 command 字段；需要该平台支持的 HTTP 连接器或桥接程序。

连接后先让客户端执行工具发现，再读取当前脚本或命令注册表。推荐的 Agent 顺序是：

list_figures 确认目标图形；
get_script 与 list_objects 理解现状；
list_commands 查询当前 2D/3D 方言的有效语法；
优先用 append_commands 增量修改；只有重写已有行时才用 set_script；
调用 list_diagnostics 检查结果，必要时修正后重试。

调用 REST API

端点契约、全部工具 Schema、导出编码、错误行为以及 JavaScript/Python/PowerShell 示例详见 REST API 参考。

先检查状态与工具：

bash

curl http://127.0.0.1:14159/api/v1/status
curl http://127.0.0.1:14159/api/v1/tools

创建两个点和一条线段：

bash

curl -X POST http://127.0.0.1:14159/api/v1/tools/append_commands \
  -H "Content-Type: application/json" \
  -H "X-Eidograph-Client: my-agent" \
  -d '{"commands":"point A -2 0\npoint B 2 0\nsegment s A B"}'

响应使用统一结构：成功为 {"ok":true,"result":...}，失败为 {"ok":false,"error":...}。X-Eidograph-Client 是可选的，会让设置中的活动记录显示易读的调用方名称。

当前工具包括读取与列出图形、创建图形、追加/替换脚本、列出对象/诊断/命令、在画布上选中对象，以及把暴露图形导出为 SVG、PNG、GIF 或 MP4。服务器的工具开关与图形暴露开关会在每次调用时生效。

配置应用内 Agent

在设置 › Agent中可以保存多个模型，并在 Agent 面板头部切换。支持三类协议：

OpenAI 兼容的 Chat Completions 端点；
Anthropic Messages；
Google Gemini / Vertex generateContent。

每个模型填写显示名称、提供商、Base URL、API 密钥和模型 ID。模型列表获取失败时仍可手动输入 ID。Ollama、LM Studio 等本地端点也可以使用，但端点需要允许应用 WebView 发起跨域请求（CORS）。

应用内 Agent 可附加或粘贴图片，适合把课本照片或草图转成构造。模型是否支持视觉输入由端点决定；不支持时错误会显示在对话中。

权限与数据边界

应用内 Agent 和外部客户端没有隐藏的特权路径，均受同一工具定义约束。
外部修改只作用于活动项目，并遵守每个图形的暴露状态。
API 密钥不会写入 .eido。Windows 和 Android 应用使用系统保护的凭据存储。
Agent 聊天默认不进入 .eido，需要共享时必须显式开启“包含 Agent 聊天”。

MCP、REST 与应用内 Agent ​

启用原生服务 ​

启用访问令牌 ​

让外部程序找到服务器 ​

Claude Desktop ​

连接 MCP 平台 ​

调用 REST API ​

配置应用内 Agent ​

权限与数据边界 ​