feat: add support for custom task IDs (e.g., CHIEF-5804)

All task-related tools now accept custom task IDs in addition to internal
IDs. When a custom task ID is detected (format: PREFIX-NUMBER), the API
calls automatically include custom_task_ids=true and team_id parameters
as required by the ClickUp API.

Changes:
- Add isCustomTaskId() helper function to detect custom ID format
- Update isTaskId() to validate both internal and custom ID formats
- Relax task_id validation across all tools (getTaskById, updateTask,
  addComment, searchTasks, getTimeEntries, createTimeEntry)
- Inject custom_task_ids=true and team_id params for API calls with custom IDs
- Update tool descriptions to document custom ID support

Co-Authored-By: Claude <[email protected]>

Author: jon-daniels-chief

CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- **Custom task ID support** - All task-related tools now accept custom task IDs (e.g., "CHIEF-5804") in addition to internal IDs (e.g., "86b852ppx")
+- New `isCustomTaskId()` helper function to detect custom task ID format
+- Automatic `custom_task_ids=true` and `team_id` parameter injection for API calls when custom IDs are used
+
+### Changed
+- Relaxed task ID validation across all tools (`getTaskById`, `updateTask`, `addComment`, `searchTasks`, `getTimeEntries`, `createTimeEntry`) to accept both internal and custom ID formats
+- Updated tool descriptions to document custom ID support
+
 ## [1.6.0] - 2025-11-25
 
 ### Added

src/shared/utils.ts

