DingTalk Log MCP

钉钉日志管理 MCP 服务器 - 为 AI 助手提供日志管理功能的 TypeScript 实现。

功能特性

本 MCP 服务器为 AI 助手提供以下钉钉日志管理功能：

核心功能

• createLog - 创建并发送工作日志到指定接收人
• saveLogDraft - 保存日志内容供后续编辑和发送
• getLogList - 查询用户发出的日志列表
• getTemplateList - 获取用户可见的日志模板列表
• getTemplateDetail - 查看日志模板字段和配置信息

技术特性

• 🚀 TypeScript 实现，类型安全
• 🔐 智能 Token 缓存机制，避免频繁刷新
• 📝 YAML 配置文件，易于维护
• 🛡️ 完善的错误处理和重试机制
• 📊 支持分页查询和批量操作
• 🔧 兼容 MCP 协议标准

安装使用

1. 环境要求

• Node.js >= 18.0.0
• npm 或 yarn

2. 安装依赖

npm install

3. 配置环境变量

复制环境变量示例文件：

cp env.example .env

编辑 .env 文件，配置钉钉应用凭证：

方式一：使用访问令牌（推荐测试用）

DINGTALK_ACCESS_TOKEN=your_access_token_here

方式二：使用应用凭证（推荐生产用）

DINGTALK_Client_ID=your_client_id_here
DINGTALK_Client_Secret=your_client_secret_here

4. 构建项目

npm run build

5. 启动服务器

# 使用启动脚本（推荐）
./start-mcp.sh

# 或直接运行
npm start

权限要求

使用本 MCP 服务器需要钉钉应用具备以下权限：

• 管理员工日志数据权限 - 用于创建和保存日志
• 查询企业员工日志权限 - 用于查询日志和模板信息

API 功能详解

创建日志 (createLog)

创建并发送工作日志到指定接收人。

参数：

• template_id - 日志模板ID（必需）
• contents - 日志内容数组（必需）
• userid - 创建日志的员工ID（必需）
• to_userids - 接收人员工ID列表（可选）
• to_chat - 是否发送单聊消息（必需）
• to_cids - 接收群ID列表（可选）
• dd_from - 日志来源标识（必需）

保存草稿 (saveLogDraft)

保存日志内容供后续编辑。

参数：

• template_id - 日志模板ID（必需）
• contents - 日志内容数组（必需）
• userid - 创建日志的员工ID（必需）
• dd_from - 日志来源标识（必需）

获取日志列表 (getLogList)

查询用户发出的日志列表。

参数：

• start_time - 开始时间戳（必需）
• end_time - 结束时间戳（必需）
• template_name - 模板名称（可选）
• userid - 员工ID（可选）
• cursor - 分页游标（必需）
• size - 每页大小（必需）

获取模板列表 (getTemplateList)

获取用户可见的日志模板。

参数：

• userid - 员工ID（可选）
• offset - 分页偏移（可选）
• size - 分页大小（可选）

获取模板详情 (getTemplateDetail)

查看模板字段和配置信息。

参数：

• template_name - 模板名称（必需）
• userid - 操作员工ID（必需）

配置说明

YAML 配置文件

项目使用 dingtalk_log_mcp.yaml 文件配置 API 接口信息。文件包含：

• 工具定义和描述
• API 接口地址和方法
• 参数定义和验证规则

Token 缓存机制

• 自动缓存访问令牌，避免频繁刷新
• 提前5分钟自动刷新，避免过期
• 支持多应用隔离缓存

开发指南

项目结构

dingtalk-log-mcp/
├── src/
│   ├── index.ts          # 主服务器类
│   ├── types.ts          # 类型定义
│   └── cli.ts           # CLI 入口
├── dingtalk_log_mcp.yaml # API 配置
├── package.json         # 项目配置
├── tsconfig.json        # TypeScript 配置
├── env.example          # 环境变量示例
└── start-mcp.sh        # 启动脚本

添加新功能

1. 在 dingtalk_log_mcp.yaml 中添加新的工具定义
2. 在 types.ts 中添加相关类型定义
3. 在 index.ts 中实现特殊的请求处理逻辑（如需要）

调试模式

启动时会输出详细的调试信息到 stderr：

• 加载的工具列表
• API 调用详情
• Token 缓存状态
• 错误信息

注意事项

时间参数

• 日志 API 使用 Unix 时间戳（毫秒）
• start_time 和 end_time 最多相隔 180 天

内容限制

• 日志内容不能超过 1000 字符，超出会被截断
• 支持 Markdown 语法格式

权限设置

• 确保应用已开通相应的日志管理权限
• 模板接收群需要在钉钉后台预先配置

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request 来改进本项目。