# MCP Server 開發指南

## 什麼是 MCP Server

MCP (Model Context Protocol) Server 是一個讓 AI 應用程式能夠存取外部工具和資料的伺服器。它可以提供三種功能：

### 1. Tools (工具)
LLM 可以主動呼叫的函式來執行操作。

**使用情境**: 當 LLM 需要執行某個動作時（如計算、API 呼叫、資料庫操作），它會選擇適當的 tool 並傳入參數執行。

**LLM 使用方式**:
- LLM 會根據 tool 的 description 決定是否使用
- LLM 根據 inputSchema 準備正確的參數
- Tool 執行後，結果會回傳給 LLM 繼續對話

**範例對話流程**:

User: "15 乘以 23 等於多少？"
LLM 思考: 需要計算，我有 calculate tool 可用
LLM 動作: 呼叫 calculate(operation="multiply", a=15, b=23)
Tool 回應: {"result": 345, "operation": "multiply"}
LLM 回覆: "15 乘以 23 等於 345"

### 2. Resources (資源)
提供上下文資料的來源（檔案、資料庫、API 內容）。

**使用情境**: Resource 不是讓 LLM 主動呼叫的，而是讓 LLM 能夠「讀取」某個資料來源的內容。當用戶要求 LLM 存取特定資料時，LLM 會讀取 resource 的內容作為上下文。

**LLM 使用方式**:
- LLM 看到 resource 清單，知道有哪些資料可以存取
- 當用戶提到需要某個資料時，LLM 會讀取對應的 resource URI
- Resource 的內容會被載入到 LLM 的上下文中
- LLM 基於這些內容來回答問題

**範例對話流程**:

User: "user://12345 的電子郵件是什麼？"
LLM 思考: 用戶要求存取 user://12345 resource
LLM 動作: 讀取 resource "user://12345"
Resource 內容: {"id": "12345", "name": "User 12345", "email": "[e-mail]", ...}
LLM 回覆: "用戶 12345 的電子郵件是 [e-mail]"

**Tool vs Resource 的差異**:
- **Tool**: LLM 主動執行動作（寫入、計算、API 呼叫）
- **Resource**: LLM 被動讀取資料（檔案內容、資料庫記錄、文件）

### 3. Prompts (提示模板)
預先定義的對話模板，用於結構化常見的互動模式。

**使用情境**: Prompt 是一個「快捷方式」，讓用戶可以快速套用預先設計好的提示詞範本。當用戶選擇某個 prompt 時，系統會用指定的參數生成完整的提示訊息。

**LLM 使用方式**:
- Prompts 主要是給「用戶」使用，不是給 LLM 自己使用
- 用戶在 UI 中選擇一個 prompt（如 "code-review"）
- 填入必要參數（如程式碼、語言、聚焦項目）
- 系統生成完整的 prompt 訊息傳給 LLM
- LLM 收到的是已經格式化好的問題

**範例使用流程**:

User 在 UI: 選擇 "code-review" prompt
User 填入: language="Python", code="def add(a,b): return a+b", focus="security"
系統生成: "Please review the following Python code, focusing on security vulnerabilities and best practices:\n\n```python\ndef add(a,b): return a+b\n```"
LLM 收到: (上述完整訊息)
LLM 回覆: (進行程式碼安全審查)

**Prompt 的價值**:
- 確保提示詞的一致性和品質
- 節省用戶重複輸入相同結構的提示
- 可以封裝複雜的提示詞工程技巧

## 實際應用案例

### Resource 實際使用案例

**案例 1: 文件系統伺服器**
- **Server**: `@modelcontextprotocol/server-filesystem`
- **Resource**: 提供檔案系統存取，如 `file:///path/to/file.txt`
- **使用方式**:

  User: "請總結 file:///docs/report.md 的內容"
  Claude: 讀取 file:///docs/report.md → 取得文件內容 → 總結

**案例 2: GitHub 儲存庫伺服器**
- **Server**: `@modelcontextprotocol/server-github`
- **Resource**: 提供 GitHub repo 內容，如 `github://owner/repo/file.ts`
- **使用方式**:

  User: "github://facebook/react/README.md 說了什麼？"
  Claude: 讀取該 resource → 取得 README 內容 → 回答問題

