外掛程式的 MCP 伺服器透過工具,讓 ChatGPT 和 Codex 執行動作及取得資料。請先構思使用情境,再定義工具,最後才實作伺服器。
每個工具都應協助使用者達成目標。設計工具時,請考慮使用者會如何提出需求及使用這項功能,避免直接照搬內部 API。
根據使用情境規劃工具
針對每個支援的使用情境,依序完成以下步驟:
- 寫下使用者預期的結果。
- 列出產生該結果所需的資訊。
- 找出伺服器必須執行的讀取、寫入或外部動作。
- 將共同完成同一項動作的操作歸為一組。
- 如果各項操作所需的權限、涉及的安全風險或確認要求不同,請將它們拆開。
例如,專案管理外掛程式可以提供下列工具:
list_projects用於尋找專案。get_project用於查看單一專案。create_project用於建立專案。update_project用於修改專案詳細資料。archive_project用於封存專案,這項動作會變更專案狀態,影響重大。
請將讀取與寫入操作分開,讓模型和使用者都能區分哪些操作只會取得資訊,哪些會變更狀態。
定義每個工具的契約
針對每個預計提供的工具,記錄以下內容:
| 欄位 | 定義內容 |
|---|---|
| 名稱 | 能表明工具執行何種動作的穩定識別碼。 |
| 標題 | 以簡短易懂的文字說明工具執行的動作。 |
| 說明 | 使用者的目標,以及應觸發工具的條件。 |
| 輸入結構描述 | 必填與選填參數,以及各參數的型別、允許值和限制。 |
| 輸出結構描述 | 模型可以檢視並重複使用的結構化欄位。 |
| 授權 | 伺服器必須驗證的帳戶、角色或資源存取權限。 |
| 副作用 | 工具可能變更的資料或外部狀態。 |
| 失敗時的行為 | 模型能夠解釋或能從中復原的錯誤。 |
請明確指定輸入。凡是執行操作時必須正確提供的值,例如識別碼或帳戶範圍,都不應由模型猜測。
請傳回穩定的識別碼,以及後續呼叫所需的足夠結構化資訊。結果中不應包含機密資訊、存取權杖、內部診斷資訊或非必要的個人資料。
撰寫說明,協助模型選擇工具
模型會根據工具說明,判斷工具何時適合處理某項要求。撰寫說明時,請著重於使用者的意圖,避免描述實作細節。
好的工具說明應做到以下幾點:
- 說明工具能做什麼。
- 解釋何時應使用這項工具。
- 說清楚它與類似工具的差異。
- 指出重要限制或先決條件。
請避免只重述工具名稱,也不要使用使用者不熟悉的內部服務術語。
規劃安全註記
請根據工具的實際行為設定註記。各項提示的正式定義、預設值及彼此之間的關係,請參閱 MCP 的 ToolAnnotations 結構描述。
readOnlyHint只有在工具無法變更狀態時才設為true。destructiveHint在工具可能造成不可逆或難以復原的結果時設為true。openWorldHint在工具會存取公開網際網路,或會接觸範圍不受限的外部對象時設為true。即使只執行網頁搜尋等唯讀動作,也適用這項規則。範圍明確的私人帳戶或工作區,即使由外部代管,也不會單憑這一點就被視為開放世界。
即使設定了註記,伺服器端仍須執行授權檢查與輸入驗證,並在執行影響重大的動作前要求確認。
檢查工具的涵蓋範圍與界線
將預計提供的工具與完整的使用情境清單逐一比對:
- 確認每個支援的使用情境都有可行的方法,讓使用者取得有用的結果。
- 找出沒有對應到任何已記錄使用情境的工具。
- 檢查是否缺少使用者在執行寫入動作前所需的讀取操作。
- 確認遇到不支援的要求時,系統會以易懂的方式說明限制,避免以不安全的方式勉強滿足要求。
- 測試兩個類似工具的說明是否有重疊之處,導致模型難以判斷該選哪一個。
保留這份工具規劃,作為實作與評估時的檢查清單。接著建置 MCP 伺服器,並分別使用具代表性、無效及未經授權的輸入測試每個工具的契約。