# 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/)