MCP, REST và tác tử trong ứng dụng

Eidograph cung cấp ba con đường cho tác tử, tất cả đều dẫn đến cùng một bộ công cụ:

Con đường	Phù hợp cho	Có trên
Tác tử trong ứng dụng	Thay đổi dự án hiện tại bằng ngôn ngữ tự nhiên	Ứng dụng Windows và Android
MCP Streamable HTTP	Các nền tảng tác tử hỗ trợ MCP HTTP từ xa	Ứng dụng Windows
API REST JSON	Tập lệnh, quy trình làm việc và tác tử tùy chỉnh	Ứng dụng Windows

Trước khi một công cụ thay đổi tập lệnh, Eidograph biên dịch bản ứng viên. Một chỉnh sửa có lỗi biên dịch hoặc cảnh báo bỏ qua lệnh sẽ bị từ chối và tập lệnh hiện tại không thay đổi. Các chỉnh sửa thành công được lưu, vẽ lại và đưa vào lịch sử hoàn tác thông thường ngay lập tức.

Bật máy chủ gốc

Trong ứng dụng đã cài đặt, mở Cài đặt › Máy chủ MCP / REST.
Bật máy chủ và xác nhận trạng thái đang chạy. Cổng mặc định là 14159.
Chỉ bật những công cụ mà máy khách cần.
Trong Hình, xem chấm mở bên cạnh từng hình. Chấm tô đặc nghĩa là máy khách bên ngoài có thể truy cập hình đó.
Giữ nguyên liên kết loopback mặc định trừ khi bạn ở trên mạng đáng tin cậy.

Các điểm cuối mặc định:

txt

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

DANGER

Chế độ LAN liên kết với 0.0.0.0 và không có chuyển tiếp qua internet. Các máy khách gốc trên mạng đó có thể gọi các công cụ bạn đã bật, vì vậy hãy bật mã thông báo truy cập trước khi bật chế độ LAN, chỉ dùng trên mạng đáng tin cậy và tắt đi sau đó.

Yêu cầu mã thông báo truy cập

Máy chủ mặc định không xác thực, điều này đủ an toàn khi nó chỉ ở loopback: chỉ các chương trình đang chạy trên PC của bạn mới truy cập được. Hãy bật Cài đặt › Máy chủ MCP / REST › Yêu cầu mã thông báo truy cập — luôn làm trước khi bật chế độ LAN — và Eidograph sẽ tạo một bí mật mà mọi yêu cầu phải mang theo:

txt

Authorization: Bearer <token>

Yêu cầu không có nó sẽ được trả lời bằng 401. Trang cài đặt hiển thị mã thông báo kèm nút sao chép, Thay mã thông báo đổi sang mã mới, và tắt tùy chọn sẽ xóa nó. Cả hai có hiệu lực ngay, vì vậy hãy cập nhật mọi máy khách bạn đã cấu hình.

Tìm máy chủ từ chương trình khác

Cổng là một cài đặt nên không có gì bên ngoài ứng dụng có thể giả định nó. Khi bộ lắng nghe đang chạy, Eidograph công bố một tệp khám phá và xóa nó khi máy chủ dừng hoặc ứng dụng thoát:

Nền tảng	Đường dẫn
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": []
}

Hãy đọc mcp hoặc api, và gửi token làm mã thông báo bearer; giá trị là null khi không yêu cầu. Các URL được công bố vẫn ở loopback ngay cả trong chế độ LAN, vì mọi bên đọc tệp này đều ở cùng một máy. Cài đặt › Máy chủ MCP / REST hiển thị đường dẫn chính xác và cho phép sao chép. Hãy coi tệp bị thiếu là "máy chủ không chạy" thay vì quay về một cổng đoán mò.

Claude Desktop

Claude Desktop cài các máy chủ MCP dưới dạng tiến trình stdio cục bộ, nên không thể dán trực tiếp một URL HTTP vào đó. Hãy cài tiện ích mở rộng eidograph-mcpb để nối hai bên — nó không cần cấu hình, tự tìm cổng và mã thông báo truy cập và đọc lại chúng ở mỗi yêu cầu. Xem Claude Desktop để có hướng dẫn cài đặt từng bước kèm ảnh chụp màn hình, và cách trỏ nó tới Eidograph đang chạy trên thiết bị khác.

Kết nối nền tảng MCP

Với máy khách hỗ trợ Streamable HTTP — bao gồm cấu hình Trae / WorkBuddy do ứng dụng sao chép — hãy thêm máy chủ này:

json

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

