dingtalk-mcp 1.0.12 → 1.0.14

package/dingtalk_checkin_mcp_server.yaml

@@ -0,0 +1,76 @@
+server:
+  name: dingtalk-checkin
+  description: 钉钉签到
+tools:
+  - name: getDepartmentCheckinRecords
+    description: 获取部门用户签到记录，以部门维度获取员工签到记录进行统计分析
+    requestTemplate:
+      method: GET
+      url: https://oapi.dingtalk.com/checkin/record
+      headers: []
+    args:
+      - name: department_id
+        type: string
+        required: true
+        position: query
+        description: 部门ID，1表示根部门，可通过获取部门列表接口获取dept_id参数值
+      - name: start_time
+        type: number
+        required: true
+        position: query
+        description: 开始时间，Unix时间戳，单位毫秒
+      - name: end_time
+        type: number
+        required: true
+        position: query
+        description: 结束时间，Unix时间戳，单位毫秒。开始时间和结束时间的间隔不能大于45天
+      - name: offset
+        type: number
+        required: false
+        position: query
+        description: 支持分页查询，与size参数同时设置时才生效，此参数代表偏移量，从0开始，默认为0
+      - name: size
+        type: number
+        required: false
+        position: query
+        description: 支持分页查询，与offset参数同时设置时才生效，此参数代表分页大小，最大100，默认为100
+      - name: order
+        type: string
+        required: false
+        position: query
+        description: 排序方式，asc为正序，desc为倒序，默认为asc
+
+  - name: getUserCheckinRecords
+    description: 获取指定用户的签到记录，可获取指定人员的签到记录进行统计分析
+    requestTemplate:
+      method: POST
+      url: https://oapi.dingtalk.com/topapi/checkin/record/get
+      headers:
+        - key: Content-Type
+          value: application/json
+    args:
+      - name: userid_list
+        type: string
+        required: true
+        position: body
+        description: 需要查询的用户列表，最大列表长度为10，多个用户用逗号分隔
+      - name: start_time
+        type: number
+        required: true
+        position: body
+        description: 开始时间，Unix时间戳，单位毫秒
+      - name: end_time
+        type: number
+        required: true
+        position: body
+        description: 截止时间，单位毫秒。如果是取1个人的数据，时间范围最大10天；如果是取多个人的数据，时间范围最大1天
+      - name: cursor
+        type: number
+        required: true
+        position: body
+        description: 分页查询的游标，最开始可以传0
+      - name: size
+        type: number
+        required: true
+        position: body
+        description: 分页查询的每页大小，最大100 

package/dingtalk_contacts_mcp_server.yaml

@@ -95,4 +95,21 @@ tools:
           value: application/json
       security:
         id: DingTalkAuth
-    responseTemplate: { }
+    responseTemplate: { }
+  - name: getDepartmentUsersByDepId
+    description: 获取指定部门下的所有成员的userId。
+    args:
+      - name: dept_id
+        description: 部门ID
+        type: number
+        required: true
+        position: body
+    requestTemplate:
+      url: https://oapi.dingtalk.com/topapi/user/listid
+      method: POST
+      headers:
+        - key: Content-Type
+          value: application/json
+      security:
+        id: DingTalkAuth
+    responseTemplate: { }

package/dingtalk_department_mcp_server.yaml

