@crypto512/jicon-mcp 1.3.0 → 2.0.0

package/dist/confluence/tools.js

@@ -2,12 +2,12 @@
  * Confluence MCP Tools
  */
 import { z } from "zod";
-import { formatSuccess, formatSuccessBuffered, formatError, isApiError } from "../utils/response-formatter.js";
+import { formatSuccess, formatSuccessJson, formatSuccessXhtml, 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";
+import { validateXhtmlAsync, parseXhtml, enhanceXhtmlError } from "../utils/xhtml/index.js";
 import { detectRawPlantUml, detectDiagramType } from "../utils/xhtml/plantuml.js";
-import { expandPlantUmlInXhtml, collapseExpandedIncludesInXhtml } from "../utils/plantuml/index.js";
+import { convertPlantUmlIncludesInXhtml, IncludeConversionError } from "../utils/plantuml/index.js";
 import { parseUrl } from "../utils/url-tools.js";
 import { DEFAULT_PAGE_EXPAND } from "./defaults.js";
 /**
@@ -136,30 +136,20 @@ async function validateContentForWrite(content, bufferId) {
     }
     return null; // Valid content
 }
-/**
- * Store XHTML content in buffer with element IDs for structured editing.
- * Parses XHTML, assigns data-jicon-id attributes, and stores with structure.
- * Content is validated before Confluence writes, so parsing always succeeds.
- */
-function storeXhtmlWithStructure(content, metadata) {
-    const parseResult = parseXhtml(content);
-    const structureResult = parseStructure(parseResult.document);
-    const contentWithIds = serializeXhtml(parseResult.document);
-    const bufferId = contentBuffer.storeWithStructure(contentWithIds, structureResult.structure, structureResult.nextId, metadata);
-    return { bufferId, structure: structureResult.structure };
-}
 export function createConfluenceTools(client) {
     return {
         confluence_search_content: {
-            description: `Search Confluence content using CQL. Auto-fetches all results.
+            description: `Search Confluence content using CQL. Auto-fetches all results (up to 5000).
 
-Returns bufferId. Use buffer_get_chunk to read, buffer_grep to search.
+Entry point for finding Confluence pages by content, title, or metadata.
 
-TIP: See help(topic="cql") for CQL syntax guide.
+REQUIRES: Valid CQL query (see help(topic="cql") for syntax)
+RETURNS: bufferId (JSON array), itemCount with page IDs and titles
+NEXT: confluence_get_page (to load), buffer_pipeline (for reports), buffer_grep (to search results)
 
-Example: type=page AND space=DOCS AND text~"API" ORDER BY lastmodified DESC
+Example: confluence_search_content(cql="type=page AND space=DOCS AND text~'API'")
 
-WARNING: Use text~ (not content~ or body~). Use space KEY (not name).`,
+WARNING: Use text~ not content~. Use space KEY not name.`,
             inputSchema: z.object({
                 cql: z.string().describe("CQL query string"),
                 expand: z.array(z.string()).optional().describe("Additional data to expand"),
@@ -167,7 +157,7 @@ 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);
-                    return formatSuccessBuffered(result, {
+                    return formatSuccessJson(result, {
                         resourceType: "confluence_search",
                         title: `CQL: ${args.cql.substring(0, 100)}${args.cql.length > 100 ? "..." : ""}`,
                     });
@@ -239,18 +229,19 @@ Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to add conten
             handler: async (args) => {
                 try {
                     const result = await client.getPage(args.pageId, args.expand);
-                    const rawContent = result.body?.storage?.value || "";
-                    // Collapse expanded includes back to !include directives
-                    const content = collapseExpandedIncludesInXhtml(rawContent);
+                    const content = result.body?.storage?.value || "";
                     // Store content with element IDs for structured editing
-                    const { bufferId, structure } = storeXhtmlWithStructure(content, {
+                    const xhtmlResult = formatSuccessXhtml(content, {
                         resourceType: "confluence_page",
                         resourceId: String(result.id),
-                        contentType: "xhtml",
                         version: result.version?.number,
                         spaceKey: result.space?.key,
-                        title: result.title,
+                        title: result.title || args.pageId,
                     });
+                    if ("errorResult" in xhtmlResult) {
+                        return xhtmlResult.errorResult;
+                    }
+                    const { bufferId, structure } = xhtmlResult;
                     return formatSuccess({
                         ...formatPageMetadata(result),
                         pageId: result.id,
@@ -288,18 +279,19 @@ Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to add conten
                             statusCode: 404,
                         });
                     }
-                    const rawContent = result.body?.storage?.value || "";
-                    // Collapse expanded includes back to !include directives
-                    const content = collapseExpandedIncludesInXhtml(rawContent);
+                    const content = result.body?.storage?.value || "";
                     // Store content with element IDs for structured editing
-                    const { bufferId, structure } = storeXhtmlWithStructure(content, {
+                    const xhtmlResult = formatSuccessXhtml(content, {
                         resourceType: "confluence_page",
                         resourceId: String(result.id),
-                        contentType: "xhtml",
                         version: result.version?.number,
                         spaceKey: result.space?.key,
-                        title: result.title,
+                        title: result.title || args.title,
                     });
+                    if ("errorResult" in xhtmlResult) {
+                        return xhtmlResult.errorResult;
+                    }
+                    const { bufferId, structure } = xhtmlResult;
                     return formatSuccess({
                         ...formatPageMetadata(result),
                         pageId: result.id,
@@ -316,27 +308,11 @@ Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to add conten
             },
         },
         confluence_edit: {
-            description: `Smart page/draft loader - auto-resolves URLs, pageIds, draftIds, or SPACE/Title.
+            description: `Load page/draft for editing. Returns bufferId, structure (element IDs), pageId, version.
 
-ACCEPTS ANY OF:
-  - Full URL: https://confluence.example.com/pages/viewpage.action?pageId=123
-  - Full URL: https://confluence.example.com/pages/resumedraft.action?draftId=456
-  - Full URL: https://confluence.example.com/display/SPACE/Page+Title
-  - Page ID: "123456"
-  - Draft ID: "draft:123456" (prefix with "draft:")
-  - Space/Title: "DOCS/API Guide"
-
-SMART BEHAVIOR:
-  - URLs are parsed automatically to extract pageId or draftId
-  - Draft IDs: tries to load draft; if 404 (published), finds page by title
-  - Returns bufferId + structure + pageId for editing
-
-WORKFLOW:
-  1. confluence_edit(input) → bufferId, structure, pageId
-  2. buffer_edit(bufferId, ...) → modify content
-  3. confluence_draft_create(pageId=..., bufferId=...) → draft linked to original page
-  4. User publishes via Confluence UI (updates original page)
-  5. For more edits: confluence_edit(same URL or "SPACE/Title") → auto-resolves`,
+ACCEPTS: URL | pageId | "draft:ID" | "SPACE/Title"
+RETURNS: bufferId, structure, pageId, version
+NEXT: buffer_edit → confluence_draft_create → confluence_review_publish`,
             inputSchema: z.object({
                 input: z.string().describe('URL, pageId, "draft:ID", or "SPACE/Title"'),
             }),
@@ -351,16 +327,18 @@ WORKFLOW:
                 }
                 // Helper to load page content and return formatted result
                 const loadPageContent = async (pageResult) => {
-                    const rawContent = pageResult.body?.storage?.value || "";
-                    const content = collapseExpandedIncludesInXhtml(rawContent);
-                    const { bufferId, structure } = storeXhtmlWithStructure(content, {
+                    const content = pageResult.body?.storage?.value || "";
+                    const xhtmlResult = formatSuccessXhtml(content, {
                         resourceType: "confluence_page",
                         resourceId: String(pageResult.id),
-                        contentType: "xhtml",
                         version: pageResult.version?.number,
                         spaceKey: pageResult.space?.key,
                         title: pageResult.title,
                     });
+                    if ("errorResult" in xhtmlResult) {
+                        throw new Error("Failed to parse XHTML content");
+                    }
+                    const { bufferId, structure } = xhtmlResult;
                     return {
                         pageId: pageResult.id,
                         spaceKey: pageResult.space?.key,
@@ -375,16 +353,18 @@ WORKFLOW:
                 // Helper to load draft content
                 const loadDraftContent = async (draftId) => {
                     const result = await client.getDraft(draftId);
-                    const rawContent = result.body?.storage?.value || "";
-                    const content = collapseExpandedIncludesInXhtml(rawContent);
-                    const { bufferId, structure } = storeXhtmlWithStructure(content, {
-                        resourceType: "confluence_page",
+                    const content = result.body?.storage?.value || "";
+                    const xhtmlResult = formatSuccessXhtml(content, {
+                        resourceType: "confluence_draft",
                         resourceId: String(result.id),
-                        contentType: "xhtml",
                         spaceKey: result.space?.key,
                         title: result.title,
                         isDraft: true,
                     });
+                    if ("errorResult" in xhtmlResult) {
+                        throw new Error("Failed to parse XHTML content");
+                    }
+                    const { bufferId, structure } = xhtmlResult;
                     return {
                         draftId: result.id,
                         spaceKey: result.space?.key,
@@ -508,7 +488,15 @@ WORKFLOW:
         // - New pages: confluence_draft_create → user publishes
         // - Existing pages: confluence_get_page → buffer_edit → confluence_draft_create → user publishes
         confluence_delete_page: {
-            description: "Delete a Confluence page",
+            description: `Delete a Confluence page permanently.
+
+Page is moved to trash. Use with caution.
+
+REQUIRES: pageId
+RETURNS: Success confirmation
+NEXT: None
+
+Example: confluence_delete_page(pageId="123456")`,
             inputSchema: z.object({
                 pageId: z.coerce.string().describe("Page ID (accepts string or number)"),
             }),
@@ -533,7 +521,13 @@ WORKFLOW:
         confluence_list_spaces: {
             description: `List all accessible Confluence spaces.
 
-Returns bufferId. Use buffer_get_chunk to read, buffer_grep to search.`,
+Discover available spaces and their keys for use in CQL queries.
+
+REQUIRES: None (optional type filter)
+RETURNS: bufferId with spaces array (key, name, type)
+NEXT: confluence_get_space (for details), confluence_search_content (to query space)
+
+Example: confluence_list_spaces(type="global")`,
             inputSchema: z.object({
                 type: z
                     .enum(["global", "personal"])
@@ -543,7 +537,7 @@ Returns bufferId. Use buffer_get_chunk to read, buffer_grep to search.`,
             handler: async (args) => {
                 try {
                     const result = await client.listSpaces(args.type);
-                    return formatSuccessBuffered(result, {
+                    return formatSuccessJson(result, {
                         resourceType: "confluence_spaces",
                         title: args.type ? `${args.type} spaces` : "All Spaces",
                     });
@@ -554,9 +548,15 @@ Returns bufferId. Use buffer_get_chunk to read, buffer_grep to search.`,
             },
         },
         confluence_get_space: {
-            description: `Get detailed information about a space.
+            description: `Get detailed information about a Confluence space.
 
-Returns bufferId. Use buffer_get_chunk to read, buffer_grep to search.`,
+View space configuration, homepage, and description.
+
+REQUIRES: spaceKey (short code like 'DOCS')
+RETURNS: bufferId with space details (name, homepage, description)
+NEXT: confluence_search_content (to query space), confluence_get_page (homepage)
+
+Example: confluence_get_space(spaceKey="DOCS")`,
             inputSchema: z.object({
                 spaceKey: z.string().describe("Space key"),
                 expand: z.array(z.string()).optional().describe("Additional data to expand"),
@@ -564,7 +564,7 @@ Returns bufferId. Use buffer_get_chunk to read, buffer_grep to search.`,
             handler: async (args) => {
                 try {
                     const result = await client.getSpace(args.spaceKey, args.expand);
-                    return formatSuccessBuffered(result, {
+                    return formatSuccessJson(result, {
                         resourceType: "confluence_space",
                         title: result.name || args.spaceKey,
                         spaceKey: args.spaceKey,
@@ -586,7 +586,7 @@ Returns bufferId. Use buffer_get_chunk to read, buffer_grep to search.`,
             handler: async (args) => {
                 try {
                     const result = await client.getPageChildren(args.pageId, args.expand);
-                    return formatSuccessBuffered(result, {
+                    return formatSuccessJson(result, {
                         resourceType: "confluence_page_children",
                         title: `Page ${args.pageId} children`,
                         pageId: args.pageId,
@@ -623,7 +623,7 @@ Returns bufferId. Use buffer_get_chunk to read, buffer_grep to search.`,
             handler: async (args) => {
                 try {
                     const result = await client.getComments(args.pageId);
-                    return formatSuccessBuffered(result, {
+                    return formatSuccessJson(result, {
                         resourceType: "confluence_comments",
                         title: `Page ${args.pageId} comments`,
                         pageId: args.pageId,
@@ -661,7 +661,7 @@ Returns bufferId. Use buffer_get_chunk to read, buffer_grep to search.`,
             handler: async (args) => {
                 try {
                     const result = await client.listAttachments(args.pageId);
-                    return formatSuccessBuffered(result, {
+                    return formatSuccessJson(result, {
                         resourceType: "confluence_attachments",
                         title: `Page ${args.pageId} attachments`,
                         pageId: args.pageId,
@@ -673,14 +673,8 @@ Returns bufferId. Use buffer_get_chunk to read, buffer_grep to search.`,
             },
         },
         confluence_get_current_user_space: {
-            description: `Get the current user's personal/home Confluence space.
-
-Use this tool when the user asks about:
-- "my space", "my home space", "my personal space"
-- "confluence home", "home space"
-- "where can I write", "my confluence area"
-
-Returns the user's personal space key and details. Use this to verify your personal space before write operations when write-home restriction is enabled.`,
+            description: `Get the current user's personal Confluence space. Returns spaceKey and homePageId.
+Use to verify personal space before write operations when write-home restriction is enabled.`,
             inputSchema: z.object({}),
             handler: async () => {
                 try {
@@ -712,30 +706,16 @@ Returns the user's personal space key and details. Use this to verify your perso
         // Note: Confluence drafts cannot be updated via API, only created, read, or deleted.
         // The workflow is: create draft → edit locally in buffer → save (delete+recreate) → publish
         confluence_draft_create: {
-            description: `Create a Confluence draft for user review. Returns draftId, bufferId, structure (element IDs), and clickable URL.
+            description: `Create draft for user review. Requires bufferId with valid XHTML.
 
-REQUIRES bufferId - content must be in a buffer for validation and error recovery.
+NEW page: confluence_draft_create(spaceKey, title, bufferId)
+EDIT page: confluence_edit → buffer_edit → confluence_draft_create(pageId, bufferId)
 
-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) 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
-
-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.`,
+Draft title auto-prefixed with "[jicon-mcp REVIEW]" when editing existing pages.
+RETURNS: draftId, bufferId, structure, url. On XHTML error: errorElementId for buffer_edit fix.
+WARNING: pageId must be a PAGE ID, not a draft ID. Use confluence_draft_open for existing drafts.`,
             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."),
+                pageId: z.coerce.string().optional().describe("Existing PAGE ID to edit (NOT a draft ID). Get from confluence_get_page or confluence_edit. 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)"),
                 bufferId: z.string().describe("Buffer ID containing XHTML content (from buffer_create or confluence_get_page)"),
@@ -773,7 +753,7 @@ IMPORTANT: Call help(topic="plantuml") for diagram syntax.`,
                     });
                 }
                 // Get full content from buffer
-                const fullContent = contentBuffer.getChunk(args.bufferId, 0, bufferInfo.totalSize);
+                const fullContent = contentBuffer.getChunk(args.bufferId, 0, bufferInfo.bufferSizeBytes);
                 if (!fullContent) {
                     return formatError({
                         error: true,
@@ -817,10 +797,18 @@ IMPORTANT: Call help(topic="plantuml") for diagram syntax.`,
                         }
                     }
                     catch (error) {
+                        // Provide helpful hint if they might have passed a draftId instead of pageId
+                        const errorMessage = isApiError(error) ? error.message :
+                            error instanceof Error ? error.message : String(error);
                         return formatError({
                             error: true,
-                            message: `Failed to fetch original page ${args.pageId}: ${error instanceof Error ? error.message : String(error)}`,
+                            message: `Page '${args.pageId}' not found. If this is a draft ID (from confluence_draft_create), use confluence_draft_open to continue editing instead.`,
                             statusCode: 404,
+                            details: {
+                                originalError: errorMessage,
+                                hint: "For existing drafts: confluence_draft_open(draftId) → buffer_edit → confluence_draft_save. For new drafts from existing pages: confluence_edit(pageId) → buffer_edit → confluence_draft_create(pageId, bufferId)",
+                                pageIdProvided: args.pageId,
+                            },
                         });
                     }
                 }
@@ -852,8 +840,26 @@ IMPORTANT: Call help(topic="plantuml") for diagram syntax.`,
                 if (validationError) {
                     return validationError;
                 }
-                // Expand PlantUML !include directives before sending to Confluence
-                const expandedContent = await expandPlantUmlInXhtml(content);
+                // Convert PlantUML !include URLs to stdlib syntax before sending to Confluence
+                let expandedContent;
+                try {
+                    expandedContent = convertPlantUmlIncludesInXhtml(content);
+                }
+                catch (error) {
+                    if (error instanceof IncludeConversionError) {
+                        return formatError({
+                            error: true,
+                            message: error.message,
+                            statusCode: 400,
+                            details: {
+                                url: error.url,
+                                suggestion: error.suggestion,
+                                hint: "Replace the HTTP URL with the suggested stdlib syntax in your PlantUML diagram",
+                            },
+                        });
+                    }
+                    throw error;
+                }
                 try {
                     // Constants for review workflow
                     const REVIEW_PREFIX = '[jicon-mcp REVIEW] ';
@@ -915,16 +921,19 @@ IMPORTANT: Call help(topic="plantuml") for diagram syntax.`,
                     }
                     // Store content with element IDs for structured editing
                     // Track originalPageId in metadata so we can link the draft to its source
-                    const { bufferId: newBufferId } = storeXhtmlWithStructure(content, {
-                        resourceType: "confluence_page",
+                    const xhtmlResult = formatSuccessXhtml(content, {
+                        resourceType: "confluence_draft",
                         resourceId: result.id,
-                        contentType: "xhtml",
                         spaceKey: result.space?.key,
                         title: result.title,
                         isDraft: true,
                         originalPageId: originalPageId,
                         originalPageVersion: originalPageVersion,
                     });
+                    if ("errorResult" in xhtmlResult) {
+                        return xhtmlResult.errorResult;
+                    }
+                    const newBufferId = xhtmlResult.bufferId;
                     // Build the draft edit URL (drafts use resumedraft.action, not the webui link)
                     const baseUrl = client.getBaseUrl();
                     const draftUrl = `${baseUrl}/pages/resumedraft.action?draftId=${result.id}`;
@@ -1000,18 +1009,19 @@ Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to modify, th
             handler: async (args) => {
                 try {
                     const result = await client.getDraft(args.draftId);
-                    const rawContent = result.body?.storage?.value || "";
-                    // Collapse expanded includes back to !include directives
-                    const content = collapseExpandedIncludesInXhtml(rawContent);
+                    const content = result.body?.storage?.value || "";
                     // Store content with element IDs for structured editing
-                    const { bufferId, structure } = storeXhtmlWithStructure(content, {
-                        resourceType: "confluence_page",
+                    const xhtmlResult = formatSuccessXhtml(content, {
+                        resourceType: "confluence_draft",
                         resourceId: result.id,
-                        contentType: "xhtml",
                         spaceKey: result.space?.key,
                         title: result.title,
                         isDraft: true,
                     });
+                    if ("errorResult" in xhtmlResult) {
+                        return xhtmlResult.errorResult;
+                    }
+                    const { bufferId, structure } = xhtmlResult;
                     // Build the draft edit URL
                     const baseUrl = client.getBaseUrl();
                     const draftUrl = `${baseUrl}/pages/resumedraft.action?draftId=${result.id}`;
@@ -1053,7 +1063,7 @@ Returns bufferId. Use buffer_get_chunk to read, buffer_grep to search.`,
                         created: page.version?.when || "",
                         url: `${baseUrl}/pages/resumedraft.action?draftId=${page.id}`,
                     }));
-                    return formatSuccessBuffered({
+                    return formatSuccessJson({
                         drafts,
                         total: result.totalSize,
                     }, {
@@ -1099,7 +1109,7 @@ Returns new draftId, bufferId, structure (element IDs), and URL. Always use the
                         });
                     }
                     // Get full content from buffer
-                    const fullContent = contentBuffer.getChunk(args.bufferId, 0, bufferChunk.totalSize);
+                    const fullContent = contentBuffer.getChunk(args.bufferId, 0, bufferChunk.bufferSizeBytes);
                     if (!fullContent) {
                         return formatError({
                             error: true,
@@ -1126,8 +1136,26 @@ Returns new draftId, bufferId, structure (element IDs), and URL. Always use the
                     if (validationError) {
                         return validationError;
                     }
-                    // Expand PlantUML !include directives before sending to Confluence
-                    const expandedContent = await expandPlantUmlInXhtml(savedContent);
+                    // Convert PlantUML !include URLs to stdlib syntax before sending to Confluence
+                    let expandedContent;
+                    try {
+                        expandedContent = convertPlantUmlIncludesInXhtml(savedContent);
+                    }
+                    catch (error) {
+                        if (error instanceof IncludeConversionError) {
+                            return formatError({
+                                error: true,
+                                message: error.message,
+                                statusCode: 400,
+                                details: {
+                                    url: error.url,
+                                    suggestion: error.suggestion,
+                                    hint: "Replace the HTTP URL with the suggested stdlib syntax in your PlantUML diagram",
+                                },
+                            });
+                        }
+                        throw error;
+                    }
                     const title = args.title || existingDraft.title;
                     // Delete old draft before creating new one
                     // NOTE: Confluence Data Center does NOT support updating drafts directly.
@@ -1158,18 +1186,21 @@ Returns new draftId, bufferId, structure (element IDs), and URL. Always use the
                     });
                     // Update buffer metadata with new draft ID
                     contentBuffer.invalidateByMetadata({
-                        resourceType: "confluence_page",
+                        resourceType: "confluence_draft",
                         resourceId: args.draftId,
                     });
                     // Store content with element IDs for structured editing
-                    const { bufferId: newBufferId, structure } = storeXhtmlWithStructure(savedContent, {
-                        resourceType: "confluence_page",
+                    const xhtmlResult = formatSuccessXhtml(savedContent, {
+                        resourceType: "confluence_draft",
                         resourceId: newDraft.id,
-                        contentType: "xhtml",
                         spaceKey: newDraft.space?.key,
                         title: newDraft.title,
                         isDraft: true,
                     });
+                    if ("errorResult" in xhtmlResult) {
+                        return xhtmlResult.errorResult;
+                    }
+                    const { bufferId: newBufferId, structure } = xhtmlResult;
                     // Build the draft edit URL
                     const baseUrl = client.getBaseUrl();
                     const draftUrl = `${baseUrl}/pages/resumedraft.action?draftId=${newDraft.id}`;
@@ -1230,14 +1261,24 @@ Drafts are NOT sent to trash - they are permanently deleted.`,
         confluence_review_publish: {
             description: `Publish a review draft to apply changes to the original page.
 
+Apply changes from "[jicon-mcp REVIEW]" draft to the original page.
+
+REQUIRES: reviewDraftId (from confluence_draft_create with pageId)
+RETURNS: Updated page info with new version number
+NEXT: confluence_get_page (to verify), confluence_edit (for more changes)
+
 This tool:
 1. Validates the draft is a "[jicon-mcp REVIEW]" draft with proper label
 2. Copies the draft content to the original page (creates new version)
 3. Deletes the review draft
 
-Use this after user has reviewed the draft in Confluence UI.`,
+Example: confluence_review_publish(reviewDraftId="123456")`,
             inputSchema: z.object({
                 reviewDraftId: z.coerce.string().describe("ID of the [jicon-mcp REVIEW] draft to publish"),
+                autoRetry: z
+                    .boolean()
+                    .optional()
+                    .describe("Auto-retry once on 409 conflict (refetches page version)"),
             }),
             handler: async (args) => {
                 const REVIEW_PREFIX = '[jicon-mcp REVIEW] ';
@@ -1294,9 +1335,23 @@ Use this after user has reviewed the draft in Confluence UI.`,
                     // 5. Get the review draft content
                     const reviewContent = reviewDraft.body?.storage?.value || "";
                     // 6. Update original page with review content
-                    const updatedPage = await client.updatePage(originalPageId, originalPage.version?.number || 1, originalPage.title, // Keep original title (not the REVIEW prefix)
-                    reviewContent, false // Not a minor edit
-                    );
+                    let updatedPage;
+                    try {
+                        updatedPage = await client.updatePage(originalPageId, originalPage.version?.number || 1, originalPage.title, // Keep original title (not the REVIEW prefix)
+                        reviewContent, false // Not a minor edit
+                        );
+                    }
+                    catch (updateError) {
+                        // Handle version conflicts with optional auto-retry
+                        if (isApiError(updateError) && updateError.statusCode === 409 && args.autoRetry) {
+                            // Re-fetch page to get current version and retry
+                            const refreshedPage = await client.getPage(originalPageId, ["version"]);
+                            updatedPage = await client.updatePage(originalPageId, refreshedPage.version?.number || 1, originalPage.title, reviewContent, false);
+                        }
+                        else {
+                            throw updateError;
+                        }
+                    }
                     // 7. Delete review draft
                     await client.deleteDraft(args.reviewDraftId);
                     // 8. Invalidate buffers