@hauptsache.net/clickup-mcp 1.6.2 → 1.7.2

package/README.md

@@ -11,7 +11,7 @@ Model Context Protocol (MCP) server enabling AI assistants to interact with Clic
 | **Setup**            | Local npm/npx install                                 | Remote MCP (no install)                     |
 | **Authentication**   | API key only                                          | OAuth only                                  |
 | **Task Context**     | Complete with comments, status history, inline images | Requires mutiple tool calls for full contxt |
-| **Image Support**    | Inline images with smart size budgeting               | Not documented                              |
+| **Image Support**    | Read and write: inline images with smart size budgeting, and `![](local/path.png)` uploads automatically | Upload via separate tool calls; base64 capped at ~200KB |
 | **Search**           | Fuzzy search on recent tasks (limited scope)          | Full ClickUp search database                |
 | **Documents**        | CRUD operations                                       | CRUD + document search                      |
 | **Time Tracking**    | View and create entries                               | Timers and entries                          |
@@ -22,6 +22,7 @@ Model Context Protocol (MCP) server enabling AI assistants to interact with Clic
 
 **Choose this MCP when:**
 - You need rich task context with inline images for AI coding tools
+- You want to write screenshots into tickets by local file path (running locally, it reads the file itself instead of taking base64)
 - You need API key authentication for automation or CI/CD pipelines
 - You want the `read-minimal` mode optimized for development workflows
 
@@ -187,6 +188,7 @@ The ClickUp MCP supports three operational modes to balance functionality, secur
 |------------------------|:------------:|:----:|:-----:|-----------------------------------------------------------------------------------------|
 | `getTaskById`          |      ✅       |  ✅   |   ✅   | Get complete task details including comments, images, and metadata                      |
 | `addComment`           |      ❌       |  ❌   |   ✅   | Add comments to tasks for collaboration                                                 |
+| `editComment`          |      ❌       |  ❌   |   ✅   | Correct your own comment within 24h instead of posting a follow-up                      |
 | `updateTask`           |      ❌       |  ❌   |   ✅   | Update tasks (status, priority, assignees, etc.) with **SAFE APPEND-ONLY** descriptions |
 | `createTask`           |      ❌       |  ❌   |   ✅   | Create new tasks with full markdown support                                             |
 | `searchTasks`          |      ✅       |  ✅   |   ✅   | Find tasks by content, keywords, assignees, or project context                          |
@@ -222,13 +224,15 @@ Add the mode to your MCP configuration:
 
 ## Configuration
 
-This MCP server can be configured using environment variables:
+This MCP server can be configured using environment variables. In the desktop extension (`.mcpb`) installer, the API key, team ID, primary language, upload size limit and comment edit window are offered as form fields; the remaining variables have to be set on the server environment directly.
 
 - `CLICKUP_API_KEY`: (Required) Your ClickUp API key.
 - `CLICKUP_TEAM_ID`: (Required) Your ClickUp Team ID (formerly Workspace ID).
 - `CLICKUP_MCP_MODE`: (Optional) Controls which tools are available. Options: `read-minimal`, `read`, `write` (default).
 - `MAX_IMAGES`: (Optional) The maximum number of images to return for a task in `getTaskById`. Defaults to 4.
 - `MAX_RESPONSE_SIZE_MB`: (Optional) The maximum response size in megabytes for `getTaskById`. Uses intelligent size budgeting to fit the most important images within the limit. Defaults to 1.
+- `MAX_UPLOAD_SIZE_MB`: (Optional) The maximum size of a single image uploaded when writing comments or descriptions. Defaults to 10.
+- `CLICKUP_COMMENT_EDIT_WINDOW_HOURS`: (Optional) How long after creation `editComment` may still rewrite a comment. Defaults to 24. Set to `0` to disable comment editing entirely.
 - `CLICKUP_PRIMARY_LANGUAGE`: (Optional) A hint for the primary language used in your ClickUp tasks (e.g., "de" for German, "en" for English). This helps the `searchTask` tool provide more tailored guidance in its description for multilingual searches.
 - `LANG`: (Optional) If `CLICKUP_PRIMARY_LANGUAGE` is not set, the MCP will check this standard environment variable (e.g., "en_US.UTF-8", "de_DE") as a fallback to infer the primary language.
 