@@ -0,0 +1,95 @@
+server:
+  name: dingtalk-department
+  description: 钉钉部门管理
+tools:
+  - name: getDepartmentDetail
+    description: 获取指定部门的详细信息，包括部门名称、父部门、管理员、权限设置等完整信息
+    requestTemplate:
+      method: POST
+      url: https://oapi.dingtalk.com/topapi/v2/department/get
+    args:
+      - name: dept_id
+        type: number
+        required: true
+        position: body
+        description: 部门ID，根部门ID为1
+      - name: language
+        type: string
+        required: false
+        position: body
+        description: 通讯录语言，zh_CN(中文)或en_US(英文)，默认zh_CN
+
+  - name: searchDepartment
+    description: 根据部门名称搜索部门ID，支持部门名称或拼音搜索
+    requestTemplate:
+      method: POST
+      url: https://api.dingtalk.com/v1.0/contact/departments/search
+    args:
+      - name: queryWord
+        type: string
+        required: true
+        position: body
+        description: 部门名称或者部门名称拼音
+      - name: offset
+        type: number
+        required: false
+        position: body
+        description: 分页页码，默认0
+      - name: size
+        type: number
+        required: false
+        position: body
+        description: 分页大小，默认10，最大100
+
+  - name: listSubDepartments
+    description: 获取指定部门的下一级子部门基础信息列表
+    requestTemplate:
+      method: POST
+      url: https://oapi.dingtalk.com/topapi/v2/department/listsub
+    args:
+      - name: dept_id
+        type: number
+        required: false
+        position: body
+        description: 父部门ID，不传则获取根部门的子部门，根部门ID为1
+      - name: language
+        type: string
+        required: false
+        position: body
+        description: 通讯录语言，zh_CN(中文)或en_US(英文)，默认zh_CN
+
+  - name: listSubDepartmentIds
+    description: 获取指定部门下的所有直属子部门ID列表
+    requestTemplate:
+      method: POST
+      url: https://oapi.dingtalk.com/topapi/v2/department/listsubid
+    args:
+      - name: dept_id
+        type: number
+        required: true
+        position: body
+        description: 父部门ID，根部门传1
+
+  - name: getDepartmentParents
+    description: 获取指定部门的所有父部门ID列表，从当前部门到根部门的完整路径
+    requestTemplate:
+      method: POST
+      url: https://oapi.dingtalk.com/topapi/v2/department/listparentbydept
+    args:
+      - name: dept_id
+        type: number
+        required: true
+        position: body
+        description: 要查询的部门ID
+
+  - name: getUserDepartmentParents
+    description: 获取指定用户所属的所有父级部门路径，返回用户所有部门归属的层级结构
+    requestTemplate:
+      method: POST
+      url: https://oapi.dingtalk.com/topapi/v2/department/listparentbyuser
+    args:
+      - name: userid
+        type: string
+        required: true
+        position: body
+        description: 要查询的用户的userid 

package/dingtalk_honor_mcp_server.yaml

