@llodev/pm-tasks-clickup 0.0.0-stage → 1.0.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/LICENSE +21 -0
- package/README.md +195 -2
- package/SKILL.md +258 -0
- package/anti-patterns/clickup.md +73 -0
- package/dist/adapter.d.ts +39 -0
- package/dist/adapter.d.ts.map +1 -0
- package/dist/adapter.js +83 -0
- package/dist/adapter.js.map +1 -0
- package/dist/bin/init.d.ts +3 -0
- package/dist/bin/init.d.ts.map +1 -0
- package/dist/bin/init.js +20 -0
- package/dist/bin/init.js.map +1 -0
- package/dist/doctor-cli.d.ts +27 -0
- package/dist/doctor-cli.d.ts.map +1 -0
- package/dist/doctor-cli.js +315 -0
- package/dist/doctor-cli.js.map +1 -0
- package/dist/env.d.ts +6 -0
- package/dist/env.d.ts.map +1 -0
- package/dist/env.js +11 -0
- package/dist/env.js.map +1 -0
- package/dist/envelope.d.ts +44 -0
- package/dist/envelope.d.ts.map +1 -0
- package/dist/envelope.js +95 -0
- package/dist/envelope.js.map +1 -0
- package/dist/errors.d.ts +30 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +60 -0
- package/dist/errors.js.map +1 -0
- package/dist/estimation.d.ts +20 -0
- package/dist/estimation.d.ts.map +1 -0
- package/dist/estimation.js +40 -0
- package/dist/estimation.js.map +1 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +3 -0
- package/dist/index.js.map +1 -0
- package/dist/init-api.d.ts +67 -0
- package/dist/init-api.d.ts.map +1 -0
- package/dist/init-api.js +271 -0
- package/dist/init-api.js.map +1 -0
- package/dist/init-flow.d.ts +27 -0
- package/dist/init-flow.d.ts.map +1 -0
- package/dist/init-flow.js +206 -0
- package/dist/init-flow.js.map +1 -0
- package/dist/status-map.d.ts +31 -0
- package/dist/status-map.d.ts.map +1 -0
- package/dist/status-map.js +38 -0
- package/dist/status-map.js.map +1 -0
- package/dist/status.d.ts +17 -0
- package/dist/status.d.ts.map +1 -0
- package/dist/status.js +21 -0
- package/dist/status.js.map +1 -0
- package/dist/transport-clickup.d.ts +99 -0
- package/dist/transport-clickup.d.ts.map +1 -0
- package/dist/transport-clickup.js +676 -0
- package/dist/transport-clickup.js.map +1 -0
- package/docs/i18n/README.es-ES.md +196 -0
- package/docs/i18n/README.pt-BR.md +196 -0
- package/i18n/en-US.json +62 -0
- package/i18n/es-ES.json +62 -0
- package/i18n/pt-BR.json +62 -0
- package/manifest.json +14 -0
- package/package.json +63 -4
- package/references/autonomous.md +85 -0
- package/references/estimation.md +115 -0
- package/references/operations.md +128 -0
- package/schemas/config.json +140 -0
|
@@ -0,0 +1,676 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ClickUp MCP transport: implements the @llodev/pm-tasks-core Transport by
|
|
3
|
+
* dispatching each canonical verb to `clickup_*` tools. The MCP dispatcher is
|
|
4
|
+
* injected, so this module is testable with a recording stub, has no side
|
|
5
|
+
* effects on import, and references no `mcp__*` symbol at build time.
|
|
6
|
+
*
|
|
7
|
+
* ClickUp specifics:
|
|
8
|
+
* - Tool names are passed without the server prefix (`clickup_create_task`).
|
|
9
|
+
* - Every call carries `workspace_id: config.workspace.id`.
|
|
10
|
+
* - Writes return an envelope, reads a bare task (see envelope.ts); a resolved
|
|
11
|
+
* `{error}` is handled like a thrown error.
|
|
12
|
+
* - Status names are pinned per list in config and resolved by role (status.ts).
|
|
13
|
+
*/
|
|
14
|
+
import { normalizeEstimate } from "@llodev/pm-tasks-core/estimation";
|
|
15
|
+
import { callTool, epochToIso, idString, isObj, taskUrl, unwrapTask, } from "./envelope.js";
|
|
16
|
+
import { classifyError, invalidRequest, shapeError } from "./errors.js";
|
|
17
|
+
import { DEFAULT_HOURS_PER_DAY, slugify, toMinutes } from "./estimation.js";
|
|
18
|
+
import { resolveStatus, statusKey } from "./status.js";
|
|
19
|
+
// ---------------------------------------------------------------------------
|
|
20
|
+
// Internal helpers
|
|
21
|
+
// ---------------------------------------------------------------------------
|
|
22
|
+
const PRIORITIES = new Map([
|
|
23
|
+
["urgent", "urgent"],
|
|
24
|
+
["high", "high"],
|
|
25
|
+
["normal", "normal"],
|
|
26
|
+
["medium", "normal"],
|
|
27
|
+
["low", "low"],
|
|
28
|
+
]);
|
|
29
|
+
/** Native priority name; undefined (omitted from the call) when unknown. */
|
|
30
|
+
function mapPriority(priority) {
|
|
31
|
+
return typeof priority === "string" ? PRIORITIES.get(priority.trim().toLowerCase()) : undefined;
|
|
32
|
+
}
|
|
33
|
+
const DATE_PREFIX = /^\d{4}-\d{2}-\d{2}/;
|
|
34
|
+
/**
|
|
35
|
+
* A string that starts with a real calendar date (`YYYY-MM-DD`). Date rolls
|
|
36
|
+
* `2026-02-30` over to March, so the prefix must survive a round trip.
|
|
37
|
+
*/
|
|
38
|
+
function isCalendarDate(value) {
|
|
39
|
+
if (typeof value !== "string" || !DATE_PREFIX.test(value))
|
|
40
|
+
return false;
|
|
41
|
+
const date = value.slice(0, 10);
|
|
42
|
+
const parsed = new Date(`${date}T00:00:00Z`);
|
|
43
|
+
return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === date;
|
|
44
|
+
}
|
|
45
|
+
/** Description with the `[ct:<token>]` footer, appended once. */
|
|
46
|
+
function withClientToken(description, clientToken) {
|
|
47
|
+
const body = description ?? "";
|
|
48
|
+
if (!clientToken)
|
|
49
|
+
return body;
|
|
50
|
+
const marker = `[ct:${clientToken}]`;
|
|
51
|
+
if (body.includes(marker))
|
|
52
|
+
return body;
|
|
53
|
+
return body.trim() === "" ? marker : `${body.trimEnd()}\n\n${marker}`;
|
|
54
|
+
}
|
|
55
|
+
/** `task.move` role words; a Map so prototype keys such as "constructor" never match. */
|
|
56
|
+
const ROLES = new Map([
|
|
57
|
+
["open", "open"],
|
|
58
|
+
["wip", "wip"],
|
|
59
|
+
["done", "done"],
|
|
60
|
+
]);
|
|
61
|
+
/** A `task.move` target of six or more digits is a destination list id. */
|
|
62
|
+
const LIST_ID = /^\d{6,}$/;
|
|
63
|
+
/** `update_task` answer when the status is not in the task's list (renamed or removed). */
|
|
64
|
+
const STATUS_REJECTED = /status does not exist/i;
|
|
65
|
+
/** Status names compare case-insensitively and trimmed; the pinned name is sent verbatim. */
|
|
66
|
+
function sameStatus(current, pinned) {
|
|
67
|
+
return statusKey(current) === statusKey(pinned);
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* INVALID_REQUEST (`id_required`, naming the field) for the first id that is not a
|
|
71
|
+
* non-blank string; null when every id is usable. Runs before any MCP call.
|
|
72
|
+
*/
|
|
73
|
+
function missingId(verb, ids) {
|
|
74
|
+
for (const [field, value] of Object.entries(ids)) {
|
|
75
|
+
if (typeof value !== "string" || value.trim() === "") {
|
|
76
|
+
return invalidRequest(verb, "id_required", `${field} must be a non-empty id`, { field });
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
return null;
|
|
80
|
+
}
|
|
81
|
+
/** A thrown or resolved MCP failure, classified. */
|
|
82
|
+
function failure(e) {
|
|
83
|
+
const { code, details } = classifyError(e);
|
|
84
|
+
return { ok: false, code, details };
|
|
85
|
+
}
|
|
86
|
+
/** The idempotency short-circuit: the requested state already holds, nothing was written. */
|
|
87
|
+
function alreadyInState(verb, details) {
|
|
88
|
+
return { ok: false, code: "ALREADY_IN_STATE", details: { ...details, verb } };
|
|
89
|
+
}
|
|
90
|
+
/** A verb ClickUp, or this config, cannot carry out; `reason` is a stable token. */
|
|
91
|
+
function notApplicable(verb, reason, message) {
|
|
92
|
+
return { ok: false, code: "NOT_APPLICABLE", details: { verb, reason, message } };
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* A failed `task.estimate.set` write. Before anything was written it is the plain
|
|
96
|
+
* classified failure. After a write it is partial: MCP_ERROR with
|
|
97
|
+
* `partial`, the steps already applied and the failed one. An auth or rate-limit
|
|
98
|
+
* failure keeps its code, so the caller still knows to sign in again or wait.
|
|
99
|
+
*/
|
|
100
|
+
function stepFailure(failed, applied, failedStep) {
|
|
101
|
+
if (applied.length === 0)
|
|
102
|
+
return failed;
|
|
103
|
+
const code = failed.code === "AUTH_ERROR" || failed.code === "RATE_LIMITED" ? failed.code : "MCP_ERROR";
|
|
104
|
+
return {
|
|
105
|
+
ok: false,
|
|
106
|
+
code,
|
|
107
|
+
details: {
|
|
108
|
+
...failed.details,
|
|
109
|
+
verb: "task.estimate.set",
|
|
110
|
+
partial: true,
|
|
111
|
+
applied: [...applied],
|
|
112
|
+
failedStep,
|
|
113
|
+
},
|
|
114
|
+
};
|
|
115
|
+
}
|
|
116
|
+
/**
|
|
117
|
+
* Raw `get_task` fields a verb relies on beyond list, status and parent, checked so
|
|
118
|
+
* a partial read never passes for a real value. `unwrapTask` reads a missing
|
|
119
|
+
* `assignees` array as "nobody" and drops an entry without an id, so the union
|
|
120
|
+
* write would unassign people; a missing `due_date` would read as "no due date";
|
|
121
|
+
* missing `tags` as "no est: tag" (a second one would be added); a missing
|
|
122
|
+
* `subtasks_count` as a leaf (the native estimate would land on a parent); and
|
|
123
|
+
* without `space.id` the est: tag cannot be created after the estimate write.
|
|
124
|
+
*/
|
|
125
|
+
const READ_CHECKS = {
|
|
126
|
+
assignees: (raw, task) => Array.isArray(raw.assignees) && raw.assignees.length === task.assigneeIds.length,
|
|
127
|
+
due_date: (raw, task) => raw.due_date === null || task.dueDate !== null,
|
|
128
|
+
tags: (raw, task) => Array.isArray(raw.tags) && raw.tags.length === task.tagNames.length,
|
|
129
|
+
subtasks_count: (raw) => typeof raw.subtasks_count === "number",
|
|
130
|
+
space: (_raw, task) => task.spaceId !== undefined,
|
|
131
|
+
};
|
|
132
|
+
/** A ClickUp user id: digits only. Anything else ("me", an email, a name) is resolved. */
|
|
133
|
+
const USER_ID = /^\d+$/;
|
|
134
|
+
/** `clickup_create_comment.comment_text` maxLength (live schema). */
|
|
135
|
+
const COMMENT_MAX_LENGTH = 40000;
|
|
136
|
+
/** `utc_offset` of `clickup_get_user` ("-03:00", "+05:30") in minutes; null when unreadable. */
|
|
137
|
+
function offsetMinutes(value) {
|
|
138
|
+
const m = typeof value === "string" ? /^([+-])(\d{2}):?(\d{2})$/.exec(value) : null;
|
|
139
|
+
if (!m)
|
|
140
|
+
return null;
|
|
141
|
+
const hours = Number(m[2]);
|
|
142
|
+
const minutes = Number(m[3]);
|
|
143
|
+
if (hours > 14 || minutes > 59)
|
|
144
|
+
return null;
|
|
145
|
+
return (m[1] === "-" ? -1 : 1) * (hours * 60 + minutes);
|
|
146
|
+
}
|
|
147
|
+
/** The calendar date (YYYY-MM-DD) of an ISO instant at a fixed UTC offset in minutes. */
|
|
148
|
+
function localDate(iso, offset) {
|
|
149
|
+
return new Date(Date.parse(iso) + offset * 60_000).toISOString().slice(0, 10);
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* The comment carrying `marker` on a `clickup_get_task_comments` page, or null.
|
|
153
|
+
* ClickUp keeps the marker verbatim and appends a newline to `comment_text`, so
|
|
154
|
+
* this is a substring match. An unreadable page, or a match without an id or a
|
|
155
|
+
* date, is a shape error: posting anyway could duplicate the comment.
|
|
156
|
+
*/
|
|
157
|
+
function markedComment(resp, marker, verb) {
|
|
158
|
+
if (!isObj(resp) || !Array.isArray(resp.comments))
|
|
159
|
+
return shapeError(verb);
|
|
160
|
+
for (const comment of resp.comments) {
|
|
161
|
+
if (!isObj(comment) || typeof comment.comment_text !== "string")
|
|
162
|
+
continue;
|
|
163
|
+
if (!comment.comment_text.includes(marker))
|
|
164
|
+
continue;
|
|
165
|
+
const commentId = idString(comment.id);
|
|
166
|
+
const postedAt = epochToIso(comment.date);
|
|
167
|
+
if (commentId === undefined || postedAt === null)
|
|
168
|
+
return shapeError(verb);
|
|
169
|
+
return { ok: true, data: { commentId, postedAt } };
|
|
170
|
+
}
|
|
171
|
+
return { ok: true, data: null };
|
|
172
|
+
}
|
|
173
|
+
// ---------------------------------------------------------------------------
|
|
174
|
+
// Factory
|
|
175
|
+
// ---------------------------------------------------------------------------
|
|
176
|
+
export function createClickUpTransport(opts) {
|
|
177
|
+
const { mcp, config } = opts;
|
|
178
|
+
const workspaceId = config.workspace.id;
|
|
179
|
+
/** Every ClickUp call carries the configured workspace. */
|
|
180
|
+
const call = (tool, args) => callTool(mcp, tool, { ...args, workspace_id: workspaceId });
|
|
181
|
+
/**
|
|
182
|
+
* One compact `clickup_get_task`: the only trusted source of a task's status,
|
|
183
|
+
* home list and parent. A bare task always carries `list.id`, a status name and
|
|
184
|
+
* a `parent` key (null for a root task). A write envelope or a partial read
|
|
185
|
+
* lacks one of them, and `unwrapTask` would default it (no status, parentId
|
|
186
|
+
* null): trusting that skips a write or lets a subtask pass as a root task, so
|
|
187
|
+
* it is a shape error instead. `checks` names the further fields the verb
|
|
188
|
+
* relies on (READ_CHECKS).
|
|
189
|
+
*/
|
|
190
|
+
async function readTask(taskId, verb, checks = []) {
|
|
191
|
+
try {
|
|
192
|
+
const raw = await call("clickup_get_task", { task_id: taskId });
|
|
193
|
+
const task = unwrapTask(raw);
|
|
194
|
+
if (!task || task.listId === undefined || task.status === undefined) {
|
|
195
|
+
return shapeError(verb);
|
|
196
|
+
}
|
|
197
|
+
const fields = raw;
|
|
198
|
+
const parent = fields.parent;
|
|
199
|
+
if (parent !== null && (typeof parent !== "string" || parent === "")) {
|
|
200
|
+
return shapeError(verb);
|
|
201
|
+
}
|
|
202
|
+
if (!checks.every((field) => READ_CHECKS[field](fields, task)))
|
|
203
|
+
return shapeError(verb);
|
|
204
|
+
return { ok: true, data: { ...task, listId: task.listId, status: task.status } };
|
|
205
|
+
}
|
|
206
|
+
catch (e) {
|
|
207
|
+
return failure(e);
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
/** `clickup_update_task` on one task: null on success, the classified failure otherwise. */
|
|
211
|
+
async function updateTask(taskId, fields) {
|
|
212
|
+
try {
|
|
213
|
+
await call("clickup_update_task", { task_id: taskId, ...fields });
|
|
214
|
+
return null;
|
|
215
|
+
}
|
|
216
|
+
catch (e) {
|
|
217
|
+
return failure(e);
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
/**
|
|
221
|
+
* The account's UTC offset in minutes, from `clickup_get_user`, read once
|
|
222
|
+
* per transport; parallel callers share the read in flight. A failure or an
|
|
223
|
+
* unreadable offset resolves null and is dropped, so the next call reads again.
|
|
224
|
+
*/
|
|
225
|
+
let offsetRead;
|
|
226
|
+
function accountOffset() {
|
|
227
|
+
offsetRead ??= call("clickup_get_user", {})
|
|
228
|
+
.then((user) => offsetMinutes(isObj(user) ? user.utc_offset : undefined), () => null)
|
|
229
|
+
.then((offset) => {
|
|
230
|
+
if (offset === null)
|
|
231
|
+
offsetRead = undefined;
|
|
232
|
+
return offset;
|
|
233
|
+
});
|
|
234
|
+
return offsetRead;
|
|
235
|
+
}
|
|
236
|
+
/**
|
|
237
|
+
* The numeric user id for `userId`. Digits are used as given; "me", an email or
|
|
238
|
+
* a username goes through `clickup_resolve_assignees`, which answers null for a
|
|
239
|
+
* name shared by several users. Anything but exactly one numeric id fails closed
|
|
240
|
+
* as `assignee_unresolved`, without echoing the input; an auth or rate-limit
|
|
241
|
+
* failure keeps its code, since it is not about the user.
|
|
242
|
+
*/
|
|
243
|
+
async function resolveAssignee(userId) {
|
|
244
|
+
if (USER_ID.test(userId))
|
|
245
|
+
return { ok: true, data: userId };
|
|
246
|
+
const unresolved = invalidRequest("task.assignee.add", "assignee_unresolved", "userId did not resolve to exactly one ClickUp user; pass a user id or a unique email");
|
|
247
|
+
try {
|
|
248
|
+
const resp = await call("clickup_resolve_assignees", { assignees: [userId] });
|
|
249
|
+
const ids = isObj(resp) && Array.isArray(resp.userIds) ? resp.userIds : [];
|
|
250
|
+
const id = ids.length === 1 ? idString(ids[0]) : undefined;
|
|
251
|
+
return id !== undefined && USER_ID.test(id) ? { ok: true, data: id } : unresolved;
|
|
252
|
+
}
|
|
253
|
+
catch (e) {
|
|
254
|
+
const failed = failure(e);
|
|
255
|
+
return failed.code === "AUTH_ERROR" || failed.code === "RATE_LIMITED" ? failed : unresolved;
|
|
256
|
+
}
|
|
257
|
+
}
|
|
258
|
+
/** The status pinned for `role` in the task's home list; fails closed when unpinned. */
|
|
259
|
+
function pinnedStatus(verb, task, role) {
|
|
260
|
+
const resolved = resolveStatus(config, task.listId, role);
|
|
261
|
+
if (resolved.ok)
|
|
262
|
+
return resolved;
|
|
263
|
+
if (resolved.reason === "list_not_configured") {
|
|
264
|
+
return invalidRequest(verb, resolved.reason, "The task's list is not in config.lists; register it with init", { listId: task.listId });
|
|
265
|
+
}
|
|
266
|
+
return invalidRequest(verb, resolved.reason, `No status is pinned for role "${role}" in the task's list; pin it with init`, { listId: task.listId, role });
|
|
267
|
+
}
|
|
268
|
+
/**
|
|
269
|
+
* `clickup_update_task {status}`. A status ClickUp rejects (renamed or removed
|
|
270
|
+
* after init) fails closed as `status_rejected`; any other error is classified.
|
|
271
|
+
* Returns null on success.
|
|
272
|
+
*/
|
|
273
|
+
async function writeStatus(verb, task, status) {
|
|
274
|
+
const failed = await updateTask(task.id, { status });
|
|
275
|
+
if (failed === null || !STATUS_REJECTED.test(String(failed.details.message)))
|
|
276
|
+
return failed;
|
|
277
|
+
return invalidRequest(verb, "status_rejected", "ClickUp rejected the pinned status (renamed or removed after init); run init again", { status, listId: task.listId });
|
|
278
|
+
}
|
|
279
|
+
/** `task.move` to a list id: `clickup_move_task`, root tasks only. */
|
|
280
|
+
async function moveToList(task, listId) {
|
|
281
|
+
const verb = "task.move";
|
|
282
|
+
if (task.listId === listId)
|
|
283
|
+
return alreadyInState(verb, { listId: task.listId });
|
|
284
|
+
if (task.parentId !== null) {
|
|
285
|
+
return invalidRequest(verb, "subtask_cannot_move", "ClickUp moves root tasks only; move the parent task instead");
|
|
286
|
+
}
|
|
287
|
+
try {
|
|
288
|
+
const resp = await call("clickup_move_task", { task_id: task.id, list_id: listId });
|
|
289
|
+
// `{success, task_id, custom_id, new_list_id}`; fall back to the requested id.
|
|
290
|
+
const reported = typeof resp === "object" && resp !== null
|
|
291
|
+
? resp.new_list_id
|
|
292
|
+
: undefined;
|
|
293
|
+
const newListId = typeof reported === "string" && reported !== "" ? reported : listId;
|
|
294
|
+
return {
|
|
295
|
+
ok: true,
|
|
296
|
+
data: { previousListOrSectionId: task.listId, newListOrSectionId: newListId },
|
|
297
|
+
};
|
|
298
|
+
}
|
|
299
|
+
catch (e) {
|
|
300
|
+
return failure(e);
|
|
301
|
+
}
|
|
302
|
+
}
|
|
303
|
+
return {
|
|
304
|
+
// -------------------------------------------------------------------
|
|
305
|
+
// task.create → clickup_create_task
|
|
306
|
+
//
|
|
307
|
+
// boardOrProjectId = list id; listOrSectionId = initial status name
|
|
308
|
+
// (empty → the list's default). `estimate` is not written here: the
|
|
309
|
+
// estimate goes through task.estimate.set.
|
|
310
|
+
// -------------------------------------------------------------------
|
|
311
|
+
async taskCreate(req) {
|
|
312
|
+
const verb = "task.create";
|
|
313
|
+
if (typeof req.boardOrProjectId !== "string" || req.boardOrProjectId.trim() === "") {
|
|
314
|
+
return invalidRequest(verb, "list_required", "boardOrProjectId (the list id) is required");
|
|
315
|
+
}
|
|
316
|
+
// null is treated like an absent dueDate; "" is still invalid.
|
|
317
|
+
if (req.dueDate != null && !isCalendarDate(req.dueDate)) {
|
|
318
|
+
return invalidRequest(verb, "invalid_due_date", "dueDate must start with a calendar date (YYYY-MM-DD)");
|
|
319
|
+
}
|
|
320
|
+
const args = { list_id: req.boardOrProjectId, name: req.name };
|
|
321
|
+
const status = typeof req.listOrSectionId === "string" ? req.listOrSectionId.trim() : "";
|
|
322
|
+
if (status !== "")
|
|
323
|
+
args.status = status;
|
|
324
|
+
const description = withClientToken(req.description, req.clientToken);
|
|
325
|
+
if (description.trim() !== "")
|
|
326
|
+
args.markdown_description = description;
|
|
327
|
+
if (req.labels && req.labels.length > 0)
|
|
328
|
+
args.tags = req.labels;
|
|
329
|
+
const priority = mapPriority(req.priority);
|
|
330
|
+
if (priority !== undefined)
|
|
331
|
+
args.priority = priority;
|
|
332
|
+
if (req.dueDate != null)
|
|
333
|
+
args.due_date = req.dueDate.slice(0, 10);
|
|
334
|
+
try {
|
|
335
|
+
const task = unwrapTask(await call("clickup_create_task", args));
|
|
336
|
+
if (!task)
|
|
337
|
+
return shapeError(verb);
|
|
338
|
+
return { ok: true, data: { id: task.id, url: task.url ?? taskUrl(task.id) } };
|
|
339
|
+
}
|
|
340
|
+
catch (e) {
|
|
341
|
+
return failure(e);
|
|
342
|
+
}
|
|
343
|
+
},
|
|
344
|
+
// -------------------------------------------------------------------
|
|
345
|
+
// task.move → clickup_update_task {status} or clickup_move_task
|
|
346
|
+
//
|
|
347
|
+
// open | wip | done (any case) → the status pinned for that role in the
|
|
348
|
+
// task's home list. A digit string of six or more is a destination list
|
|
349
|
+
// id → clickup_move_task (root tasks only). The task is read first; no
|
|
350
|
+
// write when the requested status or list already holds.
|
|
351
|
+
// -------------------------------------------------------------------
|
|
352
|
+
async taskMove(req) {
|
|
353
|
+
const verb = "task.move";
|
|
354
|
+
const noId = missingId(verb, { taskId: req.taskId });
|
|
355
|
+
if (noId)
|
|
356
|
+
return noId;
|
|
357
|
+
const target = typeof req.targetListOrSectionId === "string" ? req.targetListOrSectionId.trim() : "";
|
|
358
|
+
const role = ROLES.get(target.toLowerCase());
|
|
359
|
+
if (role === undefined && !LIST_ID.test(target)) {
|
|
360
|
+
return invalidRequest(verb, "invalid_target", "targetListOrSectionId must be open, wip, done or a numeric list id");
|
|
361
|
+
}
|
|
362
|
+
const read = await readTask(req.taskId, verb);
|
|
363
|
+
if (!read.ok)
|
|
364
|
+
return read;
|
|
365
|
+
const task = read.data;
|
|
366
|
+
if (role === undefined)
|
|
367
|
+
return moveToList(task, target);
|
|
368
|
+
const pinned = pinnedStatus(verb, task, role);
|
|
369
|
+
if (!pinned.ok)
|
|
370
|
+
return pinned;
|
|
371
|
+
if (sameStatus(task.status, pinned.status)) {
|
|
372
|
+
return alreadyInState(verb, { status: pinned.status });
|
|
373
|
+
}
|
|
374
|
+
const failed = await writeStatus(verb, task, pinned.status);
|
|
375
|
+
if (failed)
|
|
376
|
+
return failed;
|
|
377
|
+
return {
|
|
378
|
+
ok: true,
|
|
379
|
+
data: { previousListOrSectionId: task.status, newListOrSectionId: pinned.status },
|
|
380
|
+
};
|
|
381
|
+
},
|
|
382
|
+
// -------------------------------------------------------------------
|
|
383
|
+
// checklist.check → clickup_update_task {status} on a subtask
|
|
384
|
+
//
|
|
385
|
+
// Checklist items are subtasks: itemId = the subtask, checklistId = its
|
|
386
|
+
// parent. complete → the pinned `done` status, incomplete → `open`. The
|
|
387
|
+
// item is complete when its status is the pinned `done` status.
|
|
388
|
+
// -------------------------------------------------------------------
|
|
389
|
+
async checklistCheck(req) {
|
|
390
|
+
const verb = "checklist.check";
|
|
391
|
+
const noId = missingId(verb, { itemId: req.itemId, checklistId: req.checklistId });
|
|
392
|
+
if (noId)
|
|
393
|
+
return noId;
|
|
394
|
+
if (req.targetState !== "complete" && req.targetState !== "incomplete") {
|
|
395
|
+
return invalidRequest(verb, "invalid_target_state", "targetState must be complete or incomplete");
|
|
396
|
+
}
|
|
397
|
+
const read = await readTask(req.itemId, verb);
|
|
398
|
+
if (!read.ok)
|
|
399
|
+
return read;
|
|
400
|
+
const item = read.data;
|
|
401
|
+
if (item.parentId !== req.checklistId) {
|
|
402
|
+
return invalidRequest(verb, "not_a_checklist_item", "itemId must be a subtask whose parent is checklistId");
|
|
403
|
+
}
|
|
404
|
+
const done = pinnedStatus(verb, item, "done");
|
|
405
|
+
if (!done.ok)
|
|
406
|
+
return done;
|
|
407
|
+
const previousState = sameStatus(item.status, done.status) ? "complete" : "incomplete";
|
|
408
|
+
if (previousState === req.targetState) {
|
|
409
|
+
return alreadyInState(verb, { state: previousState });
|
|
410
|
+
}
|
|
411
|
+
const target = req.targetState === "complete" ? done : pinnedStatus(verb, item, "open");
|
|
412
|
+
if (!target.ok)
|
|
413
|
+
return target;
|
|
414
|
+
const failed = await writeStatus(verb, item, target.status);
|
|
415
|
+
if (failed)
|
|
416
|
+
return failed;
|
|
417
|
+
return { ok: true, data: { previousState, newState: req.targetState } };
|
|
418
|
+
},
|
|
419
|
+
// -------------------------------------------------------------------
|
|
420
|
+
// task.close → clickup_update_task {status: pinned done}
|
|
421
|
+
//
|
|
422
|
+
// Already at the pinned done status, or at the pinned closed status (a
|
|
423
|
+
// cancelled task is not turned into done) → {closed: true} with no write.
|
|
424
|
+
// closeListOrSectionId is ignored: closing never changes the list.
|
|
425
|
+
// -------------------------------------------------------------------
|
|
426
|
+
async taskClose(req) {
|
|
427
|
+
const verb = "task.close";
|
|
428
|
+
const noId = missingId(verb, { taskId: req.taskId });
|
|
429
|
+
if (noId)
|
|
430
|
+
return noId;
|
|
431
|
+
const read = await readTask(req.taskId, verb);
|
|
432
|
+
if (!read.ok)
|
|
433
|
+
return read;
|
|
434
|
+
const task = read.data;
|
|
435
|
+
const done = pinnedStatus(verb, task, "done");
|
|
436
|
+
if (!done.ok)
|
|
437
|
+
return done;
|
|
438
|
+
const closed = resolveStatus(config, task.listId, "closed");
|
|
439
|
+
const alreadyClosed = sameStatus(task.status, done.status) ||
|
|
440
|
+
(closed.ok && sameStatus(task.status, closed.status));
|
|
441
|
+
if (!alreadyClosed) {
|
|
442
|
+
const failed = await writeStatus(verb, task, done.status);
|
|
443
|
+
if (failed)
|
|
444
|
+
return failed;
|
|
445
|
+
}
|
|
446
|
+
return { ok: true, data: { closed: true } };
|
|
447
|
+
},
|
|
448
|
+
// -------------------------------------------------------------------
|
|
449
|
+
// task.due-date.set → clickup_update_task {due_date: YYYY-MM-DD}
|
|
450
|
+
//
|
|
451
|
+
// ClickUp stores a date-only value at 04:00 local time of the account
|
|
452
|
+
// timezone. The write is skipped when the stored instant's LOCAL date
|
|
453
|
+
// (account offset from clickup_get_user) is the requested date; without a
|
|
454
|
+
// readable offset it writes anyway. A one-hour DST gap cannot move 04:00
|
|
455
|
+
// across midnight. previousDueAt is the stored ISO instant; newDueAt is
|
|
456
|
+
// the date written (YYYY-MM-DD), since ClickUp keeps no time of day.
|
|
457
|
+
// -------------------------------------------------------------------
|
|
458
|
+
async taskDueDateSet(req) {
|
|
459
|
+
const verb = "task.due-date.set";
|
|
460
|
+
const noId = missingId(verb, { taskId: req.taskId });
|
|
461
|
+
if (noId)
|
|
462
|
+
return noId;
|
|
463
|
+
if (!isCalendarDate(req.dueAt)) {
|
|
464
|
+
return invalidRequest(verb, "invalid_due_date", "dueAt must start with a calendar date (YYYY-MM-DD)");
|
|
465
|
+
}
|
|
466
|
+
const date = req.dueAt.slice(0, 10);
|
|
467
|
+
const read = await readTask(req.taskId, verb, ["due_date"]);
|
|
468
|
+
if (!read.ok)
|
|
469
|
+
return read;
|
|
470
|
+
const task = read.data;
|
|
471
|
+
const data = { previousDueAt: task.dueDate, newDueAt: date };
|
|
472
|
+
if (task.dueDate !== null) {
|
|
473
|
+
const offset = await accountOffset();
|
|
474
|
+
if (offset !== null && localDate(task.dueDate, offset) === date)
|
|
475
|
+
return { ok: true, data };
|
|
476
|
+
}
|
|
477
|
+
const failed = await updateTask(task.id, { due_date: date });
|
|
478
|
+
return failed ?? { ok: true, data };
|
|
479
|
+
},
|
|
480
|
+
// -------------------------------------------------------------------
|
|
481
|
+
// task.assignee.add → clickup_update_task {assignees: current ∪ new}
|
|
482
|
+
//
|
|
483
|
+
// `assignees` replaces the whole set, so the write is the union of
|
|
484
|
+
// the assignees just read and the new id; v1 never removes. A non-numeric
|
|
485
|
+
// userId ("me", an email) is resolved to an id first. Already assigned →
|
|
486
|
+
// {added: false} with no write.
|
|
487
|
+
// -------------------------------------------------------------------
|
|
488
|
+
async taskAssigneeAdd(req) {
|
|
489
|
+
const verb = "task.assignee.add";
|
|
490
|
+
const noId = missingId(verb, { taskId: req.taskId, userId: req.userId });
|
|
491
|
+
if (noId)
|
|
492
|
+
return noId;
|
|
493
|
+
const user = await resolveAssignee(req.userId.trim());
|
|
494
|
+
if (!user.ok)
|
|
495
|
+
return user;
|
|
496
|
+
const read = await readTask(req.taskId, verb, ["assignees"]);
|
|
497
|
+
if (!read.ok)
|
|
498
|
+
return read;
|
|
499
|
+
const current = read.data.assigneeIds;
|
|
500
|
+
if (current.includes(user.data)) {
|
|
501
|
+
return { ok: true, data: { added: false, currentAssigneeIds: current } };
|
|
502
|
+
}
|
|
503
|
+
const assignees = [...current, user.data];
|
|
504
|
+
const failed = await updateTask(read.data.id, { assignees });
|
|
505
|
+
return failed ?? { ok: true, data: { added: true, currentAssigneeIds: assignees } };
|
|
506
|
+
},
|
|
507
|
+
// -------------------------------------------------------------------
|
|
508
|
+
// task.comment.add → clickup_create_comment {entity_type: "task"}
|
|
509
|
+
//
|
|
510
|
+
// With a clientToken the text is posted as `[ct:<token>] <text>`, after a
|
|
511
|
+
// scan of the task's first comments page: a comment already carrying the
|
|
512
|
+
// marker is returned instead of posting again. The attribution
|
|
513
|
+
// prefix, when configured, is already in `text`.
|
|
514
|
+
// -------------------------------------------------------------------
|
|
515
|
+
async taskCommentAdd(req) {
|
|
516
|
+
const verb = "task.comment.add";
|
|
517
|
+
const noId = missingId(verb, { taskId: req.taskId });
|
|
518
|
+
if (noId)
|
|
519
|
+
return noId;
|
|
520
|
+
if (typeof req.text !== "string" || req.text.trim() === "") {
|
|
521
|
+
return invalidRequest(verb, "text_required", "text must be a non-empty comment");
|
|
522
|
+
}
|
|
523
|
+
const marker = req.clientToken ? `[ct:${req.clientToken}]` : undefined;
|
|
524
|
+
const text = marker === undefined ? req.text : `${marker} ${req.text}`;
|
|
525
|
+
if (text.length > COMMENT_MAX_LENGTH) {
|
|
526
|
+
return invalidRequest(verb, "text_too_long", `The comment, with its [ct:] marker, exceeds ${COMMENT_MAX_LENGTH} characters`);
|
|
527
|
+
}
|
|
528
|
+
try {
|
|
529
|
+
if (marker !== undefined) {
|
|
530
|
+
const page = await call("clickup_get_task_comments", { task_id: req.taskId });
|
|
531
|
+
const found = markedComment(page, marker, verb);
|
|
532
|
+
if (!found.ok)
|
|
533
|
+
return found;
|
|
534
|
+
if (found.data !== null)
|
|
535
|
+
return { ok: true, data: found.data };
|
|
536
|
+
}
|
|
537
|
+
const resp = await call("clickup_create_comment", {
|
|
538
|
+
entity_type: "task",
|
|
539
|
+
entity_id: req.taskId,
|
|
540
|
+
comment_text: text,
|
|
541
|
+
});
|
|
542
|
+
// `{success, comment_id}`: no timestamp, so the comment was posted now.
|
|
543
|
+
const commentId = isObj(resp) ? idString(resp.comment_id) : undefined;
|
|
544
|
+
if (commentId === undefined)
|
|
545
|
+
return shapeError(verb);
|
|
546
|
+
return { ok: true, data: { commentId, postedAt: new Date().toISOString() } };
|
|
547
|
+
}
|
|
548
|
+
catch (e) {
|
|
549
|
+
return failure(e);
|
|
550
|
+
}
|
|
551
|
+
},
|
|
552
|
+
// -------------------------------------------------------------------
|
|
553
|
+
// task.parent.set → clickup_update_task {parent}
|
|
554
|
+
//
|
|
555
|
+
// The server also moves the task into the parent's list; the response
|
|
556
|
+
// type has no field for it, so it is not reported. The MCP cannot
|
|
557
|
+
// clear a parent: a missing parentId is NOT_APPLICABLE. Already under
|
|
558
|
+
// that parent → no write. parentId is trimmed once, before every use.
|
|
559
|
+
// -------------------------------------------------------------------
|
|
560
|
+
async taskParentSet(req) {
|
|
561
|
+
const verb = "task.parent.set";
|
|
562
|
+
const noId = missingId(verb, { taskId: req.taskId });
|
|
563
|
+
if (noId)
|
|
564
|
+
return noId;
|
|
565
|
+
const requested = req.parentId;
|
|
566
|
+
const parentId = typeof requested === "string" ? requested.trim() : "";
|
|
567
|
+
if (parentId === "") {
|
|
568
|
+
return notApplicable(verb, "detach_unsupported", "ClickUp cannot turn a subtask back into a top-level task through the MCP");
|
|
569
|
+
}
|
|
570
|
+
if (parentId === req.taskId.trim()) {
|
|
571
|
+
return invalidRequest(verb, "self_parent", "A task cannot be its own parent");
|
|
572
|
+
}
|
|
573
|
+
const read = await readTask(req.taskId, verb);
|
|
574
|
+
if (!read.ok)
|
|
575
|
+
return read;
|
|
576
|
+
const task = read.data;
|
|
577
|
+
const data = { previousParentId: task.parentId, newParentId: parentId };
|
|
578
|
+
if (task.parentId === parentId)
|
|
579
|
+
return { ok: true, data };
|
|
580
|
+
const failed = await updateTask(task.id, { parent: parentId });
|
|
581
|
+
return failed ?? { ok: true, data };
|
|
582
|
+
},
|
|
583
|
+
// -------------------------------------------------------------------
|
|
584
|
+
// task.estimate.set → clickup_update_task {time_estimate} + est:<slug> tag
|
|
585
|
+
//
|
|
586
|
+
// On or off: .clickup.json must declare `estimation`, and neither it nor
|
|
587
|
+
// the request config may say `enabled: false` (NOT_APPLICABLE). The
|
|
588
|
+
// request config then drives strategy, clickupTarget, scale, sizeMap and
|
|
589
|
+
// hoursPerDay. The native estimate (whole minutes) is written only when
|
|
590
|
+
// clickupTarget is "time", the strategy yields a time, and the task is a
|
|
591
|
+
// leaf: ClickUp keeps a parent's own estimate, and roll-up views would add
|
|
592
|
+
// its children's to it. The `est:<slug>` tag is always replace-set:
|
|
593
|
+
// every other `est:*` tag is removed, the tag is ensured in the space and
|
|
594
|
+
// added. What the task already holds is not written again. A failure
|
|
595
|
+
// after a write is partial.
|
|
596
|
+
// -------------------------------------------------------------------
|
|
597
|
+
async taskEstimateSet(req) {
|
|
598
|
+
const verb = "task.estimate.set";
|
|
599
|
+
const requested = req.config;
|
|
600
|
+
if (!isObj(config.estimation) ||
|
|
601
|
+
config.estimation.enabled === false ||
|
|
602
|
+
(isObj(requested) && requested.enabled === false)) {
|
|
603
|
+
return notApplicable(verb, "estimation_disabled", "Estimation is disabled: no estimation block in .clickup.json, or enabled is false");
|
|
604
|
+
}
|
|
605
|
+
const noId = missingId(verb, { taskId: req.taskId });
|
|
606
|
+
if (noId)
|
|
607
|
+
return noId;
|
|
608
|
+
if (!isObj(requested)) {
|
|
609
|
+
return invalidRequest(verb, "estimation_config_required", "config (the estimation block of .clickup.json) is required");
|
|
610
|
+
}
|
|
611
|
+
const { strategy, clickupTarget, scale, sizeMap } = req.config;
|
|
612
|
+
const hoursPerDay = req.config.hoursPerDay ?? DEFAULT_HOURS_PER_DAY;
|
|
613
|
+
if (typeof hoursPerDay !== "number" || !(hoursPerDay >= 1 && hoursPerDay <= 24)) {
|
|
614
|
+
return invalidRequest(verb, "invalid_hours_per_day", "estimation.hoursPerDay must be a number from 1 to 24");
|
|
615
|
+
}
|
|
616
|
+
// Core's `jiraTarget` is the adapter-local target: "time" or "none".
|
|
617
|
+
const jiraTarget = clickupTarget === "time" ? "time" : "none";
|
|
618
|
+
const result = normalizeEstimate(req.input, { strategy, jiraTarget, scale, sizeMap });
|
|
619
|
+
if (!result.ok) {
|
|
620
|
+
return invalidRequest(verb, "invalid_estimate", "The estimate does not fit the strategy");
|
|
621
|
+
}
|
|
622
|
+
const normalized = result.value;
|
|
623
|
+
const minutes = normalized.timeString === undefined
|
|
624
|
+
? undefined
|
|
625
|
+
: toMinutes(normalized.timeString, hoursPerDay);
|
|
626
|
+
if (minutes !== undefined && !(Number.isSafeInteger(minutes) && minutes > 0)) {
|
|
627
|
+
return invalidRequest(verb, "invalid_estimate", "A time estimate must be a finite duration of at least one minute");
|
|
628
|
+
}
|
|
629
|
+
const tag = `est:${slugify(normalized.humanReadable)}`;
|
|
630
|
+
if (tag === "est:") {
|
|
631
|
+
return invalidRequest(verb, "invalid_estimate", "The estimate has no letter or digit for its tag");
|
|
632
|
+
}
|
|
633
|
+
const read = await readTask(req.taskId, verb, ["tags", "subtasks_count", "space"]);
|
|
634
|
+
if (!read.ok)
|
|
635
|
+
return read;
|
|
636
|
+
const task = read.data;
|
|
637
|
+
// The writes, in order: the native estimate first, then the tag.
|
|
638
|
+
const steps = [];
|
|
639
|
+
const timed = jiraTarget === "time" && minutes !== undefined && task.subtaskCount === 0;
|
|
640
|
+
if (timed && task.timeEstimateMs !== minutes * 60_000) {
|
|
641
|
+
steps.push([
|
|
642
|
+
"time_estimate",
|
|
643
|
+
"clickup_update_task",
|
|
644
|
+
{ task_id: task.id, time_estimate: String(minutes) },
|
|
645
|
+
]);
|
|
646
|
+
}
|
|
647
|
+
// ClickUp stores tag names lowercased and removes them ignoring case.
|
|
648
|
+
const estTags = task.tagNames.filter((name) => name.toLowerCase().startsWith("est:"));
|
|
649
|
+
for (const name of estTags) {
|
|
650
|
+
if (name.toLowerCase() === tag)
|
|
651
|
+
continue;
|
|
652
|
+
steps.push([
|
|
653
|
+
"tag_remove",
|
|
654
|
+
"clickup_remove_tag_from_task",
|
|
655
|
+
{ task_id: task.id, tag_name: name },
|
|
656
|
+
]);
|
|
657
|
+
}
|
|
658
|
+
if (!estTags.some((name) => name.toLowerCase() === tag)) {
|
|
659
|
+
steps.push(["tag_create", "clickup_create_space_tag", { space_id: task.spaceId, name: tag }], ["tag_add", "clickup_add_tag_to_task", { task_id: task.id, tag_name: tag }]);
|
|
660
|
+
}
|
|
661
|
+
const applied = [];
|
|
662
|
+
for (const [step, tool, args] of steps) {
|
|
663
|
+
try {
|
|
664
|
+
await call(tool, args);
|
|
665
|
+
}
|
|
666
|
+
catch (e) {
|
|
667
|
+
return stepFailure(failure(e), applied, step);
|
|
668
|
+
}
|
|
669
|
+
if (!applied.includes(step))
|
|
670
|
+
applied.push(step);
|
|
671
|
+
}
|
|
672
|
+
return { ok: true, data: { normalized, fieldWritten: timed ? "time_estimate" : null } };
|
|
673
|
+
},
|
|
674
|
+
};
|
|
675
|
+
}
|
|
676
|
+
//# sourceMappingURL=transport-clickup.js.map
|