DingTalk Honor MCP Server

钉钉企业文化荣誉管理 MCP 服务器 - 为 AI 助手提供简单、易用、友好的钉钉荣誉系统集成能力。

📋 功能特性

核心功能

• 🏆 颁发荣誉 - 给员工颁发荣誉勋章，支持批量颁发
• 📊 查询企业荣誉 - 获取企业可颁发的荣誉列表
• 🎖️ 查询员工荣誉 - 查看员工已获得的荣誉记录
• ✨ 创建荣誉模板 - 创建自定义荣誉勋章模板
• 🔄 撤销荣誉 - 撤销已颁发的荣誉勋章

技术特性

• 🔐 智能Token管理 - 自动缓存和刷新access_token
• 🛡️ 错误自愈 - Token失效、网络异常自动恢复
• 📝 配置驱动 - YAML配置文件定义所有API
• 🚀 零配置启动 - 环境变量配置即可运行
• 🔧 TypeScript支持 - 完整的类型定义和智能提示

🚀 快速开始

方式1：使用 npx 直接运行（推荐）

无需安装，直接运行：

npx dingtalk-honorary-mcp@latest

方式2：全局安装

# 全局安装
npm install -g dingtalk-honorary-mcp

# 安装后运行
dingtalk-honorary-mcp

方式3：作为项目依赖

# 在项目中安装
npm install dingtalk-honorary-mcp

# 在 package.json scripts 中使用
{
  "scripts": {
    "honor-mcp": "dingtalk-honorary-mcp"
  }
}

方式4：从源码安装

git clone https://github.com/dingtalk-mcp/dingtalk-honorary-mcp.git
cd dingtalk-honorary-mcp
npm install
npm run build
npm start

配置环境变量

有三种配置方式：

方式1：环境变量（推荐用于命令行）

# Linux/macOS
export DINGTALK_Client_ID=your_app_key_here
export DINGTALK_Client_Secret=your_app_secret_here

# Windows
set DINGTALK_Client_ID=your_app_key_here
set DINGTALK_Client_Secret=your_app_secret_here

方式2：.env 文件（推荐用于开发）

创建 .env 文件：

DINGTALK_Client_ID=your_app_key_here
DINGTALK_Client_Secret=your_app_secret_here

方式3：直接传递（适合 Cursor 集成）

在 Cursor MCP 配置中直接设置 env 字段（见下文）

运行服务

根据安装方式选择相应的运行命令：

# 使用 npx（无需安装）
npx dingtalk-honorary-mcp@latest

# 全局安装后
dingtalk-honorary-mcp

# 源码方式
npm start

📖 工具使用说明

1. 给员工颁发荣誉 (mcp_dingtalk-honor_grantHonor)

给组织内的员工颁发荣誉勋章，支持单人或多人批量颁发。

参数说明：

• honorId (必填): 荣誉ID，可通过查询企业荣誉列表获取
• senderUserId (必填): 发送人userId
• grantReason (必填): 颁奖词，最多50个字符
• granterName (必填): 颁奖人名字，最多15个字符
• receiverUserIds (必填): 接收人userId数组，最多10个
• expirationTime (可选): 荣誉有效期时间戳（毫秒）
• noticeSingle (可选): 是否发送单聊通知
• noticeAnnouncer (可选): 是否使用官宣号通知
• openConversationIds (可选): 群ID列表，最多5个

使用示例：

{
  "honorId": "10001",
  "senderUserId": "manager001",
  "grantReason": "感谢您为团队做出的杰出贡献！",
  "granterName": "张经理",
  "receiverUserIds": ["user001", "user002"],
  "noticeSingle": true,
  "noticeAnnouncer": true
}

2. 查询企业荣誉列表 (mcp_dingtalk-honor_queryOrgHonors)

查询当前企业下可颁发的荣誉列表，支持分页。

参数说明：

• nextToken (必填): 分页游标，首次调用传"0"
• maxResults (可选): 每页条目数，默认20，最大100

响应示例：

{
  "success": true,
  "result": {
    "nextToken": "10",
    "openHonors": [
      {
        "honorId": "10001",
        "honorName": "优秀员工",
        "honorDesc": "表彰工作出色的员工",
        "honorImgUrl": "https://..."
      }
    ]
  }
}

3. 查询员工荣誉记录 (mcp_dingtalk-honor_queryUserHonors)

查询某个员工已获得的荣誉记录。

参数说明：

• userId (必填): 员工userId
• nextToken (必填): 分页游标，首次调用传"0"
• maxResults (可选): 每页条目数，默认20，最大100

4. 创建荣誉模板 (mcp_dingtalk-honor_createOrgHonor)

创建企业自定义荣誉勋章模板。

参数说明：

