Claude Code｜設計 MCP 工具名稱、輸入 Schema 與分頁

MCP 連線成功之後，下一個問題是工具能不能被正確使用。本篇設計 list_tasks 與 get_task 的分工、輸入 Schema、查無資料及分頁結果，並用真正的 MCP 客戶端檢查空結果、錯誤參數和多頁資料，最後再觀察 Claude 是否選對工具。

先讀自建唯讀 MCP。下載第 80 篇材料，進入 starter。需要 Node.js 22 以上；執行 npm ci --ignore-scripts 安裝鎖定版本。真實 Claude 呼叫需要有效登入。閱讀約 20 分鐘，實作約 45 分鐘。

把清單查詢與單筆查詢分開

閱讀完整文字說明

設計 MCP 工具名稱、輸入 Schema 與分頁，以流程和文件圖形呈現教學重點。

list_tasks 回答「有哪些符合條件的項目」，接受 offset、limit 與可選的 completed。get_task 回答「這個 id 的項目是什麼」，只接受 id。兩個工具名字與描述應讓使用者理解用途，不需要先猜 query、action、mode 的多層組合。

本課只有三筆固定假資料：a、c 未完成，b 已完成；a 與 c 標題相同但 id 不同。固定資料讓你能明確驗證回應，不會因資料在測試中被其他人修改而難以比較。實際系統的清單可能變動，屆時還要考慮排序、游標或快照一致性。

清單工具每頁最多二十筆，預設兩筆；offset 從零開始。回應包含 items、nextOffset、total。最後一頁 nextOffset=null，讓呼叫者知道真正結束。不要只回傳前二十筆卻沒有下一頁資訊，否則模型可能把部分資料誤當成全部。

用 Schema 拒絕不合法輸入

材料使用已鎖定的 MCP TypeScript SDK v2 套件與 Zod。inputSchema 是 z.object，offset 與 limit 要是整數，completed 必須是布林值。字串 "false" 不是布林 false；若靜默轉型，呼叫者可能以為已過濾，實際卻得到另一組結果。

import {z} from 'zod';
export const listInput = z.object({
  offset: z.number().int().min(0).default(0),
  limit: z.number().int().min(1).max(20).default(2),
  completed: z.boolean().optional()
});

Schema 驗證與資料存取層的檢查可以互補。材料的 data.mjs 也檢查分頁與 completed，因此直接呼叫資料函式時不會完全失去基本契約。兩層規則應一致，不能一層允許 limit=100，另一層再無聲截成二十。

get_task 的 id 必須是非空字串。合法但不存在的 id 是資料結果，回傳 found=false、item=null；空字串是不合法輸入，應回報驗證錯誤。這兩個情況分開，讀者才知道是修改查詢資料，還是修正呼叫程式。

把工具回應與內層資料分開讀

MCP 呼叫回應有自己的結構，本課將業務資料放在文字 content 裡的 JSON。客戶端先判斷工具是否回報 isError，再解析內層資料。不要直接對所有回應執行 JSON.parse，假設錯誤訊息也一定符合成功資料形狀。

{"found":false,"item":null}

{
  "items": [{"id":"c","title":"買牛奶","completed":false}],
  "nextOffset": null,
  "total": 3
}

第二個區塊展示回應形狀，title 應以你材料的實際 fixture 為準；驗證識別碼、筆數及分頁結束，不依賴示例文案。沒有資料時 items 是空陣列、nextOffset 為 null，仍是成功查詢。不要把空清單誤標成伺服器故障。

readOnlyHint 說明工具用途，但不會自動把寫入程式禁止。本課的唯讀性來自伺服器只有讀取 fixture 和回傳資料的路徑。新增寫入功能時需要重新設計工具、授權與驗證，不能保留同一個提示就繼續聲稱唯讀。

先用真實客戶端跑完整契約

執行 contract-probe，客戶端會建立 stdio 連線、逐頁取資料，最後查一個不存在 id 及超過末頁的 offset。預期 ids 是 a、b、c；missing 包含 found=false；empty.items 為空。腳本 finally 關閉客戶端，避免完成後留著伺服器程序。

node mcp/contract-probe.mjs
node --test tests/mcp.test.mjs

測試包含 limit=0、limit=21、offset=-1 與 completed="false"，預期工具錯誤；也包含合法的 completed=false，預期 a、c。這些是透過 MCP 客戶端送入伺服器的測試，不只是直接呼叫資料函式，因此能發現 Schema 或封裝層的差異。

分頁迴圈另外限制最多頁數並記錄已見 offset。若伺服器錯誤地一直回傳同一個 nextOffset，客戶端應停止並回報異常，而不是永遠查下一頁。上限是故障控制，超出時需要明確錯誤，不能把已讀部分當成完整成功結果。

觀察 Claude 是否選對工具

使用上一篇的 fixtures.mcp.json 在本機啟動 Claude，先查看 /mcp，再分別要求「列出所有未完成項目」與「查詢 id=b」。第一個任務應使用清單及篩選，第二個適合單筆查詢。保存實際工具名稱、參數與回應，不只看最後自然語言答案。

使用 todo-lab 的工具列出所有未完成待辦，回報 id 與數量。
如果有下一頁，繼續到 nextOffset 為 null，再說明總數。

使用 todo-lab 查詢 id=b，不修改任何資料。

若模型用清單找 b，結果可能仍正確，但你可以分析工具描述是否足夠清楚。不要只因它沒使用你偏好的工具就判定業務答案錯誤；分別評估工具選擇、資料完整性與實際成本。需要引導單筆查詢時，改善描述並以同一個任務重測。

查詢未知 id 時，模型應說明沒有找到，不自行編造內容；清單需要多頁時，不應只讀第一頁就回答全部。本課假資料很少，因此可直接人工核對。擴充到大量資料時，保留相同契約及已知結果的測試集合。

故障練習：無聲截斷與空值

在獨立副本中讓 list_tasks 固定只回兩筆，卻把 nextOffset 改為 null。重跑契約測試，應發現完整 id 集合少了 c。這個失敗不是模型能力問題，是工具說了一個不正確的完成訊號；先修正伺服器，再重新觀察模型。

另一個案例是把 get_task 的未知結果改成空物件，保留客戶端的原契約。預期檢查會發現 found 與 item 缺少。回應欄位是介面的一部分，不能因為「看起來也是沒資料」就任意變更。需要改契約時，文件、客戶端與測試應一起更新。

完成判準與小練習

交付兩個工具契約、實際協定測試、分頁探測輸出與 Claude 工具選擇紀錄。帳號未登入時，協定測試可完成，但模型選擇欄位仍為待測。資料 fixture 前後應相同，不能因查詢測試把原始內容改掉。

小練習是加入只查已完成項目的案例，確認 total 指的是篩選後的數量，並在描述中寫清楚。接著以MCP 故障實驗測試斷線和逾時，再用JSON 流程思考下游如何驗證工具結果，避免只靠自然語言聲稱成功。

回 Claude Code 教學總目錄

• AI 工具
• 教學
• Claude Code