@@ -0,0 +1,174 @@
+server:
+  name: dingtalk-honor
+  version: 1.0.0
+  description: DingTalk Honor Management MCP Server - 钉钉企业文化荣誉管理服务
+
+tools:
+  # 1. 给员工颁发荣誉
+  - name: mcp_dingtalk-honor_grantHonor
+    description: |
+      给组织内的员工颁发荣誉，支持单人或多人批量颁发。
+      颁发后员工会收到荣誉推送消息，可以选择佩戴荣誉挂件。
+      注意：同一个颁发人不允许并发执行，需要串行调用。
+    requestTemplate:
+      method: POST
+      url: "https://api.dingtalk.com/v1.0/orgCulture/honors/{honorId}/grant"
+    args:
+      - name: honorId
+        type: string
+        description: "荣誉ID，可通过查询企业荣誉列表接口获取"
+        position: path
+        required: true
+      - name: senderUserId
+        type: string
+        description: "发送人userId。注意：同一个发送人给多个员工颁发荣誉时，请分别按顺序执行，不允许并发执行"
+        position: body
+        required: true
+      - name: grantReason
+        type: string
+        description: "颁奖词，最多50个字符"
+        position: body
+        required: true
+      - name: granterName
+        type: string
+        description: "颁奖人名字，最多15个字符"
+        position: body
+        required: true
+      - name: receiverUserIds
+        type: array
+        description: "接收人userId列表，最多10个"
+        position: body
+        required: true
+        items:
+          type: string
+      - name: expirationTime
+        type: number
+        description: "荣誉有效期到期时间戳（毫秒）。不传代表永久有效。有效期时间范围要求1~366天后"
+        position: body
+        required: false
+      - name: noticeSingle
+        type: boolean
+        description: "是否发送单聊通知。true:发送，false:不发送"
+        position: body
+        required: false
+      - name: noticeAnnouncer
+        type: boolean
+        description: "是否使用官宣号通知获奖人。true:通知，false:不通知"
+        position: body
+        required: false
+      - name: openConversationIds
+        type: array
+        description: "接收荣誉消息的群openConversationId列表，最多5个。注意：发送人必须是群成员"
+        position: body
+        required: false
+        items:
+          type: string
+
+  # 2. 查询当前企业下可颁发的荣誉列表
+  - name: mcp_dingtalk-honor_queryOrgHonors
+    description: |
+      查询当前企业下可颁发的荣誉列表，包括荣誉ID、名称、描述、图标等信息。
+      支持分页查询，可用于展示荣誉选择列表。
+    requestTemplate:
+      method: GET
+      url: "https://api.dingtalk.com/v1.0/orgCulture/organizations/honors?nextToken=String&maxResults=Integer"
+    args:
+      - name: nextToken
+        type: string
+        description: "分页游标。首次调用传0，非首次调用传上次返回的nextToken值"
+        position: query
+        required: true
+      - name: maxResults
+        type: number
+        description: "每页最大条目数，默认值20，最大值100"
+        position: query
+        required: false
+
+  # 3. 查询员工已获得的组织荣誉
+  - name: mcp_dingtalk-honor_queryUserHonors
+    description: |
+      查询某个员工获得的组织荣誉记录，包括荣誉ID、名称、授予时间、发放人等信息。
+      可用于展示员工的荣誉墙或荣誉历史。
+    requestTemplate:
+      method: GET
+      url: "https://api.dingtalk.com/v1.0/orgCulture/honors/users/{userId}?nextToken=String&maxResults=Integer"
+    args:
+      - name: userId
+        type: string
+        description: "要查询的员工userId"
+        position: path
+        required: true
+      - name: nextToken
+        type: string
+        description: "分页游标。首次查询传0，非首次查询传上次返回的nextToken"
+        position: query
+        required: true
+      - name: maxResults
+        type: number
+        description: "每页返回的最大条目数，默认20，最大100"
+        position: query
+        required: false
+
+  # 4. 创建荣誉勋章模板
+  - name: mcp_dingtalk-honor_createOrgHonor
+    description: |
+      创建企业荣誉勋章模板。创建后会流入钉钉后台审核，一般5个工作日内审核完毕。
+      注意事项：
+      1. 需要主管理员或子管理员权限
+      2. 企业每周的审核次数有限制（标准版每周10次/专业版每周20次）
+      3. 不允许并发调用，如需批量创建请串行执行
+      4. 图片需要先调用上传媒体文件接口获取media_id
+    requestTemplate:
+      method: POST
+      url: "https://api.dingtalk.com/v1.0/orgCulture/honors/templates"
+    args:
+      - name: userId
+        type: string
+        description: "创建荣誉勋章模板的管理员userId，需要主管理员或子管理员角色"
+        position: body
+        required: true
+      - name: medalName
+        type: string
+        description: "荣誉勋章名称，最大长度10字符，不支持表情图标"
+        position: body
+        required: true
+      - name: medalDesc
+        type: string
+        description: "荣誉勋章描述，最大长度30字符，不支持表情图标"
+        position: body
+        required: true
+      - name: medalMediaId
+        type: string
+        description: "荣誉勋章图片的media_id（900x900，不超过1M，PNG格式）"
+        position: body
+        required: true
+      - name: avatarFrameMediaId
+        type: string
+        description: "头像挂件图片的media_id（240x240，不超过1M，PNG格式）"
+        position: body
+        required: true
+      - name: defaultBgColor
+        type: string
+        description: "背景颜色，可选值：#FFFBB4, #FFE7BC, #FFDAF4, #DAF6A8, #E4D7FF, #BFDFFF, #B9F2D6"
+        position: body
+        required: true
+
+  # 5. 撤销员工获得的荣誉勋章
+  - name: mcp_dingtalk-honor_recallHonor
+    description: |
+      撤销员工已获得的荣誉勋章。
+      撤销后员工将无法继续佩戴该荣誉。
+    requestTemplate:
+      method: POST
+      url: "https://api.dingtalk.com/v1.0/orgCulture/honors/{honorId}/recall"
+    args:
+      - name: honorId
+        type: string
+        description: "要撤销的荣誉勋章ID，可通过查询员工已获得的组织荣誉接口获取"
+        position: path
+        required: true
+      - name: userId
+        type: string
+        description: "要撤销荣誉的员工userId"
+        position: body
+        required: true

