dingtalk-appmanage-mcp

# 钉钉应用管理 MCP 服务器一个基于模型上下文协议(MCP)的钉钉应用管理服务器，为AI助手提供完整的企业应用管理能力，包括应用创建、权限管理、版本控制和发布等功能。 ## ✨ 主要功能 ### 🏢 应用管理 - **创建内部应用**: 支持H5微应用和小程序两种类型 - **更新应用信息**: 修改应用详情、描述、图标、链接等 - **应用列表查询**: 获取企业所有应用或仅内部应用 - **用户可见应用**: 查询特定用户可以使用的应用列表 ### 🔐 权限范围管理 - **获取应用权限**: 查询当前应用的使用权限设置 - **更新应用权限**: 批量添加/删除用户、部门、角色权限 - **可见性控制**: 设置仅管理员可见或全员可见 ### 📱 小程序版本管理 - **发布版本**: 支持线上版本和体验版本发布 - **版本回滚**: 安全回滚到历史版本 - **版本历史**: 查看所有版本信息和分页历史记录 - **PC端支持**: 控制是否支持PC端打开小程序 ## 🛠️ 安装部署 ### 环境要求 - Node.js 18 或更高版本 - npm 或 yarn 包管理器 - 钉钉开发者账号及应用管理权限 ### 快速安装 #### 方式1：NPM全局安装（推荐生产环境） ```bash npm install -g dingtalk-appmanage-mcp ``` #### 方式2：源码安装（推荐开发环境） ```bash git clone <项目仓库地址> cd dingtalk-appmanage-mcp npm install npm run build ``` ## ⚙️ 配置说明 ### 1. 环境变量配置复制环境变量模板并配置你的凭据： ```bash cp env.example .env # 编辑 .env 文件，填入实际的凭据信息 ``` ### 环境变量说明支持两种认证方式，选择其中一种即可： #### 方式1：直接使用访问令牌（简单） ```bash DINGTALK_ACCESS_TOKEN=你的访问令牌 ``` #### 方式2：应用凭据自动刷新（推荐） ```bash DINGTALK_Client_ID=你的应用AppKey DINGTALK_Client_Secret=你的应用AppSecret ``` ### 2. 获取钉钉凭据 1. 访问 [钉钉开放平台](https://open-dev.dingtalk.com/) 2. 创建或选择你的应用 3. 进入 **应用信息** → **基础信息** 4. 复制 **AppKey** 作为 `DINGTALK_Client_ID` 5. 复制 **AppSecret** 作为 `DINGTALK_Client_Secret` ### 3. 必需权限确保你的钉钉应用具有以下权限： - 企业微应用管理权限 - 内部应用管理权限 - 通讯录只读权限（如需用户/部门操作） ## 🚀 使用方式 ### 独立运行模式 ```bash # 使用全局安装 dingtalk-appmanage-mcp # 使用本地安装 npm start # 使用启动脚本 ./start-mcp.sh ``` ### 与 Cursor/Claude 集成在MCP客户端配置中添加： #### 选项1：相对路径配置（推荐开发环境） ```json { "mcpServers": { "dingtalk-appmanage": { "command": "node", "args": ["dist/cli.js"], "cwd": "/你的项目路径/dingtalk-appmanage-mcp", "env": { "DINGTALK_Client_ID": "你的AppKey", "DINGTALK_Client_Secret": "你的AppSecret" } } } } ``` #### 选项2：绝对路径配置 ```json { "mcpServers": { "dingtalk-appmanage": { "command": "node", "args": ["/绝对路径/dingtalk-appmanage-mcp/dist/cli.js"], "env": { "DINGTALK_Client_ID": "你的AppKey", "DINGTALK_Client_Secret": "你的AppSecret" } } } } ``` #### 选项3：全局安装配置（推荐生产环境） ```json { "mcpServers": { "dingtalk-appmanage": { "command": "dingtalk-appmanage-mcp", "env": { "DINGTALK_Client_ID": "你的AppKey", "DINGTALK_Client_Secret": "你的AppSecret" } } } } ``` ### 与其他MCP客户端集成服务器使用标准MCP协议，可以与任何兼容的客户端配合使用： ```bash # 在stdio上启动服务器 dingtalk-appmanage-mcp # 使用自定义配置 dingtalk-appmanage-mcp --config ./custom-config.yaml ``` ## 🔧 可用工具 ### 应用管理工具 | 工具名称 | 功能描述 | 主要参数 | |---------|---------|---------| | `createInnerApp` | 创建企业内部应用 | `opUnionId`, `name`, `desc`, `developType` 等 | | `updateInnerApp` | 更新应用信息 | `agentId`, `opUnionId`, `name`, `desc` 等 | | `listAllApp` | 列出所有企业应用 | 无 | | `listAllInnerApps` | 列出内部应用 | 无 | | `listUserVilebleApp` | 获取用户可见应用 | `userId` | ### 权限管理工具 | 工具名称 | 功能描述 | 主要参数 | |---------|---------|---------| | `getMicroAppScope` | 获取应用权限范围 | `agentId` | | `setMicroAppScope` | 设置应用权限范围 | `agentId`, `addUserIds`, `delUserIds` 等 | ### 版本管理工具 | 工具名称 | 功能描述 | 主要参数 | |---------|---------|---------| | `publishInnerAppVersion` | 发布小程序版本 | `agentId`, `appVersionId`, `opUnionId` 等 | | `rollbackInnerAppVersion` | 回滚到历史版本 | `agentId`, `versionId`, `opUnionId` | | `listInnerAppVersion` | 列出所有版本 | `agentId` | | `pageInnerAppHistoryVersion` | 分页获取版本历史 | `agentId`, `pageNumber`, `pageSize` | ## 📖 使用示例 ### 创建新的H5微应用 ```json { "tool": "createInnerApp", "arguments": { "opUnionId": "操作者unionId", "name": "员工门户", "desc": "内部员工管理门户系统", "homepageLink": "https://your-domain.com/employee-portal", "developType": 0 } } ``` ### 更新应用权限范围 ```json { "tool": "setMicroAppScope", "arguments": { "agentId": 123456789, "addUserIds": ["user1", "user2"], "addDeptIds": [100, 200], "onlyAdminVisible": false } } ``` ### 发布小程序版本 ```json { "tool": "publishInnerAppVersion", "arguments": { "agentId": 123456789, "appVersionId": 456, "opUnionId": "管理员unionId", "publishType": "online", "miniAppOnPc": true } } ``` ### 实际使用场景示例 #### 场景1：为新员工创建专属应用 ``` "帮我创建一个名为'新员工入职'的H5应用，描述为'新员工入职流程管理系统'，首页地址是 https://hr.company.com/onboarding" ``` #### 场景2：更新应用权限 ``` "将应用ID为3908674093的应用权限设置为仅人事部门可见" ``` #### 场景3：发布小程序新版本 ``` "发布agentId为123456的小程序版本，版本号为v1.2.0，同时支持PC端" ``` ## 🐛 故障排查 ### 常见问题 #### 1. 认证错误 ```bash # 检查凭据配置 cat .env # 清除token缓存重试 rm .dingtalk_token_cache.json ``` #### 2. 权限被拒绝 - 确保钉钉应用具有必需权限 - 检查操作用户是否具有管理员权限 - 确认应用配置正确 #### 3. 网络连接问题 - 检查防火墙设置，确保允许HTTPS出站连接 - 验证DNS解析：`nslookup api.dingtalk.com` - 测试连通性：`curl https://api.dingtalk.com` #### 4. 工具调用失败 ```bash # 启用详细日志 DEBUG=dingtalk:* dingtalk-appmanage-mcp # 检查配置文件 cat dingtalk_appmanage_mcp.yaml ``` ### 调试模式 ```bash # 启用详细调试信息 DEBUG=dingtalk:* npm start # 查看实时日志 tail -f logs/dingtalk-mcp.log # 如果有日志文件 ``` ### Token缓存问题 ```bash # 清除损坏的token缓存 rm .dingtalk_token_cache.json # 使用自定义缓存位置 dingtalk-appmanage-mcp --token-cache ./custom-cache.json ``` ## 🔒 安全考虑 - **凭据安全**: 绝不将真实凭据提交到版本控制系统 - **定期轮换**: 定期更换你的应用密钥 - **最小权限**: 仅为钉钉应用授予必要权限 - **安全存储**: 使用环境变量或安全的密钥管理系统 - **网络安全**: 确保仅使用HTTPS通信 ## 📝 API说明 ### Token管理服务器自动处理token管理： - 本地缓存token以提高性能 - 在过期前自动刷新token - 优雅处理token失效情况 ### 错误处理所有API错误都会被正确格式化并返回给MCP客户端： - 保留HTTP状态码 - 包含钉钉错误代码 - 提供清晰的错误消息 ### 频率限制注意钉钉API频率限制： - 默认：每分钟1000个请求 - 使用token缓存减少认证请求 - 为频率限制错误实现重试逻辑 ## 🤝 团队协作 ### 开发流程 1. Fork项目仓库 2. 创建功能分支：`git checkout -b feature/新功能` 3. 提交更改：`git commit -m '添加新功能'` 4. 推送分支：`git push origin feature/新功能` 5. 创建Pull Request ### 代码规范 - 使用TypeScript进行类型安全 - 遵循ESLint代码规范 - 编写单元测试 - 更新相关文档 ### 版本发布 ```bash # 更新版本号 npm version patch|minor|major # 构建项目 npm run build # 发布到NPM npm publish ``` ## 📄 许可证本项目基于MIT许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。 ## 🆘 技术支持 - **问题反馈**: [GitHub Issues](https://github.com/your-org/dingtalk-appmanage-mcp/issues) - **项目文档**: [项目Wiki](https://github.com/your-org/dingtalk-appmanage-mcp/wiki) - **钉钉API文档**: [官方文档](https://open.dingtalk.com/document/) - **MCP协议**: [MCP规范](https://modelcontextprotocol.io/) ## 🗂️ 项目结构 ``` dingtalk-appmanage-mcp/ ├── src/ # 源代码目录 │ ├── DingTalkAppManageServer.ts # 核心服务器实现 │ ├── types.ts # TypeScript类型定义 │ ├── index.ts # 库主入口 │ └── cli.ts # 命令行接口 ├── dist/ # 编译输出目录 ├── dingtalk_appmanage_mcp.yaml # 工具配置文件 ├── package.json # 项目依赖配置 ├── tsconfig.json # TypeScript配置 ├── env.example # 环境变量模板 ├── start-mcp.sh # 启动脚本 ├── CURSOR_INTEGRATION.md # Cursor集成文档 └── README.md # 项目说明文档 ``` ## 📊 性能优化 ### 缓存策略 - Token自动缓存，避免频繁认证 - 配置文件缓存，减少I/O操作 - API响应缓存（可选） ### 最佳实践 - 批量操作以减少API调用 - 使用异步处理提高并发性能 - 合理设置超时和重试机制 - 监控API调用频率 ## 🔄 更新日志 ### v1.0.0 (当前版本) - ✅ 完整的应用管理功能 - ✅ 权限范围管理 - ✅ 小程序版本控制 - ✅ 自动token管理 - ✅ 完善的错误处理 - ✅ 中英文文档支持 ### 后续版本计划 - 🔄 增加应用统计分析 - 🔄 支持批量操作 - 🔄 添加Webhook支持 - 🔄 集成更多钉钉API --- **维护团队**: 钉钉MCP开发团队 **最后更新**: 2024年12月 **文档版本**: v1.0.0