@crypto512/jicon-mcp 1.2.0 → 1.3.0

package/dist/confluence/tools.js

@@ -2,7 +2,7 @@
  * Confluence MCP Tools
  */
 import { z } from "zod";
-import { formatSuccess, formatError, isApiError } from "../utils/response-formatter.js";
+import { formatSuccess, formatSuccessBuffered, formatError, isApiError } from "../utils/response-formatter.js";
 import { contentBuffer } from "../utils/content-buffer.js";
 import { formatPageMetadata } from "./formatters.js";
 import { validateXhtmlAsync, parseXhtml, parseStructure, serializeXhtml, enhanceXhtmlError } from "../utils/xhtml/index.js";
@@ -46,72 +46,17 @@ function getContentSummary(content) {
     result.headingCount = doc.querySelectorAll('h1, h2, h3, h4, h5, h6').length;
     return result;
 }
-/**
- * Resolve content from either direct content string or bufferId.
- * Returns { content, error } - if error is set, return it as the tool result.
- */
-function resolveContentFromBuffer(contentArg, bufferIdArg) {
-    // Exactly one of content or bufferId must be provided
-    if (contentArg && bufferIdArg) {
-        return {
-            error: formatError({
-                error: true,
-                message: "Provide either 'content' or 'bufferId', not both",
-                statusCode: 400,
-            }),
-        };
-    }
-    if (bufferIdArg) {
-        const bufferChunk = contentBuffer.getChunk(bufferIdArg);
-        if (!bufferChunk) {
-            return {
-                error: formatError({
-                    error: true,
-                    message: `Buffer ${bufferIdArg} not found or expired`,
-                    statusCode: 404,
-                }),
-            };
-        }
-        // Validate that buffer contains XHTML content for Confluence
-        const bufferInfo = contentBuffer.getInfo(bufferIdArg);
-        if (bufferInfo?.metadata?.contentType && bufferInfo.metadata.contentType !== "xhtml") {
-            return {
-                error: formatError({
-                    error: true,
-                    message: `Buffer ${bufferIdArg} contains ${bufferInfo.metadata.contentType} content, but Confluence requires XHTML.`,
-                    statusCode: 400,
-                    details: {
-                        hint: "Create Confluence content with buffer_create, then edit with buffer_edit.",
-                        foundContentType: bufferInfo.metadata.contentType,
-                        expectedContentType: "xhtml",
-                    },
-                }),
-            };
-        }
-        // Get full content from buffer
-        const fullContent = contentBuffer.getChunk(bufferIdArg, 0, bufferChunk.totalSize);
-        if (!fullContent) {
-            return {
-                error: formatError({
-                    error: true,
-                    message: "Failed to retrieve full buffer content",
-                    statusCode: 500,
-                }),
-            };
-        }
-        return { content: fullContent.chunk };
-    }
-    // Direct content provided
-    return { content: contentArg };
-}
 /**
  * Validate XHTML content before Confluence write operations.
  * Returns error result if validation fails, null if valid.
+ * When bufferId is provided, includes it in error response for recovery.
  */
-async function validateContentForWrite(content) {
+async function validateContentForWrite(content, bufferId) {
     const validation = await validateXhtmlAsync(content, { validatePlantUml: true });
     if (!validation.valid) {
         const errorMessages = [];
+        let errorElementId;
+        let errorContext;
         // XHTML structure errors
         if (validation.errors && validation.errors.length > 0) {
             errorMessages.push("XHTML validation errors:");
@@ -124,6 +69,14 @@ async function validateContentForWrite(content) {
                         ? err.location.context.substring(0, 60) + "..."
                         : err.location.context;
                     errorMessages.push(`    Near: "${contextPreview}"`);
+                    // Capture first error context for recovery
+                    if (!errorContext) {
+                        errorContext = err.location.context;
+                    }
+                }
+                // Capture first error elementId for recovery
+                if (!errorElementId && err.location?.elementId) {
+                    errorElementId = err.location.elementId;
                 }
             });
         }
@@ -151,10 +104,18 @@ async function validateContentForWrite(content) {
                 errorMessages.push("  </ac:structured-macro>");
             }
         }