Mỗi nền tảng khác nhau về vị trí tệp cấu hình và lược đồ bên ngoài, nhưng các giá trị thiết yếu là tên máy chủ, URL và phương thức truyền Streamable HTTP. Nếu nền tảng chỉ hỗ trợ tiến trình MCP stdio cục bộ, đừng đặt URL này vào trường command; hãy dùng một trình kết nối hoặc cầu nối HTTP mà nền tảng đó hỗ trợ.

Sau khi kết nối, hãy để máy khách khám phá công cụ, rồi đọc tập lệnh hiện tại hoặc sổ đăng ký lệnh. Một trình tự đáng tin cậy cho tác tử là:

list_figures để xác nhận mục tiêu;
get_script và list_objects để hiểu hình hiện tại;
list_commands để xem cú pháp hợp lệ cho phương ngữ 2D/3D đang hoạt động;
append_commands cho các thay đổi bổ sung, và chỉ dùng set_script khi phải viết lại các dòng hiện có;
list_diagnostics để kiểm tra kết quả và sửa mọi vấn đề.

Gọi API REST

Về hợp đồng của các điểm cuối, mọi lược đồ công cụ, mã hóa khi xuất, cách xử lý lỗi và các ví dụ JavaScript/Python/PowerShell, xem REST API Reference.

Trước tiên hãy kiểm tra trạng thái và việc khám phá công cụ:

bash

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

Tạo hai điểm và một đoạn thẳng:

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"}'

Phản hồi dùng một phong bì duy nhất: {"ok":true,"result":...} khi thành công hoặc {"ok":false,"error":...} khi thất bại. Tiêu đề X-Eidograph-Client tùy chọn đặt cho bên gọi một cái tên dễ đọc trong phần hoạt động của Cài đặt.

Giao diện hiện tại có thể đọc và liệt kê hình, tạo hình, nối thêm hoặc thay thế tập lệnh, liệt kê đối tượng/chẩn đoán/lệnh, chọn một đối tượng trên khung vẽ và xuất một hình đã mở ra thành SVG, PNG, GIF hoặc MP4. Quyền của công cụ và việc mở hình được thực thi ở mọi lệnh gọi.

Cấu hình tác tử trong ứng dụng

Lưu nhiều mô hình trong Cài đặt › Tác tử, rồi chuyển đổi giữa chúng từ thanh tiêu đề Tác tử. Eidograph hỗ trợ ba họ giao thức:

các điểm cuối Chat Completions tương thích OpenAI;
Anthropic Messages;
Google Gemini / Vertex generateContent.

Mỗi mô hình đã lưu có tên hiển thị, nhà cung cấp, URL gốc, khóa API và ID mô hình. Bạn có thể nhập ID thủ công nếu việc khám phá mô hình thất bại. Các điểm cuối cục bộ như Ollama và LM Studio cũng dùng được, nhưng điểm cuối phải cho phép các yêu cầu khác nguồn gốc (CORS) từ WebView của ứng dụng.

Tác tử trong ứng dụng nhận ảnh đính kèm hoặc dán vào, hữu ích để biến ảnh chụp sách giáo khoa hay bản phác thảo thành bản dựng. Việc hỗ trợ hình ảnh do điểm cuối mô hình quyết định; một yêu cầu không được hỗ trợ sẽ hiện dưới dạng lỗi trong cuộc trò chuyện.

Trong ứng dụng Windows và Android, tác tử còn có thể tra cứu trên web: web_search tìm một định lý, phép dựng hoặc hình tham khảo qua DuckDuckGo, và web_fetch đọc một trang dưới dạng văn bản hoặc xem một ảnh theo URL, chẳng hạn một sơ đồ cần tái tạo. Chỉ truy cập được các trang web công khai. Hai công cụ này chỉ thuộc về tác tử trong ứng dụng; chúng không nằm trong giao diện MCP/REST.

Quyền và ranh giới dữ liệu

Tác tử trong ứng dụng và tác tử bên ngoài không có đường đặc quyền ẩn; cả hai dùng cùng các định nghĩa công cụ.
Chỉnh sửa từ bên ngoài nhắm vào dự án đang hoạt động và tuân theo trạng thái mở của từng hình.
Khóa API không bao giờ được ghi vào .eido. Ứng dụng Windows và Android dùng kho thông tin xác thực được hệ điều hành bảo vệ.
Cuộc trò chuyện với tác tử mặc định bị loại khỏi .eido và chỉ được chia sẻ khi Kèm cuộc trò chuyện với tác tử được bật rõ ràng.

MCP, REST và tác tử trong ứng dụng ​

Bật máy chủ gốc ​

Yêu cầu mã thông báo truy cập ​

Tìm máy chủ từ chương trình khác ​

Claude Desktop ​

Kết nối nền tảng MCP ​

Gọi API REST ​

Cấu hình tác tử trong ứng dụng ​

Quyền và ranh giới dữ liệu ​