@hauptsache.net/clickup-mcp 1.5.1 → 1.6.1

package/README.md

@@ -2,6 +2,34 @@
 
 Model Context Protocol (MCP) server enabling AI assistants to interact with ClickUp workspaces. Get complete task context with comments and images, search across projects, create and update tasks, collaborate through comments, and track time - all through natural language.
 
+## This MCP vs Official ClickUp MCP
+
+> See also: [Official ClickUp MCP Documentation](https://developer.clickup.com/docs/connect-an-ai-assistant-to-clickups-mcp-server)
+
+| Feature              | This MCP                                              | Official ClickUp MCP                        |
+|----------------------|-------------------------------------------------------|---------------------------------------------|
+| **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                              |
+| **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                          |
+| **Chat Integration** | Not supported                                         | Supported                                   |
+| **Connected Apps**   | Not supported                                         | Connected Search                            |
+| **Best For**         | Coding tools, automation, context gathering           | Chat apps, task management                  |
+| **Support**          | Community (open source)                               | Official ClickUp                            |
+
+**Choose this MCP when:**
+- You need rich task context with inline images for AI coding tools
+- You need API key authentication for automation or CI/CD pipelines
+- You want the `read-minimal` mode optimized for development workflows
+
+**Choose Official MCP when:**
+- You need OAuth authentication for enterprise security compliance
+- You need Chat integration or Connected Search features
+- You want official support and no local installation
+
 ## What You Can Do
 
 Turn natural language into powerful ClickUp actions:
@@ -155,21 +183,22 @@ The ClickUp MCP supports three operational modes to balance functionality, secur
 - **📖 `read`**: Full read-only access for project exploration and workflow understanding  
 - **✏️ `write`** (Default): Complete functionality for task management and productivity workflows
 
-| Tool              | read-minimal | read | write | Description                                                                             |
-|-------------------|:------------:|:----:|:-----:|-----------------------------------------------------------------------------------------|
-| `getTaskById`     |      ✅       |  ✅   |   ✅   | Get complete task details including comments, images, and metadata                      |
-| `addComment`      |      ❌       |  ❌   |   ✅   | Add comments to tasks for collaboration                                                 |
-| `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                          |
-| `searchSpaces`    |      ❌       |  ✅   |   ✅   | Browse workspace structure, project organization, and documents                         |
-| `getListInfo`     |      ❌       |  ✅   |   ✅   | Get list details and available statuses for task creation                               |
-| `updateListInfo`  |      ❌       |  ❌   |   ✅   | **SAFE APPEND-ONLY** updates to list descriptions (preserves existing content)          |
-| `getTimeEntries`  |      ❌       |  ✅   |   ✅   | View time entries and analyze time spent across projects                                |
-| `createTimeEntry` |      ❌       |  ❌   |   ✅   | Log time entries for task tracking                                                      |
-| `readDocument`    |      ❌       |  ✅   |   ✅   | Get document details, page structure, and content with navigation                       |
-| `searchDocuments` |      ❌       |  ✅   |   ✅   | Search documents by name and space with fuzzy matching and space filtering              |
-| `writeDocument`   |      ❌       |  ❌   |   ✅   | Universal document and page operations with smart document creation                     |
+| Tool                   | read-minimal | read | write | Description                                                                             |
+|------------------------|:------------:|:----:|:-----:|-----------------------------------------------------------------------------------------|
+| `getTaskById`          |      ✅       |  ✅   |   ✅   | Get complete task details including comments, images, and metadata                      |
+| `addComment`           |      ❌       |  ❌   |   ✅   | Add comments to tasks for collaboration                                                 |
+| `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                          |
+| `searchSpaces`         |      ❌       |  ✅   |   ✅   | Browse workspace structure, project organization, and documents                         |
+| `getListInfo`          |      ❌       |  ✅   |   ✅   | Get list details and available statuses for task creation                               |
+| `updateListInfo`       |      ❌       |  ❌   |   ✅   | **SAFE APPEND-ONLY** updates to list descriptions (preserves existing content)          |
+| `getTimeEntries`       |      ❌       |  ✅   |   ✅   | View time entries and analyze time spent across projects                                |
+| `createTimeEntry`      |      ❌       |  ❌   |   ✅   | Log time entries for task tracking                                                      |
+| `readDocument`         |      ❌       |  ✅   |   ✅   | Get document details, page structure, and content with navigation                       |
+| `searchDocuments`      |      ❌       |  ✅   |   ✅   | Search documents by name and space with fuzzy matching and space filtering              |
+| `updateDocumentPage`   |      ❌       |  ❌   |   ✅   | Update existing page content or name with replace/append modes                          |
+| `createDocumentOrPage` |      ❌       |  ❌   |   ✅   | Create new documents with first page, or add pages/sub-pages to existing documents      |
 
 ### Setting the Mode
 

package/dist/clickup-text.d.ts

@@ -37,12 +37,47 @@ export interface ClickUpAttachment {
  * @param textItems Array of text items from ClickUp API
  * @returns Promise resolving to an array of content blocks (text and images)
  */
-export declare function processClickUpText(textItems: ClickUpTextItem[]): Promise<(CallToolResult["content"][number] | ImageMetadataBlock)[]>;
+export declare function convertClickUpTextItemsToToolCallResult(textItems: ClickUpTextItem[]): Promise<(CallToolResult["content"][number] | ImageMetadataBlock)[]>;
 /**
  * Splits markdown text at image references and converts them to image blocks
  * @param markdownText The markdown text to process
  * @param attachments Array of attachments from the Clickup API
  * @returns Array of content blocks (text and images)
  */
-export declare function processClickUpMarkdown(markdownText: string, attachments: ClickUpAttachment[] | null | undefined): (CallToolResult["content"][number] | ImageMetadataBlock)[];
+export declare function convertMarkdownToToolCallResult(markdownText: string, attachments: ClickUpAttachment[] | null | undefined): (CallToolResult["content"][number] | ImageMetadataBlock)[];
+/**
+ * Represents a ClickUp comment block with formatting
+ */
+export interface ClickUpCommentBlock {
+    text?: string;
+    type?: string;
+    attributes?: {
+        bold?: boolean;
+        italic?: boolean;
+        code?: boolean;
+        link?: string;
+        'code-block'?: {
+            'code-block': string;
+        };
+        header?: number;
+        blockquote?: {};
+        'blockquote-size'?: 'large';
+        list?: {
+            list: 'bullet' | 'ordered' | 'unchecked' | 'checked';
+        };
+        indent?: number;
+        'block-id'?: string;
+    };
+    list?: {
+        list: 'bullet' | 'ordered' | 'unchecked' | 'checked';
+    };
+}
+/**
+ * Convert markdown text to ClickUp comment blocks format using remark
+ * Supports: headers, bold, italic, code, links, lists, blockquotes, code blocks
+ *
+ * @param markdown The markdown text to convert
+ * @returns Array of ClickUp comment blocks
+ */
+export declare function convertMarkdownToClickUpBlocks(markdown: string): 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;AAGpD;;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,kBAAkB,CACtC,SAAS,EAAE,eAAe,EAAE,GAC3B,OAAO,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,GAAG,kBAAkB,CAAC,EAAE,CAAC,CAkGrE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,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"}
+{"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"}

package/dist/clickup-text.js

@@ -1,8 +1,15 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.processClickUpText = processClickUpText;
-exports.processClickUpMarkdown = processClickUpMarkdown;
+exports.convertClickUpTextItemsToToolCallResult = convertClickUpTextItemsToToolCallResult;
+exports.convertMarkdownToToolCallResult = convertMarkdownToToolCallResult;
+exports.convertMarkdownToClickUpBlocks = convertMarkdownToClickUpBlocks;
 const data_uri_1 = require("./shared/data-uri");
+const unified_1 = require("unified");
+const remark_parse_1 = __importDefault(require("remark-parse"));
+const remark_gfm_1 = __importDefault(require("remark-gfm"));
 /**
  * Extract thumbnail URLs from data-attachment attribute JSON
  * ClickUp API sometimes has broken thumbnail URLs, but data-attachment contains working ones
@@ -31,9 +38,14 @@ function extractThumbnailsFromDataAttachment(attributes) {
  * @param textItems Array of text items from ClickUp API
  * @returns Promise resolving to an array of content blocks (text and images)
  */
-async function processClickUpText(textItems) {
+async function convertClickUpTextItemsToToolCallResult(textItems) {
     const contentBlocks = [];
     let currentTextBlock = "";
+    let currentLine = ""; // Track current line separately for block formatting
+    // Track current formatting state to avoid unnecessary close/reopen
+    let activeBold = false;
+    let activeItalic = false;
+    let activeCode = false;
     for (let i = 0; i < textItems.length; i++) {
         const item = textItems[i];
         // Handle image items
@@ -100,7 +112,108 @@ async function processClickUpText(textItems) {
         }
         // Handle text items
         else if (typeof item.text === "string") {
-            currentTextBlock += item.text;
+            // Check if this is a newline with block formatting (header, blockquote, list)
+            if (item.text === '\n' && item.attributes) {
+                // Header formatting
+                if (item.attributes.header) {
+                    const level = item.attributes.header;
+                    currentLine = '#'.repeat(level) + ' ' + currentLine;
+                }
+                // Blockquote formatting
+                else if (item.attributes.blockquote) {
+                    currentLine = '> ' + currentLine;
+                }
+                // List formatting
+                else if (item.attributes.list) {
+                    const listType = item.attributes.list.list;
+                    const indent = item.attributes.indent || 0;
+                    // Add indentation (2 spaces per level) for nested lists
+                    const indentStr = '  '.repeat(indent);
+                    switch (listType) {
+                        case 'bullet':
+                            currentLine = indentStr + '- ' + currentLine;
+                            break;
+                        case 'ordered':
+                            currentLine = indentStr + '1. ' + currentLine;
+                            break;
+                        case 'checked':
+                            currentLine = indentStr + '- [x] ' + currentLine;
+                            break;
+                        case 'unchecked':
+                            currentLine = indentStr + '- [ ] ' + currentLine;
+                            break;
+                    }
+                }
+                // Code block formatting
+                else if (item.attributes['code-block']) {
+                    // Wrap the current line in code block markers
+                    currentLine = '```\n' + currentLine + '\n```';
+                }
+                // Add formatted line to text block
+                currentTextBlock += currentLine;
+                // Add newline unless it's code block (already has newlines)
+                if (!item.attributes['code-block']) {
+                    currentTextBlock += '\n';
+                }
+                currentLine = ""; // Reset for next line
+                continue;
+            }
+            // Regular text with inline formatting
+            let formattedText = item.text;
+            // Determine current and next formatting state
+            const hasBold = item.attributes?.bold === true;
+            const hasItalic = item.attributes?.italic === true;
+            const hasLink = item.attributes?.link;
+            // Look ahead to next non-newline block
+            let nextHasBold = false;
+            let nextHasItalic = false;
+            for (let j = i + 1; j < textItems.length; j++) {
+                const nextItem = textItems[j];
+                if (nextItem.text !== '\n' || !nextItem.attributes) {
+                    nextHasBold = nextItem.attributes?.bold === true;
+                    nextHasItalic = nextItem.attributes?.italic === true;
+                    break;
+                }
+            }
+            // Build prefix (open new formatting)
+            let prefix = "";
+            if (hasBold && !activeBold)
+                prefix += "**";
+            if (hasItalic && !activeItalic)
+                prefix += "*";
+            // Build suffix (close formatting that won't continue)
+            let suffix = "";
+            if (hasItalic && !nextHasItalic)
+                suffix += "*";
+            if (hasBold && !nextHasBold)
+                suffix += "**";
+            // Close formatting that's active but not in this block
+            let closingPrefix = "";
+            if (activeBold && !hasBold)
+                closingPrefix += "**";
+            if (activeItalic && !hasItalic)
+                closingPrefix += "*";
+            formattedText = closingPrefix + prefix + formattedText + suffix;
+            // Update state
+            activeBold = hasBold && nextHasBold;
+            activeItalic = hasItalic && nextHasItalic;
+            // Link formatting (wraps everything)
+            if (hasLink) {
+                formattedText = `[${formattedText}](${hasLink})`;
+            }
+            // Code formatting
+            if (item.attributes?.code) {
+                formattedText = `\`${formattedText}\``;
+            }
+            // Add to current line (not text block yet)
+            if (item.text === '\n') {
+                // Plain newline without formatting
+                currentTextBlock += currentLine + '\n';
+                currentLine = "";
+            }
+            else {
+                currentLine += formattedText;
+            }
         }
         // Handle other types of items like bookmarks or whatever clickup can think of
         else {
@@ -108,6 +221,9 @@ async function processClickUpText(textItems) {
         }
     }
     // Add any remaining text
+    if (currentLine) {
+        currentTextBlock += currentLine;
+    }
     if (currentTextBlock.trim()) {
         contentBlocks.push({
             type: "text",
@@ -122,7 +238,7 @@ async function processClickUpText(textItems) {
  * @param attachments Array of attachments from the Clickup API
  * @returns Array of content blocks (text and images)
  */
-function processClickUpMarkdown(markdownText, attachments) {
+function convertMarkdownToToolCallResult(markdownText, attachments) {
     const contentBlocks = [];
     let currentTextBlock = "";
     // Create a map of attachment URLs to their full info for easy lookup
@@ -264,3 +380,184 @@ function extractFileTypeFromUrl(url) {
         return null;
     return filename.substring(lastDot + 1);
 }
+/**
+ * Convert markdown text to ClickUp comment blocks format using remark
+ * Supports: headers, bold, italic, code, links, lists, blockquotes, code blocks
+ *
+ * @param markdown The markdown text to convert
+ * @returns Array of ClickUp comment blocks
+ */
+function convertMarkdownToClickUpBlocks(markdown) {
+    const blocks = [];
+    try {
+        // Parse the entire markdown document using remark with GFM support (for task lists)
+        const tree = (0, unified_1.unified)()
+            .use(remark_parse_1.default)
+            .use(remark_gfm_1.default)
+            .parse(markdown);
+        // Walk the tree recursively
+        walkMdastNodes(tree.children, {}, blocks);
+    }
+    catch (error) {
+        console.error('Failed to parse markdown:', error);
+        // Fallback to plain text
+        return [{ text: markdown, attributes: {} }];
+    }
+    return blocks;
+}
+/**
+ * Recursively walk mdast nodes and convert to ClickUp blocks
+ * @param nodes Array of mdast nodes to process
+ * @param inheritedAttrs Formatting attributes inherited from parent nodes
+ * @param blocks Output array to append ClickUp blocks to
+ * @param depth Nesting depth for lists (0 = top level, 1 = first nest, etc.)
+ */
+function walkMdastNodes(nodes, inheritedAttrs, blocks, depth = 0) {
+    for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i];
+        const currentAttrs = { ...inheritedAttrs };
+        switch (node.type) {
+            case 'heading':
+                // Process heading content with inline formatting
+                walkPhrasingContent(node.children, currentAttrs, blocks);
+                // Add newline with header attribute
+                blocks.push({ text: '\n', attributes: { header: node.depth } });
+                break;
+            case 'paragraph':
+                // Process paragraph content with inline formatting
+                walkPhrasingContent(node.children, currentAttrs, blocks);
+                // Add newline unless it's the last node
+                if (i < nodes.length - 1) {
+                    blocks.push({ text: '\n', attributes: {} });
+                }
+                break;
+            case 'blockquote':
+                // ClickUp limitation: Blockquotes only support paragraph content, not headers or lists
+                // For complex blockquote content (headers, lists), only paragraph text is preserved
+                const blockquoteChildren = node.children;
+                for (const child of blockquoteChildren) {
+                    if (child.type === 'paragraph') {
+                        walkPhrasingContent(child.children, currentAttrs, blocks);
+                        blocks.push({ text: '\n', attributes: { blockquote: {} } });
+                    }
+                    // Note: Other child types (heading, list) are not supported by ClickUp blockquotes
+                    // and will be silently skipped, preserving only inline paragraph content
+                }
+                break;
+            case 'list':
+                const listNode = node;
+                const listType = listNode.ordered ? 'ordered' : 'bullet';
+                for (const item of listNode.children) {
+                    const listItem = item;
+                    // Check if it's a checkbox item
+                    const isChecked = listItem.checked === true;
+                    const isUnchecked = listItem.checked === false;
+                    const finalListType = isChecked ? 'checked' : isUnchecked ? 'unchecked' : listType;
+                    // Process list item content
+                    for (const itemChild of listItem.children) {
+                        if (itemChild.type === 'paragraph') {
+                            // Process paragraph content with inline formatting
+                            walkPhrasingContent(itemChild.children, currentAttrs, blocks);
+                            // Add newline with list formatting and optional indent
+                            const listAttrs = {
+                                list: { list: finalListType }
+                            };
+                            // Add indent for nested lists (depth 0 = no indent, depth 1+ = indented)
+                            if (depth > 0) {
+                                listAttrs.indent = depth;
+                            }
+                            blocks.push({ text: '\n', attributes: listAttrs });
+                        }
+                        else if (itemChild.type === 'list') {
+                            // Nested list - recursively process with increased depth
+                            walkMdastNodes([itemChild], currentAttrs, blocks, depth + 1);
+                        }
+                    }
+                }
+                break;
+            case 'code':
+                // Code block
+                const codeNode = node;
+                if (codeNode.value) {
+                    blocks.push({ text: codeNode.value, attributes: {} });
+                    blocks.push({
+                        text: '\n',
+                        attributes: { 'code-block': { 'code-block': codeNode.lang || 'plain' } }
+                    });
+                }
+                break;
+            case 'thematicBreak':
+                // Horizontal rule - just add a line break
+                blocks.push({ text: '\n', attributes: {} });
+                break;
+            default:
+                // For any other block-level nodes, try to process children
+                if ('children' in node && Array.isArray(node.children)) {
+                    walkMdastNodes(node.children, currentAttrs, blocks, depth);
+                }
+                break;
+        }
+    }
+}
+/**
+ * Recursively walk phrasing content (inline nodes) and build ClickUp blocks
+ * Accumulates formatting attributes from parent nodes
+ */
+function walkPhrasingContent(nodes, inheritedAttrs, blocks) {
+    for (const node of nodes) {
+        const currentAttrs = { ...inheritedAttrs };
+        switch (node.type) {
+            case 'text':
+                // Plain text node
+                if (node.value) {
+                    blocks.push({
+                        text: node.value,
+                        attributes: Object.keys(currentAttrs).length > 0 ? currentAttrs : {}
+                    });
+                }
+                break;
+            case 'strong':
+                // Bold text - recurse with bold attribute
+                currentAttrs.bold = true;
+                walkPhrasingContent(node.children, currentAttrs, blocks);
+                break;
+            case 'emphasis':
+                // Italic text - recurse with italic attribute
+                currentAttrs.italic = true;
+                walkPhrasingContent(node.children, currentAttrs, blocks);
+                break;
+            case 'inlineCode':
+                // Inline code
+                if (node.value) {
+                    currentAttrs.code = true;
+                    blocks.push({
+                        text: node.value,
+                        attributes: currentAttrs
+                    });
+                }
+                break;
+            case 'link':
+                // Link - recurse with link attribute
+                currentAttrs.link = node.url;
+                walkPhrasingContent(node.children, currentAttrs, blocks);
+                break;
+            case 'break':
+                // Line break - add as plain text
+                blocks.push({ text: '\n', attributes: {} });
+                break;
+            default:
+                // For any other node types, try to extract text if available
+                if ('value' in node && typeof node.value === 'string') {
+                    blocks.push({
+                        text: node.value,
+                        attributes: Object.keys(currentAttrs).length > 0 ? currentAttrs : {}
+                    });
+                }
+                else if ('children' in node && Array.isArray(node.children)) {
+                    // Recurse into children for other container nodes
+                    walkPhrasingContent(node.children, currentAttrs, blocks);
+                }
+                break;
+        }
+    }
+}

package/dist/shared/image-processing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image-processing.d.ts","sourceRoot":"","sources":["../../src/shared/image-processing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAE,kBAAkB,EAAC,MAAM,SAAS,CAAC;AAKzD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,CAAC,YAAY,GAAG,kBAAkB,CAAC,EAAE,EAAE,SAAS,GAAE,MAAyB,EAAE,SAAS,GAAE,MAAiC,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CA0BhM"}
+{"version":3,"file":"image-processing.d.ts","sourceRoot":"","sources":["../../src/shared/image-processing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAE,kBAAkB,EAAC,MAAM,SAAS,CAAC;AAmDzD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,CAAC,YAAY,GAAG,kBAAkB,CAAC,EAAE,EAAE,SAAS,GAAE,MAAyB,EAAE,SAAS,GAAE,MAAiC,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CA0BhM"}

package/dist/shared/image-processing.js

@@ -4,6 +4,46 @@ exports.downloadImages = downloadImages;
 const config_1 = require("./config");
 const data_uri_1 = require("./data-uri");
 const buffer_1 = require("buffer");
+/**
+ * Detect MIME type from image binary data using magic bytes (file signatures)
+ * Returns null if the format is not recognized
+ */
+function detectMimeTypeFromBuffer(buffer) {
+    const bytes = new Uint8Array(buffer);
+    if (bytes.length < 12)
+        return null;
+    // PNG: 89 50 4E 47 (‰PNG)
+    if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4E && bytes[3] === 0x47) {
+        return "image/png";
+    }
+    // JPEG: FF D8 FF
+    if (bytes[0] === 0xFF && bytes[1] === 0xD8 && bytes[2] === 0xFF) {
+        return "image/jpeg";
+    }
+    // GIF: 47 49 46 38 (GIF8)
+    if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x38) {
+        return "image/gif";
+    }
+    // WebP: RIFF....WEBP
+    if (bytes[0] === 0x52 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x46 &&
+        bytes[8] === 0x57 && bytes[9] === 0x45 && bytes[10] === 0x42 && bytes[11] === 0x50) {
+        return "image/webp";
+    }
+    return null;
+}
+/**
+ * Detect MIME type from base64-encoded image data
+ * Decodes just enough bytes to check magic numbers
+ */
+function detectMimeTypeFromBase64(base64Data) {
+    // Need at least 16 base64 chars to decode 12 bytes for magic number detection
+    if (base64Data.length < 16)
+        return null;
+    // Create a Uint8Array directly from the decoded bytes to avoid Buffer pooling issues
+    const header = buffer_1.Buffer.from(base64Data.slice(0, 16), "base64");
+    const bytes = new Uint8Array(header);
+    return detectMimeTypeFromBuffer(bytes.buffer);
+}
 /**
  * Downloads images from image_metadata blocks and applies smart size/count limiting
  * Prioritizes keeping the most recent images (assumes content is ordered with newest items last)
@@ -98,9 +138,12 @@ async function downloadSingleImage(imageMetadata, perImageBudget) {
             const actualSizeBytes = imageBuffer.byteLength;
             // Double-check actual size (in case Content-Length was missing or incorrect)
             if (actualSizeBytes <= perImageBudget) {
+                // Detect actual MIME type from binary data, fall back to header or default
+                const detectedMimeType = detectMimeTypeFromBuffer(imageBuffer);
+                const mimeType = detectedMimeType || response.headers.get("Content-Type") || "image/png";
                 return {
                     type: "image",
-                    mimeType: response.headers.get("Content-Type") || "image/png",
+                    mimeType,
                     data: buffer_1.Buffer.from(imageBuffer).toString("base64"),
                 };
             }
@@ -145,9 +188,12 @@ function convertInlineImage(imageMetadata, perImageBudget) {
         console.error(`Inline image for "${imageMetadata.alt}" is ${estimatedSize} bytes, exceeds budget of ${perImageBudget} bytes`);
         return createImageFallback(imageMetadata);
     }
+    // Detect actual MIME type from binary data, fall back to declared type or default
+    const detectedMimeType = detectMimeTypeFromBase64(inlineData.base64Data);
+    const mimeType = detectedMimeType || inlineData.mimeType || "image/png";
     return {
         type: "image",
-        mimeType: inlineData.mimeType || "image/png",
+        mimeType,
         data: inlineData.base64Data,
     };
 }

package/dist/tools/task-tools.js

@@ -93,7 +93,7 @@ async function loadTaskContent(taskId) {
             return await generateTaskMetadata(task, timeEntries, true);
         })(),
         // process markdown and download images
-        (0, clickup_text_1.processClickUpMarkdown)(task.markdown_description || "", task.attachments || []),
+        (0, clickup_text_1.convertMarkdownToToolCallResult)(task.markdown_description || "", task.attachments || []),
     ]);
     return [taskMetadata, ...content];
 }
@@ -114,7 +114,7 @@ async function loadTaskComments(id) {
             type: "text",
             text: `Comment by ${comment.user.username} on ${timestampToIso(comment.date)}:`,
         };
-        const commentBodyBlocks = await (0, clickup_text_1.processClickUpText)(comment.comment);
+        const commentBodyBlocks = await (0, clickup_text_1.convertClickUpTextItemsToToolCallResult)(comment.comment);
         return {
             date: comment.date, // String timestamp from ClickUp for sorting
             contentBlocks: [headerBlock, ...commentBodyBlocks],

package/dist/tools/task-write-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-write-tools.d.ts","sourceRoot":"","sources":["../../src/tools/task-write-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAapE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QAmZtE"}
+{"version":3,"file":"task-write-tools.d.ts","sourceRoot":"","sources":["../../src/tools/task-write-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAcpE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QAsZtE"}

package/dist/tools/task-write-tools.js

@@ -4,6 +4,7 @@ exports.registerTaskToolsWrite = registerTaskToolsWrite;
 const zod_1 = require("zod");
 const config_1 = require("../shared/config");
 const utils_1 = require("../shared/utils");
+const clickup_text_1 = require("../clickup-text");
 // Shared schemas for task parameters
 const taskNameSchema = zod_1.z.string().min(1).describe("The name/title of the task");
 const taskPrioritySchema = zod_1.z.enum(["urgent", "high", "normal", "low"]).optional().describe("Optional priority level");
@@ -36,8 +37,10 @@ function registerTaskToolsWrite(server, userData) {
         idempotentHint: false,
     }, async ({ task_id, comment }) => {
         try {
+            // Convert markdown to ClickUp formatted blocks
+            const commentBlocks = (0, clickup_text_1.convertMarkdownToClickUpBlocks)(comment);
             const requestBody = {
-                comment_text: comment,
+                comment: commentBlocks,
                 notify_all: true
             };
             const response = await fetch(`https://api.clickup.com/api/v2/task/${task_id}/comment`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hauptsache.net/clickup-mcp",
-  "version": "1.5.1",
+  "version": "1.6.1",
   "description": "Search, create, and retrieve tasks, add comments, and track time through natural language commands.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -40,12 +40,16 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.15.1",
+    "@modelcontextprotocol/sdk": "1.15.1",
     "fuse.js": "^7.1.0",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5",
     "zod": "^3.24.2"
   },
   "devDependencies": {
     "@anthropic-ai/mcpb": "^1.1.1",
+    "@types/mdast": "^4.0.4",
     "@types/node": "^22.14.1",
     "dotenv": "^16.5.0",
     "nodemon": "^3.1.9",