@crypto512/jicon-mcp 1.0.3 → 1.1.0

package/dist/utils/buffer-tools.js

@@ -10,8 +10,10 @@ import * as fs from "fs";
 import * as path from "path";
 import { contentBuffer } from "./content-buffer.js";
 import { formatSuccess, formatError, getMaxOutputSize } from "./response-formatter.js";
-import { BufferEditXhtmlSchema, parseXhtml, serializeXhtml, executeOperation, validateXhtml, validateXhtmlAsync, validatePlantUml, buildPlantUmlMacro, querySelector, updatePlantUmlInMacro, resolveSemanticPosition, findUnsupportedPseudo, } from "./xhtml/index.js";
-import { validate as validatePlantUmlWithDocker, isAvailable as isPlantUmlServiceAvailable } from "./plantuml/service.js";
+import { parseXhtml, serializeXhtml, validateXhtmlAsync, buildPlantUmlMacro, detectRawPlantUml, 
+// Element ID-based operations
+parseStructure, insertById, appendToDocument, replaceById, removeById, } from "./xhtml/index.js";
+import { validatePlantUmlWithFallback } from "./plantuml/index.js";
 /**
  * Format grep results as text output similar to grep CLI
  */
@@ -86,9 +88,14 @@ function isBinaryContentType(contentType) {
 export function createBufferTools() {
     return {
         buffer_create: {
-            description: `Create a new buffer with initial content. Use this to draft new content (e.g., for new Confluence pages) before persisting. Returns bufferId for use with buffer_edit and other buffer tools.`,
+            description: `Create a new buffer with initial content. Returns bufferId and structure (for XHTML).
+
+For XHTML content, returns structure with element IDs for use with buffer_edit:
+- Each element gets a unique ID (stable during session)
+- Use buffer_edit with after/before/replace to modify by element ID`,
             inputSchema: z.object({
                 content: z.string().describe("Initial content for the buffer"),
+                contentType: z.enum(["xhtml", "plain", "json"]).describe("Content type: 'xhtml' for Confluence, 'plain' for text, 'json' for data"),
                 metadata: z
                     .record(z.unknown())
                     .optional()
@@ -96,15 +103,65 @@ export function createBufferTools() {
             }),
             handler: async (args) => {
                 try {
-                    const bufferId = contentBuffer.store(args.content, args.metadata);
+                    const mergedMetadata = {
+                        ...args.metadata,
+                        contentType: args.contentType,
+                    };
+                    let bufferId;
+                    let structure;
+                    let nextId;
+                    if (args.contentType === "xhtml") {
+                        // Check for common CDATA mistake: wrapping entire content in CDATA
+                        const trimmedContent = args.content.trim();
+                        if (trimmedContent.startsWith("<![CDATA[")) {
+                            return formatError({
+                                error: true,
+                                message: "Content starts with CDATA wrapper. Remove <![CDATA[ and ]]> from the content parameter.",
+                                statusCode: 400,
+                                details: {
+                                    hint: "CDATA is only used inside <ac:plain-text-body> elements (for code blocks and PlantUML). Never wrap the entire content in CDATA.",
+                                    example: "Use: <h1>Title</h1><p>Text</p>\nNot: <![CDATA[<h1>Title</h1><p>Text</p>]]>",
+                                    helpTopic: 'Call help(topic="storage") for Confluence XHTML format guide.',
+                                },
+                            });
+                        }
+                        // Parse XHTML and build structure with element IDs
+                        const parseResult = parseXhtml(args.content);
+                        if (!parseResult.document) {
+                            return formatError({
+                                error: true,
+                                message: `Failed to parse XHTML: ${parseResult.error?.message}`,
+                                statusCode: 400,
+                                details: {
+                                    parseError: parseResult.error?.message,
+                                    line: parseResult.error?.line,
+                                    column: parseResult.error?.column,
+                                },
+                            });
+                        }
+                        // Assign IDs and get structure
+                        const structureResult = parseStructure(parseResult.document);
+                        structure = structureResult.structure;
+                        nextId = structureResult.nextId;
+                        // Serialize back (now with data-jicon-id attributes)
+                        const contentWithIds = serializeXhtml(parseResult.document);
+                        bufferId = contentBuffer.storeWithStructure(contentWithIds, structure, nextId, mergedMetadata);
+                    }
+                    else {
+                        bufferId = contentBuffer.store(args.content, mergedMetadata);
+                    }
                     const info = contentBuffer.getInfo(bufferId);
                     return formatSuccess({
                         bufferId,
                         totalSize: info?.totalSize ?? args.content.length,
+                        contentType: args.contentType,
                         createdAt: info ? new Date(info.createdAt).toISOString() : new Date().toISOString(),
                         expiresAt: info ? new Date(info.expiresAt).toISOString() : undefined,
-                        metadata: args.metadata,
-                        message: "Buffer created. Use buffer_edit to modify, buffer_get_chunk to read.",
+                        metadata: mergedMetadata,
+                        ...(structure && { structure, nextId }),
+                        message: args.contentType === "xhtml"
+                            ? "Buffer created with element IDs. Use buffer_edit with after/before/replace to modify."
+                            : "Buffer created.",
                     });
                 }
                 catch (error) {
@@ -343,81 +400,57 @@ Example: Find buffer for draft 12345 → look for metadata.resourceId === "12345
             },
         },
         buffer_edit: {
-            description: `Exact string replacement in buffered content. Fails if old_string is not unique (use replace_all=true for all occurrences). Changes are in-memory only - call update API to persist.
+            description: `Edit buffer content. For XHTML buffers, use element IDs. For plain/json, use string replacement.
 
-For Confluence content: Use buffer_edit_xhtml instead for structure-aware editing (tables, macros, layouts). Call help(topic="storage") for guide.`,
-            inputSchema: z.object({
-                bufferId: z.string().describe("Buffer ID to modify"),
-                old_string: z.string().describe("Exact text to replace"),
-                new_string: z.string().describe("Replacement text"),
-                replace_all: z
-                    .boolean()
-                    .optional()
-                    .default(false)
-                    .describe("Replace all occurrences (default: false, fails if not unique)"),
-            }),
-            handler: async (args) => {
-                try {
-                    // Check if buffer contains XHTML content - reject to force use of buffer_edit_xhtml
-                    const bufferInfo = contentBuffer.getInfo(args.bufferId);
-                    if (bufferInfo?.metadata?.contentType === "xhtml") {
-                        return formatError({
-                            error: true,
-                            message: "This buffer contains Confluence XHTML content. Use buffer_edit_xhtml instead for proper structure-aware editing.",
-                            statusCode: 400,
-                            details: {
-                                hint: "For PlantUML diagrams, use: buffer_edit_xhtml(bufferId, operation='insert-plantuml', ...)",
-                                contentType: "xhtml",
-                            },
-                        });
-                    }
-                    const result = contentBuffer.edit(args.bufferId, args.old_string, args.new_string, args.replace_all ?? false);
-                    if (!result) {
-                        return formatError({
-                            error: true,
-                            message: `Buffer not found or expired: ${args.bufferId}`,
-                            statusCode: 404,
-                        });
-                    }
-                    // Check if it's an error result
-                    if ("error" in result && result.error) {
-                        return formatError({
-                            error: true,
-                            message: result.message,
-                            statusCode: 400,
-                            details: { occurrences: result.occurrences },
-                        });
-                    }
-                    return formatSuccess(result);
-                }
-                catch (error) {
-                    return formatError(error instanceof Error ? error : new Error(String(error)));
-                }
-            },
-        },
-        buffer_edit_xhtml: {
-            description: `Structure-aware XHTML editing for Confluence storage format. Supports CSS-like selectors to target elements, with operations: insert, insert-plantuml, update, update-plantuml, remove, move, wrap.
+XHTML editing (by element ID) - single operation:
+- after: Insert content after element with this ID
+- before: Insert content before element with this ID
+- replace: Replace element with this ID
+- append: Add content at document end
+- remove: Remove element with this ID
+- content: XHTML to insert/replace
+- plantuml: PlantUML code (auto-wrapped in Confluence macro)
 
-Selector syntax:
-- Tag: 'p', 'h1', 'table'
-- Namespaced: 'ac:structured-macro', 'ri:page'
-- Attributes: '[ac:name="plantuml"]', 'ac:structured-macro[ac:name="code"]'
-- Pseudo: ':nth-child(2)', ':first-child', ':last-child'
-- Descendants: 'table tbody tr'
-- Direct child: 'ul > li'
+XHTML batch editing - multiple operations in one call:
+- operations: Array of {after?, before?, replace?, append?, remove?, content?, plantuml?}
+- Operations are executed sequentially; stops on first error
+- Much more efficient than multiple tool calls (parse once, serialize once)
 
-Semantic positions (for insert-plantuml, alternative to selector):
-- 'after-title': After first h1 or h2
-- 'after-heading': After first heading (h1-h6)
-- 'before-content': At document start
-- 'end': At document end
-- 'after-toc': After table of contents macro
+Example batch: operations=[{after:6, plantuml:"@startuml..."}, {after:8, plantuml:"@startuml..."}]
 
-PlantUML: Use plantuml_validate first for full Docker-based validation. This tool uses basic sync validation.`,
-            inputSchema: BufferEditXhtmlSchema,
+Plain/JSON editing (string replacement):
+- old_string: Text to replace
+- new_string: Replacement text
+- replace_all: Replace all occurrences
+
+Returns updated structure for XHTML buffers.`,
+            inputSchema: z.object({
+                bufferId: z.string().describe("Buffer ID to modify"),
+                // XHTML batch operations
+                operations: z.array(z.object({
+                    after: z.number().optional().describe("Insert after element with this ID"),
+                    before: z.number().optional().describe("Insert before element with this ID"),
+                    replace: z.number().optional().describe("Replace element with this ID"),
+                    append: z.boolean().optional().describe("Append content at document end"),
+                    remove: z.number().optional().describe("Remove element with this ID"),
+                    content: z.string().optional().describe("XHTML content to insert/replace"),
+                    plantuml: z.string().optional().describe("PlantUML code (auto-wrapped in macro)"),
+                })).optional().describe("Array of XHTML operations to execute sequentially (more efficient than multiple calls)"),
+                // XHTML element ID operations (single operation - backwards compatible)
+                after: z.number().optional().describe("Insert after element with this ID"),
+                before: z.number().optional().describe("Insert before element with this ID"),
+                replace: z.number().optional().describe("Replace element with this ID"),
+                append: z.boolean().optional().describe("Append content at document end"),
+                remove: z.number().optional().describe("Remove element with this ID"),
+                content: z.string().optional().describe("XHTML content to insert/replace"),
+                plantuml: z.string().optional().describe("PlantUML code (auto-wrapped in macro)"),
+                // Plain text operations
+                old_string: z.string().optional().describe("Text to replace (plain/json only)"),
+                new_string: z.string().optional().describe("Replacement text (plain/json only)"),
+                replace_all: z.boolean().optional().default(false).describe("Replace all occurrences"),
+            }),
             handler: async (args) => {
                 try {
-                    // Get buffer content
                     const bufferInfo = contentBuffer.getInfo(args.bufferId);
                     if (!bufferInfo) {
                         return formatError({
@@ -426,326 +459,334 @@ PlantUML: Use plantuml_validate first for full Docker-based validation. This too
                             statusCode: 404,
                         });
                     }
-                    const chunk = contentBuffer.getChunk(args.bufferId, 0, bufferInfo.totalSize);
-                    if (!chunk) {
-                        return formatError({
-                            error: true,
-                            message: `Failed to read buffer: ${args.bufferId}`,
-                            statusCode: 500,
-                        });
-                    }
-                    const originalContent = chunk.chunk;
-                    const oldSize = originalContent.length;
-                    // Parse XHTML
-                    const parseResult = parseXhtml(originalContent);
-                    if (!parseResult.document) {
-                        return formatError({
-                            error: true,
-                            message: `Failed to parse XHTML: ${parseResult.error?.message}`,
-                            statusCode: 400,
-                            details: {
-                                parseError: parseResult.error?.message,
-                                line: parseResult.error?.line,
-                                column: parseResult.error?.column,
-                                context: parseResult.error?.context,
-                                hint: parseResult.error?.context
-                                    ? `Check near: "${parseResult.error.context.substring(0, 60)}${parseResult.error.context.length > 60 ? "..." : ""}"`
-                                    : undefined,
-                            },
-                        });
-                    }
-                    // Handle PlantUML operations specially
-                    let contentToInsert = args.content;
-                    const operation = args.operation;
-                    let resolvedSelector = args.selector;
-                    let resolvedPosition = args.position;
-                    let insertDiagramType; // Track diagram type for insert-plantuml
-                    // Check if we need to derive selector from semanticPosition
-                    if (!resolvedSelector && args.semanticPosition) {
-                        const resolved = resolveSemanticPosition(parseResult.document, args.semanticPosition);
-                        if (resolved) {
-                            resolvedSelector = resolved.selector;
-                            resolvedPosition = resolved.position;
+                    const isXhtml = bufferInfo.metadata?.contentType === "xhtml";
+                    // XHTML editing with element IDs
+                    if (isXhtml) {
+                        let operations;
+                        if (args.operations && args.operations.length > 0) {
+                            // Batch mode: use operations array
+                            operations = args.operations;
                         }
                         else {
+                            // Single operation mode (backwards compatible)
+                            const hasIdOperation = args.after !== undefined || args.before !== undefined ||
+                                args.replace !== undefined || args.append || args.remove !== undefined;
+                            if (!hasIdOperation) {
+                                return formatError({
+                                    error: true,
+                                    message: "XHTML buffer requires element ID operation: after, before, replace, append, remove, or operations array",
+                                    statusCode: 400,
+                                    details: {
+                                        structure: bufferInfo.structure,
+                                        nextId: bufferInfo.nextId,
+                                        hint: "Use after=ID, before=ID, replace=ID, append=true, remove=ID, or operations=[...]",
+                                    },
+                                });
+                            }
+                            operations = [{
+                                    after: args.after,
+                                    before: args.before,
+                                    replace: args.replace,
+                                    append: args.append,
+                                    remove: args.remove,
+                                    content: args.content,
+                                    plantuml: args.plantuml,
+                                }];
+                        }
+                        // Get buffer content
+                        const chunk = contentBuffer.getChunk(args.bufferId, 0, bufferInfo.totalSize);
+                        if (!chunk) {
                             return formatError({
                                 error: true,
-                                message: `Could not resolve semantic position: ${args.semanticPosition}`,
-                                statusCode: 400,
-                                details: {
-                                    semanticPosition: args.semanticPosition,
-                                    hint: "Document may be empty or missing required elements",
-                                },
+                                message: `Failed to read buffer: ${args.bufferId}`,
+                                statusCode: 500,
                             });
                         }
-                    }
-                    // Check that we have a selector (either provided or derived from semanticPosition)
-                    if (!resolvedSelector) {
-                        return formatError({
-                            error: true,
-                            message: "Either selector or semanticPosition is required",
-                            statusCode: 400,
-                            details: {
-                                hint: "Provide selector (e.g., 'h1', 'table', 'ac:structured-macro[ac:name=\"plantuml\"]') or semanticPosition (e.g., 'after-title', 'end')",
-                            },
-                        });
-                    }
-                    if (operation === "insert-plantuml") {
-                        if (!args.plantuml) {
+                        // Parse XHTML once
+                        const parseResult = parseXhtml(chunk.chunk);
+                        if (!parseResult.document) {
                             return formatError({
                                 error: true,
-                                message: "plantuml parameter is required for insert-plantuml operation",
+                                message: `Failed to parse XHTML: ${parseResult.error?.message}`,
                                 statusCode: 400,
                             });
                         }
-                        // Validate PlantUML - use Docker service if available, else fallback to basic validation
-                        let normalizedCode;
-                        if (isPlantUmlServiceAvailable()) {
-                            // Use Docker-based validation
-                            try {
-                                const dockerValidation = await validatePlantUmlWithDocker(args.plantuml);
-                                if (!dockerValidation.valid) {
+                        const oldSize = chunk.chunk.length;
+                        let nextId = bufferInfo.nextId ?? 1;
+                        const allInsertedIds = [];
+                        const diagramTypes = [];
+                        // Execute all operations sequentially
+                        for (let opIndex = 0; opIndex < operations.length; opIndex++) {
+                            const op = operations[opIndex];
+                            // Build content to insert (handle plantuml specially)
+                            let contentToInsert = op.content;
+                            let diagramType;
+                            if (op.plantuml) {
+                                // Validate PlantUML
+                                const validation = await validatePlantUmlWithFallback(op.plantuml, "insert-plantuml", {});
+                                if (!validation.valid) {
+                                    // Return error with operation index for debugging
+                                    const errorResult = validation.error;
+                                    const errorData = JSON.parse(errorResult.content[0].text);
+                                    errorData.operationIndex = opIndex;
+                                    errorData.completedOperations = opIndex;
+                                    return {
+                                        content: [{ type: "text", text: JSON.stringify(errorData, null, 2) }],
+                                    };
+                                }
+                                contentToInsert = buildPlantUmlMacro(validation.normalizedCode);
+                                diagramType = validation.diagramType;
+                                if (diagramType)
+                                    diagramTypes.push(diagramType);
+                            }
+                            // Execute single operation
+                            let result;
+                            if (op.remove !== undefined) {
+                                result = removeById(parseResult.document, op.remove);
+                            }
+                            else if (op.replace !== undefined) {
+                                if (!contentToInsert) {
                                     return formatError({
                                         error: true,
-                                        message: "PlantUML syntax error",
+                                        message: `Operation ${opIndex + 1}: content or plantuml required for replace operation`,
                                         statusCode: 400,
-                                        details: {
-                                            plantumlErrors: dockerValidation.errors,
-                                            diagramType: dockerValidation.diagramType,
-                                            hint: "Check plantuml_validate for detailed error info",
-                                        },
                                     });
                                 }
-                                normalizedCode = dockerValidation.normalizedCode;
-                                insertDiagramType = dockerValidation.diagramType;
+                                result = replaceById(parseResult.document, op.replace, contentToInsert);
                             }
-                            catch (error) {
-                                // Docker error - fallback to basic validation
-                                const basicValidation = validatePlantUml(args.plantuml);
-                                if (!basicValidation.valid) {
+                            else if (op.append) {
+                                if (!contentToInsert) {
                                     return formatError({
                                         error: true,
-                                        message: "PlantUML syntax error",
+                                        message: `Operation ${opIndex + 1}: content or plantuml required for append operation`,
                                         statusCode: 400,
-                                        details: {
-                                            plantumlError: basicValidation.error,
-                                        },
                                     });
                                 }
-                                normalizedCode = basicValidation.normalizedCode;
-                                insertDiagramType = basicValidation.diagramType;
-                            }
-                        }
-                        else {
-                            // Use basic synchronous validation
-                            const basicValidation = validatePlantUml(args.plantuml);
-                            if (!basicValidation.valid) {
-                                return formatError({
-                                    error: true,
-                                    message: "PlantUML syntax error",
-                                    statusCode: 400,
-                                    details: {
-                                        plantumlError: basicValidation.error,
-                                        hint: "Use plantuml_validate for full Docker-based validation",
-                                    },
-                                });
+                                result = appendToDocument(parseResult.document, contentToInsert, nextId);
+                                if (result.nextId)
+                                    nextId = result.nextId;
                             }
-                            normalizedCode = basicValidation.normalizedCode;
-                            insertDiagramType = basicValidation.diagramType;
-                        }
-                        // Build the macro
-                        contentToInsert = buildPlantUmlMacro(normalizedCode, args.macroId);
-                    }
-                    else if (operation === "update-plantuml") {
-                        if (!args.plantuml) {
-                            return formatError({
-                                error: true,
-                                message: "plantuml parameter is required for update-plantuml operation",
-                                statusCode: 400,
-                            });
-                        }
-                        // Validate PlantUML - use Docker service if available, else fallback to basic validation
-                        let normalizedCode;
-                        let updateDiagramType;
-                        if (isPlantUmlServiceAvailable()) {
-                            // Use Docker-based validation
-                            try {
-                                const dockerValidation = await validatePlantUmlWithDocker(args.plantuml);
-                                if (!dockerValidation.valid) {
+                            else if (op.after !== undefined) {
+                                if (!contentToInsert) {
                                     return formatError({
                                         error: true,
-                                        message: "PlantUML syntax error",
+                                        message: `Operation ${opIndex + 1}: content or plantuml required for after operation`,
                                         statusCode: 400,
-                                        details: {
-                                            plantumlErrors: dockerValidation.errors,
-                                            diagramType: dockerValidation.diagramType,
-                                            hint: "Check plantuml_validate for detailed error info",
-                                        },
                                     });
                                 }
-                                normalizedCode = dockerValidation.normalizedCode;
-                                updateDiagramType = dockerValidation.diagramType;
+                                result = insertById(parseResult.document, op.after, "after", contentToInsert, nextId);
+                                if (result.nextId)
+                                    nextId = result.nextId;
                             }
-                            catch (error) {
-                                // Docker error - fallback to basic validation
-                                const basicValidation = validatePlantUml(args.plantuml);
-                                if (!basicValidation.valid) {
+                            else if (op.before !== undefined) {
+                                if (!contentToInsert) {
                                     return formatError({
                                         error: true,
-                                        message: "PlantUML syntax error",
+                                        message: `Operation ${opIndex + 1}: content or plantuml required for before operation`,
                                         statusCode: 400,
-                                        details: {
-                                            plantumlError: basicValidation.error,
-                                        },
                                     });
                                 }
-                                normalizedCode = basicValidation.normalizedCode;
-                                updateDiagramType = basicValidation.diagramType;
+                                result = insertById(parseResult.document, op.before, "before", contentToInsert, nextId);
+                                if (result.nextId)
+                                    nextId = result.nextId;
                             }
-                        }
-                        else {
-                            // Use basic synchronous validation
-                            const basicValidation = validatePlantUml(args.plantuml);
-                            if (!basicValidation.valid) {
+                            else {
                                 return formatError({
                                     error: true,
-                                    message: "PlantUML syntax error",
+                                    message: `Operation ${opIndex + 1}: No valid operation specified (need after, before, replace, append, or remove)`,
                                     statusCode: 400,
-                                    details: {
-                                        plantumlError: basicValidation.error,
-                                        hint: "Use plantuml_validate for full Docker-based validation",
-                                    },
                                 });
                             }
-                            normalizedCode = basicValidation.normalizedCode;
-                            updateDiagramType = basicValidation.diagramType;
-                        }
-                        // Find the macro element and update it directly
-                        const selectorResult = querySelector(parseResult.document, args.selector);
-                        if (selectorResult.matches.length === 0) {
-                            const unsupportedPseudo = findUnsupportedPseudo(args.selector);
-                            const hint = unsupportedPseudo
-                                ? `Pseudo-selector ':${unsupportedPseudo}' is not supported. Use ':contains("text")' to find elements by text content, or use 'ac:structured-macro[ac:name="plantuml"]' with matchIndex.`
-                                : "Use 'ac:structured-macro[ac:name=\"plantuml\"]' to find PlantUML macros, or use matchIndex if multiple exist.";
-                            return formatError({
-                                error: true,
-                                message: `No elements match selector: ${args.selector}`,
-                                statusCode: 400,
-                                details: { selector: args.selector, matchCount: 0, hint },
-                            });
-                        }
-                        const targetIndex = args.matchIndex ?? 0;
-                        if (targetIndex >= selectorResult.matches.length) {
-                            return formatError({
-                                error: true,
-                                message: `matchIndex ${targetIndex} out of range (${selectorResult.matches.length} matches)`,
-                                statusCode: 400,
-                            });
-                        }
-                        const macroElement = selectorResult.matches[targetIndex].element;
-                        // Verify it's a plantuml macro
-                        if (macroElement.tagName.toLowerCase() !== "ac:structured-macro" ||
-                            macroElement.getAttribute("ac:name") !== "plantuml") {
-                            return formatError({
-                                error: true,
-                                message: "Selected element is not a PlantUML macro",
-                                statusCode: 400,
-                            });
-                        }
-                        // Update the macro content
-                        const updated = updatePlantUmlInMacro(macroElement, normalizedCode);
-                        if (!updated) {
-                            return formatError({
-                                error: true,
-                                message: "Failed to update PlantUML macro content",
-                                statusCode: 500,
-                            });
-                        }
-                        // Serialize and update buffer
-                        const newContent = serializeXhtml(parseResult.document);
-                        // Validate if requested
-                        if (args.validate !== false) {
-                            const validationResult = validateXhtml(newContent);
-                            if (!validationResult.valid) {
-                                const firstError = validationResult.errors[0];
+                            if (!result.success) {
                                 return formatError({
                                     error: true,
-                                    message: `Resulting XHTML is invalid: ${firstError?.message || "Unknown error"}`,
+                                    message: `Operation ${opIndex + 1} failed: ${result.error || "Unknown error"}`,
                                     statusCode: 400,
                                     details: {
-                                        validationErrors: validationResult.errors,
-                                        hint: firstError?.location?.context
-                                            ? `Check near: "${firstError.location.context.substring(0, 60)}${firstError.location.context.length > 60 ? "..." : ""}"`
-                                            : undefined,
+                                        operationIndex: opIndex,
+                                        completedOperations: opIndex,
+                                        operation: op,
+                                        structure: bufferInfo.structure,
+                                        nextId: bufferInfo.nextId,
                                     },
                                 });
                             }
+                            // Collect inserted IDs
+                            if (result.insertedIds) {
+                                allInsertedIds.push(...result.insertedIds);
+                            }
                         }
-                        // Update buffer in place (keeps same buffer ID)
-                        contentBuffer.update(args.bufferId, newContent, { contentType: "xhtml" });
+                        // Serialize and update buffer once (after all operations)
+                        const newContent = serializeXhtml(parseResult.document);
+                        // Rebuild structure
+                        const newStructure = parseStructure(parseResult.document);
+                        // Update buffer
+                        contentBuffer.update(args.bufferId, newContent, { contentType: "xhtml" }, newStructure.structure, newStructure.nextId);
                         return formatSuccess({
                             bufferId: args.bufferId,
                             success: true,
-                            operation: "update-plantuml",
-                            matchCount: 1,
+                            operationsCompleted: operations.length,
                             oldSize,
                             newSize: newContent.length,
-                            affectedElements: ["ac:structured-macro"],
-                            diagramType: updateDiagramType,
+                            structure: newStructure.structure,
+                            nextId: newStructure.nextId,
+                            ...(allInsertedIds.length > 0 && { insertedIds: allInsertedIds }),
+                            ...(diagramTypes.length > 0 && { diagramTypes }),
+                        });
+                    }
+                    // Plain text/JSON editing
+                    if (args.old_string === undefined || args.new_string === undefined) {
+                        return formatError({
+                            error: true,
+                            message: "old_string and new_string required for plain/json buffer editing",
+                            statusCode: 400,
+                        });
+                    }
+                    const result = contentBuffer.edit(args.bufferId, args.old_string, args.new_string, args.replace_all ?? false);
+                    if (!result) {
+                        return formatError({
+                            error: true,
+                            message: `Buffer not found or expired: ${args.bufferId}`,
+                            statusCode: 404,
                         });
                     }
-                    // Execute the operation
-                    const result = executeOperation(parseResult.document, operation, resolvedSelector, {
-                        position: resolvedPosition,
-                        content: contentToInsert,
-                        attributes: args.attributes,
-                        targetSelector: args.targetSelector,
-                        matchIndex: args.matchIndex,
-                        matchAll: args.matchAll,
-                    });
                     if ("error" in result && result.error) {
                         return formatError({
                             error: true,
                             message: result.message,
                             statusCode: 400,
-                            details: result.details,
+                            details: { occurrences: result.occurrences },
                         });
                     }
-                    // Serialize back to XHTML
-                    const newContent = serializeXhtml(parseResult.document);
-                    // Validate if requested
-                    if (args.validate !== false) {
-                        const validationResult = validateXhtml(newContent);
-                        if (!validationResult.valid) {
-                            const firstError = validationResult.errors[0];
-                            return formatError({
-                                error: true,
-                                message: `Resulting XHTML is invalid: ${firstError?.message || "Unknown error"}`,
-                                statusCode: 400,
-                                details: {
-                                    validationErrors: validationResult.errors,
-                                    hint: firstError?.location?.context
-                                        ? `Check near: "${firstError.location.context.substring(0, 60)}${firstError.location.context.length > 60 ? "..." : ""}"`
-                                        : undefined,
-                                },
-                            });
-                        }
+                    return formatSuccess(result);
+                }
+                catch (error) {
+                    return formatError(error instanceof Error ? error : new Error(String(error)));
+                }
+            },
+        },
+        buffer_get_structure: {
+            description: `Get current element structure for an XHTML buffer. Returns element IDs for use with buffer_edit.
+
+Each element has:
+- id: Unique ID (stable during session)
+- type: Element type ("h1", "h2", "p", "plantuml", "ul", etc.)
+- text: Preview text (truncated)
+- children: Child count for lists/tables`,
+            inputSchema: z.object({
+                bufferId: z.string().describe("Buffer ID to get structure for"),
+            }),
+            handler: async (args) => {
+                try {
+                    const bufferInfo = contentBuffer.getInfo(args.bufferId);
+                    if (!bufferInfo) {
+                        return formatError({
+                            error: true,
+                            message: `Buffer not found or expired: ${args.bufferId}`,
+                            statusCode: 404,
+                        });
+                    }
+                    if (bufferInfo.metadata?.contentType !== "xhtml") {
+                        return formatError({
+                            error: true,
+                            message: "Buffer is not XHTML content",
+                            statusCode: 400,
+                            details: {
+                                contentType: bufferInfo.metadata?.contentType,
+                                hint: "Structure is only available for XHTML buffers",
+                            },
+                        });
                     }
-                    // Update buffer in place (keeps same buffer ID)
-                    contentBuffer.update(args.bufferId, newContent, { contentType: "xhtml" });
-                    // Check if buffer is associated with a Confluence draft and add nextStep hint
-                    const updatedBufferInfo = contentBuffer.getInfo(args.bufferId);
-                    const isDraft = updatedBufferInfo?.metadata?.isDraft === true;
-                    const isConfluencePage = updatedBufferInfo?.metadata?.resourceType === "confluence_page";
                     return formatSuccess({
-                        ...result,
                         bufferId: args.bufferId,
-                        oldSize,
-                        newSize: newContent.length,
-                        ...(insertDiagramType && { diagramType: insertDiagramType }),
-                        ...((isDraft || isConfluencePage) && {
-                            nextStep: "Call confluence_draft_save(bufferId) to persist changes to Confluence",
-                        }),
+                        structure: bufferInfo.structure ?? [],
+                        nextId: bufferInfo.nextId ?? 1,
+                    });
+                }
+                catch (error) {
+                    return formatError(error instanceof Error ? error : new Error(String(error)));
+                }
+            },
+        },
+        buffer_get_element: {
+            description: `Get the raw XHTML content of a specific element by ID.
+
+Use this to inspect problematic elements when fixing XHTML parsing errors.
+Returns the element's outerHTML, type, and line count.
+
+Example: After a Confluence error at element 12, use this to see the content:
+  buffer_get_element(bufferId="buf_xxx", elementId=12)`,
+            inputSchema: z.object({
+                bufferId: z.string().describe("Buffer ID containing XHTML content"),
+                elementId: z.number().describe("Element ID from buffer structure"),
+            }),
+            handler: async (args) => {
+                try {
+                    const bufferInfo = contentBuffer.getInfo(args.bufferId);
+                    if (!bufferInfo) {
+                        return formatError({
+                            error: true,
+                            message: `Buffer not found or expired: ${args.bufferId}`,
+                            statusCode: 404,
+                        });
+                    }
+                    if (bufferInfo.metadata?.contentType !== "xhtml") {
+                        return formatError({
+                            error: true,
+                            message: "Buffer is not XHTML content",
+                            statusCode: 400,
+                        });
+                    }
+                    // Get full buffer content
+                    const chunk = contentBuffer.getChunk(args.bufferId, 0, bufferInfo.totalSize);
+                    if (!chunk) {
+                        return formatError({
+                            error: true,
+                            message: `Failed to read buffer: ${args.bufferId}`,
+                            statusCode: 500,
+                        });
+                    }
+                    // Parse and find element
+                    const parseResult = parseXhtml(chunk.chunk);
+                    if (!parseResult.document) {
+                        return formatError({
+                            error: true,
+                            message: `Failed to parse XHTML: ${parseResult.error?.message}`,
+                            statusCode: 400,
+                        });
+                    }
+                    const root = parseResult.document.querySelector("xhtml-root");
+                    if (!root) {
+                        return formatError({
+                            error: true,
+                            message: "XHTML has no content root",
+                            statusCode: 400,
+                        });
+                    }
+                    const element = root.querySelector(`[data-jicon-id="${args.elementId}"]`);
+                    if (!element) {
+                        return formatError({
+                            error: true,
+                            message: `Element not found: ${args.elementId}`,
+                            statusCode: 404,
+                            details: {
+                                availableIds: bufferInfo.structure?.map((e) => e.id) ?? [],
+                            },
+                        });
+                    }
+                    const content = element.outerHTML;
+                    const lineCount = (content.match(/\n/g) || []).length + 1;
+                    // Determine element type
+                    let elementType = element.tagName.toLowerCase();
+                    if (elementType === "ac:structured-macro") {
+                        elementType = element.getAttribute("ac:name") || "macro";
+                    }
+                    return formatSuccess({
+                        bufferId: args.bufferId,
+                        elementId: args.elementId,
+                        elementType,
+                        lineCount,
+                        content,
                     });
                 }
                 catch (error) {
@@ -795,10 +836,24 @@ Use this to validate content before calling confluence_update_page or confluence
                             statusCode: 500,
                         });
                     }
+                    // Check for raw PlantUML (same check as confluence_draft_create)
+                    // This ensures validation and draft creation agree on what's valid
+                    const rawPlantUml = detectRawPlantUml(chunk.chunk);
                     // Validate XHTML with async PlantUML validation
                     const validationResult = await validateXhtmlAsync(chunk.chunk, {
                         validatePlantUml: args.validatePlantUml !== false,
                     });
+                    // Add raw PlantUML error if detected
+                    if (rawPlantUml) {
+                        validationResult.errors.push({
+                            type: "raw_plantuml",
+                            message: "Content contains raw PlantUML code that is not wrapped in a Confluence macro.",
+                            location: {
+                                context: rawPlantUml.hint,
+                            },
+                        });
+                        validationResult.valid = false;
+                    }
                     return formatSuccess({
                         bufferId: args.bufferId,
                         valid: validationResult.valid,