@d4works/mcp-clickup 0.1.0

package/README.md

@@ -0,0 +1,134 @@
+# @d4works/mcp-clickup
+
+MCP (Model Context Protocol) server for ClickUp task management. Allows Claude to read task details from ClickUp and help with implementation.
+
+## Features
+
+- Fetch task details (description, comments, attachments, custom fields, etc.)
+- Support for multiple task ID formats (URL, custom ID, number)
+- Instructions for Claude to analyze tasks before implementation
+
+## Configuration
+
+### 1. Environment Variables
+
+| Variable              | Required | Description                                      |
+| --------------------- | -------- | ------------------------------------------------ |
+| `CLICKUP_API_TOKEN`   | Yes      | Your ClickUp API token                           |
+| `CLICKUP_TEAM_ID`     | Yes      | Your ClickUp team/workspace ID                   |
+| `CLICKUP_TASK_PREFIX` | No       | Task prefix for number-only input (e.g., "PROJ") |
+
+### 2. Get Your API Token
+
+1. Open ClickUp → Click your avatar → **Settings**
+2. Go to **Apps** section
+3. Generate or copy your **API Token**
+
+### 3. Find Your Team ID
+
+1. Open ClickUp → Go to any workspace
+2. Look at the URL: `https://app.clickup.com/{TEAM_ID}/...`
+3. The number in the URL is your Team ID
+
+### 4. Create MCP Configuration
+
+Create `.mcp.json` in your project root.
+
+First, store your API token in a local file that's gitignored:
+
+```bash
+echo "export CLICKUP_API_TOKEN=pk_your_token_here" >> .claude/.env.local
+```
+
+Then configure `.mcp.json` to source this file before running the server:
+
+```json
+{
+  "mcpServers": {
+    "clickup": {
+      "command": "bash",
+      "args": [
+        "-c",
+        "source .claude/.env.local && npx -y @d4works/mcp-clickup"
+      ],
+      "env": {
+        "CLICKUP_TEAM_ID": "your_team_id",
+        "CLICKUP_TASK_PREFIX": "PROJ"
+      }
+    }
+  }
+}
+```
+
+> **Note:** If you have `CLICKUP_API_TOKEN` exported in your global `~/.zshrc` or `~/.bashrc`, you can simplify the command to just `npx -y @d4works/mcp-clickup`.
+
+## Usage
+
+Ask Claude to work on a task using any of these formats:
+
+```
+> Work on task ABC-123
+> Work on task 123
+> Work on task https://app.clickup.com/t/12345/ABC-123
+```
+
+Claude will:
+
+1. Fetch task details from ClickUp
+2. Analyze the task (description, comments, attachments)
+3. Propose an implementation plan
+4. Wait for your approval before writing code
+
+## Available Tools
+
+### `test-connection`
+
+Test connection to ClickUp API.
+
+### `get-task`
+
+Get task details from ClickUp (description, status, comments, attachments, custom fields, checklists, etc.).
+
+**Parameters:**
+
+- `taskId` (string, required): Task URL, custom ID (ABC-123), or number
+
+### `get-task-statuses`
+
+Get available statuses for a task. Use this before updating status to see valid options.
+
+**Parameters:**
+
+- `taskId` (string, required): Task URL, custom ID (ABC-123), or number
+
+### `set-task-status`
+
+Set the status of a ClickUp task. Only used with explicit user confirmation.
+
+**Parameters:**
+
+- `taskId` (string, required): Task URL, custom ID (ABC-123), or number
+- `status` (string, required): New status name (must match one of the available statuses)
+
+### `get-release-options`
+
+Get available Release dropdown options for a task. Use this to see valid values before setting Release.
+
+**Parameters:**
+
+- `taskId` (string, required): Task URL, custom ID (ABC-123), or number
+- `fieldName` (string, optional): Name of the dropdown field (default: "Release")
+
+### `set-task-release`
+
+Set the Release dropdown value on a ClickUp task. Only used with explicit user confirmation.
+
+**Parameters:**
+
+- `taskId` (string, required): Task URL, custom ID (ABC-123), or number
+- `release` (string, required): Release value to set (must match one of the available options)
+- `fieldName` (string, optional): Name of the dropdown field (default: "Release")
+
+## License
+
+MIT

package/dist/clickup.d.ts

