dingtalk-mcp-calendar/README.md

DingTalk Calendar MCP Server - TypeScript implementation for AI assistants

# DingTalk Calendar MCP Server | 钉钉日程 MCP Server

[![npm version](https://badge.fury.io/js/dingtalk-mcp-calendar.svg)](https://badge.fury.io/js/dingtalk-mcp-calendar)
[![npm downloads](https://img.shields.io/npm/dm/dingtalk-mcp-calendar.svg)](https://www.npmjs.com/package/dingtalk-mcp-calendar)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8+-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)

**Languages | 语言**: [English](#english) | [中文](#中文)

---

## English

### 📖 Overview

A TypeScript-based Model Context Protocol (MCP) server for DingTalk Calendar integration. This server enables AI assistants like Claude Desktop and Cursor to interact with DingTalk Calendar APIs through the MCP protocol, providing seamless calendar management capabilities.

### ✨ Features

- **🔥 NPX Ready**: Run directly with `npx dingtalk-mcp-calendar` - no installation required
- **📝 Full TypeScript Support**: Complete type definitions and compile-time safety
- **🚀 11 Calendar Tools**: Comprehensive DingTalk calendar operations
- **🔐 Smart Token Management**: Automatic access token caching and refresh
- **⚡ Modern ESM**: Uses latest ES modules with optimal performance
- **🛡️ Error Handling**: Robust error handling and detailed logging
- **🎯 AI-First Design**: Optimized for AI assistant integration

### 📦 Installation

#### Prerequisites

Before using DingTalk Calendar MCP Server, ensure you have:

- **Node.js** >= 18.0.0
- **DingTalk Application Credentials**: App ID and App Secret from DingTalk Open Platform

#### Installation using NPX (Recommended)

The easiest way to use the DingTalk Calendar MCP Server is with NPX:

```bash
# Run directly without installation
npx dingtalk-mcp-calendar
```

Alternative installation methods:

```bash
# Global installation
npm install -g dingtalk-mcp-calendar

# Project dependency
npm install dingtalk-mcp-calendar
```

### 🚀 Using DingTalk Calendar MCP

#### 1. Set Environment Variables

Configure your DingTalk application credentials:

```bash
# Option A: Use direct access token
export DINGTALK_ACCESS_TOKEN=your_access_token_here

# Option B: Use app credentials (recommended)
export DINGTALK_Client_ID=your_app_id
export DINGTALK_Client_Secret=your_app_secret
```

#### 2. Configure MCP Client

Add to your MCP client configuration (e.g., Claude Desktop `config.json`):

```json
{
  "mcpServers": {
    "dingtalk-calendar": {
      "command": "npx",
      "args": ["dingtalk-mcp-calendar@1.0.2"],
      "env": {
        "DINGTALK_Client_ID": "your_app_id",
        "DINGTALK_Client_Secret": "your_app_secret"
      }
    }
  }
}
```

#### 3. Available Tools

The server provides 11 powerful DingTalk Calendar tools:

| Tool | Description |
|------|-------------|
| `createEvent` | 📅 Create new calendar events |
| `updateEvent` | ✏️ Update existing events |
| `deleteEvent` | 🗑️ Delete calendar events |
| `listEvents` | 📋 List calendar events in a time range |
| `getEventDetails` | 🔍 Get detailed event information |
| `getEventsView` | 📆 Get calendar view with recurring events |
| `addAttendee` | ➕ Add participants to events |
| `removeAttendee` | ➖ Remove participants from events |
| `listAttendees` | 👥 List event participants |
| `searchUser` | 🔎 Search for users in organization |
| `getUserDetails` | 👤 Get detailed user information |

#### 4. Start Using

Once configured, your AI assistant can now:
- Create and manage calendar events
- Query schedules and availability
- Add/remove event participants
- Search users in your organization
- And much more!

### 💻 Programmatic Usage

For developers who want to integrate the server programmatically:

```typescript
import { DingTalkMCPServer } from 'dingtalk-mcp-calendar';

const server = new DingTalkMCPServer({
  appId: 'your_app_id',
  appSecret: 'your_app_secret',
  // Optional: custom config path
  configPath: './custom_config.yaml'
});

await server.run();
```

### 🔧 Configuration

#### Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `DINGTALK_ACCESS_TOKEN` | Direct access token | Either this or app credentials |
| `DINGTALK_Client_ID` | Application ID | Either this with app secret |
| `DINGTALK_Client_Secret` | Application secret | Either this with app ID |

#### Token Caching

The server automatically caches access tokens for optimal performance:

- 📁 **Cache file**: `.dingtalk_token_cache.json`
- ⏰ **Auto-refresh**: 5 minutes before expiration
- 🔄 **Multi-app support**: Supports different app configurations

### 🏗️ Development

#### Build from Source

```bash
# Clone and setup
git clone https://github.com/your-org/dingtalk-mcp-calendar.git
cd dingtalk-mcp-calendar
npm install

# Build and run
npm run build
npm start
```

#### Development Scripts

```bash
npm run build        # Compile TypeScript
npm run dev          # Build and run in development mode
npm run clean        # Clean build artifacts
npm run type-check   # Type check without building
npm start            # Build and start server
```

### 🧪 Testing

Verify the installation:

```bash
# Test NPX functionality
npx dingtalk-mcp-calendar@1.0.2

# Should output:
# Loaded 11 tools from config
# Tools: addAttendee, createEvent, deleteEvent, getEventsView, getEventDetails...
# DingTalk Calendar MCP server running on stdio
```

### 🔍 Troubleshooting

#### Common Issues

**🔑 Token Authentication Failed**
- Verify app credentials are correct
- Check network connectivity to DingTalk APIs
- Ensure token cache file permissions

**📦 NPX/Installation Issues**
- Update Node.js to >= 18.0.0
- Clear npm cache: `npm cache clean --force`
- Try with explicit version: `npx dingtalk-mcp-calendar@1.0.2`

**⚙️ TypeScript Compilation Errors**
- Ensure TypeScript >= 5.3.0
- Run `npm install` to update dependencies
- Check for conflicting dependencies

#### Debug Mode

Enable verbose logging:

```bash
DEBUG=dingtalk-mcp npx dingtalk-mcp-calendar
```

### 📊 Version History

- **1.0.2** - 🎉 **Current**: Optimized MCP configuration with enhanced response templates and improved parameter descriptions
- **1.0.0** - Initial release with TypeScript implementation, 11 DingTalk calendar tools, and improved environment variable naming

### 🙏 Acknowledgments

- **DingTalk Open Platform** for providing comprehensive APIs
- **Model Context Protocol** for the excellent MCP framework
- **TypeScript Community** for the amazing language and tooling

---

**📱 Ready to supercharge your AI assistant with DingTalk Calendar integration?**

```bash
npx dingtalk-mcp-calendar@1.0.2
```

**🎉 Get started in seconds!**

---

## 中文

### 📖 概述

基于 TypeScript 的钉钉日程 Model Context Protocol (MCP) server。该 MCP Server 使 Claude Desktop 和 Cursor 等 AI 助手能够通过 MCP 协议与钉钉日程 API 进行交互，提供无缝的日程管理功能。

### ✨ 功能特性

- **🔥 NPX 即用**: 使用 `npx dingtalk-mcp-calendar` 直接运行，无需安装
- **📝 完整 TypeScript 支持**: 完整的类型定义和编译时类型安全
- **🚀 11 个钉钉日程工具**: 全面的钉钉日程操作功能
- **🔐 智能令牌管理**: 自动访问令牌缓存和刷新
- **⚡ 现代 ESM**: 使用最新的 ES 模块，性能最优
- **🛡️ 错误处理**: 健壮的错误处理和详细日志记录
- **🎯 AI 优先设计**: 专为 AI 助手集成优化

### 📦 安装

#### 前置要求

使用钉钉日程 MCP Server 之前，请确保你有：

- **Node.js** >= 18.0.0
- **钉钉应用凭证**: 从钉钉开放平台获取应用 ID 和应用密钥

#### 使用 NPX 安装（推荐）

使用钉钉日程 MCP Server 最简单的方式是使用 NPX：

```bash
# 无需安装直接运行
npx dingtalk-mcp-calendar
```

其他安装方式：

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

# 项目依赖
npm install dingtalk-mcp-calendar
```

### 🚀 使用钉钉日程 MCP

#### 1. 设置环境变量

配置你的钉钉应用凭证：

```bash
# 方式 A: 使用直接访问令牌
export DINGTALK_ACCESS_TOKEN=your_access_token_here

# 方式 B: 使用应用凭证（推荐）
export DINGTALK_Client_ID=your_app_id
export DINGTALK_Client_Secret=your_app_secret
```

#### 2. 配置 MCP 客户端

在你的 MCP 客户端配置中添加（例如 Claude Desktop 的 `config.json`）：

```json
{
  "mcpServers": {
        "dingtalk-calendar": {
      "command": "npx",
       "args": ["dingtalk-mcp-calendar@1.0.2"],
       "env": {
        "DINGTALK_Client_ID": "your_app_id",
        "DINGTALK_Client_Secret": "your_app_secret"
      }
    }
  }
}
```

#### 3. 可用工具

该 MCP Server 提供 11 个强大的钉钉日程工具：

| 工具 | 描述 |
|------|------|
| `createEvent` | 📅 创建新的日程 |
| `updateEvent` | ✏️ 更新日程 |
| `deleteEvent` | 🗑️ 删除日程 |
| `listEvents` | 📋 查询日程列表 |
| `getEventDetails` | 🔍 获取日程详情 |
| `getEventsView` | 📆 查询日程视图 |
| `addAttendee` | ➕ 新增日程参与者 |
| `removeAttendee` | ➖ 从日程中删除参与者 |
| `listAttendees` | 👥 列出日程参与者 |
| `searchUser` | 🔎 在组织中搜索用户 |
| `getUserDetails` | 👤 获取详细的用户信息 |

#### 4. 开始使用

配置完成后，你的 AI 助手现在可以：
- 创建和管理日程
- 查询日程和用户闲忙
- 添加/删除日程参与者
- 搜索组织中的用户
- 还有更多功能！

### 💻 编程式使用

对于想要以编程方式集成服务器的开发者：

```typescript
import { DingTalkMCPServer } from 'dingtalk-mcp-calendar';

const server = new DingTalkMCPServer({
  appId: 'your_app_id',
  appSecret: 'your_app_secret',
  // 可选：自定义配置路径
  configPath: './custom_config.yaml'
});

await server.run();
```

### 🔧 配置选项

#### 环境变量

| 变量 | 描述 | 是否必需 |
|------|------|----------|
| `DINGTALK_ACCESS_TOKEN` | 钉钉应用凭证（access_token） | 二选一 |
| `DINGTALK_Client_ID` | 应用 ID （Client ID） | 二选一（与应用密钥配合） |
| `DINGTALK_Client_Secret` | 应用密钥 (Client Secret) | 二选一（与应用 ID 配合） |

#### 凭证缓存

该 MCP Server 会自动缓存应用凭证以获得最佳性能：

- 📁 **缓存文件**: `.dingtalk_token_cache.json`
- ⏰ **自动刷新**: 过期前 5 分钟自动刷新
- 🔄 **多应用支持**: 支持不同的应用配置

### 🔍 故障排除

#### 常见问题

**🔑 令牌认证失败**
- 验证应用凭证是否正确
- 检查到钉钉 API 的网络连接
- 确保应用凭证缓存文件权限正确

**📦 NPX/安装问题**
- 将 Node.js 更新到 >= 18.0.0
- 清理 npm 缓存: `npm cache clean --force`
- 尝试指定版本: `npx dingtalk-mcp-calendar@1.0.2`

**⚙️ TypeScript 编译错误**
- 确保 TypeScript >= 5.3.0
- 运行 `npm install` 更新依赖
- 检查是否有冲突的依赖

#### 调试模式

启用详细日志记录：

```bash
DEBUG=dingtalk-mcp npx dingtalk-mcp-calendar
```

### 📊 版本历史

- **1.0.2** - 🎉 **当前版本**: 优化的 MCP 配置，增强响应模板和改进参数描述
- **1.0.0** - 完整的 TypeScript 实现，包含 11 个钉钉日程工具，改进了环境变量命名

### 🙏 致谢

- **钉钉开放平台** 提供全面的 API
- **Model Context Protocol** 提供出色的 MCP 框架
- **TypeScript 社区** 提供优秀的语言和工具

---

**📱 准备好使用钉钉日程集成来增强你的 AI 助手了吗？**

```bash
npx dingtalk-mcp-calendar@1.0.2
```

**🎉 几秒钟即可开始！**