• userId (必填): 管理员userId（需要管理员权限）
• medalName (必填): 荣誉名称，最多10字符
• medalDesc (必填): 荣誉描述，最多30字符
• medalMediaId (必填): 荣誉图片media_id（900x900 PNG）
• avatarFrameMediaId (必填): 头像挂件media_id（240x240 PNG）
• defaultBgColor (必填): 背景颜色，可选值：
  • #FFFBB4 (浅黄色)
  • #FFE7BC (浅橙色)
  • #FFDAF4 (浅粉色)
  • #DAF6A8 (浅绿色)
  • #E4D7FF (浅紫色)
  • #BFDFFF (浅蓝色)
  • #B9F2D6 (薄荷绿)

5. 撤销荣誉勋章 (mcp_dingtalk-honor_recallHonor)

撤销员工已获得的荣誉勋章。

参数说明：

• honorId (必填): 荣誉勋章ID
• userId (必填): 员工userId

🔧 Cursor 集成配置

在 Cursor 中使用本 MCP 服务器：

1. 打开 Cursor 设置（Cmd/Ctrl + ,）
2. 搜索 "MCP" 或找到 "Model Context Protocol" 设置
3. 点击 "Edit MCP Settings (JSON)"
4. 添加以下配置：

推荐配置（使用 npx）

{
  "dingtalk-honor": {
    "command": "npx",
    "args": ["dingtalk-honorary-mcp@latest"],
    "env": {
      "DINGTALK_Client_ID": "your_app_key",
      "DINGTALK_Client_Secret": "your_app_secret"
    }
  }
}

备选配置（全局安装）

如果您已全局安装：

{
  "dingtalk-honor": {
    "command": "dingtalk-honorary-mcp",
    "env": {
      "DINGTALK_Client_ID": "your_app_key",
      "DINGTALK_Client_Secret": "your_app_secret"
    }
  }
}

配置完成后，重启 Cursor 即可使用。

✅ 安装验证

安装完成后，可以通过以下命令验证是否安装成功：

# 查看版本
npx dingtalk-honorary-mcp@latest --version

# 查看帮助（会启动 MCP 服务）
npx dingtalk-honorary-mcp@latest --help

如果看到 "DingTalk Honor MCP server running on stdio" 说明安装成功。

📝 注意事项

1. 权限要求：

   • 需要"组织文化荣誉信息读权限"和"组织文化荣誉信息写权限"
   • 创建荣誉模板需要管理员权限

2. 并发限制：

   • 同一个颁发人不允许并发执行颁发操作
   • 创建荣誉模板不允许并发调用

3. 审核说明：

   • 创建的荣誉模板需要钉钉审核（一般5个工作日）
   • 企业每周审核次数有限制

4. Token管理：

   • 推荐使用Client ID/Secret方式，支持自动刷新
   • Token缓存在本地，有效期2小时

🛠️ 开发指南

项目结构

dingtalk-honorary-mcp/
├── src/
│   ├── index.ts                 # 入口文件
│   ├── DingTalkHonorServer.ts   # 主服务器类
│   ├── types.ts                 # TypeScript类型定义
│   └── cli.ts                   # CLI启动脚本
├── dist/                        # 编译输出目录
├── dingtalk_honor_mcp.yaml      # API配置文件
├── package.json                 # 项目配置
├── tsconfig.json               # TypeScript配置
├── env.example                 # 环境变量示例
├── start-mcp.sh               # 启动脚本
├── test-honor-mcp.js          # 测试脚本
├── cursor-mcp-config.json     # Cursor配置示例
├── README.md                  # 使用文档
├── USAGE_GUIDE.md            # 详细使用指南
├── PROJECT_SUMMARY.md        # 项目总结
├── LICENSE                   # MIT许可证
└── .gitignore               # Git忽略配置

添加新API

1. 在 dingtalk_honor_mcp.yaml 中添加新的工具定义
2. 在 types.ts 中添加相应的类型定义
3. 重新构建项目：npm run build

调试模式

设置环境变量 DEBUG=true 可以查看详细的请求和响应日志。

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📦 发布信息

• npm 包地址: https://www.npmjs.com/package/dingtalk-honorary-mcp
• 当前版本: 1.0.0
• 发布日期: 2024-06-24
• 维护者: plutozhang
• 下载量:

📞 联系方式

如有问题或建议，请通过以下方式联系：

• 提交 GitHub Issue
• 发送邮件至：[email protected]

📝 更新日志

v1.0.0 (2024-06-24)

• 🎉 首次发布
• ✨ 支持 5 个核心功能：颁发荣誉、查询荣誉、创建模板、撤销荣誉
• 🔐 智能 Token 管理
• 📋 配置驱动架构
• 🔧 完整的 TypeScript 支持