Overhaul all API routes and tools against the current ClickUp API (v6.0.0)

Closed
PI
3mo ago
+5524-5852

Description

Full audit and overhaul of the core server's HTTP layer, MCP tool schemas, and zod schemas against the current ClickUp REST API (v2 + v3). Every area was audited against the current OpenAPI specs (api-evangelist mirror, May 2026) plus current SDK/docs research, every finding was adversarially verified by an independent second pass, and only confirmed findings were applied (186 confirmed / 6 refuted out of ~192 reported).

Critical fixes

  • Task descriptions were silently lost: create/update sent markdown_content, but the API field is markdown_description (single + bulk paths).
  • Chat module rewritten for API v3 — previous v2-style paths (/team/{id}/chat/...) never existed; now /api/v3/workspaces/{workspace_id}/chat/... with correct bodies ({type, content}), {data, next_cursor} envelopes, and cursor pagination.
  • List-from-template paths fixed (/list/template/ → /list_template/, both variants always 404'd).
  • Goals key results: correct endpoints (POST /goal/{id}/key_result, PUT/DELETE /key_result/{id}), fields (steps_start/steps_end/steps_current/task_ids, note), {key_result} envelope, real type enum (percentage/automatic).
  • Webhooks: real 27-event enum + *, location scoping, full-body updates, real delivery payload schema ({webhook_id, event, history_items}), raw-body HMAC verification; removed fabricated get-by-id/events/ping/stats/retry endpoints.
  • Views: real filter grammar ({field, op, values} with EQ/ANY/ALL…), full-object PUT semantics, real settings/divide/columns fields, 0-indexed required page, Everything-level (team) views.
  • Attachments rebuilt around the two real endpoints: multipart POST /task/{id}/attachment (was sending JSON with base64) and v3 parent-entity listing; removed 13 tools calling invented endpoints.
  • Custom fields: removed field-definition create/update/delete tools (no such API exists), real type vocabulary, value_options (date time flag), workspace-level field listing.
  • Dependencies: correct depends_on vs dependency_of semantics (direction was inverted), query-param delete, reads via the task's dependencies/linked_tasks arrays; removed 11 fabricated endpoints.
  • Docs v3: create-doc body (parent{id,type}, visibility, create_page), next_cursor pagination (was silently restarting at page 1), real content_format values, content_edit_mode append/prepend, pageListing; removed unsupported update/delete/sharing/template tools.
  • Time tracking: single-object running-timer response (validation crashed before), end field on update, tag_action, required duration, start-timer body params.
  • Client/auth: OAuth Bearer vs raw pk_ token handling, Retry-After honored as a minimum wait, ECODE in errors, 429 retry.
  • Systemic: custom_task_ids/team_id support across task-scoped endpoints; several pagination fixes.

New tools (documented endpoints previously missing): workspace-wide task search, native task merge, task tag add/remove, task-from-template, get folder, folder-from-template, list members, space create/update/delete + space tag CRUD, team views, workspace custom fields, single time entry + time-entry tags, doc pageListing, whoami, user groups, workspace plan, custom roles.

~40 tools that could never succeed (fabricated endpoints) were removed rather than left to 404. The server now registers 157 tools, all backed by documented ClickUp endpoints. Versions bumped to 5.1.0; release notes and README counts updated.

Type of change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected) — tools backed by nonexistent endpoints were removed, and several tool input shapes changed to match the real API

How Has This Been Tested?

  • npx jest in packages/core: 150/150 tests pass (10 suites, including updated assignee/merge/markdown/time tests)
  • Strict tsc --noEmit over src/clickup-client, src/schemas, src/utils: clean
  • Syntax parse of all 77 core source files: clean
  • Live MCP smoke test: server boots via stdio, completes initialize, and tools/list returns all 157 registered tools
  • Note: a full-project tsc including the tool files hits a pre-existing TypeScript type-instantiation blowup in the MCP SDK + zod generics (present on main; the intelligence package fails to build on main for the same reason) — unchanged by this PR

Checklist:

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have updated the RELEASE_NOTES.md file with details of changes
  • New and existing unit tests pass locally with my changes

🤖 Generated with Claude Code

https://claude.ai/code/session_01M18XtDQugWqcmBQLjhyjRo

Generated by Claude Code

Summary by cubic

Overhauled all API routes, tools, and schemas to match the current ClickUp REST API (v2/v3) in @chykalophia/clickup-mcp-server 6.0.0. Removed ~40 nonexistent endpoints, added missing features, fixed critical mismatches, standardized auth/pagination, and now register 157 tools; all 178 tests pass and team_id is enforced when custom_task_ids is used.

  • New Features

    • Chat v3: workspace-scoped routes, messages/replies/reactions, cursor pagination; channel listing supports description_format.
    • Tasks: native merge, tag add/remove, task-from-template, workspace task search.
    • Spaces: create/update/delete + space tag CRUD; lists/folders-from-template (with options.return_immediately), list members; team-level views.
    • Docs v3: parent{id,type} create, pageListing, content_format/content_edit_mode, cursor pagination.
    • Time tracking: running timer, single time entry CRUD, time-entry tags (updates accept start+duration and derive end).

  • Migration

    • Use task markdown_description; markdown_content is accepted (including empty strings to clear descriptions).
    • Chat: require post_data.subtype when sending posts (schema-enforced).
    • Webhooks: documented events/scoping; raw-body HMAC verification; fail-closed when validate_signature is true or signature/secret are missing; status filter uses health states.
    • Attachments: multipart task upload + v3 listing only; exactly one upload source; base64 size pre-check; URL downloads stream with a byte limit; file_path limited to canonical CLICKUP_UPLOAD_DIR; SSRF guard on file_url.
    • custom_task_ids: always provide team_id on task-scoped tools; bulk dependency ops accept per-item custom_task_ids/team_id (max 100).
    • Time tracking: tag_action is replace; create requires exactly one of end/duration; updates may send start+duration (end is derived); stop > start enforced.
    • Comments: create requires content (comment_text or structured blocks); blocks take precedence and empty arrays are rejected; updates allow resolve-only or assign-only and must include at least one update field.
    • Views: real filter grammar and full-object PUT semantics; duplicate-view guard for types the API cannot create.
    • Dependencies: direction semantics fixed; delete via query params; reads via dependencies/linked_tasks.
    • Dependencies: packages/intelligence peer range widened to ^5.0.0 || ^6.0.0.