這章要學會什麼
- 用官方 MCP 開發套件，在網站上開出一個專門給 AI 助理呼叫的入口。
- 在後臺把一個「已發布」的服務版本映射成 AI 看得懂的「工具」：指定工具名稱，平台自動帶入說明文字跟參數規格；名稱不合規則、規格不合 MCP 規定、名稱重複都會被拒絕。
- 寫出「列出工具」跟「呼叫工具」兩個處理程式：工具清單即時從資料庫讀出，版本一下架工具就自動消失，呼叫一律轉交給第 8 章的安全閘道。
- 分辨「協定層級的錯誤」（例如根本沒有這個工具）跟「工具本身執行失敗」（例如參數不符合規格）是兩種不同性質的錯誤。
- 用一個測試用的 AI 助理程式，完成探索工具、成功呼叫、參數錯誤、呼叫不存在的工具四種情境。
先備知識
要先完成第 8 章：呼叫服務會經過安全閘道，每次呼叫都留下紀錄。要記得第 1 章講過 MCP 的基本概念：AI 助理怎麼問「有哪些工具」、怎麼「呼叫工具」。
觀念白話講
為什麼需要多開一個「/mcp」入口
到第 8 章為止，只有管理員能在測試台裡呼叫上游服務。這門課真正的目標，是讓會員自己的 AI 助理（例如市面上的對話型 AI 產品，或內建在編輯器裡的 AI 助手）也能使用這些服務。AI 助理不會讀我們的網頁，它們講的是 MCP 這種公版協定，所以平台要多開一個入口，專門講這種語言。這個入口本身不重做任何安全檢查——它只負責把 MCP 的請求翻譯成內部格式，再轉交給第 8 章的安全閘道，版本狀態、規格驗證、允許清單、逾時、紀錄，全部沿用同一套。
官方套件跟兩個處理常式
MCP 的訊息格式是一套固定的訊息交換規範，自己手寫解析很容易出錯，所以這門課直接用官方維護的開發套件。套件提供兩種定義工具的方式：一種是把工具寫死在程式碼裡、編譯時就固定；另一種是自己註冊「怎麼列出工具清單」跟「怎麼呼叫工具」兩個處理常式，自己決定清單內容。這個平台的工具來自資料庫（管理員隨時可能新增映射、服務隨時可能被下架），所以選第二種寫法。
tools/list 跟 tools/call：AI 只會問這兩件事
AI 助理只需要問兩件事：「有哪些工具」跟「用這些參數執行這個工具」。「有哪些工具」這一步只會回傳「狀態是已發布」的服務對應到的工具，一旦服務被下架，下一次問這個問題時，這個工具就自動消失了——不需要另外寫程式去清理。
工具長什麼樣：名稱、描述、參數規格
| 欄位 | 來源 | 本課程的規則 |
|---|---|---|
| 名稱 | 管理員在映射頁指定 | 只能用小寫英文、數字、底線，以英文字母開頭；建立後不能再改，因為 AI 助理會記住這個名字 |
| 標題 | 服務名稱加版本 | 自動產生 |
| 描述 | 服務名稱、版本、用途說明 | AI 就是靠這段文字判斷「什麼時候該用這個工具」 |
| 參數規格 | 這個版本核准過的輸入規格 | 跟審核通過的內容完全相同；最外層一定要是「物件」型別，這是 MCP 的硬性規定 |
| 唯讀提示 | 依這個版本用的呼叫方法決定 | 提示 AI 這個工具會不會改變資料，讓某些助理決定要不要先問使用者一次 |
「協定錯誤」跟「工具錯誤」，AI 收到的意義完全不同
找不到工具屬於協定層級的錯誤——代表這次請求打從一開始就是錯的，重新送出也沒有用，AI 應該重新去問一次有哪些工具。而「參數不符合規格」「上游逾時」這類則是工具本身執行時的失敗，會正常回傳結果、只是標記成「有錯誤」並附上具體原因的文字說明——這樣設計是為了讓 AI 能讀懂錯誤內容，自己修正參數後重新嘗試。
老師示範做了什麼
示範情境：管理員把幾支已發布的服務映射成工具，過程中看到兩種映射被拒絕的情況；接著用一個測試用的 AI 助理程式探索並呼叫工具，得到成功、工具錯誤、協定錯誤三種結果；最後把其中一支服務下架，證明對應的工具會從清單消失。
老師依序嘗試映射幾種情況：工具名稱帶大寫字母跟空格被拒絕；名稱合規則的服務映射成功；某支服務因為參數規格不合硬性規定被拒絕；同一個名稱重複映射也被拒絕。接著用測試用的 AI 助理程式連線，列出目前所有工具，逐一測試：正常呼叫得到成功結果並附上追查代碼；帶入不合規格的參數得到工具錯誤，內容清楚寫著哪裡不符合規格；呼叫一個不存在的工具名稱，得到協定層級的錯誤。最後把其中一支服務下架，重新問一次工具清單，這支服務的工具確實消失，網站完全不需要重新啟動。
自己動手的步驟
步驟一：由已發布版本建立工具映射
映射的規則要求三項都通過才會真正寫入：名稱符合命名規則、版本必須是已發布狀態、參數規格的最外層必須是「物件」型別。都通過後才寫入一筆工具定義，說明文字自動組成「服務名稱（版本）：用途說明」，參數規格則直接複製自這個版本核准過的內容。
步驟二：暫時的開發用通行憑證
因為 /mcp 這個入口不能用網站的登入憑證（AI 助理沒有瀏覽器），這一章先設計一組固定的通行憑證：請求標頭裡帶著正確的憑證字串才能通過，沒帶或帶錯一律回傳「未認證」。比對這段字串時要用「固定耗時」的比對方式，而不是遇到第一個不同字元就提早結束比對——否則有心人可以透過量測回應時間的細微差異，一個字元一個字元把正確答案猜出來。
步驟三：建立 /mcp 端點與兩個處理常式
依序註冊：驗證方案（先前那組固定憑證的驗證邏輯）、MCP 伺服器本身、「列出工具」跟「呼叫工具」兩個處理常式，最後把 /mcp 這個網址掛上去、要求一定要通過驗證才能使用。「列出工具」只選「對應版本狀態是已發布」的工具，依名稱排序後轉換成 MCP 格式。「呼叫工具」先用工具名稱查出對應的版本，查不到就丟出協定層級的錯誤；查得到的話，把參數重新包裝成安全閘道看得懂的請求格式，交給它處理，再把結果包成 MCP 要的回應格式——內容第一段是實際的回應或錯誤說明，第二段固定是追查代碼，方便使用者回報問題時附上。
步驟四：寫一個測試用戶端
用官方套件寫一個主控台程式，模擬「一個真正的 AI 助理」：連線、握手、列出工具、依序呼叫幾個測試案例（正常參數、不合規格的參數、不存在的工具名稱），把結果印出來當作驗收依據。
常見錯誤
| 症狀 | 原因 | 怎麼處理 |
|---|---|---|
| 測試用戶端回報一個籠統的錯誤，看不出細節 | 伺服器端處理常式內部丟出例外時，套件只把籠統的訊息回傳給用戶端，不會外洩內部細節 | 回頭看網站自己的主控台輸出，裡面才有完整的例外訊息 |
| 某支服務映射之後，整個「列出工具」都失敗 | 那支服務的參數規格最外層不是「物件」型別，只要有一筆不合格，整個清單都會壞掉 | 把那筆映射記錄刪除；映射的時候要事先檢查這個條件再放行 |
| 帶了正確的通行憑證，卻還是一直被拒絕 | 設定檔裡的鍵名跟程式讀取的屬性名稱兜不起來，讀取時不會報錯，只是安靜地維持空值 | 仔細核對設定節點跟鍵名是否完全一致 |
怎麼驗收＋反向驗證
- 能探索：測試用戶端能列出所有已映射的工具，每個都有名稱跟清楚的說明文字。
- 能呼叫：正常參數呼叫得到成功結果與正確內容。
- 參數格式錯誤 → 工具錯誤：不合規格的參數得到明確的錯誤說明，而且上游完全沒有收到請求。
- 呼叫不存在的工具 → 協定錯誤：回傳固定格式的協定層級錯誤，沒有任何正常結果內容。
- 每次結果都能追查：成功跟工具錯誤都附有追查代碼，在呼叫紀錄裡查得到同一組代碼、對應的會員與工具名稱。
- 反向驗證：帶錯誤的通行憑證完全連不上；把一支已映射的服務下架後，它的工具立刻從清單消失，呼叫它會得到協定錯誤。