@@ -5,11 +5,28 @@ const GLOBAL_REFRESH_INTERVAL = 60000; // 60 seconds - that is the rate limit ti
 
 /**
  * Checks if a string looks like a valid ClickUp task ID
- * Valid task IDs are 6-9 characters long and contain only alphanumeric characters
+ * Valid task IDs are either:
+ * - Internal IDs: 6-9 alphanumeric characters (e.g., "86b852ppx")
+ * - Custom IDs: PREFIX-NUMBER format (e.g., "CHIEF-5804")
  */
 export function isTaskId(str: string): boolean {
-  // Task IDs are 6-9 characters long and contain only alphanumeric characters
-  return /^[a-z0-9]{6,9}$/i.test(str);
+  // Internal task IDs: 6-9 alphanumeric characters
+  if (/^[a-z0-9]{6,9}$/i.test(str)) {
+    return true;
+  }
+  // Custom task IDs: PREFIX-NUMBER format (e.g., "CHIEF-5804", "PROJ-123")
+  if (/^[A-Z]+-\d+$/i.test(str)) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Checks if a task ID is a custom task ID (vs internal ID)
+ * Custom task IDs require special API parameters
+ */
+export function isCustomTaskId(str: string): boolean {
+  return /^[A-Z]+-\d+$/i.test(str);
 }
 
 // Cache for current user info to avoid repeated API calls and race conditions

src/tools/search-tools.ts

@@ -1,7 +1,7 @@
 import {McpServer} from "@modelcontextprotocol/sdk/server/mcp.js";
 import {z} from "zod";
 import {CONFIG} from "../shared/config";
-import {isTaskId, getTaskSearchIndex, performMultiTermSearch} from "../shared/utils";
+import {isTaskId, isCustomTaskId, getTaskSearchIndex, performMultiTermSearch} from "../shared/utils";
 import {generateTaskMetadata} from "./task-tools";
 
 const MAX_SEARCH_RESULTS = 50;
@@ -131,8 +131,9 @@ export function registerSearchTools(server: McpServer, userData: any) {
         console.error(`Attempting direct fetch for task IDs: ${taskIdsToFetchDirectly.join(', ')}`);
         const directFetchPromises = taskIdsToFetchDirectly.map(async (id) => {
           try {
+            const customIdParams = isCustomTaskId(id) ? `?custom_task_ids=true&team_id=${CONFIG.teamId}` : '';
             const response = await fetch(
-              `https://api.clickup.com/api/v2/task/${id}`,
+              `https://api.clickup.com/api/v2/task/${id}${customIdParams}`,
               {headers: {Authorization: CONFIG.apiKey}}
             );
             if (response.ok) {

src/tools/task-tools.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { convertMarkdownToToolCallResult, convertClickUpTextItemsToToolCallResult } from "../clickup-text";
 import { ContentBlock, DatedContentEvent, ImageMetadataBlock } from "../shared/types";
 import { CONFIG } from "../shared/config";
-import { isTaskId, getSpaceDetails, getAllTeamMembers } from "../shared/utils";
+import { isTaskId, isCustomTaskId, getSpaceDetails, getAllTeamMembers } from "../shared/utils";
 import { downloadImages } from "../shared/image-processing";
 
 // Read-specific utility functions
@@ -19,13 +19,12 @@ export function registerTaskToolsRead(server: McpServer, userData: any) {
     {
       id: z
         .string()
-        .min(6)
-        .max(9)
+        .min(1)
         .refine(val => isTaskId(val), {
-          message: "Task ID must be 6-9 alphanumeric characters only"
+          message: "Task ID must be either 6-9 alphanumeric characters or a custom ID like 'CHIEF-5804'"
         })
         .describe(
-          `The 6-9 character ID of the task to get without a prefix like "#", "CU-" or "https://app.clickup.com/t/"`
+          `The task ID - either internal (6-9 chars like "86b852ppx") or custom (like "CHIEF-5804"). Do not include prefixes like "#", "CU-" or full URLs.`
         ),
     },
     {
@@ -104,8 +103,9 @@ async function fetchTaskTimeEntries(taskId: string): Promise<any[]> {
 }
 
 async function loadTaskContent(taskId: string): Promise<(ContentBlock | ImageMetadataBlock)[]> {
+  const customIdParams = isCustomTaskId(taskId) ? `&custom_task_ids=true&team_id=${CONFIG.teamId}` : '';
   const response = await fetch(
-    `https://api.clickup.com/api/v2/task/${taskId}?include_markdown_description=true&include_subtasks=true`,
+    `https://api.clickup.com/api/v2/task/${taskId}?include_markdown_description=true&include_subtasks=true${customIdParams}`,
     { headers: { Authorization: CONFIG.apiKey } }
   );
   const task = await response.json();
@@ -127,8 +127,9 @@ async function loadTaskContent(taskId: string): Promise<(ContentBlock | ImageMet
 }
 
 async function loadTaskComments(id: string): Promise<DatedContentEvent[]> {
+  const customIdParams = isCustomTaskId(id) ? `&custom_task_ids=true&team_id=${CONFIG.teamId}` : '';
   const response = await fetch(
-    `https://api.clickup.com/api/v2/task/${id}/comment?start_date=0`, // Ensure all comments are fetched
+    `https://api.clickup.com/api/v2/task/${id}/comment?start_date=0${customIdParams}`, // Ensure all comments are fetched
     { headers: { Authorization: CONFIG.apiKey } }
   );
   if (!response.ok) {
@@ -159,7 +160,8 @@ async function loadTaskComments(id: string): Promise<DatedContentEvent[]> {
 }
 
 async function loadTimeInStatusHistory(taskId: string): Promise<DatedContentEvent[]> {
-  const url = `https://api.clickup.com/api/v2/task/${taskId}/time_in_status`;
+  const customIdParams = isCustomTaskId(taskId) ? `?custom_task_ids=true&team_id=${CONFIG.teamId}` : '';
+  const url = `https://api.clickup.com/api/v2/task/${taskId}/time_in_status${customIdParams}`;
   try {
     const response = await fetch(url, { headers: { Authorization: CONFIG.apiKey } });
     if (!response.ok) {

src/tools/task-write-tools.ts

@@ -1,7 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { CONFIG } from "../shared/config";
-import { getCurrentUser } from "../shared/utils";
+import { getCurrentUser, isTaskId, isCustomTaskId } from "../shared/utils";
 import { convertMarkdownToClickUpBlocks } from "../clickup-text";
 
 // Shared schemas for task parameters
@@ -35,7 +35,9 @@ export function registerTaskToolsWrite(server: McpServer, userData: any) {
       return descriptionBase.join("\n");
     })(),
     {
-      task_id: z.string().min(6).max(9).describe("The 6-9 character task ID to comment on"),
+      task_id: z.string().min(1).refine(val => isTaskId(val), {
+        message: "Task ID must be either 6-9 alphanumeric characters or a custom ID like 'CHIEF-5804'"
+      }).describe("The task ID to comment on (internal like '86b852ppx' or custom like 'CHIEF-5804')"),
       comment: z.string().min(1).describe("The comment text to add to the task"),
     },
     {
@@ -53,7 +55,8 @@ export function registerTaskToolsWrite(server: McpServer, userData: any) {
           notify_all: true
         };
 
-        const response = await fetch(`https://api.clickup.com/api/v2/task/${task_id}/comment`, {
+        const customIdParams = isCustomTaskId(task_id) ? `?custom_task_ids=true&team_id=${CONFIG.teamId}` : '';
+        const response = await fetch(`https://api.clickup.com/api/v2/task/${task_id}/comment${customIdParams}`, {
           method: 'POST',
           headers: {
             Authorization: CONFIG.apiKey,
@@ -122,7 +125,9 @@ export function registerTaskToolsWrite(server: McpServer, userData: any) {
       return descriptionBase.join("\n");
     })(),
     {
-      task_id: z.string().min(6).max(9).describe("The 6-9 character task ID to update"),
+      task_id: z.string().min(1).refine(val => isTaskId(val), {
+        message: "Task ID must be either 6-9 alphanumeric characters or a custom ID like 'CHIEF-5804'"
+      }).describe("The task ID to update (internal like '86b852ppx' or custom like 'CHIEF-5804')"),
       name: taskNameSchema.optional(),
       append_description: z.string().optional().describe("Optional markdown content to APPEND to existing task description (preserves existing content for safety)"),
       status: z.string().optional().describe("Optional new status name - use getListInfo to see valid options"),
@@ -148,7 +153,8 @@ export function registerTaskToolsWrite(server: McpServer, userData: any) {
         const userData = await getCurrentUser();
 
         // Get task details including current markdown description
-        const taskResponse = await fetch(`https://api.clickup.com/api/v2/task/${task_id}?include_markdown_description=true`, {
+        const customIdParams = isCustomTaskId(task_id) ? `&custom_task_ids=true&team_id=${CONFIG.teamId}` : '';
+        const taskResponse = await fetch(`https://api.clickup.com/api/v2/task/${task_id}?include_markdown_description=true${customIdParams}`, {
           headers: { Authorization: CONFIG.apiKey },
         });
 
@@ -180,8 +186,9 @@ export function registerTaskToolsWrite(server: McpServer, userData: any) {
           // Add new tags
           for (const tagName of tagsToAdd) {
             try {
+              const tagCustomIdParams = isCustomTaskId(task_id) ? `?custom_task_ids=true&team_id=${CONFIG.teamId}` : '';
               const addTagResponse = await fetch(
-                `https://api.clickup.com/api/v2/task/${task_id}/tag/${encodeURIComponent(tagName)}`,
+                `https://api.clickup.com/api/v2/task/${task_id}/tag/${encodeURIComponent(tagName)}${tagCustomIdParams}`,
                 {
                   method: 'POST',
                   headers: { Authorization: CONFIG.apiKey }
@@ -200,8 +207,9 @@ export function registerTaskToolsWrite(server: McpServer, userData: any) {
           // Remove old tags
           for (const tagName of tagsToRemove) {
             try {
+              const tagCustomIdParams = isCustomTaskId(task_id) ? `?custom_task_ids=true&team_id=${CONFIG.teamId}` : '';
               const removeTagResponse = await fetch(
-                `https://api.clickup.com/api/v2/task/${task_id}/tag/${encodeURIComponent(tagName)}`,
+                `https://api.clickup.com/api/v2/task/${task_id}/tag/${encodeURIComponent(tagName)}${tagCustomIdParams}`,
                 {
                   method: 'DELETE',
                   headers: { Authorization: CONFIG.apiKey }
@@ -257,7 +265,8 @@ export function registerTaskToolsWrite(server: McpServer, userData: any) {
         // Update the task (if there are non-tag updates)
         let updatedTask = taskData;
         if (Object.keys(updateBody).length > 0) {
-          const updateResponse = await fetch(`https://api.clickup.com/api/v2/task/${task_id}`, {
+          const updateCustomIdParams = isCustomTaskId(task_id) ? `?custom_task_ids=true&team_id=${CONFIG.teamId}` : '';
+          const updateResponse = await fetch(`https://api.clickup.com/api/v2/task/${task_id}${updateCustomIdParams}`, {
             method: 'PUT',
             headers: {
               Authorization: CONFIG.apiKey,
@@ -276,7 +285,8 @@ export function registerTaskToolsWrite(server: McpServer, userData: any) {
 
         // If only tags or dependencies were updated, fetch the task again to get the updated state
         if ((tags !== undefined || blocking !== undefined || waiting_on !== undefined || linked_tasks !== undefined) && Object.keys(updateBody).length === 0) {
-          const refreshResponse = await fetch(`https://api.clickup.com/api/v2/task/${task_id}`, {
+          const refreshCustomIdParams = isCustomTaskId(task_id) ? `?custom_task_ids=true&team_id=${CONFIG.teamId}` : '';
+          const refreshResponse = await fetch(`https://api.clickup.com/api/v2/task/${task_id}${refreshCustomIdParams}`, {
             headers: { Authorization: CONFIG.apiKey },
           });
           if (refreshResponse.ok) {

src/tools/time-tools.ts

@@ -1,7 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { CONFIG } from "../shared/config";
-import { getAllTeamMembers } from "../shared/utils";
+import { getAllTeamMembers, isTaskId } from "../shared/utils";
 
 /**
  * Converts ISO date string to Unix timestamp in milliseconds
@@ -60,7 +60,9 @@ export function registerTimeToolsRead(server: McpServer) {
     "getTimeEntries",
     "Gets time entries for a specific task or all user's time entries. Returns last 30 days by default if no dates specified.",
     {
-      task_id: z.string().min(6).max(9).optional().describe("Optional 6-9 character task ID to filter entries. If not provided, returns all user's time entries."),
+      task_id: z.string().min(1).refine(val => isTaskId(val), {
+        message: "Task ID must be either 6-9 alphanumeric characters or a custom ID like 'CHIEF-5804'"
+      }).optional().describe("Optional task ID to filter entries (internal like '86b852ppx' or custom like 'CHIEF-5804'). If not provided, returns all user's time entries."),
       start_date: z.string().optional().describe("Optional start date filter as ISO date string (e.g., '2024-10-06T00:00:00+02:00'). Defaults to 30 days ago."),
       end_date: z.string().optional().describe("Optional end date filter as ISO date string (e.g., '2024-10-06T23:59:59+02:00'). Defaults to current date."),
       list_id: z.string().optional().describe("Optional single list ID to filter time entries by a specific list"),
@@ -329,7 +331,9 @@ export function registerTimeToolsWrite(server: McpServer) {
       "Suggest moving the task to an active status like 'in progress' first."
     ].join("\n"),
     {
-      task_id: z.string().min(6).max(9).describe("The 6-9 character task ID to book time against"),
+      task_id: z.string().min(1).refine(val => isTaskId(val), {
+        message: "Task ID must be either 6-9 alphanumeric characters or a custom ID like 'CHIEF-5804'"
+      }).describe("The task ID to book time against (internal like '86b852ppx' or custom like 'CHIEF-5804')"),
       hours: z.number().min(0.01).max(24).describe("Hours to book (decimal format, e.g., 0.25 = 15min, 1.5 = 1h 30min)"),
       description: z.string().optional().describe("Optional description for the time entry"),
       start_time: z.string().optional().describe("Optional start time as ISO date string (e.g., '2024-10-06T09:00:00+02:00', defaults to current time)")