README.md•4.13 kB
# Node.js MCP Server
一個使用 Node.js 和 TypeScript 實現的 Model Context Protocol (MCP) 服務器。
## 什麼是 MCP？
Model Context Protocol (MCP) 是一個開放標準協議，用於在 AI 模型和各種數據源、工具之間建立安全、可控的連接。MCP 允許 AI 助手：
- 訪問本地和遠程資源
- 執行工具和功能
- 維護安全的上下文邊界
- 提供結構化的能力發現
## 功能特性
這個 MCP 服務器提供以下工具類別：
### 📁 文件操作工具
- `read_file` - 讀取文件內容
- `write_file` - 寫入文件內容
- `list_directory` - 列出目錄內容
- `create_directory` - 創建目錄
- `delete_file` - 刪除文件
### 🧮 計算器工具
- `calculate` - 執行數學計算（支持基本運算和函數）
- `convert_units` - 單位轉換（長度、重量、溫度）
- `statistics` - 計算統計信息（平均值、中位數、標準差等）
### 💻 系統信息工具
- `get_system_info` - 獲取系統基本信息
- `get_current_time` - 獲取當前時間和日期
- `execute_command` - 執行安全的系統命令
- `get_network_info` - 獲取網絡接口信息
- `get_process_info` - 獲取當前進程信息
## 安裝和使用
### 前置需求
- Node.js 18.0.0 或更高版本
- npm 或 yarn
### 安裝依賴
\`\`\`bash
npm install
\`\`\`
### 建構項目
\`\`\`bash
npm run build
\`\`\`
### 啟動服務器
\`\`\`bash
npm start
\`\`\`
### 開發模式
\`\`\`bash
npm run dev
\`\`\`
## 配置 Claude Desktop
要在 Claude Desktop 中使用這個 MCP 服務器，請在 Claude 配置文件中添加以下內容：
\`\`\`json
{
"mcpServers": {
"nodejs-mcp-server": {
"command": "node",
"args": ["path/to/your/dist/index.js"]
}
}
}
\`\`\`
## 架構說明
### 核心組件
1. **Server (index.ts)** - 主要的 MCP 服務器實現
2. **Tool Modules** - 各種功能工具的實現
- `fileTools.ts` - 文件操作工具
- `calculatorTools.ts` - 計算工具
- `systemTools.ts` - 系統信息工具
### 安全考慮
- 文件操作限制在允許的路徑範圍內
- 命令執行只允許預定義的安全命令
- 數學表達式求值使用安全的解析方式
- 所有輸入都經過驗證和清理
## 擴展功能
要添加新的工具，請：
1. 在 `src/tools/` 目錄下創建新的工具模組
2. 實現 `ToolDefinition` 和 `ToolResult` 接口
3. 在主服務器文件中註冊新工具
### 工具模組示例
\`\`\`typescript
class MyCustomTools {
getToolDefinitions(): ToolDefinition[] {
return [
{
name: 'my_tool',
description: '我的自定義工具',
inputSchema: {
type: 'object',
properties: {
param: { type: 'string', description: '參數描述' }
},
required: ['param']
}
}
];
}
async handleToolCall(name: string, args: Record<string, any>): Promise<ToolResult> {
// 實現工具邏輯
}
}
\`\`\`
## 測試
### 手動測試
\`\`\`bash
# 建構項目
npm run build
# 啟動服務器並測試工具列表
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | node dist/index.js
\`\`\`
### 測試工具調用
\`\`\`bash
# 測試計算工具
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "calculate", "arguments": {"expression": "2 + 3 * 4"}}}' | node dist/index.js
\`\`\`
## 故障排除
### 常見問題
1. **模組找不到錯誤**
- 確保運行了 \`npm run build\`
- 檢查 TypeScript 配置
2. **權限錯誤**
- 檢查文件路徑權限
- 確保工作目錄正確
3. **連接問題**
- 驗證 MCP 客戶端配置
- 檢查服務器日誌輸出
## 貢獻指南
歡迎提交問題報告和功能請求！請確保：
1. 遵循現有的代碼風格
2. 添加適當的錯誤處理
3. 包含安全考慮
4. 更新文檔
## 許可證
MIT License - 詳見 LICENSE 文件。
## 更多資源
- [MCP 官方文檔](https://modelcontextprotocol.io/)
- [MCP SDK 文檔](https://github.com/modelcontextprotocol/typescript-sdk)
- [Claude Desktop 配置指南](https://claude.ai/docs/)