package/dingtalk_notice_mcp_server.yaml

@@ -0,0 +1,85 @@
+server:
+  name: dingtalk-notice
+  version: 1.0.0
+  description: DingTalk Work Notice MCP Server - 钉钉工作通知
+
+tools:
+  # 发送工作通知消息
+  - name: sendNotice
+    description: 发送工作通知消息，支持3种消息类型：text、link、markdown
+    requestTemplate:
+      method: POST
+      url: https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2
+    args:
+      - name: userid_list
+        type: string
+        required: false
+        position: body
+        description: 接收人用户ID列表，用逗号分隔，最多5000人
+      - name: dept_id_list
+        type: string
+        required: false
+        position: body
+        description: 接收部门ID列表，用逗号分隔（可选）
+      - name: to_all_user
+        type: boolean
+        required: false
+        position: body
+        description: 是否发送给全员（可选，默认false）
+      - name: msg
+        type: object
+        required: true
+        position: body
+        description: 消息内容，支持text、link、markdown三种类型
+
+  # 获取工作通知消息的发送结果
+  - name: getSendResult
+    description: 获取工作通知消息的发送结果，查询消息发送状态和统计信息
+    requestTemplate:
+      method: POST
+      url: https://oapi.dingtalk.com/topapi/message/corpconversation/getsendresult
+    args:
+      - name: task_id
+        type: number
+        required: true
+        position: body
+        description: 发送任务ID（发送消息时返回的task_id）
+
+  # 获取工作通知消息的发送进度
+  - name: getSendProgress
+    description: 获取工作通知消息的发送进度，实时查询消息发送进度
+    requestTemplate:
+      method: POST
+      url: https://oapi.dingtalk.com/topapi/message/corpconversation/getsendprogress
+    args:
+      - name: task_id
+        type: number
+        required: true
+        position: body
+        description: 发送任务ID（发送消息时返回的task_id）
+
+  # 撤回工作通知消息
+  - name: recallNotice
+    description: 撤回已发送的工作通知消息，消息撤回后接收人将无法看到该消息
+    requestTemplate:
+      method: POST
+      url: https://oapi.dingtalk.com/topapi/message/corpconversation/recall
+    args:
+      - name: msg_task_id
+        type: number
+        required: true
+        position: body
+        description: 要撤回的消息任务ID
+
+  # 获取消息模板（内置功能）
+  - name: getMessageTemplates
+    description: 获取所有支持的消息类型模板和示例，帮助用户快速了解消息格式
+    requestTemplate:
+      method: LOCAL
+      url: local://templates
+    args:
+      - name: msgtype
+        type: string
+        required: false
+        position: query
+        description: 指定消息类型（text、link、markdown），不指定则返回所有类型 

package/dingtalk_servicewindow_mcp_server.yaml