@@ -284,6 +288,38 @@ When updating task descriptions, content is safely appended:
 
 This ensures no existing content is ever lost while maintaining a clear audit trail.
 
+## Writing Images Into Tickets
+
+`addComment`, `editComment`, `createTask` and `updateTask` accept images as ordinary markdown. Because
+this server runs locally, it reads the file itself - so a **local path is enough**:
+
+```markdown
+Ist umgesetzt. So sieht es aus:
+
+**1. Login öffnen** – der Kunde gibt nur seine E-Mail-Adresse ein.
+
+![Die Login-Maske fragt nur nach der E-Mail](/Users/me/shots/login.png)
+```
+
+Accepted sources: local file paths, `data:` URIs, http(s) URLs (downloaded, then
+re-uploaded), and existing ClickUp attachment URLs (embedded without re-uploading).
+
+Notes:
+
+- **Prefer paths over base64.** A path costs a few tokens; the same screenshot as a
+  `data:` URI costs roughly 4/3 of its file size in the request.
+- **The caption becomes the attachment filename**, and that filename is what ClickUp
+  displays beneath the image - so write a caption that reads well.
+- **An image inside a numbered list breaks ClickUp's numbering.** Write walkthrough
+  steps as bold lines with the image between them, as above.
+- Only real PNG/JPEG/GIF/WebP files are uploaded - the content is checked, not the
+  extension. A file that fails **aborts the write**: `addComment`, `editComment` and
+  `updateTask` report every broken reference and change nothing, so the markdown can be
+  fixed and the call retried without creating duplicates. `createTask` validates its
+  images before creating the task; only an upload failing afterwards is reported as a
+  warning, since the task already exists at that point.
+- Attachments always belong to a task, so document pages cannot embed uploads this way.
+
 ## Performance & Limitations
 
 **Optimized for AI Workflows:**

package/dist/cli.js

