dingtalk-department-mcp
Version:
DingTalk Department Management MCP Server - TypeScript implementation for AI assistants
300 lines (230 loc) • 7.36 kB
Markdown
# DingTalk Department Management MCP Server
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](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**