@@ -0,0 +1,148 @@
+/**
+ * ClickUp API client
+ */
+export interface ClickUpStatus {
+    id?: string;
+    status: string;
+    color: string;
+    orderindex: number;
+    type: string;
+}
+export interface ClickUpList {
+    id: string;
+    name: string;
+    statuses: ClickUpStatus[];
+}
+export interface ClickUpTask {
+    id: string;
+    custom_id: string | null;
+    name: string;
+    description: string;
+    status: {
+        status: string;
+        color: string;
+    };
+    priority: {
+        priority: string;
+        color: string;
+    } | null;
+    list: {
+        id: string;
+        name: string;
+    };
+    assignees: Array<{
+        id: number;
+        username: string;
+        email: string;
+    }>;
+    tags: Array<{
+        name: string;
+    }>;
+    due_date: string | null;
+    checklists: Array<{
+        name: string;
+        items: Array<{
+            name: string;
+            resolved: boolean;
+        }>;
+    }>;
+    custom_fields: Array<{
+        id: string;
+        name: string;
+        type: string;
+        value?: unknown;
+        type_config?: {
+            options?: Array<{
+                id: string;
+                name: string;
+                color: string;
+            }>;
+        };
+    }>;
+    attachments: Array<{
+        id: string;
+        title: string;
+        url: string;
+    }>;
+    linked_tasks: Array<{
+        task_id: string;
+        link_id: string;
+    }>;
+    url: string;
+}
+export interface ClickUpComment {
+    id: string;
+    comment_text: string;
+    user: {
+        username: string;
+        email: string;
+    };
+    date: string;
+}
+export interface TaskDetails {
+    task: ClickUpTask;
+    comments: ClickUpComment[];
+}
+export declare class ClickUpClient {
+    private apiToken;
+    private teamId;
+    constructor(apiToken: string, teamId: string);
+    /**
+     * Make authenticated request to ClickUp API
+     */
+    private request;
+    /**
+     * Test API connection by fetching team info
+     */
+    testConnection(): Promise<{
+        ok: boolean;
+        teamName?: string;
+        error?: string;
+    }>;
+    /**
+     * Get task by ID
+     */
+    getTask(taskId: string): Promise<ClickUpTask>;
+    /**
+     * Get task by custom ID (e.g., ABC-123)
+     */
+    getTaskByCustomId(customId: string): Promise<ClickUpTask>;
+    /**
+     * Get comments for a task
+     */
+    getTaskComments(taskId: string): Promise<ClickUpComment[]>;
+    /**
+     * Get task with all details (including comments)
+     */
+    getTaskDetails(taskId: string): Promise<TaskDetails>;
+    /**
+     * Get task details by custom ID (e.g., ABC-123)
+     */
+    getTaskDetailsByCustomId(customId: string): Promise<TaskDetails>;
+    /**
+     * Get list with available statuses
+     */
+    getList(listId: string): Promise<ClickUpList>;
+    /**
+     * Get available statuses for a task (via its list)
+     */
+    getTaskStatuses(taskId: string, isCustomId?: boolean): Promise<ClickUpStatus[]>;
+    /**
+     * Update task status
+     */
+    updateTaskStatus(taskId: string, status: string, isCustomId?: boolean): Promise<ClickUpTask>;
+    /**
+     * Update custom field value on a task
+     */
+    updateCustomField(taskId: string, fieldId: string, value: unknown, isCustomId?: boolean): Promise<void>;
+    /**
+     * Get dropdown custom field options (e.g., for Release field)
+     */
+    getDropdownFieldOptions(taskId: string, fieldName: string, isCustomId?: boolean): Promise<{
+        fieldId: string;
+        options: Array<{
+            id: string;
+            name: string;
+        }>;
+    } | null>;
+}

package/dist/clickup.js