**案例 3: 資料庫查詢結果**
- **Server**: 自訂 PostgreSQL MCP server
- **Resource**: 提供資料表內容，如 `postgres://users/table`
- **使用方式**:

  User: "postgres://users/active 這些用戶的平均年齡是多少？"
  Claude: 讀取 active users 資料 → 計算平均年齡 → 回答

### Prompt 實際使用案例

**案例 1: Git Commit Message 生成器**
- **Prompt**: `git-commit`
- **參數**: `changes` (變更描述)
- **UI 操作**:
1. 用戶選擇 "git-commit" prompt
2. 貼上變更內容：「Added user authentication, fixed login bug」
3. 系統生成完整 prompt 給 Claude
4. Claude 回覆標準格式的 commit message

**案例 2: Bug Report 模板**
- **Prompt**: `bug-report`
- **參數**: `title`, `steps`, `expected`, `actual`
- **UI 操作**:
1. 用戶選擇 "bug-report" prompt
2. 填入各欄位
3. Claude 收到結構化的 bug report prompt
4. Claude 生成完整且格式正確的 bug report

**案例 3: API 文件生成器**
- **Prompt**: `api-documentation`
- **參數**: `endpoint`, `method`, `parameters`
- **UI 操作**:
1. 用戶選擇 "api-documentation" prompt
2. 填入 API 資訊
3. Claude 生成標準化的 API 文件

## 為什麼 Resources 和 Prompts 需要用戶主動使用？

### Resources 的設計理念
Resources 設計為「被動讀取」是為了：
1. **安全性**: LLM 不能隨意讀取所有檔案，必須由用戶明確指定
2. **效能**: 只在需要時載入資料，避免浪費 context window
3. **明確性**: 用戶清楚知道 LLM 存取了哪些資料來源

實際上在支援 MCP 的 IDE（如 Claude Desktop、Cursor）中，當你提到某個檔案路徑或 URI 時，系統會自動建議可用的 resources，讓存取變得很方便。

### Prompts 的設計理念
Prompts 設計為「用戶選擇」是為了：
1. **可重複性**: 確保相同任務使用相同的提示詞結構
2. **專業性**: 封裝 prompt engineering 的最佳實踐
3. **效率**: 快速套用複雜的提示詞模板

在實際使用中，IDE 會在適當時機顯示相關的 prompts 供你選擇，就像是程式碼片段（snippets）一樣方便。

## MCP Client 功能支援比較

不同的 MCP clients 對 MCP 功能的支援程度不同：

### IDE / 編輯器

#### Cursor
根據社群討論，**Cursor 目前只支援 Tools**。
**支援功能**:
- ✅ Tools
- ❌ Resources (計劃中)
- ❌ Prompts (計劃中)

**Note**: Cursor 論壇有多個討論串詢問 Resources 和 Prompts 支援，目前尚未實作。

#### Kiro
**支援功能**:
- ✅ Tools (完整支援)
- ✅ Resources (完整支援)
- ✅ Prompts (完整支援)
- ✅ 完整 MCP 支援

**特點**:
- AWS 推出的 agentic IDE（基於 VS Code fork）
- 專注於 spec-driven development
- 內建 MCP 支援，配置位於 `.kiro/settings/mcp.json`
- 與 Claude Code 整合良好
- 提供 spec 和 steering documents 管理

**注意**: Kiro 是獨立的 IDE，不是 VS Code extension。另有第三方 extension "Kiro for Claude Code" 提供類似功能於 VS Code 中。

**文件**: https://kiro.dev/docs/guides/learn-by-playing/07-extending-kiro-with-mcp/
**官網**: https://kiro.dev/

#### VS Code Copilot
**支援功能**:
- ✅ Tools (完整支援)
- ✅ Resources (完整支援)
- ❌ Prompts (不支援)