@@ -0,0 +1,109 @@
+server:
+  name: dingtalk-servicewindow
+  version: 1.0.0
+  description: 钉钉服务窗
+  securitySchemes:
+    - id: DingTalkAuth
+      type: apiKey
+      in: header
+      name: x-acs-dingtalk-access-token
+
+# 注意：当前版本的工具定义在代码中，此配置文件为预留扩展
+tools:
+  - name: buildServiceWindowMessage
+    description: "构建服务窗消息体，支持文本、链接、markdown、卡片等多种类型"
+    requestTemplate:
+      method: POST
+      url: "internal://message-builder"
+      
+  - name: sendServiceWindowMessage
+    description: "发送服务窗单人消息"
+    requestTemplate:
+      method: POST
+      url: "https://api.dingtalk.com/v1.0/crm/officialAccounts/oToMessages/send"
+      security:
+        id: DingTalkAuth
+        
+  - name: batchSendServiceWindowMessage
+    description: "批量发送服务窗消息"
+    requestTemplate:
+      method: POST
+      url: "https://api.dingtalk.com/v1.0/crm/officialAccounts/oToMessages/batchSend"
+      security:
+        id: DingTalkAuth
+        
+  - name: getServiceWindowFollower
+    description: "获取关注服务窗的单个用户信息"
+    requestTemplate:
+      method: GET
+      url: "https://api.dingtalk.com/v1.0/link/followers/infos"
+      security:
+        id: DingTalkAuth
+        
+  - name: listServiceWindowFollowers
+    description: "分页获取关注服务窗的用户列表"
+    requestTemplate:
+      method: GET
+      url: "https://api.dingtalk.com/v1.0/link/followers"
+      security:
+        id: DingTalkAuth
+        
+  - name: getUserFollowStatus
+    description: "获取用户的服务窗关注状态"
+    requestTemplate:
+      method: GET
+      url: "https://api.dingtalk.com/v1.0/link/followers/status"
+      security:
+        id: DingTalkAuth
+        
+  - name: listServiceWindows
+    description: "获取企业下的服务窗列表"
+    requestTemplate:
+      method: GET
+      url: "https://api.dingtalk.com/v1.0/link/accounts"
+      security:
+        id: DingTalkAuth
+
+# 消息类型定义
+messageTypes:
+  text:
+    description: "纯文本消息"
+    maxLength: 500
+    
+  link:
+    description: "链接消息"
+    fields:
+      title:
+        maxLength: 128
+        required: true
+      text:
+        maxLength: 500
+        required: true
+      messageUrl:
+        pattern: "^https?://.+"
+        required: true
+      picUrl:
+        required: true
+        
+  markdown:
+    description: "Markdown格式消息"
+    fields:
+      title:
+        maxLength: 30
+        required: true
+      text:
+        maxLength: 500
+        required: true
+        
+  actionCard:
+    description: "卡片消息"
+    fields:
+      title:
+        maxLength: 30
+        required: true
+      markdown:
+        maxLength: 1000
+        required: true
+      cardType:
+        enum: ["single", "independent"]
+        required: true

package/dist/DingTalkMCPServer.js

@@ -386,7 +386,7 @@ export class DingTalkMCPServer {
             'Content-Type': 'application/json'
         };
         // 只有对新版API (api.dingtalk.com) 才添加token到header
