dingtalk-checkin-mcp/README.md

DingTalk Checkin MCP Server - Check-in records management for AI assistants

# 钉钉签到MCP Server

这是一个基于钉钉签到API的MCP (Model Context Protocol) Server，提供签到记录查询功能，可与AI助手集成。

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

## 功能特性

- 📋 **部门签到记录** - 获取指定部门的员工签到记录
- 👤 **用户签到记录** - 获取指定用户的签到记录  
- 🔐 **自动认证** - 支持Client ID/Secret自动获取和刷新access_token
- 💾 **Token缓存** - 本地缓存access_token，避免频繁刷新
- 🚀 **标准化接口** - 基于MCP协议，可与任何支持MCP的AI助手集成

## 安装

### 方式一：npm 安装（推荐）

```bash
npm install -g dingtalk-checkin-mcp
```

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

```bash
git clone https://github.com/your-org/dingtalk-checkin-mcp.git
cd dingtalk-checkin-mcp
npm install
```

## 快速开始

### 1. 获取钉钉应用凭证

1. 登录[钉钉开放平台](https://open.dingtalk.com)
2. 创建企业内部应用
3. 获取`Client ID`和`Client Secret`
4. 配置应用权限：
   - **获取签到数据的权限**
   - 通讯录部门信息读权限（可选，如需查询部门信息）

### 2. 配置环境变量

```bash
# 如果从 npm 安装，可以创建配置文件
mkdir -p ~/.config/dingtalk-checkin-mcp
echo "CLIENT_ID=your_client_id" >> ~/.config/dingtalk-checkin-mcp/.env
echo "CLIENT_SECRET=your_client_secret" >> ~/.config/dingtalk-checkin-mcp/.env

# 如果从源码安装
cp env.example .env
# 编辑.env文件，填入你的应用凭证
vim .env
```

### 3. 启动服务

```bash
# 如果从 npm 安装
dingtalk-checkin-mcp

# 如果从源码安装
# 加载环境变量
source .env
# 启动MCP Server
node mcp-server.js
```

## 可用的API工具

### 1. getDepartmentCheckinRecords

获取部门用户签到记录，以部门维度获取员工签到记录进行统计分析。

**参数：**
- `department_id` (必填) - 部门ID，1表示根部门
- `start_time` (必填) - 开始时间，Unix时间戳（毫秒）
- `end_time` (必填) - 结束时间，Unix时间戳（毫秒）
- `offset` (可选) - 分页偏移量，默认0
- `size` (可选) - 分页大小，最大100，默认100
- `order` (可选) - 排序方式，asc/desc，默认asc

**使用示例：**
```javascript
{
  "department_id": "1",
  "start_time": 1704067200000,  // 2024-01-01 00:00:00
  "end_time": 1704153600000,    // 2024-01-02 00:00:00
  "offset": 0,
  "size": 50,
  "order": "asc"
}
```

### 2. getUserCheckinRecords

获取指定用户的签到记录，可获取指定人员的签到记录进行统计分析。

**参数：**
- `userid_list` (必填) - 用户ID列表，多个用逗号分隔，最多10个
- `start_time` (必填) - 开始时间，Unix时间戳（毫秒）
- `end_time` (必填) - 结束时间，Unix时间戳（毫秒）
- `cursor` (必填) - 分页游标，开始时传0
- `size` (必填) - 分页大小，最大100

**使用示例：**
```javascript
{
  "userid_list": "manager4220",
  "start_time": 1704067200000,  // 2024-01-01 00:00:00
  "end_time": 1704153600000,    // 2024-01-02 00:00:00
  "cursor": 0,
  "size": 100
}
```

## 返回数据格式

### 部门签到记录返回格式
```json
{
  "errcode": 0,
  "data": [
    {
      "name": "张三",
      "userId": "manager4220",
      "avatar": "https://static.dingtalk.com/media/xxxx",
      "timestamp": 1599544940000,
      "place": "绿城未来park",
      "detailPlace": "杭州市五常街道",
      "remark": "拜访客户",
      "imageList": ["https://static.dingtalk.com/media/xxxx"],
      "latitude": "30.286053",
      "longitude": "120.017394"
    }
  ],
  "errmsg": "ok"
}
```

### 用户签到记录返回格式
```json
{
  "errcode": 0,
  "result": {
    "page_list": [
      {
        "checkin_time": 1599544940000,
        "detail_place": "浙江省杭州市余杭区五常街道",
        "image_list": ["https://static.dingtalk.com/media/xxxx"],
        "place": "绿城未来park",
        "remark": "客户拜访",
        "userid": "manager4220",
        "longitude": "120.017394",
        "latitude": "30.286046",
        "visit_user": "刘先生"
      }
    ],
    "next_cursor": 100
  },
  "request_id": "pod643x3uywf"
}
```

## 在AI助手中使用

### Cursor IDE

1. 确保MCP Server正在运行
2. 在Cursor中配置MCP服务器连接
3. 使用自然语言询问签到相关问题：
   - "帮我查询技术部门昨天的签到记录"
   - "获取张三这周的签到统计"
   - "分析销售部门本月的签到情况"

### 其他MCP兼容工具

任何支持MCP协议的AI工具都可以使用此服务器，包括但不限于：
- Claude Desktop
- VS Code extensions
- 自定义AI应用

## 故障排除

### 1. 认证失败
- 检查Client ID和Client Secret是否正确
- 确认应用已获得"获取签到数据的权限"
- 检查应用类型是否为企业内部应用

### 2. API调用失败
- 检查参数格式是否正确
- 确认时间范围不超过限制（部门记录45天，用户记录1-10天）
- 查看错误信息中的errcode和errmsg

### 3. 服务启动失败
- 确认Node.js版本 >= 18.0.0
- 检查所有依赖是否正确安装
- 查看启动日志获取详细错误信息

## 开发

### 项目结构
```
dingtalk-checkin-mcp/
├── package.json                 # 项目配置
├── mcp-server.js               # MCP服务器主文件
├── dingtalk_mcp_server.yaml    # API工具配置
├── env.example                 # 环境变量示例
├── README.md                   # 项目文档
└── .dingtalk_token_cache.json  # Token缓存文件（自动生成）
```

### 修改和扩展

如需添加更多API功能：
1. 在`dingtalk_mcp_server.yaml`中添加新的工具配置
2. 确保mcp-server.js能正确解析新的配置
3. 测试新功能是否正常工作

## 许可证

本项目基于MIT许可证开源。

## 相关链接

- [钉钉开放平台](https://open.dingtalk.com)
- [MCP协议规范](https://modelcontextprotocol.io)
- [签到记录API文档](https://open.dingtalk.com/document/orgapp/obtain-employee-attendance-data)