**特點**:
- VS Code 1.102+ 正式支援 MCP（GA）
- 可透過 `copilot-mcp` extension 管理 MCP servers
- 支援本地和遠端 MCP servers
- 官方提供 GitHub MCP server（可透過 Copilot Chat 操作 GitHub）
- 企業可透過 group policies 管理 MCP 功能

**文件**: https://code.visualstudio.com/docs/copilot/customization/mcp-servers
**Extension**: https://marketplace.visualstudio.com/items?itemName=AutomataLabs.copilot-mcp

#### Cline (VS Code Extension)
**支援功能**:
- ✅ Tools (完整支援)
- ✅ Resources (完整支援)
- ✅ Prompts (完整支援)
- ✅ 完整 MCP 支援

**特點**:
- 開源 AI coding assistant (前身為 Claude Dev)
- 支援多種 LLM providers
- 完整 MCP 協定支援
- MCP Marketplace 提供預設 servers
- 支援 MCP Rules 進行智能工具啟動
- 可透過 `.clinerules` 自訂 MCP 伺服器觸發邏輯

**文件**: https://docs.cline.bot/mcp/mcp-overview
**Marketplace**: https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev

#### Continue (VS Code Extension)
**支援功能**:
- ✅ Tools
- ✅ Resources
- ✅ Prompts
- ✅ 完整 MCP 支援

#### Roo Code (VS Code Extension)
**支援功能**:
- ✅ Tools
- ❌ Resources
- ❌ Prompts

### AI 平台
#### Claude Desktop
**支援功能**:
- ✅ Tools
- ✅ Resources
- ✅ Prompts
- ✅ 完整 MCP 支援

#### ChatGPT (OpenAI)
**支援功能**:
- ✅ Tools (完整支援)
- ✅ Resources (完整支援)
- ⚠️ Prompts (文件未明確說明)

**特點**:
- OpenAI 於 2025 年 1 月正式支援 MCP
- ChatGPT Developer Mode (beta) 提供完整 MCP client 支援
- 支援 read/write tools
- Workspace admins 可為 Deep Research 建立 custom MCP connectors
- 透過 OpenAI Agents SDK 整合 MCP
- 支援 MCP server tools 於 ChatGPT developer mode

**文件**: https://platform.openai.com/docs/mcp
**Agents SDK**: https://openai.github.io/openai-agents-python/mcp/

#### Google AI Studio
**支援功能**:
- ❌ Tools (無原生 MCP 支援)
- ❌ Resources (無原生 MCP 支援)
- ❌ Prompts (無原生 MCP 支援)

**特點**:
- Google 官方的 web-based AI 開發平台
- 主要用於 prompt 設計和 Gemini API 測試
- **不支援原生 MCP 協定**
- 可透過第三方瀏覽器擴充功能（如 MCP SuperAssistant）間接使用 MCP
- 適合快速原型開發和 API 測試

**官網**: https://aistudio.google.com/
**注意**: Google AI Studio 本身不支援 MCP，需要透過外部工具整合

### CLI 工具

#### Codex CLI (OpenAI)
**支援功能**:
- ✅ Tools (完整支援)
- ✅ Resources (完整支援)
- ⚠️ Prompts (文件未明確說明)

**特點**:
- OpenAI 官方發布的輕量級 coding agent
- 在 terminal 中運行
- 支援 MCP servers（透過 `~/.codex/config.toml` 配置）
- 支援圖片分享（截圖、線框圖、架構圖）
- 內建 to-do list 追蹤進度
- 內建 web search 功能

**重要**:
- Codex CLI 支援 MCP
- Codex Cloud (SWE Agent) **目前不支援 MCP**（有社群討論要求加入）
- Codex IDE extension 支援 MCP

**文件**: https://developers.openai.com/codex/cli/
**GitHub**: https://github.com/openai/codex
**MCP 配置**: https://developers.openai.com/codex/mcp

#### Claude CLI / Claude Code (Anthropic)
**支援功能**:
- ✅ Tools (完整支援)
- ✅ Resources (完整支援)
- ✅ Prompts (完整支援)

