MCP Server

MCP Server 的三個核心原語（Resources、Tools、Prompts）各自的用途是什麼？什麼時候用哪個？

Resources（資源）：代表 MCP Server 能讓 Claude 讀取的資料。Resources 是「被動的」——Claude 可以請求讀取它們，但它們本身不執行任何操作。適合的場景：靜態或動態的資料存取（文件內容、資料庫記錄、API 快照）。每個 Resource 有一個 URI（如 file:///path/to/doc 或 db://customers/1234），Claude 可以通過這個 URI 讀取對應的內容。

Tools（工具）：代表 Claude 能執行的功能。Tools 是「主動的」——Claude 在判斷需要時可以呼叫它們，傳入參數，並接收執行結果。這是最常用的原語。適合的場景：任何你希望 Claude 能「做」的操作（搜尋、寫入、查詢、發送、轉換）。每個 Tool 有名稱、description、和輸入參數的 JSON Schema。

Prompts（提示詞範本）：代表預定義的提示詞工作流，讓 MCP Client 能快速呼叫標準化的任務。Prompts 是「可重用的任務範本」——使用者可以從 MCP Client 的介面直接選用，不需要每次都手動輸入完整的提示詞。適合的場景：你有標準化的工作流（「分析這份合約的關鍵風險」「生成週報摘要」），希望讓用戶能一鍵使用。

三者的選擇原則：如果你想讓 Claude 能讀取某個資料來源，用 Resources；如果你想讓 Claude 能執行某個操作，用 Tools；如果你有一個標準化的任務流程希望讓用戶能快速使用，用 Prompts。在大多數 MCP Server 的實作裡，Tools 是最核心的原語，Resources 和 Prompts 是補充。

怎麼用 Python 建構一個最基本的 MCP Server？最小可用版本的結構是什麼？

用 Anthropic 官方的 Python MCP SDK 建構一個最基本的 MCP Server，核心結構如下：

from mcp.server.fastmcp import FastMCP

# 建立 MCP Server 實例
mcp = FastMCP("my-server")

# 定義一個 Tool
@mcp.tool()
def search_documents(query: str, max_results: int = 5) -> str:
    """
    搜尋文件庫中的文件。
    適用於：用戶需要查找特定主題的文件時。
    不適用於：查找特定文件 ID（請用 get_document）。
    
    Args:
        query: 搜尋關鍵字
        max_results: 最多返回幾筆結果（預設 5）
    """
    # 實際的搜尋邏輯
    results = your_search_function(query, max_results)
    return format_results(results)

# 定義一個 Resource
@mcp.resource("docs://{doc_id}")
def get_document(doc_id: str) -> str:
    """通過 ID 讀取特定文件的完整內容。"""
    return your_db.get_document(doc_id)

if __name__ == "__main__":
    mcp.run()

最重要的設計決策：Tool 的 docstring。上面範例裡 search_documents 的 docstring 不是給人看的，是給 Claude 看的——Claude 完全靠這段文字決定什麼時候呼叫這個工具。一個好的 Tool docstring 應該包含：這個工具做什麼（一句話描述）、什麼情況下應該呼叫（適用場景）、什麼情況下不應該呼叫（排除場景）、輸入參數的含義和格式。

在 Claude Desktop 裡連接這個 Server：在 claude_desktop_config.json 裡加入：

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["/path/to/your/server.py"]
    }
  }
}

本地 MCP Server 和遠端（Remote）MCP Server 的技術差別和適用場景？

本地 MCP Server（Local）：跑在用戶自己電腦上的 MCP Server，通過 Standard I/O（stdio）和 MCP Client 通信。這是目前 Claude Desktop 最主要的 MCP 連接方式。

適合本地 Server 的場景：需要存取本地文件系統或本地資料庫；需要執行本地的命令列工具；用於個人開發和測試；涉及敏感資料、不適合傳到外部服務的情況。

遠端 MCP Server（Remote）：部署在雲端或企業伺服器上，通過 HTTP/HTTPS 和 Server-Sent Events（SSE）通信。多個用戶可以共用同一個遠端 Server。

適合遠端 Server 的場景：需要多個用戶共用同一個工具（如企業內部知識庫）；需要連接到外部 SaaS 服務（Slack、GitHub、Salesforce）；需要集中管理和更新（修改一次、所有用戶立刻用到新版本）；需要認證和授權（遠端 Server 更容易整合 OAuth 和 SSO）。

企業部署的選擇原則：對個人工具和本地資源，用本地 Server；對團隊共用的工具和需要集中管理的服務，用遠端 Server。很多企業的 MCP 架構是「混合型」——把公司內部系統連接部分做成遠端 Server，把個人工作流工具保留為本地 Server。

MCP Server 在生產環境部署時有哪些常見的錯誤和最佳實踐？

最常見的錯誤一：Tool description 太模糊

這是 MCP Server 最常見、影響最大的問題。「搜尋資訊」「查詢資料庫」這樣的描述讓 Claude 不知道什麼時候該用這個工具、和其他工具有什麼區別。好的 description 應該說清楚：適用場景、排除場景、和參數格式。

最常見的錯誤二：返回的資料量太大

Tool 返回幾千字的原始資料，讓 Claude 難以識別關鍵資訊。最好的做法是：Tool 在伺服器端做預處理，只返回 Claude 真正需要的關鍵欄位和摘要，而不是把整個資料庫記錄或文件原文返回。

最常見的錯誤三：沒有設計錯誤處理

Tool 執行失敗時（網路超時、資料不存在、API 限流），應該返回結構化的錯誤訊息（包含錯誤類型、原因、建議的下一步），而不是讓 Python 拋出未處理的異常。Claude 收到結構化的錯誤訊息後，能給用戶更有意義的回應。

最佳實踐：

用 MCP Inspector 工具（Anthropic 官方提供）在連接 Claude Desktop 之前先測試你的 Server，確認每個 Tool 能正確執行、返回格式符合預期。把 Tool 的輸入驗證做在 Server 端（使用 Pydantic 或 TypeScript 的 Zod），而不是依賴 Claude 傳入正確的參數。對需要多步驟操作的複雜任務，考慮把它拆成多個 Tools，讓 Claude 能分步驟執行和驗證，而不是一個 Tool 做所有事情。