@@ -0,0 +1,145 @@
+/**
+ * ClickUp API client
+ */
+const CLICKUP_API_BASE = "https://api.clickup.com/api/v2";
+export class ClickUpClient {
+    apiToken;
+    teamId;
+    constructor(apiToken, teamId) {
+        this.apiToken = apiToken;
+        this.teamId = teamId;
+    }
+    /**
+     * Make authenticated request to ClickUp API
+     */
+    async request(endpoint, options = {}) {
+        const url = `${CLICKUP_API_BASE}${endpoint}`;
+        const response = await fetch(url, {
+            ...options,
+            headers: {
+                Authorization: this.apiToken,
+                "Content-Type": "application/json",
+                ...options.headers,
+            },
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`ClickUp API error (${response.status}): ${error}`);
+        }
+        return response.json();
+    }
+    /**
+     * Test API connection by fetching team info
+     */
+    async testConnection() {
+        try {
+            const data = await this.request("/team");
+            const team = data.teams.find((t) => t.id === this.teamId);
+            if (team) {
+                return { ok: true, teamName: team.name };
+            }
+            else {
+                return {
+                    ok: false,
+                    error: `Team ID ${this.teamId} not found. Available teams: ${data.teams.map(t => `${t.name} (${t.id})`).join(", ")}`
+                };
+            }
+        }
+        catch (error) {
+            return { ok: false, error: String(error) };
+        }
+    }
+    /**
+     * Get task by ID
+     */
+    async getTask(taskId) {
+        return this.request(`/task/${taskId}`);
+    }
+    /**
+     * Get task by custom ID (e.g., ABC-123)
+     */
+    async getTaskByCustomId(customId) {
+        return this.request(`/task/${customId}?custom_task_ids=true&team_id=${this.teamId}`);
+    }
+    /**
+     * Get comments for a task
+     */
+    async getTaskComments(taskId) {
+        const data = await this.request(`/task/${taskId}/comment`);
+        return data.comments;
+    }
+    /**
+     * Get task with all details (including comments)
+     */
+    async getTaskDetails(taskId) {
+        const [task, comments] = await Promise.all([
+            this.getTask(taskId),
+            this.getTaskComments(taskId),
+        ]);
+        return { task, comments };
+    }
+    /**
+     * Get task details by custom ID (e.g., ABC-123)
+     */
+    async getTaskDetailsByCustomId(customId) {
+        const task = await this.getTaskByCustomId(customId);
+        const comments = await this.getTaskComments(task.id);
+        return { task, comments };
+    }
+    /**
+     * Get list with available statuses
+     */
+    async getList(listId) {
+        return this.request(`/list/${listId}`);
+    }
+    /**
+     * Get available statuses for a task (via its list)
+     */
+    async getTaskStatuses(taskId, isCustomId = false) {
+        const task = isCustomId
+            ? await this.getTaskByCustomId(taskId)
+            : await this.getTask(taskId);
+        const list = await this.getList(task.list.id);
+        return list.statuses;
+    }
+    /**
+     * Update task status
+     */
+    async updateTaskStatus(taskId, status, isCustomId = false) {
+        const endpoint = isCustomId
+            ? `/task/${taskId}?custom_task_ids=true&team_id=${this.teamId}`
+            : `/task/${taskId}`;
+        return this.request(endpoint, {
+            method: "PUT",
+            body: JSON.stringify({ status }),
+        });
+    }
+    /**
+     * Update custom field value on a task
+     */
+    async updateCustomField(taskId, fieldId, value, isCustomId = false) {
+        const task = isCustomId
+            ? await this.getTaskByCustomId(taskId)
+            : await this.getTask(taskId);
+        await this.request(`/task/${task.id}/field/${fieldId}`, {
+            method: "POST",
+            body: JSON.stringify({ value }),
+        });
+    }
+    /**
+     * Get dropdown custom field options (e.g., for Release field)
+     */
+    async getDropdownFieldOptions(taskId, fieldName, isCustomId = false) {
+        const task = isCustomId
+            ? await this.getTaskByCustomId(taskId)
+            : await this.getTask(taskId);
+        const field = task.custom_fields.find((f) => f.name.toLowerCase() === fieldName.toLowerCase() && f.type === "drop_down");
+        if (!field || !field.type_config?.options) {
+            return null;
+        }
+        return {
+            fieldId: field.id,
+            options: field.type_config.options.map((o) => ({ id: o.id, name: o.name })),
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "dotenv/config";

package/dist/index.js

@@ -0,0 +1,406 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { ClickUpClient } from "./clickup.js";
+import { parseTaskId, isCustomTaskId } from "./utils.js";
+// Load configuration from environment
+const apiToken = process.env.CLICKUP_API_TOKEN;
+const teamId = process.env.CLICKUP_TEAM_ID;
+if (!apiToken || !teamId) {
+    console.error("Error: CLICKUP_API_TOKEN and CLICKUP_TEAM_ID must be set");
+    process.exit(1);
+}
+// Create ClickUp client
+const clickup = new ClickUpClient(apiToken, teamId);
+// Create MCP server instance
+const server = new Server({
+    name: "mcp-clickup",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Handler for listing available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "test-connection",
+                description: "Test connection to ClickUp API",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    required: [],
+                },
+            },
+            {
+                name: "get-task",
+                description: "Get task details from ClickUp. Accepts task URL, custom ID (e.g., ABC-123), or task number.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        taskId: {
+                            type: "string",
+                            description: "Task identifier: URL, custom ID (ABC-123), or number",
+                        },
+                    },
+                    required: ["taskId"],
+                },
+            },
+            {
+                name: "get-task-statuses",
+                description: "Get available statuses for a task. Use this before updating status to see valid options.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        taskId: {
+                            type: "string",
+                            description: "Task identifier: URL, custom ID (ABC-123), or number",
+                        },
+                    },
+                    required: ["taskId"],
+                },
+            },
+            {
+                name: "set-task-status",
+                description: "Update the status of a ClickUp task. IMPORTANT: Only use with explicit user confirmation!",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        taskId: {
+                            type: "string",
+                            description: "Task identifier: URL, custom ID (ABC-123), or number",
+                        },
+                        status: {
+                            type: "string",
+                            description: "New status name (must match one of the available statuses)",
+                        },
+                    },
+                    required: ["taskId", "status"],
+                },
+            },
+            {
+                name: "get-release-options",
+                description: "Get available Release dropdown options for a task. Use this to see valid values before setting Release.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        taskId: {
+                            type: "string",
+                            description: "Task identifier: URL, custom ID (ABC-123), or number",
+                        },
+                        fieldName: {
+                            type: "string",
+                            description: "Name of the dropdown field (default: 'Release')",
+                        },
+                    },
+                    required: ["taskId"],
+                },
+            },
+            {
+                name: "set-task-release",
+                description: "Set the Release dropdown value on a ClickUp task. IMPORTANT: Only use with explicit user confirmation!",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        taskId: {
+                            type: "string",
+                            description: "Task identifier: URL, custom ID (ABC-123), or number",
+                        },
+                        release: {
+                            type: "string",
+                            description: "Release value to set (must match one of the available options)",
+                        },
+                        fieldName: {
+                            type: "string",
+                            description: "Name of the dropdown field (default: 'Release')",
+                        },
+                    },
+                    required: ["taskId", "release"],
+                },
+            },
+        ],
+    };
+});
+// Format task details for display
+function formatTaskDetails(task) {
+    const { task: t, comments } = task;
+    const lines = [];
+    lines.push(`# ${t.custom_id || t.id} - ${t.name}`);
+    lines.push("");
+    lines.push(`**Status:** ${t.status.status}`);
+    lines.push(`**Priority:** ${t.priority?.priority || "None"}`);
+    lines.push(`**URL:** ${t.url}`);
+    if (t.assignees.length > 0) {
+        lines.push(`**Assignees:** ${t.assignees.map((a) => a.username).join(", ")}`);
+    }
+    if (t.tags.length > 0) {
+        lines.push(`**Tags:** ${t.tags.map((tag) => tag.name).join(", ")}`);
+    }
+    if (t.due_date) {
+        lines.push(`**Due:** ${new Date(parseInt(t.due_date)).toLocaleDateString()}`);
+    }
+    lines.push("");
+    lines.push("## Description");
+    lines.push(t.description || "(no description)");
+    if (t.checklists.length > 0) {
+        lines.push("");
+        lines.push("## Checklists");
+        for (const checklist of t.checklists) {
+            lines.push(`### ${checklist.name}`);
+            for (const item of checklist.items) {
+                lines.push(`- [${item.resolved ? "x" : " "}] ${item.name}`);
+            }
+        }
+    }
+    if (t.custom_fields.length > 0) {
+        const fieldsWithValues = t.custom_fields.filter((f) => f.value !== undefined && f.value !== null);
+        if (fieldsWithValues.length > 0) {
+            lines.push("");
+            lines.push("## Custom Fields");
+            for (const field of fieldsWithValues) {
+                let displayValue;
+                if (field.type === "drop_down" && field.type_config?.options) {
+                    const option = field.type_config.options.find((o, index) => index === field.value || o.id === field.value);
+                    displayValue = option?.name || String(field.value);
+                }
+                else if (field.type === "automatic_progress" && typeof field.value === "object") {
+                    const progress = field.value;
+                    displayValue = `${progress.percent_complete || 0}%`;
+                }
+                else {
+                    displayValue = String(field.value);
+                }
+                lines.push(`- **${field.name}:** ${displayValue}`);
+            }
+        }
+    }
+    if (t.attachments.length > 0) {
+        lines.push("");
+        lines.push("## Attachments");
+        for (const attachment of t.attachments) {
+            lines.push(`- [${attachment.title}](${attachment.url})`);
+        }
+    }
+    if (comments.length > 0) {
+        lines.push("");
+        lines.push("## Comments");
+        for (const comment of comments) {
+            const date = new Date(parseInt(comment.date)).toLocaleString();
+            lines.push(`### ${comment.user.username} (${date})`);
+            lines.push(comment.comment_text);
+            lines.push("");
+        }
+    }
+    // Add instructions for Claude
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    lines.push("## Instructions");
+    lines.push("1. Analyze this task thoroughly (description, comments, attachments)");
+    lines.push("2. Propose an implementation plan with clear steps");
+    lines.push("3. **WAIT for user approval** before starting any implementation");
+    lines.push("4. Do NOT write any code until the user explicitly approves the plan");
+    return lines.join("\n");
+}
+// Handler for calling tools
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    if (name === "test-connection") {
+        const result = await clickup.testConnection();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.ok
+                        ? `Connected to ClickUp team: ${result.teamName}`
+                        : `Connection failed: ${result.error}`,
+                },
+            ],
+        };
+    }
+    if (name === "get-task") {
+        const taskId = parseTaskId(args.taskId);
+        try {
+            let taskDetails;
+            if (isCustomTaskId(taskId)) {
+                taskDetails = await clickup.getTaskDetailsByCustomId(taskId);
+            }
+            else {
+                taskDetails = await clickup.getTaskDetails(taskId);
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: formatTaskDetails(taskDetails),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error fetching task: ${error}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    if (name === "get-task-statuses") {
+        const taskId = parseTaskId(args.taskId);
+        try {
+            const statuses = await clickup.getTaskStatuses(taskId, isCustomTaskId(taskId));
+            const statusList = statuses
+                .map((s) => `- ${s.status} (${s.type})`)
+                .join("\n");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Available statuses for task ${taskId}:\n${statusList}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error fetching statuses: ${error}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    if (name === "set-task-status") {
+        const { taskId: rawTaskId, status } = args;
+        const taskId = parseTaskId(rawTaskId);
+        try {
+            const updatedTask = await clickup.updateTaskStatus(taskId, status, isCustomTaskId(taskId));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Task ${updatedTask.custom_id || updatedTask.id} status updated to: ${updatedTask.status.status}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error updating status: ${error}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    if (name === "get-release-options") {
+        const { taskId: rawTaskId, fieldName = "Release" } = args;
+        const taskId = parseTaskId(rawTaskId);
+        try {
+            const fieldData = await clickup.getDropdownFieldOptions(taskId, fieldName, isCustomTaskId(taskId));
+            if (!fieldData) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No dropdown field "${fieldName}" found on task ${taskId}`,
+                        },
+                    ],
+                };
+            }
+            const optionsList = fieldData.options.map((o) => `- ${o.name}`).join("\n");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Available "${fieldName}" options for task ${taskId}:\n${optionsList}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error fetching field options: ${error}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    if (name === "set-task-release") {
+        const { taskId: rawTaskId, release, fieldName = "Release" } = args;
+        const taskId = parseTaskId(rawTaskId);
+        try {
+            const fieldData = await clickup.getDropdownFieldOptions(taskId, fieldName, isCustomTaskId(taskId));
+            if (!fieldData) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No dropdown field "${fieldName}" found on task ${taskId}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const option = fieldData.options.find((o) => o.name.toLowerCase() === release.toLowerCase());
+            if (!option) {
+                const availableOptions = fieldData.options.map((o) => o.name).join(", ");
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Invalid release value "${release}". Available options: ${availableOptions}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            await clickup.updateCustomField(taskId, fieldData.fieldId, option.id, isCustomTaskId(taskId));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Task ${taskId} "${fieldName}" set to: ${option.name}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error setting release: ${error}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    throw new Error(`Unknown tool: ${name}`);
+});
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP ClickUp server running on stdio");
+}
+main().catch(console.error);

package/dist/test-connection.d.ts

@@ -0,0 +1 @@
+import "dotenv/config";

package/dist/test-connection.js

@@ -0,0 +1,17 @@
+import "dotenv/config";
+import { ClickUpClient } from "./clickup.js";
+const apiToken = process.env.CLICKUP_API_TOKEN;
+const teamId = process.env.CLICKUP_TEAM_ID;
+if (!apiToken || !teamId) {
+    console.error("Error: CLICKUP_API_TOKEN and CLICKUP_TEAM_ID must be set");
+    process.exit(1);
+}
+const clickup = new ClickUpClient(apiToken, teamId);
+console.log("Testing ClickUp connection...");
+const result = await clickup.testConnection();
+if (result.ok) {
+    console.log(`✓ Connected to team: ${result.teamName}`);
+}
+else {
+    console.error(`✗ Connection failed: ${result.error}`);
+}

package/dist/test-get-task.d.ts

@@ -0,0 +1 @@
+import "dotenv/config";

package/dist/test-get-task.js

@@ -0,0 +1,93 @@
+import "dotenv/config";
+import { ClickUpClient } from "./clickup.js";
+import { parseTaskId } from "./utils.js";
+const apiToken = process.env.CLICKUP_API_TOKEN;
+const teamId = process.env.CLICKUP_TEAM_ID;
+if (!apiToken || !teamId) {
+    console.error("Error: CLICKUP_API_TOKEN and CLICKUP_TEAM_ID must be set");
+    process.exit(1);
+}
+// Get task ID from command line argument
+const taskInput = process.argv[2];
+if (!taskInput) {
+    console.error("Usage: node dist/test-get-task.js <task-id>");
+    console.error("Examples:");
+    console.error("  node dist/test-get-task.js ABC-123");
+    console.error("  node dist/test-get-task.js 123");
+    console.error("  node dist/test-get-task.js https://app.clickup.com/t/12345/ABC-123");
+    process.exit(1);
+}
+// Parse task ID from various formats
+const customId = parseTaskId(taskInput);
+const clickup = new ClickUpClient(apiToken, teamId);
+console.log(`Fetching task: ${customId}\n`);
+try {
+    const { task, comments } = await clickup.getTaskDetailsByCustomId(customId);
+    console.log("=".repeat(60));
+    console.log(`TASK: ${task.custom_id || task.id} - ${task.name}`);
+    console.log("=".repeat(60));
+    console.log(`\nStatus: ${task.status.status}`);
+    console.log(`Priority: ${task.priority?.priority || "None"}`);
+    console.log(`URL: ${task.url}`);
+    if (task.assignees.length > 0) {
+        console.log(`Assignees: ${task.assignees.map(a => a.username).join(", ")}`);
+    }
+    if (task.tags.length > 0) {
+        console.log(`Tags: ${task.tags.map(t => t.name).join(", ")}`);
+    }
+    if (task.due_date) {
+        console.log(`Due: ${new Date(parseInt(task.due_date)).toLocaleDateString()}`);
+    }
+    console.log("\n--- DESCRIPTION ---");
+    console.log(task.description || "(no description)");
+    if (task.checklists.length > 0) {
+        console.log("\n--- CHECKLISTS ---");
+        for (const checklist of task.checklists) {
+            console.log(`\n${checklist.name}:`);
+            for (const item of checklist.items) {
+                console.log(`  [${item.resolved ? "x" : " "}] ${item.name}`);
+            }
+        }
+    }
+    if (task.custom_fields.length > 0) {
+        console.log("\n--- CUSTOM FIELDS ---");
+        for (const field of task.custom_fields) {
+            if (field.value !== undefined && field.value !== null) {
+                let displayValue;
+                // Handle dropdown fields - value is orderindex (number)
+                if (field.type === "drop_down" && field.type_config?.options) {
+                    const option = field.type_config.options.find((o, index) => index === field.value || o.id === field.value);
+                    displayValue = option?.name || String(field.value);
+                }
+                // Handle automatic progress fields
+                else if (field.type === "automatic_progress" && typeof field.value === "object") {
+                    const progress = field.value;
+                    displayValue = `${progress.percent_complete || 0}%`;
+                }
+                // Handle other types
+                else {
+                    displayValue = String(field.value);
+                }
+                console.log(`${field.name}: ${displayValue}`);
+            }
+        }
+    }
+    if (task.attachments.length > 0) {
+        console.log("\n--- ATTACHMENTS ---");
+        for (const attachment of task.attachments) {
+            console.log(`- ${attachment.title}: ${attachment.url}`);
+        }
+    }
+    if (comments.length > 0) {
+        console.log("\n--- COMMENTS ---");
+        for (const comment of comments) {
+            const date = new Date(parseInt(comment.date)).toLocaleString();
+            console.log(`\n[${date}] ${comment.user.username}:`);
+            console.log(comment.comment_text);
+        }
+    }
+    console.log("\n" + "=".repeat(60));
+}
+catch (error) {
+    console.error("Error fetching task:", error);
+}

package/dist/utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Utility functions for parsing task identifiers
+ */
+/**
+ * Parse task identifier from various formats:
+ * - Full URL: https://app.clickup.com/t/12345/ABC-123
+ * - Custom ID: ABC-123
+ * - Number only: 123 (requires CLICKUP_TASK_PREFIX to be set)
+ *
+ * Returns the custom task ID (e.g., "ABC-123") or internal ID
+ */
+export declare function parseTaskId(input: string): string;
+/**
+ * Check if the task ID is a custom ID (ABC-123 format) or internal ID
+ */
+export declare function isCustomTaskId(taskId: string): boolean;

package/dist/utils.js

@@ -0,0 +1,66 @@
+/**
+ * Utility functions for parsing task identifiers
+ */
+// Task prefix from environment variable (e.g., "PROJ", "TASK", etc.)
+const TASK_PREFIX = process.env.CLICKUP_TASK_PREFIX || "";
+/**
+ * Parse task identifier from various formats:
+ * - Full URL: https://app.clickup.com/t/12345/ABC-123
+ * - Custom ID: ABC-123
+ * - Number only: 123 (requires CLICKUP_TASK_PREFIX to be set)
+ *
+ * Returns the custom task ID (e.g., "ABC-123") or internal ID
+ */
+export function parseTaskId(input) {
+    const trimmed = input.trim();
+    // Check if it's a URL
+    if (trimmed.startsWith("http")) {
+        return parseTaskIdFromUrl(trimmed);
+    }
+    // Check if it already has a prefix (ABC-123 format)
+    if (/^[A-Za-z]+-\d+$/.test(trimmed)) {
+        return trimmed.toUpperCase();
+    }
+    // Check if it's just a number and we have a prefix configured
+    if (/^\d+$/.test(trimmed) && TASK_PREFIX) {
+        return `${TASK_PREFIX}-${trimmed}`;
+    }
+    // Return as-is if we can't parse it (could be internal ID)
+    return trimmed;
+}
+/**
+ * Extract task ID from ClickUp URL
+ * Supports formats:
+ * - https://app.clickup.com/t/12345/ABC-123 (with custom ID)
+ * - https://app.clickup.com/t/abc123xyz (internal ID only)
+ */
+function parseTaskIdFromUrl(url) {
+    try {
+        const urlObj = new URL(url);
+        const pathParts = urlObj.pathname.split("/").filter(Boolean);
+        // URL format: /t/{team_id_or_task_id}/{custom_id}
+        // or: /t/{internal_task_id}
+        if (pathParts[0] === "t" && pathParts.length >= 2) {
+            // If there's a third part, it's likely the custom ID
+            if (pathParts.length >= 3) {
+                const customId = pathParts[2];
+                // Check if it looks like a custom ID (has prefix)
+                if (customId.includes("-")) {
+                    return customId.toUpperCase();
+                }
+            }
+            // Otherwise return the second part (could be internal task ID)
+            return pathParts[1];
+        }
+        throw new Error("Could not parse task ID from URL");
+    }
+    catch (error) {
+        throw new Error(`Invalid ClickUp URL: ${url}`);
+    }
+}
+/**
+ * Check if the task ID is a custom ID (ABC-123 format) or internal ID
+ */
+export function isCustomTaskId(taskId) {
+    return /^[A-Za-z]+-\d+$/.test(taskId);
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@d4works/mcp-clickup",
+  "version": "0.1.0",
+  "description": "MCP server for ClickUp task management",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-clickup": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "clickup",
+    "claude",
+    "ai",
+    "task-management",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "dotenv": "^17.2.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}