# DingTalk Department Management MCP Server

[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-43853D?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blue?style=for-the-badge)](https://modelcontextprotocol.io/)

一个专门用于钉钉部门管理的 Model Context Protocol (MCP) 服务器，为AI助手提供完整的企业部门查询和管理功能。

## ✨ 功能特性

### 🏢 核心部门管理功能
- **部门详情查询** - 获取指定部门的完整信息（名称、管理员、权限设置等）
- **部门搜索** - 根据部门名称或拼音快速搜索部门ID
- **子部门管理** - 获取部门的下级子部门列表和ID
- **部门层级** - 查询部门的完整父级路径
- **用户部门关系** - 获取用户所属的所有部门层级

### 🔐 智能认证机制
- ✅ 支持 App ID + Secret 自动获取token
- ✅ 支持直接使用 Access Token
- ✅ 自动token刷新和本地缓存
- ✅ 错误处理和重试机制

### 🚀 技术特点
- **TypeScript** - 完整类型安全支持
- **模块化架构** - 基于成熟的MCP框架
- **YAML配置** - 灵活的API配置管理
- **缓存优化** - 减少API调用频率

## 📦 安装

### 环境要求
- Node.js 18.0.0 或更高版本
- npm 或 yarn 包管理器

### 从源码安装
```bash
# 克隆项目
git clone https://github.com/your-org/dingtalk-department-mcp.git
cd dingtalk-department-mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 全局安装
npm install -g .
```

### 从npm安装（发布后）
```bash
npm install -g dingtalk-department-mcp
```

## ⚙️ 配置

### 1. 环境变量配置

复制环境变量模板：
```bash
cp env.example .env
```

编辑 `.env` 文件：
```env
# 推荐方式：使用App ID和Secret
DINGTALK_Client_ID=your_app_id_here
DINGTALK_Client_Secret=your_app_secret_here

# 或者直接使用Access Token
# DINGTALK_ACCESS_TOKEN=your_access_token_here
```

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

1. 访问 [钉钉开发者后台](https://open-dev.dingtalk.com/)
2. 创建或选择你的应用
3. 在应用详情中找到 **App ID (AppKey)** 和 **App Secret**
4. 确保应用拥有 **"通讯录部门信息读权限"**

### 3. Cursor IDE 配置

在 Cursor 的设置中添加 MCP 服务器：

```json
{
  "mcpServers": {
    "dingtalk-department": {
      "command": "dingtalk-department-mcp",
      "env": {
        "DINGTALK_Client_ID": "your_app_id_here",
        "DINGTALK_Client_Secret": "your_app_secret_here"
      }
    }
  }
}
```

## 🛠️ 可用工具

### 1. getDepartmentDetail
获取指定部门的详细信息
```typescript
// 参数
{
  dept_id: number;      // 部门ID，根部门ID为1
  language?: string;    // 语言设置，zh_CN或en_US
}
```

### 2. searchDepartment
根据部门名称搜索部门ID
```typescript
// 参数
{
  queryWord: string;    // 部门名称或拼音
  offset?: number;      // 分页页码，默认0
  size?: number;        // 分页大小，默认10
}
```

### 3. listSubDepartments
获取指定部门的下级子部门列表
```typescript
// 参数
{
  dept_id?: number;     // 父部门ID，不传则获取根部门
  language?: string;    // 语言设置
}
```

### 4. listSubDepartmentIds
获取指定部门的直属子部门ID列表
```typescript
// 参数
{
  dept_id: number;      // 父部门ID，根部门传1
}
```

### 5. getDepartmentParents
获取指定部门的所有父部门路径
```typescript
// 参数
{
  dept_id: number;      // 要查询的部门ID
}
```

### 6. getUserDepartmentParents
获取用户所属的所有部门层级
```typescript
// 参数
{
  userid: string;       // 用户的userid
}
```

## 💡 使用示例

### 在AI助手中使用

```
用户: 帮我查找财务部门的详细信息
AI: 我来帮你搜索财务部门并获取详细信息...

用户: 列出市场部的所有子部门
AI: 我来获取市场部的子部门列表...

用户: 查看张三所属的所有部门层级
AI: 我来查询张三的部门归属情况...
```

### 直接命令行使用

```bash
# 启动服务器
dingtalk-department-mcp

# 开发模式
npm run dev
```

## 🏗️ 开发

### 项目结构
```
dingtalk-department-mcp/
├── src/
│   ├── index.ts              # 主服务器类
│   ├── cli.ts                # 命令行入口
│   └── types.ts              # 类型定义
├── dingtalk_department_mcp.yaml  # API配置
├── package.json              # 项目配置
├── tsconfig.json             # TypeScript配置
├── env.example               # 环境变量模板
└── README.md                 # 说明文档
```

### 开发命令
```bash
# 安装依赖
npm install

# 开发模式（自动重新构建）
npm run dev

# 构建项目
npm run build

# 类型检查
npm run type-check

# 清理构建产物
npm run clean

# 测试
npm test
```

### 添加新的API

1. 在 `dingtalk_department_mcp.yaml` 中添加新的工具配置
2. 更新 `src/types.ts` 中的类型定义
3. 如需特殊处理，修改 `src/index.ts` 中的相关方法
4. 重新构建项目

## 📚 API 文档

本项目支持的钉钉API：

| API | 版本 | 端点 | 说明 |
|-----|------|------|------|
| 获取部门详情 | v2 | `/topapi/v2/department/get` | 获取完整部门信息 |
| 搜索部门 | v1.0 | `/v1.0/contact/departments/search` | 按名称搜索部门 |
| 获取子部门列表 | v2 | `/topapi/v2/department/listsub` | 获取下级部门 |
| 获取子部门ID | v2 | `/topapi/v2/department/listsubid` | 获取子部门ID |
| 获取部门父级 | v2 | `/topapi/v2/department/listparentbydept` | 获取父部门路径 |
| 获取用户部门 | v2 | `/topapi/v2/department/listparentbyuser` | 获取用户部门路径 |

## 🔧 故障排除

### 常见问题

1. **Token认证失败**
   - 检查App ID和Secret是否正确
   - 确认应用拥有必要的权限
   - 查看token缓存文件是否损坏

2. **API调用失败**
   - 检查网络连接
   - 确认API端点是否正确
   - 查看钉钉API文档获取最新信息

3. **构建错误**
   - 确保Node.js版本 >= 18.0.0
   - 删除 `node_modules` 重新安装依赖
   - 检查TypeScript版本兼容性

### 调试模式

设置环境变量启用详细日志：
```bash
DEBUG=dingtalk-department:* npm run dev
```

## 🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🔗 相关链接

- [钉钉开放平台](https://open.dingtalk.com/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Cursor IDE](https://cursor.sh/)
- [TypeScript](https://www.typescriptlang.org/)

## 📞 支持

如果你遇到问题或有建议，请：

1. 查看 [Issues](https://github.com/your-org/dingtalk-department-mcp/issues)
2. 创建新的 Issue
3. 联系维护者

---

**Made with ❤️ for the DingTalk developer community**