python-mcp-server-generator

產生 Python MCP 伺服器

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

需求

1. 專案結構：使用 uv 建立具有適當結構的新 Python 專案
2. 相依套件：使用 uv 加入 mcp[cli] 套件
3. 傳輸類型：選擇 stdio（用於本機）或 streamable-http（用於遠端）
4. 工具：建立至少一個有用的工具，並附帶適當的型別提示
5. 錯誤處理：包含全面的錯誤處理和驗證

實作細節

專案設定

• 使用 uv init project-name 初始化
• 加入 MCP SDK：uv add "mcp[cli]"
• 建立主要伺服器檔案（例如 server.py）
• 為 Python 專案加入 .gitignore
• 使用 if __name__ == "__main__" 設定直接執行

伺服器設定

• 使用 FastMCP 類別（來自 mcp.server.fastmcp）
• 設定伺服器名稱和可選的說明
• 選擇傳輸方式：stdio（預設）或 streamable-http
• 對於 HTTP：可選設定主機、連接埠和無狀態模式

工具實作

• 在函式上使用 @mcp.tool() 裝飾器
• 務必包含型別提示——它們會自動產生結構定義
• 撰寫清晰的 docstring——它們會成為工具描述
• 使用 Pydantic 模型或 TypedDict 處理結構化輸出
• 支援非同步操作以處理 I/O 密集型任務
• 包含適當的錯誤處理

資源/提示設定（可選）

• 使用 @mcp.resource() 裝飾器加入資源
• 使用 URI 模板處理動態資源："resource://{param}"
• 使用 @mcp.prompt() 裝飾器加入提示
• 從提示中回傳字串或訊息列表

程式碼品質

• 為所有函式參數和回傳值使用型別提示
• 為工具、資源和提示撰寫 docstring
• 遵循 PEP 8 風格指南
• 使用 async/await 處理非同步操作
• 實作 context manager 以清理資源
• 為複雜邏輯加入行內註解

可考慮的工具類型範例

• 資料處理與轉換
• 檔案系統操作（讀取、分析、搜尋）
• 外部 API 整合
• 資料庫查詢
• 文字分析或生成（含取樣）
• 系統資訊擷取
• 數學或科學計算

設定選項

• 對於 stdio 伺服器：

  • 簡單的直接執行
  • 使用 uv run mcp dev server.py 測試
  • 安裝到 Claude：uv run mcp install server.py

• 對於 HTTP 伺服器：

  • 透過環境變數設定連接埠
  • 無狀態模式以利擴展：stateless_http=True
  • JSON 回應模式：json_response=True
  • 為瀏覽器客戶端設定 CORS
  • 掛載到現有的 ASGI 伺服器（Starlette/FastAPI）

測試指引

• 說明如何執行伺服器：
  • stdio：python server.py 或 uv run server.py
  • HTTP：python server.py 然後連線到 http://localhost:PORT/mcp
• 使用 MCP Inspector 測試：uv run mcp dev server.py
• 安裝到 Claude Desktop：uv run mcp install server.py
• 包含範例工具呼叫
• 加入疑難排解提示

可考慮的額外功能

• 使用 Context 進行記錄、進度和通知
• LLM 取樣以實現 AI 驅動的工具
• 使用者輸入徵詢以實現互動式工作流程
• 生命週期管理以處理共享資源（資料庫、連線）
• 使用 Pydantic 模型的結構化輸出
• 用於 UI 顯示的圖示
• 使用 Image 類別處理圖片
• 自動完成支援以改善使用者體驗

最佳實務

• 隨處使用型別提示——它們不是可選的
• 盡可能回傳結構化資料
• 記錄到 stderr（或使用 Context 記錄）以避免 stdout 污染
• 正確清理資源
• 及早驗證輸入
• 提供清晰的錯誤訊息
• 在整合 LLM 之前獨立測試工具

產生一個完整、可上線的 MCP 伺服器，具備型別安全、適當的錯誤處理和全面的文件說明。