-        // Add help hints
+        // Add recovery instructions
         errorMessages.push("");
-        errorMessages.push('TIP: Call help(topic="storage") for Confluence XHTML format guide.');
-        errorMessages.push('TIP: Call help(topic="plantuml") for PlantUML macro examples.');
+        if (bufferId) {
+            errorMessages.push(`RECOVERY: Use buffer_edit(bufferId="${bufferId}", ...) to fix errors.`);
+            if (errorElementId) {
+                errorMessages.push(`  buffer_edit(bufferId="${bufferId}", replace=${errorElementId}, content="<fixed>...</fixed>")`);
+            }
+            else if (errorContext) {
+                errorMessages.push(`  Use buffer_grep(bufferId="${bufferId}", pattern="...") to find the error location.`);
+            }
+        }
+        errorMessages.push('TIP: Call help(topic="storage") for XHTML syntax (HTML vs XHTML differences).');
         errorMessages.push("");
         errorMessages.push("ACTION REQUIRED: Fix content errors before calling this tool again.");
         errorMessages.push("DO NOT claim success - the draft was NOT created.");
@@ -164,7 +125,12 @@ async function validateContentForWrite(content) {
             statusCode: 400,
             details: {
                 validationErrors: errorMessages,
-                hint: "Use buffer_validate_xhtml to check content, or plantuml_validate for PlantUML syntax",
+                ...(bufferId && { bufferId }),
+                ...(errorElementId && { errorElementId }),
+                ...(errorContext && { errorContext }),
+                hint: errorElementId
+                    ? `Use buffer_edit(bufferId="${bufferId}", replace=${errorElementId}, content="...") to fix`
+                    : `Use buffer_grep to find the error, then buffer_edit to fix`,
             },
         });
     }