-        if (tool.requestTemplate.url && !tool.requestTemplate.url.includes('oapi.dingtalk.com') && tool.requestTemplate.security && this.accessToken) {
+        if (tool.requestTemplate.url && !tool.requestTemplate.url.includes('oapi.dingtalk.com') && this.accessToken) {
             headers['x-acs-dingtalk-access-token'] = this.accessToken;
         }
         if (tool.requestTemplate.headers) {

package/dist/cli.js

@@ -1,20 +1,67 @@
 #!/usr/bin/env node
 import { DingTalkMCPServer } from './DingTalkMCPServer.js';
 async function main() {
+    // 检查环境变量
+    const appId = process.env.DINGTALK_Client_ID;
+    const appSecret = process.env.DINGTALK_Client_Secret;
+    const accessToken = process.env.DINGTALK_ACCESS_TOKEN;
+    process.env.ACTIVE_PROFILES = 'dingtalk-contacts,dingtalk-department'
+    // 如果既没有AppKey/Secret也没有AccessToken，显示帮助信息
+    if (!accessToken && (!appId || !appSecret)) {
+        console.error('🔧 DingTalk MCP Server 配置指南');
+        console.error('');
+        console.error('📋 需要设置以下环境变量之一：');
+        console.error('');
+        console.error('方式1 - 使用AppKey/Secret（推荐）：');
+        console.error('  DINGTALK_Client_ID=your_app_key');
+        console.error('  DINGTALK_Client_Secret=your_app_secret');
+        console.error('');
+        console.error('方式2 - 直接使用AccessToken（测试用）：');
+        console.error('  DINGTALK_ACCESS_TOKEN=your_access_token');
+        console.error('');
+        console.error('🌐 获取应用信息：');
+        console.error('  访问：https://open-dev.dingtalk.com/');
+        console.error('  创建企业内部应用或服务窗应用');
+        console.error('');
+        console.error('📝 示例配置文件（.env）：');
+        console.error('  DINGTALK_Client_ID=dingXXXXXXXX');
+        console.error('  DINGTALK_Client_Secret=XXXXXXXXXXXXX');
+        console.error('');
+        console.error('🚀 启动命令：');
+        console.error('  npx dingtalk-mcp');
+        console.error('');
+        process.exit(1);
+    }
     try {
-        // process.env.DEBUG = true;
-        // process.env.ACTIVE_PROFILES = "ALL";
-        // process.env.ROBOT_CODE = "234234"
         const server = new DingTalkMCPServer();
+        console.error('🎯 DingTalk MCP Server 启动中...');
+        console.error('🔗 连接方式：stdio transport');
         await server.run();
+        console.error('🎯 DingTalk MCP Server 启动成功.');
     }
     catch (error) {
-        console.error('Failed to start DingTalk MCP server:', error);
+        console.error('❌ 服务器启动失败:', error);
+        console.error('');
+        console.error('🔍 常见问题排查：');
+        console.error('  1. 检查网络连接');
+        console.error('  2. 验证AppKey/Secret是否正确');
+        console.error('  3. 确认应用权限是否充足');
+        console.error('  4. 查看详细错误信息');
+        console.error('');
         process.exit(1);
     }
 }
+// 处理未捕获的异常
+process.on('uncaughtException', (error) => {
+    console.error('❌ 未捕获的异常:', error);
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason, promise) => {
+    console.error('❌ 未处理的Promise拒绝:', reason);
+    process.exit(1);
+});
 main().catch(error => {
-    console.error('Unexpected error:', error);
+    console.error('❌ 启动过程中发生错误:', error);
     process.exit(1);
 });
 //# sourceMappingURL=cli.js.map

package/dist/utils/apiClient.d.ts

@@ -0,0 +1,49 @@
+/**
+ * API Client - 抽象DingTalk API调用
+ * 负责构建请求、发送API调用和处理响应
+ */
+import { type AxiosResponse } from 'axios';
+import type { DingTalkApiResponse } from '../types.js';
+import type { ProcessedMessage } from './messageProcessor.js';
+export interface ApiClientOptions {
+    baseURL?: string;
+    timeout?: number;
+    retries?: number;
+}
+export declare class ApiClient {
+    private readonly baseURL;
+    private readonly timeout;
+    private readonly retries;
+    constructor(options?: ApiClientOptions);
+    /**
+     * 发送单人消息
+     */
+    sendMessage(accessToken: string, message: ProcessedMessage, params: {
+        userId?: string;
+        unionId?: string;
+        bizId?: string;
+        accountId?: string;
+    }): Promise<AxiosResponse<DingTalkApiResponse>>;
+    /**
+     * 批量发送消息
+     */
+    batchSendMessage(accessToken: string, message: ProcessedMessage, params: {
+        userIdList?: string[];
+        sendToAll?: boolean;
+        bizRequestId?: string;
+        bizId?: string;
+        accountId?: string;
+    }): Promise<AxiosResponse<DingTalkApiResponse>>;
+    /**
+     * 通用请求方法
+     */
+    private makeRequest;
+    /**
+     * 获取access_token
+     */
+    getAccessToken(appId: string, appSecret: string): Promise<{
+        access_token: string;
+        expires_in: number;
+    }>;
+}
+//# sourceMappingURL=apiClient.d.ts.map