wework-bot-mcp-server/CODEBUDDY.md

企业微信机器人 MCP Server - 提供企业微信消息发送、群管理等功能

# 企业微信机器人 MCP Server

## 常用开发命令

### 构建和运行
```bash
npm run build          # 编译 TypeScript 到 dist/
npm start              # 运行编译后的服务器
npm run dev            # 开发模式运行（使用 tsx）
```

### 安装和发布
```bash
npm install -g .       # 本地全局安装
uvx wework-bot-mcp-server  # 使用 uvx 运行（推荐）
npm publish            # 发布到 npm（需要先登录）
```

### 代码质量
```bash
npm run lint           # ESLint 代码检查
npm run format         # Prettier 代码格式化
npm test               # 运行 Jest 测试
```

### 测试和调试
```bash
DEBUG=1 npm run dev    # 启用详细日志的开发模式
node test-server.js    # 手动测试服务器（如果存在）
```

## 项目架构

### 核心组件
- **WeWorkMCPServer** (`src/index.ts`): MCP Server 主类，处理工具注册和请求路由
- **WeWorkClient** (`src/services/wework-client.ts`): 企业微信 API 客户端，封装所有 HTTP 请求
- **配置管理** (`src/utils/config.ts`): 环境变量加载和验证

### MCP 工具架构
项目实现了 4 个 MCP 工具：
1. `send_wework_message` - 发送文本/Markdown 消息，支持 @用户
2. `send_wework_news` - 发送图文消息（最多8条）
3. `send_wework_image` - 发送 base64 编码图片
4. `test_wework_connection` - 连接测试

### 数据流
1. MCP Client (Claude Desktop) → StdioServerTransport → WeWorkMCPServer
2. WeWorkMCPServer → WeWorkClient → 企业微信 Webhook API
3. 企业微信 API 响应 → WeWorkClient → MCP Client

### 环境配置
必需环境变量：
- `WEWORK_BOT_WEBHOOK_URL`: 企业微信机器人 Webhook URL

可选环境变量（高级功能）：
- `WEWORK_CORP_ID`: 企业ID
- `WEWORK_CORP_SECRET`: 企业密钥  
- `WEWORK_AGENT_ID`: 应用ID

### 错误处理策略
- 配置验证失败时立即退出进程
- HTTP 请求失败时返回结构化错误响应
- 所有工具调用都有统一的错误处理和响应格式

### 部署注意事项
- 需要 Node.js >= 18.0.0
- 构建后的入口文件为 `dist/index.js`
- 使用 StdioServerTransport，适合作为子进程运行
- 企业微信 API 有频率限制（建议每分钟不超过20条消息）