dingtalk-honorary-mcp/README.md

DingTalk Honor MCP Server - TypeScript implementation for AI assistants to manage enterprise honor system

# DingTalk Honor MCP Server

[![npm version](https://badge.fury.io/js/dingtalk-honorary-mcp.svg)](https://www.npmjs.com/package/dingtalk-honorary-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

## 📋 功能特性

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

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

## 🚀 快速开始

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

无需安装，直接运行：
```bash
npx dingtalk-honorary-mcp@latest
```

### 方式2：全局安装

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

# 安装后运行
dingtalk-honorary-mcp
```

### 方式3：作为项目依赖

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

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

### 方式4：从源码安装

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

### 配置环境变量

有三种配置方式：

#### 方式1：环境变量（推荐用于命令行）
```bash
# 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` 文件：
```bash
DINGTALK_Client_ID=your_app_key_here
DINGTALK_Client_Secret=your_app_secret_here
```

#### 方式3：直接传递（适合 Cursor 集成）
在 Cursor MCP 配置中直接设置 env 字段（见下文）

### 运行服务

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

```bash
# 使用 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个

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

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

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

**参数说明：**
- `nextToken` (必填): 分页游标，首次调用传"0"
- `maxResults` (可选): 每页条目数，默认20，最大100

**响应示例：**
```json
{
  "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）
```json
{
  "dingtalk-honor": {
    "command": "npx",
    "args": ["dingtalk-honorary-mcp@latest"],
    "env": {
      "DINGTALK_Client_ID": "your_app_key",
      "DINGTALK_Client_Secret": "your_app_secret"
    }
  }
}
```

### 备选配置（全局安装）
如果您已全局安装：
```json
{
  "dingtalk-honor": {
    "command": "dingtalk-honorary-mcp",
    "env": {
      "DINGTALK_Client_ID": "your_app_key",
      "DINGTALK_Client_Secret": "your_app_secret"
    }
  }
}
```

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

## ✅ 安装验证

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

```bash
# 查看版本
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
- **下载量**: [![npm downloads](https://img.shields.io/npm/dm/dingtalk-honorary-mcp.svg)](https://www.npmjs.com/package/dingtalk-honorary-mcp)

## 📞 联系方式

如有问题或建议，请通过以下方式联系：
- 提交 GitHub Issue
- 发送邮件至：dingtalk-mcp@example.com

## 📝 更新日志

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