@@ -185,7 +151,9 @@ function storeXhtmlWithStructure(content, metadata) {
 export function createConfluenceTools(client) {
     return {
         confluence_search_content: {
-            description: `Search Confluence content using CQL. Auto-fetches all results (up to 5000).
+            description: `Search Confluence content using CQL. Auto-fetches all results.
+
+Returns bufferId. Use buffer_get_chunk to read, buffer_grep to search.
 
 TIP: See help(topic="cql") for CQL syntax guide.
 
@@ -199,8 +167,10 @@ WARNING: Use text~ (not content~ or body~). Use space KEY (not name).`,
             handler: async (args) => {
                 try {
                     const result = await client.searchContentAll(args.cql, args.expand);
-                    // Use formatSuccess for automatic buffering of large responses
-                    return formatSuccess(result);
+                    return formatSuccessBuffered(result, {
+                        resourceType: "confluence_search",
+                        title: `CQL: ${args.cql.substring(0, 100)}${args.cql.length > 100 ? "..." : ""}`,
+                    });
                 }
                 catch (error) {
                     // Enhanced error handling for common CQL errors
@@ -561,7 +531,9 @@ WORKFLOW:
             },
         },
         confluence_list_spaces: {
-            description: `List all accessible Confluence spaces.`,
+            description: `List all accessible Confluence spaces.
+
+Returns bufferId. Use buffer_get_chunk to read, buffer_grep to search.`,
             inputSchema: z.object({
                 type: z
                     .enum(["global", "personal"])
@@ -571,7 +543,10 @@ WORKFLOW:
             handler: async (args) => {
                 try {
                     const result = await client.listSpaces(args.type);
-                    return formatSuccess(result);
+                    return formatSuccessBuffered(result, {
+                        resourceType: "confluence_spaces",
+                        title: args.type ? `${args.type} spaces` : "All Spaces",
+                    });
                 }
                 catch (error) {
                     return formatError(isApiError(error) ? error : new Error(String(error)));
@@ -579,7 +554,9 @@ WORKFLOW:
             },
         },
         confluence_get_space: {
-            description: "Get detailed information about a space",
+            description: `Get detailed information about a space.
+
+Returns bufferId. Use buffer_get_chunk to read, buffer_grep to search.`,
             inputSchema: z.object({
                 spaceKey: z.string().describe("Space key"),
                 expand: z.array(z.string()).optional().describe("Additional data to expand"),
@@ -587,8 +564,11 @@ WORKFLOW:
             handler: async (args) => {
                 try {
                     const result = await client.getSpace(args.spaceKey, args.expand);
-                    // Use formatSuccess for automatic buffering of large responses
-                    return formatSuccess(result);
+                    return formatSuccessBuffered(result, {
+                        resourceType: "confluence_space",
+                        title: result.name || args.spaceKey,
+                        spaceKey: args.spaceKey,
+                    });
                 }
                 catch (error) {
                     return formatError(isApiError(error) ? error : new Error(String(error)));
@@ -596,7 +576,9 @@ WORKFLOW:
             },
         },
         confluence_get_page_children: {
-            description: `Get all child pages of a page.`,
+            description: `Get all child pages of a page.
+
+Returns bufferId. Use buffer_get_chunk to read, buffer_grep to search.`,
             inputSchema: z.object({
                 pageId: z.coerce.string().describe("Parent page ID (accepts string or number)"),
                 expand: z.array(z.string()).optional().describe("Additional data to expand"),
@@ -604,7 +586,11 @@ WORKFLOW:
             handler: async (args) => {
                 try {
                     const result = await client.getPageChildren(args.pageId, args.expand);
-                    return formatSuccess(result);
+                    return formatSuccessBuffered(result, {
+                        resourceType: "confluence_page_children",
+                        title: `Page ${args.pageId} children`,
+                        pageId: args.pageId,
+                    });
                 }
                 catch (error) {
                     return formatError(isApiError(error) ? error : new Error(String(error)));
@@ -628,14 +614,20 @@ WORKFLOW:
             },
         },
         confluence_get_comments: {
-            description: `Get all comments on a Confluence page.`,
+            description: `Get all comments on a Confluence page.
+
+Returns bufferId. Use buffer_get_chunk to read, buffer_grep to search.`,
             inputSchema: z.object({
                 pageId: z.coerce.string().describe("Page ID (accepts string or number)"),
             }),
             handler: async (args) => {
                 try {
                     const result = await client.getComments(args.pageId);
-                    return formatSuccess(result);
+                    return formatSuccessBuffered(result, {
+                        resourceType: "confluence_comments",
+                        title: `Page ${args.pageId} comments`,
+                        pageId: args.pageId,
+                    });
                 }
                 catch (error) {
                     return formatError(isApiError(error) ? error : new Error(String(error)));
@@ -660,14 +652,20 @@ WORKFLOW:
             },
         },
         confluence_list_attachments: {
-            description: `List all attachments on a Confluence page.`,
+            description: `List all attachments on a Confluence page.
+
+Returns bufferId. Use buffer_get_chunk to read, buffer_grep to search.`,
             inputSchema: z.object({
                 pageId: z.coerce.string().describe("Page ID (accepts string or number)"),
             }),
             handler: async (args) => {
                 try {
                     const result = await client.listAttachments(args.pageId);
-                    return formatSuccess(result);
+                    return formatSuccessBuffered(result, {
+                        resourceType: "confluence_attachments",
+                        title: `Page ${args.pageId} attachments`,
+                        pageId: args.pageId,
+                    });
                 }
                 catch (error) {
                     return formatError(isApiError(error) ? error : new Error(String(error)));
@@ -716,37 +714,31 @@ Returns the user's personal space key and details. Use this to verify your perso
         confluence_draft_create: {
             description: `Create a Confluence draft for user review. Returns draftId, bufferId, structure (element IDs), and clickable URL.
 
-IMPORTANT: Call help(topic="plantuml") BEFORE creating content with PlantUML diagrams.
-IMPORTANT: Call help(topic="storage") BEFORE creating XHTML content for proper syntax.
-IMPORTANT: User must validate the draft in Confluence UI before publishing.
-IMPORTANT: Raw @startuml outside macros is NOT supported. Use buffer_edit with plantuml parameter.
+REQUIRES bufferId - content must be in a buffer for validation and error recovery.
 
-Two modes:
-1. NEW PAGE: Provide spaceKey + title + content/bufferId → creates standalone draft
-2. EDIT EXISTING PAGE (Review Workflow): Provide pageId + bufferId
-   - Creates "[jicon-mcp REVIEW] Title" draft linked to original via label
-   - REQUIRED: bufferId must come from confluence_get_page(pageId) or confluence_edit(pageId)
-   - Use confluence_review_publish(draftId) to apply changes to original
-   - Use confluence_review_discard(draftId) to cancel without changes
-   - Use confluence_review_list() to find all review drafts
+Workflow for NEW page:
+1. buffer_create(content="<h1>Title</h1><p>Content</p>", contentType="xhtml") → bufferId, structure
+2. buffer_validate_xhtml(bufferId) → check for errors, get elementId if invalid
+3. buffer_edit(bufferId, replace=elementId, content="...") → fix errors if any
+4. confluence_draft_create(spaceKey, title, bufferId) → creates draft for review
 
-Workflow for editing existing page:
-1. confluence_get_page(pageId) → bufferId, structure
-2. buffer_edit(bufferId, ...) → modify content
-3. confluence_draft_create(pageId=..., bufferId=...) → creates review draft
-4. User reviews in Confluence UI
-5. confluence_review_publish(draftId) → applies changes to original page
+Workflow for EDITING existing page:
+1. confluence_get_page(pageId) or confluence_edit(input) → bufferId, structure
+2. buffer_edit(bufferId, after=ID, content/plantuml) → modify content
+3. buffer_validate_xhtml(bufferId) → check for errors
+4. confluence_draft_create(pageId, bufferId) → creates "[jicon-mcp REVIEW] Title" draft
+5. User reviews in Confluence UI
+6. confluence_review_publish(draftId) → applies changes to original page
 
-Provide either 'content' (string) OR 'bufferId' (from buffer_create/buffer_edit).`,
+On validation error: returns bufferId + errorElementId for surgical fix with buffer_edit.
+
+IMPORTANT: Call help(topic="storage") for XHTML syntax (HTML vs XHTML differences).
+IMPORTANT: Call help(topic="plantuml") for diagram syntax.`,
             inputSchema: z.object({
                 pageId: z.coerce.string().optional().describe("Existing page ID to create edit draft for. When provided, bufferId must come from that page."),
                 spaceKey: z.string().optional().describe("Space key (required for new pages, auto-populated when pageId is provided)"),
                 title: z.string().optional().describe("Page title (required for new pages, auto-populated when pageId is provided)"),
-                content: z
-                    .string()
-                    .optional()
-                    .describe("Page content in Confluence storage format (XHTML-based)"),
-                bufferId: z.string().optional().describe("Buffer ID containing content (alternative to content)"),
+                bufferId: z.string().describe("Buffer ID containing XHTML content (from buffer_create or confluence_get_page)"),
                 parentId: z.string().optional().describe("Parent page ID"),
                 labels: z.array(z.string()).optional().describe("Array of labels"),
             }),
@@ -757,27 +749,41 @@ Provide either 'content' (string) OR 'bufferId' (from buffer_create/buffer_edit)
                 let parentId = args.parentId;
                 let originalPageId;
                 let originalPageVersion;
+                // Validate buffer exists and get content
+                const bufferInfo = contentBuffer.getInfo(args.bufferId);
+                if (!bufferInfo) {
+                    return formatError({
+                        error: true,
+                        message: `Buffer not found or expired: ${args.bufferId}`,
+                        statusCode: 404,
+                        details: {
+                            hint: "Create a buffer first: buffer_create(content='<h1>...</h1>', contentType='xhtml')",
+                        },
+                    });
+                }
+                // Validate buffer contains XHTML content
+                if (bufferInfo.metadata?.contentType && bufferInfo.metadata.contentType !== "xhtml") {
+                    return formatError({
+                        error: true,
+                        message: `Buffer '${args.bufferId}' is not XHTML content (found: ${bufferInfo.metadata.contentType})`,
+                        statusCode: 400,
+                        details: {
+                            hint: "Use buffer_create(content='...', contentType='xhtml') to create an XHTML buffer",
+                        },
+                    });
+                }
+                // Get full content from buffer
+                const fullContent = contentBuffer.getChunk(args.bufferId, 0, bufferInfo.totalSize);
+                if (!fullContent) {
+                    return formatError({
+                        error: true,
+                        message: "Failed to retrieve buffer content",
+                        statusCode: 500,
+                    });
+                }
+                const content = fullContent.chunk;
                 if (args.pageId) {
                     // MODE: Edit existing page - validate bufferId came from this page
-                    if (!args.bufferId) {
-                        return formatError({
-                            error: true,
-                            message: "When pageId is provided, bufferId is required (must come from confluence_get_page or confluence_edit of that page)",
-                            statusCode: 400,
-                            details: {
-                                hint: "First call confluence_get_page(pageId) or confluence_edit(pageId) to get a bufferId, then modify with buffer_edit",
-                            },
-                        });
-                    }
-                    // Validate buffer originated from the specified page
-                    const bufferInfo = contentBuffer.getInfo(args.bufferId);
-                    if (!bufferInfo) {
-                        return formatError({
-                            error: true,
-                            message: `Buffer not found or expired: ${args.bufferId}`,
-                            statusCode: 404,
-                        });
-                    }
                     const bufferSourceId = bufferInfo.metadata?.resourceId;
                     if (bufferSourceId !== args.pageId) {
                         return formatError({
@@ -828,19 +834,6 @@ Provide either 'content' (string) OR 'bufferId' (from buffer_create/buffer_edit)
                         });
                     }
                 }
-                // Resolve content from either content string or bufferId
-                const resolved = resolveContentFromBuffer(args.content, args.bufferId);
-                if (resolved.error) {
-                    return resolved.error;
-                }
-                if (!resolved.content) {
-                    return formatError({
-                        error: true,
-                        message: "Either 'content' or 'bufferId' must be provided",
-                        statusCode: 400,
-                    });
-                }
-                const content = resolved.content;
                 // Check for raw PlantUML that should use buffer_edit with plantuml parameter
                 const rawPlantUml = detectRawPlantUml(content);
                 if (rawPlantUml) {
@@ -855,7 +848,7 @@ Provide either 'content' (string) OR 'bufferId' (from buffer_create/buffer_edit)
                     });
                 }
                 // Validate XHTML and PlantUML content before writing
-                const validationError = await validateContentForWrite(content);
+                const validationError = await validateContentForWrite(content, args.bufferId);
                 if (validationError) {
                     return validationError;
                 }
@@ -1041,14 +1034,15 @@ Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to modify, th
             },
         },
         confluence_draft_list: {
-            description: `List your draft pages. Use confluence_draft_open to load a draft for editing.`,
+            description: `List your draft pages. Use confluence_draft_open to load a draft for editing.
+
+Returns bufferId. Use buffer_get_chunk to read, buffer_grep to search.`,
             inputSchema: z.object({
                 spaceKey: z.string().optional().describe("Filter by space key"),
-                limit: z.number().optional().describe("Max results (default: 25)"),
             }),
             handler: async (args) => {
                 try {
-                    const result = await client.listUserDrafts(args.spaceKey, args.limit);
+                    const result = await client.listUserDrafts(args.spaceKey);
                     // Build the base URL for constructing full URLs
                     const baseUrl = client.getBaseUrl();
                     const drafts = result.results.map((page) => ({
@@ -1059,9 +1053,12 @@ Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to modify, th
                         created: page.version?.when || "",
                         url: `${baseUrl}/pages/resumedraft.action?draftId=${page.id}`,
                     }));
-                    return formatSuccess({
+                    return formatSuccessBuffered({
                         drafts,
                         total: result.totalSize,
+                    }, {
+                        resourceType: "confluence_drafts",
+                        title: args.spaceKey ? `Drafts in ${args.spaceKey}` : "All Drafts",
                     });
                 }
                 catch (error) {
@@ -1125,7 +1122,7 @@ Returns new draftId, bufferId, structure (element IDs), and URL. Always use the
                         });
                     }
                     // Validate XHTML and PlantUML content before writing
-                    const validationError = await validateContentForWrite(savedContent);
+                    const validationError = await validateContentForWrite(savedContent, args.bufferId);
                     if (validationError) {
                         return validationError;
                     }