Rea-FigmaDesign
Contract · MCP · 2026

當別人的 agent 用你的 MCP

別人的 host、別人的模型、別人的提示詞——你控制不了。你能控制的是四道閘門,以及一道管不到的地方。

工具契約:docs/QUERY.md · 一次真實查詢:case-popup.html

00你控制什麼,不控制什麼

不在你手上在你手上
host 是哪一個、會不會驗 schemaschema 長什麼樣
模型是哪一個、提示詞怎麼寫server 怎麼回應、拒絕什麼
它先問哪個問題、怎麼解讀答案文件寫什麼、資料能證明什麼

所以「約束」不是一個開關,是四個先後不同的閘門。

強制
schema參數形狀
→
強制
server動作與副作用
→
引導
文件選工具、解讀
→
保證
資料數字與來源

圖 1:前兩道是程式可強制的;後兩道不是「強制」,是讓錯誤變得可被發現。

01第一道:schema 管形狀

每個工具都帶一份 JSON Schema。它管的是「參數能不能被接受」,不是「模型該不該這樣做」。

list_screens.inputSchema
  archetype : string, enum: page | overlay-panel | overlay | unknown
  limit     : number, minimum 1, maximum 2000
  unique    : boolean
  additionalProperties: false

打錯型別、多給欄位、給不存在的 enum 值,都會在這一層被擋下——如果 host 有驗的話。

不是每個 host 都會驗 schema。所以 server 自己也驗:archetype 傳 popup 會直接回錯誤,不會默默回 0 筆。

schema 還帶一個給 host 看的訊號:annotations。

readOnlyHint     true            → 唯讀,不需要確認
readOnlyHint     false(apply_labels)→ 會寫檔
destructiveHint  true(apply_labels)→ 可能覆蓋既有分類

Host 可以用它決定要不要跳確認視窗;這是給人看的,不是給模型看的。

02第二道:server 管動作

schema 被繞過(或 host 不驗)時,server 是最後一道程式防線。

不合法的參數:直接拒絕

tools/call list_screens { "archetype": "popup" }

error: invalid archetype: popup
       (allowed: page, overlay-panel, overlay, unknown)

不是回 0 筆——回 0 筆會讓模型以為「這份檔案沒有彈窗」。

有副作用的動作:要明確確認

tools/call apply_labels { "rows": [...] }

error: apply_labels is mutating:
       pass confirm:true (or dryRun:true)

不存在的工具:協議層錯誤

tools/call not_a_tool {}
→ JSON-RPC error: unknown tool: not_a_tool

三個拒絕都帶可讀的原因。模型看到原因,可以自己修正;人看到原因,知道是用法錯了,不是資料錯了。

03第三道:文件管流程

schema 可以強制「參數是 enum」,但不能強制「模型選對工具」。這件事只能靠文件與提示詞。

文件裡的規則解決什麼
「有多少」一律先用 list_screens模型拿單頁工具去數全部
沒有 labels 時,語意分類回 unknown把結構答案說成語意答案
回答附 node id講得好像對,但無法查證

這一層是「引導」而不是「強制」:模型可以不照做。所以還需要第四道。

04第四道:資料管來源

前三道都可能被繞過。最後這道不依賴 agent 合作,因為它管的是「答案從哪裡來」。

保證怎麼做到
數字不是模型算的list_screens 回傳 server 端計數
答案可以回查每一列都帶 Figma node id
重跑結果相同核心是決定性的,沒有隨機性
錯了能被抓到ID 貼回 Figma 對一次就知道
模型可以說錯話,但改不了數字。

這是四道裡唯一「不要求 agent 守規矩」的一道——它要求的是答案可被驗證。

05schema 管不到的事

做不到後果
模型選哪個工具可以用 screen_sheet 硬數,得到錯的答案
模型怎麼解讀 119 與 87可以說成同一個數字,或挑對自己有利的那個
模型是否標註定義與來源可以只給數字,不說是結構還是語意
模型是否先問清需求可以假設「彈窗 = dialog」直接回答

這一頁不假裝這些被解決了。它們被降低:文件寫清楚、資料可回查、錯誤有代價。

06驗證:不是靠聲明,是靠測試

npm run test:mcp 每次啟動一個真的 server,跑 14 項檢查:

ok  tools/list advertises 11 tools — 11
ok  tool present: list_screens
ok  list_screens archetype is an enum — page,overlay-panel,overlay,unknown
ok  list_screens is read-only
ok  apply_labels is destructive
ok  unknown tool returns a JSON-RPC error
ok  invalid archetype is rejected
ok  apply_labels without confirm is refused
ok  server_info answers ok

RESULT: OK — MCP surface, constraints and annotations match the contract

這些檢查會隨 doctor 一起跑。如果哪天有人改了 schema 或拿掉 confirm,測試會紅,而不是等使用者踩到。

07給外部 agent 的三條規則

  1. 問「有多少」先用 list_screens,不要自己遍歷資料庫,也不要拿單頁工具硬數。
  2. 沒有 labels 就回 unknown;結構答案不能冒充語意答案。
  3. 附上 node id;沒有 ID 的答案,使用者無法驗證,等於沒有答案。

這三條不在 schema 裡,因為它們管的是判斷,不是形狀。協議約束形狀,文件約束流程,資料保證來源。