@@ -116,7 +116,9 @@ async function main() {
     // Parse parameters
     for (let i = 1; i < args.length; i++) {
         const arg = args[i];
-        const match = arg.match(/^([^=]+)=(.*)$/);
+        // The `s` flag matters: without it `.` stops at a newline and multi-line values
+        // (markdown descriptions, comments with images) are silently skipped entirely.
+        const match = arg.match(/^([^=]+)=(.*)$/s);
         if (match) {
             const [, key, value] = match;
             // Try to parse as JSON if it looks like a JSON value

package/dist/clickup-text.d.ts

@@ -6,6 +6,9 @@ import { ImageMetadataBlock } from "./shared/types";
 export interface ClickUpTextItem {
     text?: string;
     type?: string;
+    task_mention?: {
+        task_id?: string;
+    };
     image?: {
         id?: string;
         name?: string;
@@ -54,6 +57,7 @@ export interface ClickUpCommentBlock {
     attributes?: {
         bold?: boolean;
         italic?: boolean;
+        strike?: boolean;
         code?: boolean;
         link?: string;
         'code-block'?: {
@@ -67,17 +71,94 @@ export interface ClickUpCommentBlock {
         };
         indent?: number;
         'block-id'?: string;
+        alt?: string;
     };
     list?: {
         list: 'bullet' | 'ordered' | 'unchecked' | 'checked';
     };
+    /**
+     * Present on task mention fragments. ClickUp renders these as live task references
+     * showing the current task name, status and assignee.
+     */
+    task_mention?: {
+        task_id: string;
+    };
+    /**
+     * Present on image fragments. ClickUp only renders a preview when this holds the
+     * complete attachment object from the upload response - a bare URL string produces
+     * an empty placeholder tile.
+     */
+    image?: {
+        id?: string;
+        name?: string;
+        title?: string;
+        extension?: string;
+        url: string;
+        thumbnail_small?: string;
+        thumbnail_medium?: string;
+        thumbnail_large?: string;
+        width?: number;
+        height?: number;
+    };
+}
+/**
+ * Minimal shape needed to embed an already-uploaded attachment as an image fragment
+ */
+export interface EmbeddableAttachment {
+    id?: string;
+    name?: string;
+    title?: string;
+    extension?: string;
+    url: string;
+    thumbnail_small?: string;
+    thumbnail_medium?: string;
+    thumbnail_large?: string;
+    width?: number;
+    height?: number;
+    [key: string]: any;
 }
+/**
+ * Build the image fragment ClickUp needs to render an inline image in a comment.
+ * `title`/`text` carry the caption; the rest is copied straight from the upload response.
+ */
+export declare function buildImageFragment(attachment: EmbeddableAttachment, caption: string): ClickUpCommentBlock;
+/**
+ * Extract the task ID from a ClickUp task URL, or null if it is not one.
+ */
+export declare function parseClickUpTaskUrl(url: string): string | null;
+/**
+ * Wrap image destinations that contain spaces in angle brackets.
+ *
+ * CommonMark rejects a bare destination with spaces, so `![x](/tmp/Screen Shot.png)`
+ * is not an image at all - it would silently stay literal text and never be uploaded.
+ * Screenshot filenames have spaces constantly ("Screenshot 2026-07-27 at 14.30.png"),
+ * so normalising to the `<...>` form is what makes the obvious thing work.
+ */
+export declare function normalizeImageDestinations(markdown: string): string;
+/**
+ * Collect every image reference in a markdown document, in document order.
+ * Callers use this to know what needs uploading before converting.
+ */
+export declare function collectMarkdownImageSources(markdown: string): {
+    src: string;
+    alt: string;
+}[];
+/**
+ * Replace image sources in markdown with their uploaded ClickUp URLs.
+ *
+ * Used for task descriptions: `markdown_description` renders `![alt](url)` directly,
+ * so descriptions need no fragment handling - only the URL has to be swapped.
+ * Images without an upload keep their original source untouched.
+ */
+export declare function rewriteMarkdownImageUrls(markdown: string, attachmentsBySrc: Map<string, EmbeddableAttachment>): string;
 /**
  * Convert markdown text to ClickUp comment blocks format using remark
- * Supports: headers, bold, italic, code, links, lists, blockquotes, code blocks
+ * Supports: headers, bold, italic, code, links, lists, blockquotes, code blocks, images
  *
  * @param markdown The markdown text to convert
+ * @param attachmentsBySrc Uploaded attachments keyed by the markdown `src` they came from.
+ *   Images without an entry degrade to a link so their information is not lost.
  * @returns Array of ClickUp comment blocks
  */
-export declare function convertMarkdownToClickUpBlocks(markdown: string): ClickUpCommentBlock[];
+export declare function convertMarkdownToClickUpBlocks(markdown: string, attachmentsBySrc?: Map<string, EmbeddableAttachment>): ClickUpCommentBlock[];
 //# sourceMappingURL=clickup-text.d.ts.map

package/dist/clickup-text.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clickup-text.d.ts","sourceRoot":"","sources":["../src/clickup-text.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAOpD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE;QACN,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;IACF,UAAU,CAAC,EAAE,GAAG,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AA4BD;;;;;;GAMG;AACH,wBAAsB,uCAAuC,CAC3D,SAAS,EAAE,eAAe,EAAE,GAC3B,OAAO,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,GAAG,kBAAkB,CAAC,EAAE,CAAC,CAsNrE;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,iBAAiB,EAAE,GAAG,IAAI,GAAG,SAAS,GAClD,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,GAAG,kBAAkB,CAAC,EAAE,CA0I5D;AA8BD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE;QACX,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,YAAY,CAAC,EAAE;YACb,YAAY,EAAE,MAAM,CAAC;SACtB,CAAC;QACF,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,EAAE,CAAC;QAChB,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,IAAI,CAAC,EAAE;YACL,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;SACtD,CAAC;QACF,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,IAAI,CAAC,EAAE;QACL,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;KACtD,CAAC;CACH;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAoBtF"}
+{"version":3,"file":"clickup-text.d.ts","sourceRoot":"","sources":["../src/clickup-text.ts"],"names":[],"mappings":"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"}