Node.js MCP Server

# MCP Server 操作手冊與使用說明 ## 📑 目錄 1. [MCP 簡介](#mcp-簡介) 2. [系統需求](#系統需求) 3. [安裝指南](#安裝指南) 4. [配置說明](#配置說明) 5. [工具使用指南](#工具使用指南) 6. [Claude Desktop 集成](#claude-desktop-集成) 7. [測試驗證](#測試驗證) 8. [故障排除](#故障排除) 9. [開發擴展](#開發擴展) 10. [最佳實踐](#最佳實踐) 11. [常見問題](#常見問題) --- ## 🔍 MCP 簡介 ### 什麼是 Model Context Protocol (MCP)？ Model Context Protocol (MCP) 是由 Anthropic 開發的開放標準協議，用於在 AI 模型和外部數據源、工具之間建立安全、標準化的連接。 ### 核心概念 - **Server（服務器）**：提供工具和資源的後端服務 - **Client（客戶端）**：使用工具和資源的 AI 應用（如 Claude Desktop） - **Tools（工具）**：可執行的功能，如文件操作、計算等 - **Resources（資源）**：可訪問的數據源，如文檔、API 等 - **Transport（傳輸）**：通信方式，通常使用 stdio ### 優勢 ✅ **統一標準**：提供一致的 API 接口 ✅ **安全可控**：嚴格的權限管理和驗證 ✅ **易於擴展**：模組化設計，方便添加新功能 ✅ **跨平台**：支持多種程式語言和操作系統 --- ## ⚙️ 系統需求 ### 最低要求 - **Node.js**: 18.0.0 或更高版本 - **npm**: 8.0.0 或更高版本 - **操作系統**: Windows 10+, macOS 10.15+, Linux (Ubuntu 18.04+) - **內存**: 至少 512MB 可用內存 - **硬碟空間**: 100MB 可用空間 ### 推薦環境 - **Node.js**: 20.x LTS - **npm**: 最新版本 - **TypeScript**: 5.x（開發時） - **VS Code**: 推薦的開發環境 ### 檢查系統版本 ```bash # 檢查 Node.js 版本 node --version # 檢查 npm 版本 npm --version # 檢查 TypeScript 版本（如果已安裝） npx tsc --version ``` --- ## 📦 安裝指南 ### 步驟 1：克隆或下載項目 ```bash # 如果您有 Git git clone <repository-url> cd nodejs-mcp-server # 或者直接下載並解壓到目標目錄 ``` ### 步驟 2：安裝依賴 ```bash # 安裝所有必要的依賴包 npm install ``` ### 步驟 3：建構項目 ```bash # 編譯 TypeScript 到 JavaScript npm run build ``` ### 步驟 4：驗證安裝 ```bash # 測試服務器是否正常啟動 npm start ``` 如果看到 "MCP Server running on stdio" 消息，表示安裝成功。 ### 安裝故障排除 #### 常見問題 **問題**: `npm install` 失敗 ```bash # 清除 npm 緩存 npm cache clean --force # 刪除 node_modules 並重新安裝 rm -rf node_modules package-lock.json npm install ``` **問題**: TypeScript 編譯錯誤 ```bash # 檢查 TypeScript 版本 npx tsc --version # 重新安裝 TypeScript npm install -g typescript ``` --- ## ⚙️ 配置說明 ### 項目結構 ``` nodejs-mcp-server/ ├── src/ # 源代碼目錄 │ ├── index.ts # 主服務器文件 │ └── tools/ # 工具模組目錄 │ ├── fileTools.ts # 文件操作工具 │ ├── calculatorTools.ts # 計算器工具 │ └── systemTools.ts # 系統信息工具 ├── dist/ # 編譯後的文件 ├── package.json # 項目配置 ├── tsconfig.json # TypeScript 配置 └── README.md # 項目說明 ``` ### 配置文件說明 #### package.json 包含項目元數據和依賴信息： ```json { "name": "nodejs-mcp-server", "version": "1.0.0", "scripts": { "build": "tsc", "start": "node dist/index.js", "dev": "tsc && node dist/index.js" } } ``` #### tsconfig.json TypeScript 編譯配置： ```json { "compilerOptions": { "target": "ES2022", "module": "ESNext", "outDir": "./dist", "rootDir": "./src" } } ``` ### 環境變量配置 可以通過環境變量自定義行為： ```bash # Windows set NODE_ENV=production set MCP_LOG_LEVEL=info # macOS/Linux export NODE_ENV=production export MCP_LOG_LEVEL=info ``` --- ## 🛠️ 工具使用指南 ### 文件操作工具 #### 1. read_file - 讀取文件 **功能**: 讀取指定文件的內容 **參數**: - `filepath` (string, 必需): 文件路徑 **範例**: ```json { "name": "read_file", "arguments": { "filepath": "./test.txt" } } ``` **注意事項**: - 支持相對路徑和絕對路徑 - 文件必須存在且可讀 - 支持 UTF-8 編碼 #### 2. write_file - 寫入文件 **功能**: 向指定文件寫入內容 **參數**: - `filepath` (string, 必需): 文件路徑 - `content` (string, 必需): 要寫入的內容 **範例**: ```json { "name": "write_file", "arguments": { "filepath": "./output.txt", "content": "Hello, MCP World!" } } ``` #### 3. list_directory - 列出目錄 **功能**: 列出指定目錄的內容 **參數**: - `dirpath` (string, 必需): 目錄路徑 **範例**: ```json { "name": "list_directory", "arguments": { "dirpath": "./" } } ``` #### 4. create_directory - 創建目錄 **功能**: 創建新目錄 **參數**: - `dirpath` (string, 必需): 要創建的目錄路徑 **範例**: ```json { "name": "create_directory", "arguments": { "dirpath": "./new_folder" } } ``` #### 5. delete_file - 刪除文件 **功能**: 刪除指定文件 **參數**: - `filepath` (string, 必需): 要刪除的文件路徑 **範例**: ```json { "name": "delete_file", "arguments": { "filepath": "./temp.txt" } } ``` ### 計算器工具 #### 1. calculate - 數學計算 **功能**: 執行數學表達式計算 **參數**: - `expression` (string, 必需): 數學表達式 **支持的運算**: - 基本運算: `+`, `-`, `*`, `/` - 函數: `sqrt()`, `sin()`, `cos()`, `tan()`, `log()`, `exp()`, `abs()` - 常數: `Math.PI`, `Math.E` **範例**: ```json { "name": "calculate", "arguments": { "expression": "sqrt(16) + sin(30) * 2" } } ``` #### 2. convert_units - 單位轉換 **功能**: 在不同單位之間進行轉換 **參數**: - `value` (number, 必需): 要轉換的數值 - `from_unit` (string, 必需): 原始單位 - `to_unit` (string, 必需): 目標單位 **支持的單位類型**: **長度單位**: - `meter`, `m` - 米 - `kilometer`, `km` - 公里 - `centimeter`, `cm` - 厘米 - `millimeter`, `mm` - 毫米 - `inch` - 英寸 - `foot`, `ft` - 英尺 - `yard` - 碼 - `mile` - 英里 **重量單位**: - `kilogram`, `kg` - 公斤 - `gram`, `g` - 克 - `pound`, `lb` - 磅 - `ounce`, `oz` - 盎司 - `ton` - 噸 **溫度單位**: - `celsius` - 攝氏度 - `fahrenheit` - 華氏度 - `kelvin` - 開爾文 **範例**: ```json { "name": "convert_units", "arguments": { "value": 100, "from_unit": "centimeter", "to_unit": "meter" } } ``` #### 3. statistics - 統計計算 **功能**: 計算數組的統計信息 **參數**: - `numbers` (array, 必需): 數字數組 **返回的統計信息**: - 數量、總和、平均值 - 中位數、最小值、最大值 - 方差、標準差 **範例**: ```json { "name": "statistics", "arguments": { "numbers": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] } } ``` ### 系統信息工具 #### 1. get_system_info - 系統信息 **功能**: 獲取系統基本信息 **範例**: ```json { "name": "get_system_info", "arguments": {} } ``` **返回信息包括**: - 操作系統類型和版本 - CPU 信息和核心數 - 內存使用情況 - 主機名和用戶目錄 #### 2. get_current_time - 當前時間 **功能**: 獲取當前時間和日期 **參數**: - `timezone` (string, 可選): 時區，例如 "Asia/Taipei" **範例**: ```json { "name": "get_current_time", "arguments": { "timezone": "Asia/Taipei" } } ``` #### 3. execute_command - 執行命令 **功能**: 執行安全的系統命令 **參數**: - `command` (string, 必需): 要執行的命令 **安全限制**: 只允許執行以下安全命令： - `ls`, `dir` - 列出文件 - `pwd` - 顯示當前目錄 - `whoami` - 顯示當前用戶 - `date` - 顯示日期 - `echo` - 輸出文字 - `node --version`, `npm --version` - 版本信息 - `ping -c 1`, `ping -n 1` - 網絡測試 **範例**: ```json { "name": "execute_command", "arguments": { "command": "node --version" } } ``` #### 4. get_network_info - 網絡信息 **功能**: 獲取網絡接口信息 **範例**: ```json { "name": "get_network_info", "arguments": {} } ``` #### 5. get_process_info - 進程信息 **功能**: 獲取當前進程信息 **範例**: ```json { "name": "get_process_info", "arguments": {} } ``` --- ## 🔗 Claude Desktop 集成 ### 配置 Claude Desktop #### 步驟 1：找到配置文件 **Windows**: ``` %APPDATA%\Claude\claude_desktop_config.json ``` **macOS**: ``` ~/Library/Application Support/Claude/claude_desktop_config.json ``` **Linux**: ``` ~/.config/Claude/claude_desktop_config.json ``` #### 步驟 2：添加 MCP 服務器配置 在配置文件中添加以下內容： ```json { "mcpServers": { "nodejs-mcp-server": { "command": "node", "args": ["D:\\開發練習\\MCPtest\\dist\\index.js"], "env": { "NODE_ENV": "production" } } } } ``` **重要**: 請將路徑替換為您的實際項目路徑。 #### 步驟 3：重啟 Claude Desktop 保存配置文件後，完全關閉並重新啟動 Claude Desktop。 #### 步驟 4：驗證連接 在 Claude Desktop 中，您應該能看到 MCP 服務器提供的工具。可以嘗試以下測試： 1. "請幫我計算 2 + 3 * 4" 2. "請獲取當前系統信息" 3. "請創建一個名為 test.txt 的文件，內容為 'Hello MCP'" ### 高級配置選項 #### 環境變量設置 ```json { "mcpServers": { "nodejs-mcp-server": { "command": "node", "args": ["path/to/dist/index.js"], "env": { "NODE_ENV": "production", "MCP_LOG_LEVEL": "info", "MCP_TIMEOUT": "30000" } } } } ``` #### 多個 MCP 服務器 ```json { "mcpServers": { "nodejs-mcp-server": { "command": "node", "args": ["path/to/nodejs-mcp/dist/index.js"] }, "python-mcp-server": { "command": "python", "args": ["path/to/python-mcp/server.py"] } } } ``` --- ## 🧪 測試驗證 ### 手動測試 #### 1. 基本連接測試 ```bash # 啟動服務器 node dist/index.js # 在另一個終端發送測試請求 echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | node dist/index.js ``` #### 2. 工具調用測試 ```bash # 測試計算器 echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "calculate", "arguments": {"expression": "2 + 3"}}}' | node dist/index.js ``` ### 自動化測試腳本 創建測試腳本 `test-runner.js`： ```javascript #!/usr/bin/env node import { spawn } from 'child_process'; class MCPTester { async testAllTools() { const tests = [ { name: "列出工具", request: { jsonrpc: "2.0", id: 1, method: "tools/list", params: {} } }, { name: "測試計算器", request: { jsonrpc: "2.0", id: 2, method: "tools/call", params: { name: "calculate", arguments: { expression: "2 + 3 * 4" } } } }, { name: "測試系統信息", request: { jsonrpc: "2.0", id: 3, method: "tools/call", params: { name: "get_system_info", arguments: {} } } } ]; for (const test of tests) { console.log(`\n🧪 ${test.name}...`); try { const result = await this.runTest(test.request); console.log(`✅ 成功: ${JSON.stringify(result).substring(0, 100)}...`); } catch (error) { console.log(`❌ 失敗: ${error.message}`); } } } async runTest(request) { return new Promise((resolve, reject) => { const server = spawn('node', ['dist/index.js'], { stdio: ['pipe', 'pipe', 'pipe'] }); let output = ''; server.stdout.on('data', (data) => { output += data.toString(); }); server.on('close', () => { try { const lines = output.split('\n').filter(line => line.trim()); const response = JSON.parse(lines[lines.length - 1]); resolve(response); } catch (e) { reject(e); } }); server.stdin.write(JSON.stringify(request) + '\n'); server.stdin.end(); setTimeout(() => { server.kill(); reject(new Error('Test timeout')); }, 5000); }); } } // 運行測試 new MCPTester().testAllTools().catch(console.error); ``` ### 性能測試 #### 響應時間測試 ```bash # 測量工具調用響應時間 time echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_system_info", "arguments": {}}}' | node dist/index.js ``` #### 併發測試 ```bash # 同時發送多個請求 for i in {1..10}; do echo '{"jsonrpc": "2.0", "id": '$i', "method": "tools/list", "params": {}}' | node dist/index.js & done wait ``` --- ## 🔧 故障排除 ### 常見錯誤及解決方案 #### 1. 服務器啟動失敗 **錯誤**: "Cannot find module '@modelcontextprotocol/sdk'" ```bash # 解決方案：重新安裝依賴 npm install @modelcontextprotocol/sdk ``` **錯誤**: "Permission denied" ```bash # Windows - 以管理員身份運行 # macOS/Linux - 檢查文件權限 chmod +x dist/index.js ``` #### 2. 工具調用失敗 **錯誤**: "Unknown tool: calculate" - 檢查工具名稱拼寫 - 確認工具已正確註冊 - 查看服務器日誌 **錯誤**: "Invalid arguments" - 檢查參數類型和格式 - 確認必需參數已提供 - 參考工具文檔 #### 3. Claude Desktop 連接問題 **問題**: Claude Desktop 無法看到 MCP 工具 1. 檢查配置文件路徑是否正確 2. 確認配置文件 JSON 格式正確 3. 重啟 Claude Desktop 4. 檢查服務器路徑是否正確 **問題**: 工具執行失敗 1. 檢查服務器是否正常運行 2. 查看 Claude Desktop 錯誤日誌 3. 測試服務器獨立運行 ### 日誌和調試 #### 啟用詳細日誌 ```bash # 設置環境變量 export MCP_LOG_LEVEL=debug node dist/index.js ``` #### 查看 Claude Desktop 日誌 **Windows**: `%APPDATA%\Claude\logs\` **macOS**: `~/Library/Logs/Claude/` **Linux**: `~/.local/share/Claude/logs/` #### 調試工具 ```javascript // 在代碼中添加調試輸出 console.error('Debug: Tool called with args:', args); ``` ### 性能優化 #### 內存使用優化 ```javascript // 限制大文件處理 if (fileSize > 10 * 1024 * 1024) { // 10MB throw new Error('File too large'); } ``` #### 響應時間優化 ```javascript // 添加超時控制 const timeout = setTimeout(() => { throw new Error('Operation timeout'); }, 30000); // 30秒 ``` --- ## 🚀 開發擴展 ### 添加新工具 #### 步驟 1：創建工具模組 在 `src/tools/` 目錄下創建新文件，例如 `myTools.ts`： ```typescript import { ToolDefinition, ToolResult } from './fileTools.js'; class MyTools { getToolDefinitions(): ToolDefinition[] { return [ { name: 'my_custom_tool', description: '我的自定義工具', inputSchema: { type: 'object', properties: { input: { type: 'string', description: '輸入參數', }, }, required: ['input'], }, }, ]; } hasToolName(name: string): boolean { return this.getToolDefinitions().some(tool => tool.name === name); } async handleToolCall(name: string, args: Record<string, any>): Promise<ToolResult> { switch (name) { case 'my_custom_tool': return await this.myCustomTool(args.input); default: throw new Error(`Unknown tool: ${name}`); } } private async myCustomTool(input: string): Promise<ToolResult> { try { // 實現您的工具邏輯 const result = `處理結果: ${input}`; return { content: [ { type: 'text', text: result, }, ], }; } catch (error) { return { content: [ { type: 'text', text: `錯誤: ${error instanceof Error ? error.message : String(error)}`, }, ], isError: true, }; } } } export const myTools = new MyTools(); ``` #### 步驟 2：註冊工具 在 `src/index.ts` 中導入並註冊新工具： ```typescript // 添加導入 import { myTools } from './tools/myTools.js'; // 在 setupToolHandlers 方法中添加工具 this.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ ...fileTools.getToolDefinitions(), ...calculatorTools.getToolDefinitions(), ...systemTools.getToolDefinitions(), ...myTools.getToolDefinitions(), // 添加新工具 ], }; }); // 在工具調用處理器中添加路由 if (myTools.hasToolName(name)) { result = await myTools.handleToolCall(name, args || {}); } ``` #### 步驟 3：重新建構和測試 ```bash npm run build npm start ``` ### 添加新資源 #### 資源定義範例 ```typescript // 在 setupResourceHandlers 中添加 this.server.setRequestHandler(ListResourcesRequestSchema, async () => { return { resources: [ // 現有資源... { uri: 'mcp://my-custom-resource', mimeType: 'application/json', name: 'My Custom Resource', description: '我的自定義資源', }, ], }; }); // 在資源讀取處理器中添加 case 'mcp://my-custom-resource': return { contents: [ { uri, mimeType: 'application/json', text: JSON.stringify({ message: 'Hello from custom resource' }, null, 2), }, ], }; ``` ### 工具開發最佳實踐 #### 1. 錯誤處理 ```typescript try { // 工具邏輯 return { content: [{ type: 'text', text: result }] }; } catch (error) { return { content: [{ type: 'text', text: `錯誤: ${error.message}` }], isError: true, }; } ``` #### 2. 輸入驗證 ```typescript private validateInput(args: Record<string, any>): void { if (!args.requiredParam) { throw new Error('缺少必需參數: requiredParam'); } if (typeof args.requiredParam !== 'string') { throw new Error('參數類型錯誤: requiredParam 必須是字符串'); } } ``` #### 3. 異步處理 ```typescript async handleToolCall(name: string, args: Record<string, any>): Promise<ToolResult> { // 使用 Promise.race 添加超時 const result = await Promise.race([ this.actualWork(args), new Promise((_, reject) => setTimeout(() => reject(new Error('操作超時')), 30000) ) ]); return result; } ``` --- ## 📋 最佳實踐 ### 安全考慮 #### 1. 輸入清理 ```typescript private sanitizeInput(input: string): string { // 移除危險字符 return input.replace(/[<>\"'&]/g, ''); } ``` #### 2. 路徑驗證 ```typescript private validatePath(filepath: string): void { const resolvedPath = path.resolve(filepath); const allowedDir = path.resolve('./allowed_directory'); if (!resolvedPath.startsWith(allowedDir)) { throw new Error('路徑不在允許範圍內'); } } ``` #### 3. 資源限制 ```typescript private checkResourceLimits(data: any): void { if (JSON.stringify(data).length > 1024 * 1024) { // 1MB throw new Error('數據過大'); } } ``` ### 性能優化 #### 1. 緩存機制 ```typescript private cache = new Map<string, any>(); private getCachedResult(key: string): any { const cached = this.cache.get(key); if (cached && Date.now() - cached.timestamp < 60000) { // 1分鐘緩存 return cached.data; } return null; } ``` #### 2. 批量處理 ```typescript async processBatch(items: any[]): Promise<any[]> { const batchSize = 10; const results = []; for (let i = 0; i < items.length; i += batchSize) { const batch = items.slice(i, i + batchSize); const batchResults = await Promise.all( batch.map(item => this.processItem(item)) ); results.push(...batchResults); } return results; } ``` ### 代碼組織 #### 1. 模組化設計 - 每個工具類別獨立模組 - 共享功能提取為工具函數 - 配置和常量集中管理 #### 2. 類型安全 ```typescript interface ToolParams { [key: string]: string | number | boolean | any[]; } interface ValidationRule { required: boolean; type: 'string' | 'number' | 'boolean' | 'array'; validator?: (value: any) => boolean; } ``` #### 3. 文檔註釋 ```typescript /** * 計算兩個數字的和 * @param a 第一個數字 * @param b 第二個數字 * @returns 兩數之和 * @throws {Error} 當參數不是數字時拋出錯誤 */ private add(a: number, b: number): number { if (typeof a !== 'number' || typeof b !== 'number') { throw new Error('參數必須是數字'); } return a + b; } ``` --- ## ❓ 常見問題 ### Q1: MCP 服務器可以同時被多個客戶端使用嗎？ **A**: 目前的實現是單客戶端的。每個 MCP 服務器實例只能同時服務一個客戶端。如果需要多客戶端支持，需要實現服務器池或使用不同的傳輸方式。 ### Q2: 如何限制工具的執行權限？ **A**: 可以通過以下方式限制權限： - 文件操作限制在特定目錄 - 命令執行使用白名單 - 網絡訪問限制特定域名 - 資源使用限制（內存、CPU、時間） ### Q3: MCP 服務器崩潰後如何自動重啟？ **A**: Claude Desktop 會自動重啟崩潰的 MCP 服務器。您也可以使用進程管理工具： ```bash # 使用 PM2 npm install -g pm2 pm2 start dist/index.js --name mcp-server # 使用 nodemon 開發時自動重啟 npm install -g nodemon nodemon dist/index.js ``` ### Q4: 如何監控 MCP 服務器的性能？ **A**: 添加性能監控： ```typescript class PerformanceMonitor { private metrics = { requestCount: 0, errorCount: 0, averageResponseTime: 0, }; recordRequest(startTime: number, error?: boolean): void { this.metrics.requestCount++; if (error) this.metrics.errorCount++; const responseTime = Date.now() - startTime; this.metrics.averageResponseTime = (this.metrics.averageResponseTime + responseTime) / 2; } getMetrics(): any { return { ...this.metrics }; } } ``` ### Q5: 如何升級 MCP SDK 版本？ **A**: 升級步驟： 1. 檢查新版本兼容性 2. 更新 package.json 中的版本 3. 運行 `npm update @modelcontextprotocol/sdk` 4. 測試所有功能 5. 重新建構和部署 ### Q6: 可以在 MCP 工具中調用外部 API 嗎？ **A**: 可以，但需要注意： - 添加適當的錯誤處理 - 設置請求超時 - 處理網絡錯誤 - 考慮速率限制 ```typescript async callExternalAPI(url: string): Promise<any> { try { const response = await fetch(url, { timeout: 10000, // 10秒超時 headers: { 'User-Agent': 'MCP-Server/1.0.0' } }); if (!response.ok) { throw new Error(`HTTP ${response.status}: ${response.statusText}`); } return await response.json(); } catch (error) { throw new Error(`API 調用失敗: ${error.message}`); } } ``` ### Q7: 如何處理大文件操作？ **A**: 對於大文件，使用流式處理： ```typescript import { createReadStream, createWriteStream } from 'fs'; import { pipeline } from 'stream/promises'; async processLargeFile(inputPath: string, outputPath: string): Promise<void> { const readStream = createReadStream(inputPath); const writeStream = createWriteStream(outputPath); await pipeline( readStream, // 添加處理轉換 writeStream ); } ``` --- ## 📞 支持和聯繫 ### 獲取幫助 1. **檢查日誌**: 查看服務器和客戶端日誌 2. **查閱文檔**: 參考本操作手冊和 MCP 官方文檔 3. **社區討論**: 參與 MCP 社區討論 4. **提交問題**: 在項目倉庫提交 Issue ### 相關資源 - [MCP 官方文檔](https://modelcontextprotocol.io/) - [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - [Claude Desktop 配置指南](https://claude.ai/docs/) ### 版本信息 - **MCP SDK 版本**: 1.18.1 - **Node.js 最低版本**: 18.0.0 - **文檔版本**: 1.0.0 - **最後更新**: 2025年9月23日 --- *本操作手冊持續更新中，如有問題或建議，歡迎反饋。*