@crypto512/jicon-mcp 1.2.0 → 2.0.0

package/dist/confluence/tools.js

@@ -2,12 +2,12 @@
  * Confluence MCP Tools
  */
 import { z } from "zod";
-import { formatSuccess, 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";
 /**
@@ -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,34 +125,31 @@ 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`,
             },
         });
     }
     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 (up to 5000).
 
-TIP: See help(topic="cql") for CQL syntax guide.
+Entry point for finding Confluence pages by content, title, or metadata.
+
+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"),
@@ -199,8 +157,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 formatSuccessJson(result, {
+                        resourceType: "confluence_search",
+                        title: `CQL: ${args.cql.substring(0, 100)}${args.cql.length > 100 ? "..." : ""}`,
+                    });
                 }
                 catch (error) {
                     // Enhanced error handling for common CQL errors
@@ -269,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,
@@ -318,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,
@@ -346,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"'),
             }),
@@ -381,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,
@@ -405,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,
@@ -538,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)"),
             }),
@@ -561,7 +519,15 @@ WORKFLOW:
             },
         },
         confluence_list_spaces: {
-            description: `List all accessible Confluence spaces.`,
+            description: `List all accessible Confluence spaces.
+
+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"])
@@ -571,7 +537,10 @@ WORKFLOW:
             handler: async (args) => {
                 try {
                     const result = await client.listSpaces(args.type);
-                    return formatSuccess(result);
+                    return formatSuccessJson(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 +548,15 @@ WORKFLOW:
             },
         },
         confluence_get_space: {
-            description: "Get detailed information about a space",
+            description: `Get detailed information about a Confluence space.
+
+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"),
@@ -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 formatSuccessJson(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 formatSuccessJson(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 formatSuccessJson(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 formatSuccessJson(result, {
+                        resourceType: "confluence_attachments",
+                        title: `Page ${args.pageId} attachments`,
+                        pageId: args.pageId,
+                    });
                 }
                 catch (error) {
                     return formatError(isApiError(error) ? error : new Error(String(error)));
@@ -675,14 +673,8 @@ WORKFLOW:
             },
         },
         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 {
@@ -714,39 +706,19 @@ 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.
 
-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.
+NEW page: confluence_draft_create(spaceKey, title, bufferId)
+EDIT page: confluence_edit → buffer_edit → confluence_draft_create(pageId, bufferId)
 
-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 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
-
-Provide either 'content' (string) OR 'bufferId' (from buffer_create/buffer_edit).`,
+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)"),
-                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 +729,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.bufferSizeBytes);
+                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({
@@ -811,10 +797,18 @@ Provide either 'content' (string) OR 'bufferId' (from buffer_create/buffer_edit)
                         }
                     }
                     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,
+                            },
                         });
                     }
                 }
@@ -828,19 +822,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,12 +836,30 @@ 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;
                 }
-                // 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] ';
@@ -922,16 +921,19 @@ Provide either 'content' (string) OR 'bufferId' (from buffer_create/buffer_edit)
                     }
                     // 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}`;
@@ -1007,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}`;
@@ -1041,14 +1044,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 +1063,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 formatSuccessJson({
                         drafts,
                         total: result.totalSize,
+                    }, {
+                        resourceType: "confluence_drafts",
+                        title: args.spaceKey ? `Drafts in ${args.spaceKey}` : "All Drafts",
                     });
                 }
                 catch (error) {
@@ -1102,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,
@@ -1125,12 +1132,30 @@ 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;
                     }
-                    // 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.
@@ -1161,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}`;
@@ -1233,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] ';
@@ -1297,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