MCP、REST 與應用內 Agent

Eidograph 提供三種 Agent 使用路徑，但最終都會呼叫同一組工具介面：

路徑	適合場景	可用範圍
應用內 Agent	以自然語言修改目前的專案	Windows 與 Android 應用程式
MCP Streamable HTTP	支援遠端 HTTP MCP 的 Agent 平台	Windows 應用程式
JSON REST API	腳本、工作流程與自訂 Agent	Windows 應用程式

工具在修改腳本前，Eidograph 會先編譯候選內容。含有編譯錯誤或「指令被略過」警告的修改會被拒絕，目前的腳本不會變動。成功的修改會立即持久化、重繪，並進入一般的復原歷史紀錄。

啟用原生伺服器

在已安裝的應用程式中開啟設定 › MCP / REST 伺服器。
啟用伺服器，並確認狀態顯示為執行中。預設連接埠為 14159。
只啟用客戶端實際需要的工具。
在圖形面板中，檢查每個圖形旁的暴露圓點。實心圓點代表外部客戶端可以存取該圖形。
除非在受信任的網路環境中，否則請維持預設的僅本機迴路（loopback）繫結。

預設端點：

txt

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

DANGER

區域網路模式會繫結到 0.0.0.0，也沒有網際網路中繼。同一網路上的原生客戶端都能呼叫你所啟用的工具，因此請先啟用存取權杖再開啟區域網路模式，只在受信任的網路中使用，並在使用完畢後關閉。

啟用存取權杖

伺服器預設不做身分驗證。只監聽本機時這是安全的：只有本機已在執行的程式才能存取。在設定 › MCP / REST 伺服器 › 需要存取權杖中開啟後（開啟區域網路模式之前務必先開啟），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。即使在區域網路模式下，檔案中發布的 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

先檢查狀態並探索可用工具：

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 標題列切換使用。Eidograph 支援三種協定家族：

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 ​

權限與資料邊界 ​