dingtalk-appmanage-mcp

v1.0.0

Published

7 months ago

钉钉应用管理MCP服务器 - 为AI助手提供完整的企业应用管理能力

0High
0Medium
0Low

plutozhang

mcp dingtalk 钉钉应用管理 application-management app-management cursor claude ai typescript model-context-protocol 企业应用小程序管理

钉钉应用管理 MCP 服务器

一个基于模型上下文协议(MCP)的钉钉应用管理服务器，为AI助手提供完整的企业应用管理能力，包括应用创建、权限管理、版本控制和发布等功能。

✨ 主要功能

🏢 应用管理

创建内部应用: 支持H5微应用和小程序两种类型
更新应用信息: 修改应用详情、描述、图标、链接等
应用列表查询: 获取企业所有应用或仅内部应用
用户可见应用: 查询特定用户可以使用的应用列表

🔐 权限范围管理

获取应用权限: 查询当前应用的使用权限设置
更新应用权限: 批量添加/删除用户、部门、角色权限
可见性控制: 设置仅管理员可见或全员可见

📱 小程序版本管理

发布版本: 支持线上版本和体验版本发布
版本回滚: 安全回滚到历史版本
版本历史: 查看所有版本信息和分页历史记录
PC端支持: 控制是否支持PC端打开小程序

🛠️ 安装部署

环境要求

Node.js 18 或更高版本
npm 或 yarn 包管理器
钉钉开发者账号及应用管理权限

快速安装

方式1：NPM全局安装（推荐生产环境）

npm install -g dingtalk-appmanage-mcp

方式2：源码安装（推荐开发环境）

git clone <项目仓库地址>
cd dingtalk-appmanage-mcp
npm install
npm run build

⚙️ 配置说明

1. 环境变量配置

复制环境变量模板并配置你的凭据：

cp env.example .env
# 编辑 .env 文件，填入实际的凭据信息

环境变量说明

支持两种认证方式，选择其中一种即可：

方式1：直接使用访问令牌（简单）

DINGTALK_ACCESS_TOKEN=你的访问令牌

方式2：应用凭据自动刷新（推荐）

DINGTALK_Client_ID=你的应用AppKey
DINGTALK_Client_Secret=你的应用AppSecret

2. 获取钉钉凭据

访问钉钉开放平台
创建或选择你的应用
进入 应用信息 → 基础信息
复制 AppKey 作为 DINGTALK_Client_ID
复制 AppSecret 作为 DINGTALK_Client_Secret

3. 必需权限

确保你的钉钉应用具有以下权限：

企业微应用管理权限
内部应用管理权限
通讯录只读权限（如需用户/部门操作）

🚀 使用方式

独立运行模式

# 使用全局安装
dingtalk-appmanage-mcp

# 使用本地安装
npm start

# 使用启动脚本
./start-mcp.sh

与 Cursor/Claude 集成

在MCP客户端配置中添加：

选项1：相对路径配置（推荐开发环境）

{
  "mcpServers": {
    "dingtalk-appmanage": {
      "command": "node",
      "args": ["dist/cli.js"],
      "cwd": "/你的项目路径/dingtalk-appmanage-mcp",
      "env": {
        "DINGTALK_Client_ID": "你的AppKey",
        "DINGTALK_Client_Secret": "你的AppSecret"
      }
    }
  }
}

选项2：绝对路径配置

{
  "mcpServers": {
    "dingtalk-appmanage": {
      "command": "node",
      "args": ["/绝对路径/dingtalk-appmanage-mcp/dist/cli.js"],
      "env": {
        "DINGTALK_Client_ID": "你的AppKey",
        "DINGTALK_Client_Secret": "你的AppSecret"
      }
    }
  }
}

选项3：全局安装配置（推荐生产环境）

{
  "mcpServers": {
    "dingtalk-appmanage": {
      "command": "dingtalk-appmanage-mcp",
      "env": {
        "DINGTALK_Client_ID": "你的AppKey",
        "DINGTALK_Client_Secret": "你的AppSecret"
      }
    }
  }
}

与其他MCP客户端集成

服务器使用标准MCP协议，可以与任何兼容的客户端配合使用：

# 在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微应用

{
  "tool": "createInnerApp",
  "arguments": {
    "opUnionId": "操作者unionId",
    "name": "员工门户",
    "desc": "内部员工管理门户系统",
    "homepageLink": "https://your-domain.com/employee-portal",
    "developType": 0
  }
}

更新应用权限范围

{
  "tool": "setMicroAppScope",
  "arguments": {
    "agentId": 123456789,
    "addUserIds": ["user1", "user2"],
    "addDeptIds": [100, 200],
    "onlyAdminVisible": false
  }
}

发布小程序版本

{
  "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. 认证错误

# 检查凭据配置
cat .env

# 清除token缓存重试
rm .dingtalk_token_cache.json

2. 权限被拒绝

确保钉钉应用具有必需权限
检查操作用户是否具有管理员权限
确认应用配置正确

3. 网络连接问题

检查防火墙设置，确保允许HTTPS出站连接
验证DNS解析：nslookup api.dingtalk.com
测试连通性：curl https://api.dingtalk.com

4. 工具调用失败

# 启用详细日志
DEBUG=dingtalk:* dingtalk-appmanage-mcp

# 检查配置文件
cat dingtalk_appmanage_mcp.yaml

调试模式

# 启用详细调试信息
DEBUG=dingtalk:* npm start

# 查看实时日志
tail -f logs/dingtalk-mcp.log  # 如果有日志文件

Token缓存问题

# 清除损坏的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缓存减少认证请求
为频率限制错误实现重试逻辑

🤝 团队协作

开发流程

Fork项目仓库
创建功能分支：git checkout -b feature/新功能
提交更改：git commit -m '添加新功能'
推送分支：git push origin feature/新功能
创建Pull Request

代码规范

使用TypeScript进行类型安全
遵循ESLint代码规范
编写单元测试
更新相关文档

版本发布

# 更新版本号
npm version patch|minor|major

# 构建项目
npm run build

# 发布到NPM
npm publish

📄 许可证

本项目基于MIT许可证 - 查看 LICENSE 文件了解详情。

🆘 技术支持

问题反馈: GitHub Issues
项目文档: 项目Wiki
钉钉API文档: 官方文档
MCP协议: MCP规范

🗂️ 项目结构

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