@crypto512/jicon-mcp 1.1.1 → 1.3.0

package/dist/confluence/tools.js

@@ -2,12 +2,14 @@
  * 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";
 import { detectRawPlantUml, detectDiagramType } from "../utils/xhtml/plantuml.js";
-import { expandPlantUmlInXhtml } from "../utils/plantuml/index.js";
+import { expandPlantUmlInXhtml, collapseExpandedIncludesInXhtml } from "../utils/plantuml/index.js";
+import { parseUrl } from "../utils/url-tools.js";
+import { DEFAULT_PAGE_EXPAND } from "./defaults.js";
 /**
  * Generate a summary of content structure for draft responses.
  * Helps AI assistants verify that diagrams and other elements are included.
@@ -44,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:");
@@ -122,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;
                 }
             });
         }
@@ -149,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.");
@@ -162,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`,
             },
         });
     }
@@ -183,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.
 
@@ -197,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
@@ -225,7 +197,7 @@ WARNING: Use text~ (not content~ or body~). Use space KEY (not name).`,
                                 hint += "- ✅ RIGHT: (text~\"a\" OR text~\"b\") - Each term needs its own text~\n";
                             }
                             hint += "\nExamples:\n";
-                            hint += "  text~\"Nicolas Pernoud\" - finds pages mentioning this person\n";
+                            hint += "  text~\"Mike Tasc\" - finds pages mentioning this person\n";
                             hint += "  text~\"meeting\" AND space=MESH - finds meetings in MESH space\n";
                             hint += "  title~\"sprint review\" - finds pages with sprint review in title";
                             return formatError({
@@ -256,7 +228,7 @@ WARNING: Use text~ (not content~ or body~). Use space KEY (not name).`,
 PREFERRED method when you have a page ID from search results. Faster and more reliable than get_page_by_title.
 
 Returns pageId, version, bufferId, and structure (element IDs) for structured editing.
-Use buffer_edit with element IDs to modify, then confluence_draft_create for user review.`,
+Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to add content, then confluence_draft_create(pageId=..., bufferId=...) for user review.`,
             inputSchema: z.object({
                 pageId: z.coerce.string().describe("Page ID (accepts string or number)"),
                 expand: z
@@ -267,7 +239,9 @@ Use buffer_edit with element IDs to modify, then confluence_draft_create for use
             handler: async (args) => {
                 try {
                     const result = await client.getPage(args.pageId, args.expand);
-                    const content = result.body?.storage?.value || "";
+                    const rawContent = result.body?.storage?.value || "";
+                    // Collapse expanded includes back to !include directives
+                    const content = collapseExpandedIncludesInXhtml(rawContent);
                     // Store content with element IDs for structured editing
                     const { bufferId, structure } = storeXhtmlWithStructure(content, {
                         resourceType: "confluence_page",
@@ -284,7 +258,7 @@ Use buffer_edit with element IDs to modify, then confluence_draft_create for use
                         bufferId,
                         ...(structure && { structure }),
                         contentSize: content.length,
-                        message: "Page loaded. Use buffer_edit to modify, then confluence_draft_create for user review.",
+                        message: "Page loaded. Use buffer_edit to modify, then confluence_draft_create(pageId=..., bufferId=...) for user review.",
                     });
                 }
                 catch (error) {
@@ -298,7 +272,7 @@ Use buffer_edit with element IDs to modify, then confluence_draft_create for use
 Use ONLY when you don't have a page ID. IMPORTANT: Use the space KEY (e.g. 'MESH', 'TC'), NOT the space name.
 
 Returns pageId, version, bufferId, and structure (element IDs) for structured editing.
-Use buffer_edit with element IDs to modify, then confluence_draft_create for user review.`,
+Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to add content, then confluence_draft_create(pageId=..., bufferId=...) for user review.`,
             inputSchema: z.object({
                 spaceKey: z.string().describe("Space key (short code like 'MESH', 'TC'), NOT the full space name"),
                 title: z.string().describe("Page title"),
@@ -314,7 +288,9 @@ Use buffer_edit with element IDs to modify, then confluence_draft_create for use
                             statusCode: 404,
                         });
                     }
-                    const content = result.body?.storage?.value || "";
+                    const rawContent = result.body?.storage?.value || "";
+                    // Collapse expanded includes back to !include directives
+                    const content = collapseExpandedIncludesInXhtml(rawContent);
                     // Store content with element IDs for structured editing
                     const { bufferId, structure } = storeXhtmlWithStructure(content, {
                         resourceType: "confluence_page",
@@ -331,7 +307,196 @@ Use buffer_edit with element IDs to modify, then confluence_draft_create for use
                         bufferId,
                         ...(structure && { structure }),
                         contentSize: content.length,
-                        message: "Page loaded. Use buffer_edit to modify, then confluence_draft_create for user review.",
+                        message: "Page loaded. Use buffer_edit to modify, then confluence_draft_create(pageId=..., bufferId=...) for user review.",
+                    });
+                }
+                catch (error) {
+                    return formatError(isApiError(error) ? error : new Error(String(error)));
+                }
+            },
+        },
+        confluence_edit: {
+            description: `Smart page/draft loader - auto-resolves URLs, pageIds, draftIds, or SPACE/Title.
+
+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`,
+            inputSchema: z.object({
+                input: z.string().describe('URL, pageId, "draft:ID", or "SPACE/Title"'),
+            }),
+            handler: async (args) => {
+                const input = args.input.trim();
+                if (!input) {
+                    return formatError({
+                        error: true,
+                        message: "Input is required. Provide a URL, pageId, draft:ID, or SPACE/Title.",
+                        statusCode: 400,
+                    });
+                }
+                // 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, {
+                        resourceType: "confluence_page",
+                        resourceId: String(pageResult.id),
+                        contentType: "xhtml",
+                        version: pageResult.version?.number,
+                        spaceKey: pageResult.space?.key,
+                        title: pageResult.title,
+                    });
+                    return {
+                        pageId: pageResult.id,
+                        spaceKey: pageResult.space?.key,
+                        title: pageResult.title,
+                        version: pageResult.version?.number,
+                        bufferId,
+                        structure,
+                        contentSize: content.length,
+                        message: "Content loaded. Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to add content, then confluence_draft_create(pageId=..., bufferId=...) for user review.",
+                    };
+                };
+                // 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",
+                        resourceId: String(result.id),
+                        contentType: "xhtml",
+                        spaceKey: result.space?.key,
+                        title: result.title,
+                        isDraft: true,
+                    });
+                    return {
+                        draftId: result.id,
+                        spaceKey: result.space?.key,
+                        title: result.title,
+                        bufferId,
+                        structure,
+                        contentSize: content.length,
+                        message: "Draft loaded. Use buffer_edit to modify, then confluence_draft_save to update.",
+                    };
+                };
+                try {
+                    // Case 1: Full URL
+                    if (input.startsWith("http://") || input.startsWith("https://")) {
+                        const parsed = parseUrl(input);
+                        if (parsed.type === "confluence_page" && parsed.pageId) {
+                            const result = await client.getPage(parsed.pageId);
+                            return formatSuccess(await loadPageContent(result));
+                        }
+                        if (parsed.type === "confluence_draft" && parsed.draftId) {
+                            try {
+                                return formatSuccess(await loadDraftContent(parsed.draftId));
+                            }
+                            catch (error) {
+                                // Draft may have been published - try to find page by title
+                                if (isApiError(error) && error.statusCode === 404 && parsed.spaceKey && parsed.title) {
+                                    const pageResult = await client.getPageByTitle(parsed.spaceKey, parsed.title);
+                                    if (pageResult) {
+                                        return formatSuccess({
+                                            ...await loadPageContent(pageResult),
+                                            note: "Draft was published. Loaded the published page instead.",
+                                        });
+                                    }
+                                }
+                                throw error;
+                            }
+                        }
+                        if (parsed.type === "confluence_space_path" && parsed.spaceKey && parsed.title) {
+                            const pageResult = await client.getPageByTitle(parsed.spaceKey, parsed.title);
+                            if (!pageResult) {
+                                return formatError({
+                                    error: true,
+                                    message: `Page not found: "${parsed.title}" in space ${parsed.spaceKey}`,
+                                    statusCode: 404,
+                                });
+                            }
+                            return formatSuccess(await loadPageContent(pageResult));
+                        }
+                        return formatError({
+                            error: true,
+                            message: `Unable to parse URL: "${input}". Use Confluence page, draft, or display URL.`,
+                            statusCode: 400,
+                        });
+                    }
+                    // Case 2: Draft ID (prefix with "draft:")
+                    if (input.startsWith("draft:")) {
+                        const draftId = input.substring(6);
+                        try {
+                            return formatSuccess(await loadDraftContent(draftId));
+                        }
+                        catch (error) {
+                            if (isApiError(error) && error.statusCode === 404) {
+                                return formatError({
+                                    error: true,
+                                    message: `Draft ${draftId} not found. It may have been published. Try using the page URL or "SPACE/Title" format.`,
+                                    statusCode: 404,
+                                    details: {
+                                        hint: "If the draft was published, ask the user for the published page URL.",
+                                    },
+                                });
+                            }
+                            throw error;
+                        }
+                    }
+                    // Case 3: Space/Title format (e.g., "DOCS/API Guide")
+                    if (input.includes("/") && !input.match(/^\d+$/)) {
+                        const slashIndex = input.indexOf("/");
+                        const spaceKey = input.substring(0, slashIndex).trim();
+                        const title = input.substring(slashIndex + 1).trim();
+                        if (!spaceKey || !title) {
+                            return formatError({
+                                error: true,
+                                message: `Invalid SPACE/Title format: "${input}". Expected "SPACEKEY/Page Title".`,
+                                statusCode: 400,
+                            });
+                        }
+                        const pageResult = await client.getPageByTitle(spaceKey, title);
+                        if (!pageResult) {
+                            return formatError({
+                                error: true,
+                                message: `Page not found: "${title}" in space ${spaceKey}`,
+                                statusCode: 404,
+                            });
+                        }
+                        return formatSuccess(await loadPageContent(pageResult));
+                    }
+                    // Case 4: Pure numeric page ID
+                    if (/^\d+$/.test(input)) {
+                        const result = await client.getPage(input);
+                        return formatSuccess(await loadPageContent(result));
+                    }
+                    return formatError({
+                        error: true,
+                        message: `Unable to parse input: "${input}". Expected URL, pageId, "draft:ID", or "SPACE/Title".`,
+                        statusCode: 400,
+                        details: {
+                            examples: [
+                                "https://confluence.example.com/pages/viewpage.action?pageId=123",
+                                "123456 (page ID)",
+                                "draft:456789 (draft ID)",
+                                "DOCS/API Guide (space/title)",
+                            ],
+                        },
                     });
                 }
                 catch (error) {
@@ -366,7 +531,9 @@ Use buffer_edit with element IDs to modify, then confluence_draft_create for use
             },
         },
         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"])
@@ -376,7 +543,10 @@ Use buffer_edit with element IDs to modify, then confluence_draft_create for use
             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)));
@@ -384,7 +554,9 @@ Use buffer_edit with element IDs to modify, then confluence_draft_create for use
             },
         },
         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"),
@@ -392,8 +564,11 @@ Use buffer_edit with element IDs to modify, then confluence_draft_create for use
             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)));
@@ -401,7 +576,9 @@ Use buffer_edit with element IDs to modify, then confluence_draft_create for use
             },
         },
         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"),
@@ -409,7 +586,11 @@ Use buffer_edit with element IDs to modify, then confluence_draft_create for use
             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)));
@@ -433,14 +614,20 @@ Use buffer_edit with element IDs to modify, then confluence_draft_create for use
             },
         },
         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)));
@@ -465,14 +652,20 @@ Use buffer_edit with element IDs to modify, then confluence_draft_create for use
             },
         },
         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)));
@@ -521,44 +714,126 @@ 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: User must validate the draft in Confluence UI before publishing.
-IMPORTANT: Raw @startuml outside macros is NOT supported. Use buffer_edit for auto-wrapping, or embed properly formatted ac:structured-macro elements.
+REQUIRES bufferId - content must be in a buffer for validation and error recovery.
+
+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
 
-TIP: See help(topic="storage") for XHTML syntax, help(topic="plantuml") for diagrams.
+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
 
-Workflow:
-1. Create draft with this tool → returns URL and structure with element IDs
-2. User reviews draft in Confluence UI (can edit there)
-3. If user requests changes: use confluence_draft_open to get user's edits
-4. Modify with buffer_edit using element IDs, then confluence_draft_save for new review
-5. User publishes manually via Confluence UI
+On validation error: returns bufferId + errorElementId for surgical fix with buffer_edit.
 
-Provide either 'content' (string) OR 'bufferId' (from buffer_create/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({
-                spaceKey: z.string().describe("Space key"),
-                title: z.string().describe("Page title"),
-                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)"),
+                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)"),
+                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"),
             }),
             handler: async (args) => {
-                // Resolve content from either content string or bufferId
-                const resolved = resolveContentFromBuffer(args.content, args.bufferId);
-                if (resolved.error) {
-                    return resolved.error;
+                // Determine the mode: editing existing page vs creating new draft
+                let spaceKey = args.spaceKey;
+                let title = args.title;
+                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')",
+                        },
+                    });
                 }
-                if (!resolved.content) {
+                // Validate buffer contains XHTML content
+                if (bufferInfo.metadata?.contentType && bufferInfo.metadata.contentType !== "xhtml") {
                     return formatError({
                         error: true,
-                        message: "Either 'content' or 'bufferId' must be provided",
+                        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",
+                        },
                     });
                 }
-                const content = resolved.content;
+                // 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
+                    const bufferSourceId = bufferInfo.metadata?.resourceId;
+                    if (bufferSourceId !== args.pageId) {
+                        return formatError({
+                            error: true,
+                            message: `Buffer '${args.bufferId}' does not belong to page '${args.pageId}'`,
+                            statusCode: 400,
+                            details: {
+                                bufferSource: bufferSourceId || "unknown",
+                                expectedPage: args.pageId,
+                                hint: "Two options: (1) Load page first with confluence_edit(pageId) then use buffer_edit to modify, OR (2) If you already created content in a separate buffer, use buffer_edit(pageBufferId, after=N, fromBufferId=yourNewBuffer) to merge it into the page buffer",
+                            },
+                        });
+                    }
+                    // Fetch original page info to get space, title, parent, etc.
+                    try {
+                        const originalPage = await client.getPage(args.pageId, ["space", "ancestors", "version"]);
+                        spaceKey = originalPage.space?.key;
+                        title = args.title || originalPage.title; // Allow title override
+                        originalPageId = originalPage.id;
+                        originalPageVersion = originalPage.version?.number;
+                        // Get parent from ancestors if not explicitly provided
+                        if (!parentId && originalPage.ancestors && originalPage.ancestors.length > 0) {
+                            parentId = originalPage.ancestors[originalPage.ancestors.length - 1].id;
+                        }
+                        if (!spaceKey) {
+                            return formatError({
+                                error: true,
+                                message: `Could not determine space key for page ${args.pageId}`,
+                                statusCode: 400,
+                            });
+                        }
+                    }
+                    catch (error) {
+                        return formatError({
+                            error: true,
+                            message: `Failed to fetch original page ${args.pageId}: ${error instanceof Error ? error.message : String(error)}`,
+                            statusCode: 404,
+                        });
+                    }
+                }
+                else {
+                    // MODE: New page - require spaceKey and title
+                    if (!spaceKey || !title) {
+                        return formatError({
+                            error: true,
+                            message: "For new drafts, both 'spaceKey' and 'title' are required. For editing existing pages, provide 'pageId' instead.",
+                            statusCode: 400,
+                        });
+                    }
+                }
                 // Check for raw PlantUML that should use buffer_edit with plantuml parameter
                 const rawPlantUml = detectRawPlantUml(content);
                 if (rawPlantUml) {
@@ -573,21 +848,73 @@ 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);
                 try {
-                    const result = await client.createDraft({
-                        spaceKey: args.spaceKey,
-                        title: args.title,
-                        content: expandedContent,
-                        parentId: args.parentId,
-                        labels: args.labels,
-                    });
+                    // Constants for review workflow
+                    const REVIEW_PREFIX = '[jicon-mcp REVIEW] ';
+                    const REVIEW_LABEL_PREFIX = 'jicon-review-';
+                    let result;
+                    let existingReviewDraft = null;
+                    let reviewLabel;
+                    if (originalPageId) {
+                        // REVIEW WORKFLOW: Creating/updating review draft for existing page
+                        reviewLabel = `${REVIEW_LABEL_PREFIX}${originalPageId}`;
+                        // Check if review draft already exists for this page
+                        existingReviewDraft = await client.findDraftByLabel(reviewLabel);
+                        if (existingReviewDraft) {
+                            // Delete existing review draft to update it (API doesn't support draft updates)
+                            await client.deleteDraft(existingReviewDraft.id);
+                        }
+                        // Prevent nested review drafts
+                        const reviewTitle = title.startsWith(REVIEW_PREFIX)
+                            ? title
+                            : `${REVIEW_PREFIX}${title}`;
+                        // Create review draft with label linking to original page
+                        const labels = [...(args.labels || []), reviewLabel];
+                        result = await client.createDraft({
+                            spaceKey: spaceKey,
+                            title: reviewTitle,
+                            content: expandedContent,
+                            parentId: parentId,
+                            labels: labels,
+                        });
+                    }
+                    else {
+                        // NEW PAGE MODE: Create standalone draft
+                        result = await client.createDraft({
+                            spaceKey: spaceKey,
+                            title: title,
+                            content: expandedContent,
+                            parentId: parentId,
+                            labels: args.labels,
+                        });
+                    }
+                    // Verify draft is readable with labels (catches label attachment failures)
+                    if (originalPageId && reviewLabel) {
+                        const verifyDraft = await client.getDraft(result.id, [
+                            ...DEFAULT_PAGE_EXPAND,
+                            "metadata.labels",
+                        ]);
+                        const labels = verifyDraft.metadata?.labels?.results || [];
+                        const hasReviewLabel = labels.some((l) => l.name === reviewLabel);
+                        if (!hasReviewLabel) {
+                            // Label attachment may have failed - try to add it again
+                            // This can happen due to eventual consistency or API timing
+                            try {
+                                await client.addLabels(result.id, [reviewLabel], true);
+                            }
+                            catch {
+                                // If label add fails, warn but continue (draft still exists)
+                            }
+                        }
+                    }
                     // 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",
                         resourceId: result.id,
@@ -595,13 +922,16 @@ Provide either 'content' (string) OR 'bufferId' (from buffer_create/buffer_edit)
                         spaceKey: result.space?.key,
                         title: result.title,
                         isDraft: true,
+                        originalPageId: originalPageId,
+                        originalPageVersion: originalPageVersion,
                     });
                     // 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}`;
                     // Generate content summary for verification
                     const summary = getContentSummary(content);
-                    return formatSuccess({
+                    // Build response with original page info if editing existing page
+                    const response = {
                         draftId: result.id,
                         bufferId: newBufferId,
                         title: result.title,
@@ -616,11 +946,37 @@ Provide either 'content' (string) OR 'bufferId' (from buffer_create/buffer_edit)
                             hasTable: summary.hasTable,
                             headings: summary.headingCount,
                         },
-                        message: "Draft created. IMPORTANT: Display the URL above to the user so they can review and publish.",
-                        ...(summary.plantumlCount === 0 && {
-                            warning: "No PlantUML diagrams found in content. If diagrams were expected, use buffer_edit with plantuml parameter.",
-                        }),
-                    });
+                    };
+                    // Add review workflow info when editing existing page
+                    if (originalPageId) {
+                        response.reviewDraft = {
+                            originalPageId: originalPageId,
+                            originalPageVersion: originalPageVersion,
+                            reviewLabel: reviewLabel,
+                            wasUpdated: !!existingReviewDraft,
+                            note: "This is a REVIEW draft linked to the original page.",
+                        };
+                        response.message = existingReviewDraft
+                            ? `Review draft updated for page ${originalPageId}. Use confluence_review_publish(${result.id}) to apply changes.`
+                            : `Review draft created for page ${originalPageId}. Use confluence_review_publish(${result.id}) to apply changes.`;
+                        response.nextSteps = {
+                            toPublish: `confluence_review_publish(reviewDraftId="${result.id}")`,
+                            toDiscard: `confluence_review_discard(reviewDraftId="${result.id}")`,
+                            toList: "confluence_review_list()",
+                        };
+                    }
+                    else {
+                        response.message = "Draft created. IMPORTANT: Display the URL above to the user so they can review and publish.";
+                        response.afterPublish = {
+                            note: "After user publishes, the draft ID becomes invalid.",
+                            editAgain: `confluence_edit("${result.space?.key}/${result.title}")`,
+                            tip: "Use confluence_edit with the same SPACE/Title or page URL to edit the published page.",
+                        };
+                    }
+                    if (summary.plantumlCount === 0) {
+                        response.warning = "No PlantUML diagrams found in content. If diagrams were expected, use buffer_edit with plantuml parameter.";
+                    }
+                    return formatSuccess(response);
                 }
                 catch (error) {
                     // Try to enhance XHTML errors with location info for targeted fixes
@@ -637,14 +993,16 @@ Provide either 'content' (string) OR 'bufferId' (from buffer_create/buffer_edit)
         confluence_draft_open: {
             description: `Open an existing draft page for editing. Loads content into buffer with structure (element IDs).
 
-Use buffer_edit with element IDs to modify content, then confluence_draft_save. User publishes via Confluence UI.`,
+Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to modify, then confluence_draft_save. User publishes via Confluence UI.`,
             inputSchema: z.object({
                 draftId: z.coerce.string().describe("Draft page ID"),
             }),
             handler: async (args) => {
                 try {
                     const result = await client.getDraft(args.draftId);
-                    const content = result.body?.storage?.value || "";
+                    const rawContent = result.body?.storage?.value || "";
+                    // Collapse expanded includes back to !include directives
+                    const content = collapseExpandedIncludesInXhtml(rawContent);
                     // Store content with element IDs for structured editing
                     const { bufferId, structure } = storeXhtmlWithStructure(content, {
                         resourceType: "confluence_page",
@@ -676,14 +1034,15 @@ Use buffer_edit with element IDs to modify content, then confluence_draft_save.
             },
         },
         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) => ({
@@ -694,9 +1053,12 @@ Use buffer_edit with element IDs to modify content, then confluence_draft_save.
                         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) {
@@ -760,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;
                     }
@@ -859,6 +1221,195 @@ Drafts are NOT sent to trash - they are permanently deleted.`,
                 }
             },
         },
+        // ========================================
+        // Review Workflow Tools
+        // ========================================
+        // These tools manage the "[jicon-mcp REVIEW]" workflow for editing existing pages.
+        // Review drafts are linked to original pages via labels and can be published
+        // to apply changes to the original page.
+        confluence_review_publish: {
+            description: `Publish a review draft to apply changes to the original page.
+
+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.`,
+            inputSchema: z.object({
+                reviewDraftId: z.coerce.string().describe("ID of the [jicon-mcp REVIEW] draft to publish"),
+            }),
+            handler: async (args) => {
+                const REVIEW_PREFIX = '[jicon-mcp REVIEW] ';
+                const REVIEW_LABEL_PREFIX = 'jicon-review-';
+                try {
+                    // 1. Get review draft with labels
+                    const reviewDraft = await client.getDraft(args.reviewDraftId, [
+                        ...DEFAULT_PAGE_EXPAND,
+                        "metadata.labels",
+                    ]);
+                    // 2. Validate it's a review draft
+                    if (!reviewDraft.title.startsWith(REVIEW_PREFIX)) {
+                        return formatError({
+                            error: true,
+                            message: `Not a jicon review draft. Title must start with "${REVIEW_PREFIX}"`,
+                            statusCode: 400,
+                            details: {
+                                actualTitle: reviewDraft.title,
+                                hint: "Use confluence_draft_create with pageId to create a review draft",
+                            },
+                        });
+                    }
+                    // 3. Find original page from label
+                    const labels = reviewDraft.metadata?.labels?.results || [];
+                    const reviewLabel = labels.find((l) => l.name.startsWith(REVIEW_LABEL_PREFIX));
+                    if (!reviewLabel) {
+                        return formatError({
+                            error: true,
+                            message: "Review draft missing link to original page (no jicon-review-* label found)",
+                            statusCode: 400,
+                            details: {
+                                labels: labels.map((l) => l.name),
+                                hint: "This draft may have been created manually. Use confluence_draft_create with pageId to create proper review drafts.",
+                            },
+                        });
+                    }
+                    const originalPageId = reviewLabel.name.replace(REVIEW_LABEL_PREFIX, '');
+                    // 4. Fetch original page to get current version
+                    let originalPage;
+                    try {
+                        originalPage = await client.getPage(originalPageId, ["version", "space"]);
+                    }
+                    catch (error) {
+                        return formatError({
+                            error: true,
+                            message: `Original page ${originalPageId} not found. It may have been deleted.`,
+                            statusCode: 404,
+                            details: {
+                                originalPageId,
+                                hint: "If the original page was deleted, use confluence_review_discard to remove this review draft.",
+                            },
+                        });
+                    }
+                    // 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
+                    );
+                    // 7. Delete review draft
+                    await client.deleteDraft(args.reviewDraftId);
+                    // 8. Invalidate buffers
+                    contentBuffer.invalidateByMetadata({ resourceId: originalPageId });
+                    contentBuffer.invalidateByMetadata({ resourceId: args.reviewDraftId });
+                    // Build the page URL
+                    const baseUrl = client.getBaseUrl();
+                    const pageUrl = `${baseUrl}${updatedPage._links?.webui || `/pages/viewpage.action?pageId=${originalPageId}`}`;
+                    return formatSuccess({
+                        success: true,
+                        originalPageId,
+                        originalTitle: updatedPage.title,
+                        newVersion: updatedPage.version?.number,
+                        reviewDraftDeleted: args.reviewDraftId,
+                        viewUrl: pageUrl,
+                        message: `Changes from review draft applied to page "${updatedPage.title}" (version ${updatedPage.version?.number}). Review draft deleted.`,
+                    });
+                }
+                catch (error) {
+                    return formatError(isApiError(error) ? error : new Error(String(error)));
+                }
+            },
+        },
+        confluence_review_discard: {
+            description: `Discard a review draft without applying changes to the original page.
+
+This tool:
+1. Validates the draft is a "[jicon-mcp REVIEW]" draft
+2. Deletes the review draft permanently
+3. Original page remains unchanged`,
+            inputSchema: z.object({
+                reviewDraftId: z.coerce.string().describe("ID of the [jicon-mcp REVIEW] draft to discard"),
+            }),
+            handler: async (args) => {
+                const REVIEW_PREFIX = '[jicon-mcp REVIEW] ';
+                try {
+                    // 1. Get review draft to validate
+                    const reviewDraft = await client.getDraft(args.reviewDraftId);
+                    // 2. Validate it's a review draft
+                    if (!reviewDraft.title.startsWith(REVIEW_PREFIX)) {
+                        return formatError({
+                            error: true,
+                            message: `Not a jicon review draft. Title must start with "${REVIEW_PREFIX}"`,
+                            statusCode: 400,
+                            details: {
+                                actualTitle: reviewDraft.title,
+                                hint: "Use confluence_draft_delete for non-review drafts",
+                            },
+                        });
+                    }
+                    // 3. Delete review draft
+                    await client.deleteDraft(args.reviewDraftId);
+                    // 4. Invalidate buffer
+                    contentBuffer.invalidateByMetadata({ resourceId: args.reviewDraftId });
+                    return formatSuccess({
+                        success: true,
+                        discarded: true,
+                        reviewDraftId: args.reviewDraftId,
+                        originalTitle: reviewDraft.title.replace(REVIEW_PREFIX, ''),
+                        message: "Review draft discarded. Original page was not modified.",
+                    });
+                }
+                catch (error) {
+                    return formatError(isApiError(error) ? error : new Error(String(error)));
+                }
+            },
+        },
+        confluence_review_list: {
+            description: `List all "[jicon-mcp REVIEW]" drafts for cleanup or management.
+
+Returns review drafts with their linked original page IDs.
+Use this to find abandoned review drafts or manage multiple review workflows.`,
+            inputSchema: z.object({
+                spaceKey: z.string().optional().describe("Filter by space key (optional)"),
+            }),
+            handler: async (args) => {
+                const REVIEW_PREFIX = '[jicon-mcp REVIEW] ';
+                const REVIEW_LABEL_PREFIX = 'jicon-review-';
+                try {
+                    // 1. List user's drafts with labels expanded
+                    const drafts = await client.listUserDrafts(args.spaceKey, 500);
+                    // 2. Filter to review drafts only
+                    const reviewDrafts = drafts.results.filter((draft) => draft.title?.startsWith(REVIEW_PREFIX));
+                    // 3. Build response with original page info from labels
+                    const baseUrl = client.getBaseUrl();
+                    const reviews = reviewDrafts.map((draft) => {
+                        const labels = draft.metadata?.labels?.results || [];
+                        const reviewLabel = labels.find((l) => l.name.startsWith(REVIEW_LABEL_PREFIX));
+                        const originalPageId = reviewLabel?.name.replace(REVIEW_LABEL_PREFIX, '') || 'unknown';
+                        return {
+                            reviewDraftId: draft.id,
+                            title: draft.title,
+                            originalTitle: draft.title.replace(REVIEW_PREFIX, ''),
+                            originalPageId,
+                            spaceKey: draft.space?.key || '',
+                            spaceName: draft.space?.name || '',
+                            createdDate: draft.version?.when || '',
+                            editUrl: `${baseUrl}/pages/resumedraft.action?draftId=${draft.id}`,
+                        };
+                    });
+                    return formatSuccess({
+                        reviewDrafts: reviews,
+                        total: reviews.length,
+                        message: reviews.length > 0
+                            ? `Found ${reviews.length} review draft(s). Use confluence_review_publish or confluence_review_discard to manage.`
+                            : "No review drafts found.",
+                    });
+                }
+                catch (error) {
+                    return formatError(isApiError(error) ? error : new Error(String(error)));
+                }
+            },
+        },
     };
 }
 //# sourceMappingURL=tools.js.map