ework3-task-mcp 0.0.0-stage → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +169 -3
- package/dist/index.js +25344 -0
- package/package.json +41 -6
package/README.md
CHANGED
|
@@ -1,3 +1,169 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
# task-mcp
|
|
2
|
+
|
|
3
|
+
易工作「工作计划」任务的 MCP server(包名 `ework3-task-mcp`,命令 `task-mcp`)。让 Claude Desktop 等支持 stdio 的客户端通过自然语言查询和处理分配给你的任务。
|
|
4
|
+
|
|
5
|
+
## 能力
|
|
6
|
+
|
|
7
|
+
| 工具 | 作用 |
|
|
8
|
+
| --- | --- |
|
|
9
|
+
| `get_task` | 按任务链接或 taskId 查详情(正文、状态、成员、标签、附件、子任务、评论) |
|
|
10
|
+
| `list_my_tasks` | 查我负责的任务,支持状态名、状态类型、关键词、标签、计划、个人分组、分页 |
|
|
11
|
+
| `list_created_tasks` | 查我创建的任务(创建人角色 `R`),筛选参数与负责人列表一致 |
|
|
12
|
+
| `my_task_stats` | 按状态名与状态类型统计我负责的任务,支持标签与计划过滤 |
|
|
13
|
+
| `update_task` | 改标题/正文 |
|
|
14
|
+
| `change_task_owner` | 改负责人(只替换 `O`,参与人/抄送人按改后结果保留) |
|
|
15
|
+
| `change_task_status` | 改状态(按名称精确匹配,需备注时要求 `remark`) |
|
|
16
|
+
| `add_task_comment` | 加评论,图片支持本地路径、URL、data URI |
|
|
17
|
+
| `search_employee` | 按姓名搜员工,拿 empId |
|
|
18
|
+
| `create_task` | 在计划下创建任务(仅计划任务,可指定个人分组,预演 + confirm) |
|
|
19
|
+
| `list_task_groups` | 列出我的个人任务分组,可选返回每组任务数(不限角色) |
|
|
20
|
+
| `manage_task_group` | 创建/重命名/删除我的个人任务分组(预演 + confirm) |
|
|
21
|
+
| `assign_task_to_group` | 把任务移入我的个人任务分组,传「未分组」则移出(预演 + confirm) |
|
|
22
|
+
|
|
23
|
+
任务级工具都接受 `taskId` 或 `url` 二选一。链接的域名必须与 `EWORK_BASE_URL` 属于同一环境(例如 `eazytec.ygzuo.com` 与 `gateway.eazytec.ygzuo.com`),否则直接报错,避免测试链接打到正式库。
|
|
24
|
+
|
|
25
|
+
「我负责的任务」只算**负责人**(任务成员角色 `O`),不包含参与人和抄送人视角;「我创建的任务」只看创建人(角色 `R`),两者不要混用。
|
|
26
|
+
|
|
27
|
+
## 环境要求
|
|
28
|
+
|
|
29
|
+
- Node.js 18+
|
|
30
|
+
- 一把易工作 API Key(`ewk_` 开头),绑定到你本人;该员工至少登录过一次易工作
|
|
31
|
+
|
|
32
|
+
## 安装
|
|
33
|
+
|
|
34
|
+
发布到 npm 后(维护者见根 [README](../../README.md)「分发(npm)」):
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
npx -y -p ework3-task-mcp@0.3.0 task-mcp # 免安装试用
|
|
38
|
+
npm i -g ework3-task-mcp@0.3.0 && task-mcp # 全局安装
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
也可以直接安装维护者给的 tarball:`npm i -g ./ework3-task-mcp-0.3.0.tgz`。
|
|
42
|
+
|
|
43
|
+
## 构建(开发)
|
|
44
|
+
|
|
45
|
+
在仓库根目录执行:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
npm install
|
|
49
|
+
npm run build:task
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
产物是单文件 `apps/task-mcp/dist/index.js`,运行时不需要 `node_modules`。
|
|
53
|
+
|
|
54
|
+
## 客户端配置
|
|
55
|
+
|
|
56
|
+
Claude Desktop 的配置文件(Windows 通常在 `%APPDATA%\Claude\claude_desktop_config.json`),用 npx 拉起:
|
|
57
|
+
|
|
58
|
+
```json
|
|
59
|
+
{
|
|
60
|
+
"mcpServers": {
|
|
61
|
+
"ework-task": {
|
|
62
|
+
"command": "npx",
|
|
63
|
+
"args": ["-y", "-p", "ework3-task-mcp@0.3.0", "task-mcp"],
|
|
64
|
+
"env": {
|
|
65
|
+
"EWORK_API_KEY": "<你的Key>",
|
|
66
|
+
"EWORK_BASE_URL": "https://eazytec.ygzuo.com"
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
已经全局安装时把 `command` 改为 `task-mcp`、去掉 `args`。用仓库里的本地构建产物时改为:
|
|
74
|
+
|
|
75
|
+
```json
|
|
76
|
+
"command": "node",
|
|
77
|
+
"args": ["E:/Project/ework/ework-mcp/apps/task-mcp/dist/index.js"]
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
内网机器首次 `npx` 需要能访问 npm 源;可把 registry 指到 `https://registry.npmmirror.com`。建议在 `args` 里写死版本(如 `ework3-task-mcp@0.3.0`)避免自动升级。
|
|
81
|
+
|
|
82
|
+
| 环境变量 | 必填 | 默认 | 说明 |
|
|
83
|
+
| --- | --- | --- | --- |
|
|
84
|
+
| `EWORK_API_KEY` | 是 | — | API Key;只从环境变量读取 |
|
|
85
|
+
| `EWORK_BASE_URL` | 否 | `https://eazytec.ygzuo.com` | 测试环境可用 `http://gateway.yanshi.ygzuo.com` |
|
|
86
|
+
| `EWORK_TIMEOUT_MS` | 否 | 读 15000 / 写 20000 | 统一超时覆盖 |
|
|
87
|
+
| `EWORK_DEBUG` | 否 | — | 设为 `1` 时把请求结果码打到 stderr |
|
|
88
|
+
|
|
89
|
+
测试和正式各有一把 Key,互不通用。
|
|
90
|
+
|
|
91
|
+
## 写操作:必须先预演
|
|
92
|
+
|
|
93
|
+
所有写工具都分两步:
|
|
94
|
+
|
|
95
|
+
1. **预演**:不带 `confirm` 调用,返回改前/改后和一次性 `previewToken`,不写数据。
|
|
96
|
+
2. **执行**:把预演展示给用户,得到明确同意后,带 `previewToken` 和 `confirm=true` 再调一次。
|
|
97
|
+
|
|
98
|
+
`previewToken` 10 分钟有效、只能使用一次;内容与预演不一致或服务重启后需要重新预演。执行前会重新读取任务,写完后会回读确认。
|
|
99
|
+
|
|
100
|
+
### 创建任务
|
|
101
|
+
|
|
102
|
+
`create_task` 只支持计划任务,必填 `plan`(计划名或 32 位 id)、`taskType`(任务类型名或 id)、`title`、`dueDate`。默认负责人为当前员工、开始日期为今天、优先级普通、状态为工作流起始节点、全天任务。可选正文、参与人、抄送人、优先级、计划内标签、父任务、`template` 和个人分组 `group`。
|
|
103
|
+
|
|
104
|
+
计划/任务类型/标签/模板/成员解析不到或重名时返回候选,不写入;计划已归档、当前员工不是计划成员、任务类型存在必填自定义字段、日期非法、父任务跨计划或为周期任务时拒绝。
|
|
105
|
+
|
|
106
|
+
## 行为约定
|
|
107
|
+
|
|
108
|
+
- **计划解析**:计划名或 32 位 id;完全相等的计划优先,没有完全相等时唯一模糊命中可用;重名返回候选,未命中返回可用计划清单,不返回任务。
|
|
109
|
+
- **个人分组只属于当前员工**:`list_task_groups` / `manage_task_group` / `assign_task_to_group` 管理的是「我的任务」看板的个人分组(`type=T`),不是计划共享分组(`type=P`),也不影响他人。
|
|
110
|
+
- **分组解析**:分组名或分组 id;重名返回候选。任务只能属于当前员工自己的个人分组;`assign_task_to_group` 传「未分组」表示移出所有个人分组。
|
|
111
|
+
- **分组删除要求为空**:分组下仍有任务时拒绝删除,需先把任务移出。
|
|
112
|
+
- **我创建的 ≠ 我负责的**:`list_created_tasks` 看创建人角色 `R`;`list_my_tasks` 看负责人角色 `O`。
|
|
113
|
+
- **创建任务用平台默认模板**:按计划业务自动选「业务类任务」/「管理类任务」,兼容「标准行动计划-业务-任务」/「标准行动计划-管理-任务」命名;失败时用返回的模板清单指定 `template`。
|
|
114
|
+
- **状态名精确匹配**:系统里没有「未处理」「处理中」;常见状态是未开始/进行中/已完成/已取消(默认流程)或待处理/修复中/待发布/已解决/已关闭(需求/缺陷流程)。
|
|
115
|
+
- **S/P/F/E 是状态类型,不是状态名**:写状态时只接受中文状态名或完整节点 id;裸 `S/P/F/E` 会被拒绝,防止把类型误当节点 id。
|
|
116
|
+
- **状态不存在时给清单**:目标不在任务所属工作流时,返回可用状态名,不写入;列表按不存在的状态名过滤时,也会返回实际状态名。
|
|
117
|
+
- **不跨级猜测**:平台允许同一工作流内任意跳转,MCP 不发明流转规则,只限制目标必须在该任务的工作流内。
|
|
118
|
+
- **标签按名称或 id 匹配**:数组表示同时具备。
|
|
119
|
+
- **输出有预算**:`get_task` 默认只返回正文纯文本预览和最近 20 条评论;需要完整正文 HTML 时用 `include=fullContent`;评论和附件有上限并标注截断。
|
|
120
|
+
- **图片**:支持本地绝对路径、`http(s)` URL、`data:image/...;base64`;最多 10 张、单张 10 MB;预览阶段先做存在性/可访问性校验。
|
|
121
|
+
- **私有地址拦截**:图片 URL 会校验域名解析结果,拒绝本机、内网 IPv4/IPv6 地址。
|
|
122
|
+
- **写后回读**:改标题/正文、改负责人、改状态、加评论、创建任务后都会重新读取任务确认,回读失败会提示手动检查。
|
|
123
|
+
|
|
124
|
+
## 常见错误
|
|
125
|
+
|
|
126
|
+
| 错误 | 处理 |
|
|
127
|
+
| --- | --- |
|
|
128
|
+
| 401 `NOT_FOUND` / `REVOKED` / `EXPIRED` | 检查 `EWORK_API_KEY`,或重新签发 |
|
|
129
|
+
| 401 `AUTH_UNAVAILABLE` | 网关或 appcore 不可用 |
|
|
130
|
+
| 403 | 当前员工无权访问该任务/接口;确认任务编号或换有权限的 Key |
|
|
131
|
+
| 缺少 previewToken | 先不带 `confirm` 调一次预演,用户同意后再带令牌执行 |
|
|
132
|
+
| 任务链接属于其他环境 | 切换 `EWORK_BASE_URL`,或只提供 taskId |
|
|
133
|
+
| 状态名不在工作流 | 用返回的可用状态清单;粗粒度筛选用 `statusType` |
|
|
134
|
+
| 任务编号格式不正确 | taskId 应为 16–20 位数字,周期任务可带 `-yyyyMMdd` 后缀 |
|
|
135
|
+
|
|
136
|
+
## 开发
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
npm run dev:task # tsx 直接运行(仓库根)
|
|
140
|
+
npm test # node:test 单测(所有模块)
|
|
141
|
+
npm run build:task # 只构建 task-mcp;类型检查用根目录 npm run typecheck
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
本地联调可以调单个工具(注意预演和执行必须在同一个 MCP 进程里,`call.mjs` 每次都会新起进程,只适合只读工具):
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
EWORK_API_KEY=ewk_xxx node scripts/call.mjs get_task '{"taskId":"2026110601020028957"}'
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
`--module` 默认 `task`;显式写成 `node scripts/call.mjs --module task ...` 效果相同。
|
|
151
|
+
|
|
152
|
+
预演+执行需要保持同一个 MCP 进程,可以用 `flow.mjs` 顺序调用;`$PREVIEW_TOKEN` 会自动替换上一调用的令牌:
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
EWORK_API_KEY=ewk_xxx node scripts/flow.mjs '[
|
|
156
|
+
{"tool":"update_task","args":{"taskId":"2026110601020028957","title":"新标题"}},
|
|
157
|
+
{"tool":"update_task","args":{"taskId":"2026110601020028957","title":"新标题","previewToken":"$PREVIEW_TOKEN","confirm":true}}
|
|
158
|
+
]'
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
## 安全
|
|
162
|
+
|
|
163
|
+
- Key 只从环境变量读取,不写日志、不进仓库。
|
|
164
|
+
- 只调用任务与员工搜索相关接口,不调用 `/external/admin/**`。
|
|
165
|
+
- 只把 `X-Api-Key` 发给网关;不自带 `currentEmpId` / `appToken`。
|
|
166
|
+
- 写工具必须经过预演令牌:改任务要求 `authority.canEdit`,评论要求 `canComment`;个人分组只要求任务可见(分组不改任务本身)。
|
|
167
|
+
- 图片 URL 做协议、域名解析、IPv4/IPv6 私网校验;不跟随到内网地址的重定向。
|
|
168
|
+
|
|
169
|
+
仓库结构见 [根 README](../../README.md),术语见 [GLOSSARY.md](../../GLOSSARY.md)。
|