typescript-mcp-server-generator

生成 TypeScript MCP 伺服器

建立一個完整的 Model Context Protocol (MCP) 伺服器，使用 TypeScript，並符合以下規格：

需求

1. 專案結構：建立新的 TypeScript/Node.js 專案，並有適當的目錄結構
2. NPM 套件：包含 @modelcontextprotocol/sdk、zod@3，以及 express（用於 HTTP）或 stdio 支援
3. TypeScript 設定：正確的 tsconfig.json，支援 ES 模組
4. 伺服器類型：選擇 HTTP（使用 Streamable HTTP 傳輸）或基於 stdio 的伺服器
5. 工具：至少建立一個有用的工具，並有正確的 schema 驗證
6. 錯誤處理：包含全面的錯誤處理與驗證

實作細節

專案設定

• 使用 npm init 初始化，並建立 package.json
• 安裝相依套件：@modelcontextprotocol/sdk、zod@3，以及傳輸相關套件
• 設定 TypeScript 使用 ES 模組：在 package.json 中加入 "type": "module"
• 加入開發相依套件：tsx 或 ts-node 用於開發
• 建立適當的 .gitignore 檔案

伺服器設定

• 使用 McpServer 類別進行高階實作
• 設定伺服器名稱與版本
• 選擇適當的傳輸方式（StreamableHTTPServerTransport 或 StdioServerTransport）
• 對於 HTTP：使用 Express 並設定適當的中介軟體與錯誤處理
• 對於 stdio：直接使用 StdioServerTransport

工具實作

• 使用 registerTool() 方法，並提供描述性名稱
• 使用 zod 定義輸入與輸出的 schema 驗證
• 提供明確的 title 與 description 欄位
• 在結果中同時回傳 content 與 structuredContent
• 使用 try-catch 區塊實作適當的錯誤處理
• 在適當情況下支援非同步操作

資源/提示設定（選用）

• 使用 registerResource() 搭配 ResourceTemplate 加入資源，支援動態 URI
• 使用 registerPrompt() 加入提示，並搭配引數 schema
• 考慮加入完成支援以提升使用者體驗

程式碼品質

• 使用 TypeScript 確保型別安全
• 一致地使用 async/await 模式
• 在傳輸關閉事件中實作適當的清理
• 使用環境變數進行設定
• 為複雜邏輯加入行內註解
• 程式碼結構要有清楚的關注點分離

可考慮的工具類型範例

• 資料處理與轉換
• 外部 API 整合
• 檔案系統操作（讀取、搜尋、分析）
• 資料庫查詢
• 文字分析或摘要（搭配取樣）
• 系統資訊擷取

設定選項

• 對於 HTTP 伺服器：

  • 透過環境變數設定連接埠
  • 為瀏覽器客戶端設定 CORS
  • 工作階段管理（無狀態 vs 有狀態）
  • 本機伺服器的 DNS 重新綁定保護

• 對於 stdio 伺服器：

  • 正確的 stdin/stdout 處理
  • 基於環境的設定
  • 程序生命週期管理

測試指引

• 說明如何執行伺服器（npm start 或 npx tsx server.ts）
• 提供 MCP Inspector 指令：npx @modelcontextprotocol/inspector
• 對於 HTTP 伺服器，包含連線 URL：http://localhost:PORT/mcp
• 包含範例工具呼叫
• 加入常見問題的疑難排解提示

可考慮的額外功能

• 支援取樣，用於 LLM 驅動的工具
• 使用者輸入提示，用於互動式工作流程
• 動態工具註冊，具備啟用/停用功能
• 通知去抖動，用於批次更新
• 資源連結，用於高效的資料參考

生成一個完整、可上線的 MCP 伺服器，包含全面的文件、型別安全與錯誤處理。