**特點**:
- Anthropic 官方產品
- MCP 協定的創始者，支援最完整
- 支援 local 和 remote MCP servers
- Claude Desktop Extensions 提供一鍵安裝 MCP servers
- 可透過 gh CLI 與 GitHub 互動

**文件**: https://docs.claude.com/en/docs/claude-code/mcp
**Desktop Extensions**: https://www.anthropic.com/engineering/desktop-extensions
**Remote MCP**: https://www.anthropic.com/news/claude-code-remote-mcp

#### Gemini CLI (Google)
**支援功能**:
- ✅ Tools (完整支援)
- ✅ Resources (完整支援)
- ✅ Prompts (完整支援)

**特點**:
- Google 官方發布
- 完整 MCP 支援
- 適合 terminal 工作流程

### 框架整合

#### LangChain / LangGraph
**langchain-mcp-adapters** 套件支援：
- ✅ Tools (MCP tools → LangChain tools)
- ✅ Resources (可轉換為 context)
- ⚠️ Prompts (需要自行整合)

**特點**:
- 可以將 MCP servers 整合到 LangGraph workflows
- 支援將 LangGraph agents 作為 MCP server 暴露
- 雙向整合：MCP → LangChain 和 LangChain → MCP

**套件**: `langchain-mcp-adapters`
**文件**: https://langchain-ai.github.io/langgraph/agents/mcp/

#### GenAIScript (Microsoft)
**支援功能**:
- ✅ Tools (可將 scripts 暴露為 MCP tools)
- ✅ Resources (支援 https, file, git, gist, vscode 等協定)
- ✅ Prompts (可用 JavaScript 組裝)
- ✅ 雙向整合：可作為 MCP client 也可作為 MCP server

**特點**:
- 由 Microsoft 開發的 JavaScript/TypeScript 框架
- 專門用於程式化組裝 LLM prompts
- 內建 MCP tool 驗證和安全功能

**文件**: https://microsoft.github.io/genaiscript/
**MCP 整合**: https://microsoft.github.io/genaiscript/reference/scripts/mcp-tools/

### 開發策略建議

- 優先開發 Tools（所有 clients 都支援）
- 根據目標 client 的支援程度決定是否實作 Resources 和 Prompts
- 選擇框架時，需考慮所需 MCP 功能的支援程度（LangChain/LangGraph 支援 Tools 和 Resources，GenAIScript 支援完整功能）
- 參考上方「MCP Client 功能支援比較」表格評估需求

## 開發環境設定

### TypeScript

npm install @modelcontextprotocol/sdk zod

### Python

pip install mcp
# 或使用 uv
uv add mcp

## 快速開始

完整的開發範例和程式碼請參考：

- **官方文件**: https://modelcontextprotocol.io/
- **快速入門教學**: https://modelcontextprotocol.io/quickstart/server
- **TypeScript SDK**: https://github.com/modelcontextprotocol/typescript-sdk
- **Python SDK**: https://github.com/modelcontextprotocol/python-sdk
- **實際案例集合**: https://www.pulsemcp.com/use-cases
- **完整教學**: https://www.dailydoseofds.com/model-context-protocol-crash-course-part-4/
- **Prompts 進階指南**: https://www.speakeasy.com/mcp/building-servers/advanced-concepts/prompts

## 常見 MCP Servers

以下是一些實際可用的 MCP servers，可以直接安裝使用：

### 檔案系統存取

npm install -g @modelcontextprotocol/server-filesystem

### GitHub 整合

npm install -g @modelcontextprotocol/server-github

### SQLite 資料庫

pip install mcp-server-sqlite

### Google Drive

npm install -g @modelcontextprotocol/server-gdrive

### Brave Search

npm install -g @modelcontextprotocol/server-brave-search

這些 servers 可以在 Claude Desktop 的設定檔中配置後立即使用，不需要自己開發。

## 測試你的 Server

### 使用 MCP Inspector

**TypeScript:**

npx @modelcontextprotocol/inspector npx tsx server.ts

**Python:**

uv run mcp dev server.py

### 整合到 Claude Desktop

編輯 `claude_desktop_config.json`：

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