建立一個遠端 MCP 連接器

建立一個無狀態的 Streamable-HTTP MCP 伺服器（TypeScript、@modelcontextprotocol/sdk），可作為 claude.ai 的自訂連接器，並選擇性地包含內嵌視覺卡片（MCP Apps），然後部署到 Vercel。經過真實專案（超過 30 個工具）驗證。

範本位於此檔案旁邊的 templates/ 目錄中。更詳細的說明在 references/ 目錄中；只在需要時閱讀：

references/mcp-apps-cards.md — 內嵌卡片：ui:// 資源、postMessage 協定、CSP、可點擊列表
references/deploy-vercel.md — Vercel 設定、部署、在 claude.ai 中重新加入連接器
references/gotchas.md — 實際耗費時間的陷阱（除錯前閱讀）

工作流程

釐清（只詢問無法推斷的事項）：資料/API 為何、唯讀或寫入、是否需要認證、是否要卡片或純文字。預設值：公開資料、唯讀、無認證、文字 + 卡片。
在撰寫程式碼前探測每個上游 API。 對每個端點執行 curl：狀態、回應格式、日期格式、速率限制、逾時設定、重新導向（301 表示 URL 已變更，例如 api.frankfurter.dev，而非 .app）。公開的 SPARQL/搜尋端點可能很慢：測量時間、保持查詢簡單、在程式碼中過濾。
從 templates/ 建立專案（複製 package.json、tsconfig.json、vercel.json、api/、src/、scripts/），重新命名 my-connector，執行 npm install。
在 src/server.ts 中撰寫工具（每個工具一個 registerTool）。遵守以下規則。
將每個工具加入 scripts/test-client.ts。 測試執行器會因未測試的工具、空輸出和 isError 而失敗。
在本機驗證：執行 npm run typecheck，然後執行 PORT=<新的埠號> npm run dev，確認日誌顯示「listening」（而非 EADDRINUSE），再執行 npm test -- http://localhost:<埠號>/mcp。目標：Untested tools: none. Problems: 0。
撰寫文件：README 工具表格（每個工具一行）、CONTRIBUTING、LICENSE。
提交、推送、部署必須在使用者同意後進行（請參閱 references/deploy-vercel.md），然後對實際運作的 URL 執行測試。
告知使用者在 claude.ai 中移除並重新加入連接器（它會快取工具列表），並提供 3-5 個簡短的測試提示。

工具設計規則

少而精、可正常運作的工具。名稱使用 snake_case 動詞：search_x、get_x、list_x。
每個輸入都使用 Zod schema 設定限制（min/max、default）；為每個欄位提供說明與範例。
描述以一到兩句話說明工具的回傳值與使用時機。模型會據此選擇工具。
註解：readOnlyHint: true, idempotentHint: true, destructiveHint: false，以及用於外部 API 的 openWorldHint: true。
將每個處理函式包在 safe(...) 中：上游失敗會變成帶有可讀訊息的 isError 結果，絕不導致當機。
在每個結果中標明資料來源。若資料是由社群編輯或為暫定性質，請予以說明。
絕不在缺少欄位時當機；改為回傳「unknown」。
打字容錯：若無符合結果，回傳「您是否想找」的建議，而非空結果。
快取上游呼叫（範本中的 getJson/getText 具有 TTL、進行中重複請求消除、短暫失敗快取、逾時設定）。即時資料使用短 TTL（分鐘），靜態資料使用小時。對免費 API 保持友善。
同時回傳文字（供模型使用）和 structuredContent（供卡片使用），可透過 card(text, data) 等輔助函式。
儲存庫中不包含機密資訊。如果需要金鑰，請從 process.env 讀取並記錄在文件中。
當上游查詢速度較慢時，應在程式碼中進行大量過濾，而非在上游查詢中進行。

無狀態伺服器（Vercel 友善）

每次請求都會建立全新的 McpServer 和傳輸層（src/handler.ts）；無工作階段，請求之間不保留記憶體。唯一的狀態是記憶體快取，其效果為盡力而為。處理常式中包含 CORS 和請求主體大小限制。api/mcp.ts 匯出 { fetch } 和 maxDuration: 30；vercel.json 將 /mcp 重寫至 /api/mcp。

卡片（MCP Apps），簡短版本

註冊一個 ui://… HTML 資源（mimeType: text/html;profile=mcp-app），然後為每個工具加上 _meta: { ui: { resourceUri }, "ui/resourceUri": resourceUri }，並回傳包含 kind 欄位的 structuredContent。HTML 是一個自包含的檔案，會根據 kind 進行渲染。請參閱 references/mcp-apps-cards.md 和 templates/src/view.ts。

提供給使用者的輸出

保持簡潔。回報：建置的內容（工具列表）、測試結果、URL，以及在 claude.ai 中重新整理連接器的確切步驟。誠實說明注意事項（未經驗證的 UI 路徑、上游速度慢、社群資料）。

create-connector