@crypto512/jicon-mcp 2.3.27 → 2.4.2

package/dist/confluence/tools.js

@@ -13,11 +13,7 @@ import { detectRawPlantUml, detectDiagramType } from "../utils/xhtml/plantuml.js
 import { convertPlantUmlIncludesInXhtml, IncludeConversionError } from "../utils/plantuml/index.js";
 import { parseUrl } from "../utils/url-tools.js";
 import { DEFAULT_PAGE_EXPAND } from "./defaults.js";
-/**
- * Schema that accepts either a comma-separated string or an array of strings.
- * Examples: "space,metadata" or ["space", "metadata"]
- */
-const stringOrArray = z.preprocess((val) => typeof val === "string" ? val.split(",").map(s => s.trim()).filter(Boolean) : val, z.array(z.string()));
+import { stringOrArray } from "../utils/zod-helpers.js";
 /**
  * Generate a summary of content structure for draft responses.
  * Helps AI assistants verify that diagrams and other elements are included.
@@ -137,7 +133,7 @@ async function validateContentForWrite(content, bufferId) {
                 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('TIP: Call jicon_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.");
@@ -178,7 +174,7 @@ export function createConfluenceTools() {
 
 Entry point for finding Confluence pages by content, title, or metadata.
 
-REQUIRES: Valid CQL query (see help(topic="cql") for syntax)
+REQUIRES: Valid CQL query (see jicon_help(topic="cql") for syntax)
 RETURNS: bufferId (JSON array), itemCount with page IDs and titles
 NEXT: confluence_get_page (to load), buffer_transform (for reports), buffer_grep (to search results)
 
@@ -229,7 +225,7 @@ WARNING: Use text~ not content~. Use space KEY not name.`,
                             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\n";
-                            hint += '\nTIP: Call help(topic="cql") for full CQL syntax guide.';
+                            hint += '\nTIP: Call jicon_help(topic="cql") for full CQL syntax guide.';
                             return formatError({
                                 ...error,
                                 message: error.message + hint
@@ -258,9 +254,9 @@ WARNING: Use text~ not content~. 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(bufferId, after=ID, content/plantuml/fromBufferId) to add content, then confluence_draft_create(pageId=..., bufferId=...) for user review.`,
+Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to add content, then confluence_create_draft(pageId=..., bufferId=...) for user review.`,
             inputSchema: z.object({
-                pageId: z.coerce.string().describe("Page ID (accepts string or number)"),
+                pageId: z.coerce.string().describe('Page ID (number or string, e.g. "123456")'),
                 expand: stringOrArray.optional().describe("Additional data to expand (string or array)"),
             }),
             handler: async (args) => {
@@ -291,7 +287,7 @@ Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to add conten
                         ...(navHint && { hint: navHint }),
                         message: navHint
                             ? `Index page with child listing macro. ${navHint}`
-                            : "Page loaded. Use buffer_edit to modify, then confluence_draft_create(pageId=..., bufferId=...) for user review.",
+                            : "Page loaded. Use buffer_edit to modify, then confluence_create_draft(pageId=..., bufferId=...) for user review.",
                     });
                 }
                 catch (error) {
@@ -305,7 +301,7 @@ Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to add conten
 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(bufferId, after=ID, content/plantuml/fromBufferId) to add content, then confluence_draft_create(pageId=..., bufferId=...) for user review.`,
+Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to add content, then confluence_create_draft(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"),
@@ -346,7 +342,7 @@ Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to add conten
                         ...(navHint && { hint: navHint }),
                         message: navHint
                             ? `Index page with child listing macro. ${navHint}`
-                            : "Page loaded. Use buffer_edit to modify, then confluence_draft_create(pageId=..., bufferId=...) for user review.",
+                            : "Page loaded. Use buffer_edit to modify, then confluence_create_draft(pageId=..., bufferId=...) for user review.",
                     });
                 }
                 catch (error) {
@@ -357,11 +353,11 @@ Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to add conten
         confluence_load: {
             description: `Load an EXISTING page or draft into a buffer for editing.
 
-For NEW pages: buffer_create(contentType="xhtml") → confluence_draft_create(spaceKey, title, bufferId)
+For NEW pages: buffer_create(contentType="xhtml") → confluence_create_draft(spaceKey, title, bufferId)
 
 ACCEPTS: URL | pageId | "draft:ID" | "SPACE/Title"
 RETURNS: bufferId, structure, pageId, version
-NEXT: buffer_edit → confluence_draft_create → confluence_review_publish`,
+NEXT: buffer_edit → confluence_create_draft → confluence_publish_review`,
             inputSchema: z.object({
                 input: z.string().describe('URL, pageId, "draft:ID", or "SPACE/Title"'),
             }),
@@ -396,7 +392,7 @@ NEXT: buffer_edit → confluence_draft_create → confluence_review_publish`,
                         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.",
+                        message: "Content loaded. Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to add content, then confluence_create_draft(pageId=..., bufferId=...) for user review.",
                     };
                 };
                 // Helper to load draft content
@@ -421,7 +417,7 @@ NEXT: buffer_edit → confluence_draft_create → confluence_review_publish`,
                         bufferId,
                         structure,
                         contentSize: content.length,
-                        message: "Draft loaded. Use buffer_edit to modify, then confluence_draft_save to update.",
+                        message: "Draft loaded. Use buffer_edit to modify, then confluence_save_draft to update.",
                     };
                 };
                 try {
@@ -458,7 +454,7 @@ NEXT: buffer_edit → confluence_draft_create → confluence_review_publish`,
                                     message: `Page not found: "${parsed.title}" in space ${parsed.spaceKey}`,
                                     statusCode: 404,
                                     details: {
-                                        hint: `To CREATE a new page: buffer_create(content, contentType="xhtml") → confluence_draft_create(spaceKey="${parsed.spaceKey}", title="${parsed.title}", bufferId=...)`,
+                                        hint: `To CREATE a new page: buffer_create(content, contentType="xhtml") → confluence_create_draft(spaceKey="${parsed.spaceKey}", title="${parsed.title}", bufferId=...)`,
                                     },
                                 });
                             }
@@ -509,7 +505,7 @@ NEXT: buffer_edit → confluence_draft_create → confluence_review_publish`,
                                 message: `Page not found: "${title}" in space ${spaceKey}`,
                                 statusCode: 404,
                                 details: {
-                                    hint: `To CREATE a new page: buffer_create(content, contentType="xhtml") → confluence_draft_create(spaceKey="${spaceKey}", title="${title}", bufferId=...)`,
+                                    hint: `To CREATE a new page: buffer_create(content, contentType="xhtml") → confluence_create_draft(spaceKey="${spaceKey}", title="${title}", bufferId=...)`,
                                 },
                             });
                         }
@@ -540,8 +536,8 @@ NEXT: buffer_edit → confluence_draft_create → confluence_review_publish`,
             },
         },
         // All page writes go through draft workflow: LLM creates/edits drafts, user publishes via Confluence UI
-        // - New pages: confluence_draft_create → user publishes
-        // - Existing pages: confluence_get_page → buffer_edit → confluence_draft_create → user publishes
+        // - New pages: confluence_create_draft → user publishes
+        // - Existing pages: confluence_get_page → buffer_edit → confluence_create_draft → user publishes
         confluence_delete_page: {
             description: `Delete a Confluence page permanently.
 
@@ -553,7 +549,7 @@ NEXT: None
 
 Example: confluence_delete_page(pageId="123456")`,
             inputSchema: z.object({
-                pageId: z.coerce.string().describe("Page ID (accepts string or number)"),
+                pageId: z.coerce.string().describe('Page ID (number or string, e.g. "123456")'),
             }),
             handler: async (args) => {
                 try {
@@ -578,7 +574,7 @@ Example: confluence_delete_page(pageId="123456")`,
 
 Discover available spaces and their keys for use in CQL queries.
 
-TIP: For YOUR personal space, use whoami() instead — it returns your spaceKey directly.
+TIP: For YOUR personal space, use user_whoami() instead — it returns your spaceKey directly.
 
 REQUIRES: None (optional type filter)
 RETURNS: bufferId with spaces array (key, name, type)
@@ -618,7 +614,7 @@ NEXT: confluence_search_content (to query space), confluence_get_page (homepage)
 
 Example: confluence_get_space(spaceKey="DOCS")`,
             inputSchema: z.object({
-                spaceKey: z.string().describe("Space key"),
+                spaceKey: z.string().describe('Space key — the short code (e.g. "DOCS"), not the full space name'),
                 expand: stringOrArray.optional().describe("Additional data to expand (string or array)"),
             }),
             handler: async (args) => {
@@ -646,7 +642,7 @@ Example: confluence_get_space(spaceKey="DOCS")`,
 Use when you need: "my space", user's space key for creating pages/drafts.
 This is the DEFAULT space when the user does not specify a target space.
 
-RETURNS: spaceKey, homePageId — use with confluence_draft_create(spaceKey=...).`,
+RETURNS: spaceKey, homePageId — use with confluence_create_draft(spaceKey=...).`,
             inputSchema: z.object({}),
             handler: async () => {
                 try {
@@ -752,10 +748,16 @@ NEXT: buffer_transform (RECOMMENDED for 10+ pages — aggregate server-side to a
             },
         },
         confluence_add_comment: {
-            description: "Add a comment to a Confluence page",
+            description: `Add a comment to a Confluence page.
+
+REQUIRES: pageId, comment (XHTML storage format)
+RETURNS: Created comment (direct json)
+NEXT: confluence_get_comments (to view all comments)
+
+Example: confluence_add_comment(pageId="123456", comment="<p>Reviewed — looks good.</p>")`,
             inputSchema: z.object({
-                pageId: z.coerce.string().describe("Page ID (accepts string or number)"),
-                comment: z.string().describe("Comment text (HTML format)"),
+                pageId: z.coerce.string().describe('Page ID (number or string, e.g. "123456"). From a search/load result.'),
+                comment: z.string().describe("Comment body in Confluence XHTML storage format (e.g. <p>text</p>)"),
             }),
             handler: async (args) => {
                 try {
@@ -772,7 +774,7 @@ NEXT: buffer_transform (RECOMMENDED for 10+ pages — aggregate server-side to a
 
 Returns bufferId. Use buffer_get_items to read, buffer_grep to search.`,
             inputSchema: z.object({
-                pageId: z.coerce.string().describe("Page ID (accepts string or number)"),
+                pageId: z.coerce.string().describe('Page ID (number or string, e.g. "123456")'),
             }),
             handler: async (args) => {
                 try {
@@ -792,11 +794,17 @@ Returns bufferId. Use buffer_get_items to read, buffer_grep to search.`,
             },
         },
         confluence_upload_attachment: {
-            description: "Upload an attachment to a Confluence page",
+            description: `Upload a local file as an attachment to a Confluence page.
+
+REQUIRES: pageId, filePath (path readable by the server)
+RETURNS: Uploaded attachment metadata (direct json)
+NEXT: confluence_list_attachments (to verify)
+
+Example: confluence_upload_attachment(pageId="123456", filePath="/tmp/report.pdf")`,
             inputSchema: z.object({
-                pageId: z.coerce.string().describe("Page ID (accepts string or number)"),
-                filePath: z.string().describe("Local file path"),
-                comment: z.string().optional().describe("Attachment comment"),
+                pageId: z.coerce.string().describe('Page ID (number or string, e.g. "123456"). From a search/load result.'),
+                filePath: z.string().describe("Absolute local file path to upload (must be readable by the server)"),
+                comment: z.string().optional().describe("Optional version comment for the attachment"),
             }),
             handler: async (args) => {
                 try {
@@ -813,7 +821,7 @@ Returns bufferId. Use buffer_get_items to read, buffer_grep to search.`,
 
 Returns bufferId. Use buffer_get_items to read, buffer_grep to search.`,
             inputSchema: z.object({
-                pageId: z.coerce.string().describe("Page ID (accepts string or number)"),
+                pageId: z.coerce.string().describe('Page ID (number or string, e.g. "123456")'),
             }),
             handler: async (args) => {
                 try {
@@ -837,17 +845,17 @@ Returns bufferId. Use buffer_get_items to read, buffer_grep to search.`,
         // ========================================
         // Note: Confluence drafts cannot be updated via API, only created, read, or deleted.
         // The workflow is: create draft → edit locally in buffer → save (delete+recreate) → publish
-        confluence_draft_create: {
+        confluence_create_draft: {
             description: `Create draft for user review. Requires bufferId with valid XHTML.
 
-NEW page: confluence_draft_create(spaceKey, title, bufferId)
-EDIT page: confluence_load → buffer_edit → confluence_draft_create(pageId, bufferId)
+NEW page: confluence_create_draft(spaceKey, title, bufferId)
+EDIT page: confluence_load → buffer_edit → confluence_create_draft(pageId, bufferId)
 
-TIP: Need your personal spaceKey? Use whoami() first.
+TIP: Need your personal spaceKey? Use user_whoami() first.
 
 Draft title auto-prefixed with "[jicon-mcp REVIEW]" when editing existing pages.
 RETURNS: draftId, bufferId, structure, url. On XHTML error: errorElementId for buffer_edit fix.
-WARNING: pageId must be a PAGE ID, not a draft ID. Use confluence_draft_open for existing drafts.`,
+WARNING: pageId must be a PAGE ID, not a draft ID. Use confluence_open_draft for existing drafts.`,
             inputSchema: z.object({
                 pageId: z.coerce.string().optional().describe("Existing PAGE ID to edit (NOT a draft ID). Get from confluence_get_page or confluence_load. 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)"),
@@ -936,11 +944,11 @@ WARNING: pageId must be a PAGE ID, not a draft ID. Use confluence_draft_open for
                             error instanceof Error ? error.message : String(error);
                         return formatError({
                             error: true,
-                            message: `Page '${args.pageId}' not found. If this is a draft ID (from confluence_draft_create), use confluence_draft_open to continue editing instead.`,
+                            message: `Page '${args.pageId}' not found. If this is a draft ID (from confluence_create_draft), use confluence_open_draft to continue editing instead.`,
                             statusCode: 404,
                             details: {
                                 originalError: errorMessage,
-                                hint: "For existing drafts: confluence_draft_open(draftId) → buffer_edit → confluence_draft_save. For new drafts from existing pages: confluence_load(pageId) → buffer_edit → confluence_draft_create(pageId, bufferId)",
+                                hint: "For existing drafts: confluence_open_draft(draftId) → buffer_edit → confluence_save_draft. For new drafts from existing pages: confluence_load(pageId) → buffer_edit → confluence_create_draft(pageId, bufferId)",
                                 pageIdProvided: args.pageId,
                             },
                         });
@@ -1100,12 +1108,12 @@ WARNING: pageId must be a PAGE ID, not a draft ID. Use confluence_draft_open for
                             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.`;
+                            ? `Review draft updated for page ${originalPageId}. Use confluence_publish_review(${result.id}) to apply changes.`
+                            : `Review draft created for page ${originalPageId}. Use confluence_publish_review(${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()",
+                            toPublish: `confluence_publish_review(reviewDraftId="${result.id}")`,
+                            toDiscard: `confluence_discard_review(reviewDraftId="${result.id}")`,
+                            toList: "confluence_list_reviews()",
                         };
                     }
                     else {
@@ -1133,10 +1141,10 @@ WARNING: pageId must be a PAGE ID, not a draft ID. Use confluence_draft_open for
                 }
             },
         },
-        confluence_draft_open: {
+        confluence_open_draft: {
             description: `Open an existing draft page for editing. Loads content into buffer with structure (element IDs).
 
-Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to modify, then confluence_draft_save. User publishes via Confluence UI.`,
+Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to modify, then confluence_save_draft. User publishes via Confluence UI.`,
             inputSchema: z.object({
                 draftId: z.coerce.string().describe("Draft page ID"),
             }),
@@ -1177,12 +1185,12 @@ Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to modify, th
                 }
             },
         },
-        confluence_draft_list: {
+        confluence_list_drafts: {
             description: `List your UNPUBLISHED draft pages (work-in-progress, not yet published).
 
 NOTE: To find PUBLISHED pages you edited, use:
   confluence_search_content(cql="contributor=currentUser() ORDER BY lastmodified DESC")
-TIP: To find your personal space key, use whoami().
+TIP: To find your personal space key, use user_whoami().
 
 Returns bufferId. Use buffer_get_items to read, buffer_grep to search.`,
             inputSchema: z.object({
@@ -1209,7 +1217,7 @@ Returns bufferId. Use buffer_get_items to read, buffer_grep to search.`,
                 }
             },
         },
-        confluence_draft_save: {
+        confluence_save_draft: {
             description: `Save buffer content to server as a new draft for user review.
 
 IMPORTANT: Raw @startuml outside macros is NOT supported. Use buffer_edit for auto-wrapping, or embed properly formatted ac:structured-macro elements.
@@ -1359,7 +1367,7 @@ Returns new draftId, bufferId, structure (element IDs), and URL. Always use the
                 }
             },
         },
-        confluence_draft_delete: {
+        confluence_delete_draft: {
             description: `Delete a draft page permanently.
 
 Drafts are NOT sent to trash - they are permanently deleted.`,
@@ -1391,12 +1399,12 @@ Drafts are NOT sent to trash - they are permanently deleted.`,
         // 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: {
+        confluence_publish_review: {
             description: `Publish a review draft to apply changes to the original page.
 
 Apply changes from "[jicon-mcp REVIEW]" draft to the original page.
 
-REQUIRES: reviewDraftId (from confluence_draft_create with pageId)
+REQUIRES: reviewDraftId (from confluence_create_draft with pageId)
 RETURNS: Updated page info with new version number
 NEXT: confluence_get_page (to verify), confluence_load (for more changes)
 
@@ -1405,7 +1413,7 @@ This tool:
 2. Copies the draft content to the original page (creates new version)
 3. Deletes the review draft
 
-Example: confluence_review_publish(reviewDraftId="123456")`,
+Example: confluence_publish_review(reviewDraftId="123456")`,
             inputSchema: z.object({
                 reviewDraftId: z.coerce.string().describe("ID of the [jicon-mcp REVIEW] draft to publish"),
                 autoRetry: z
@@ -1430,7 +1438,7 @@ Example: confluence_review_publish(reviewDraftId="123456")`,
                             statusCode: 400,
                             details: {
                                 actualTitle: reviewDraft.title,
-                                hint: "Use confluence_draft_create with pageId to create a review draft",
+                                hint: "Use confluence_create_draft with pageId to create a review draft",
                             },
                         });
                     }
@@ -1444,7 +1452,7 @@ Example: confluence_review_publish(reviewDraftId="123456")`,
                             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.",
+                                hint: "This draft may have been created manually. Use confluence_create_draft with pageId to create proper review drafts.",
                             },
                         });
                     }
@@ -1461,7 +1469,7 @@ Example: confluence_review_publish(reviewDraftId="123456")`,
                             statusCode: 404,
                             details: {
                                 originalPageId,
-                                hint: "If the original page was deleted, use confluence_review_discard to remove this review draft.",
+                                hint: "If the original page was deleted, use confluence_discard_review to remove this review draft.",
                             },
                         });
                     }
@@ -1508,7 +1516,7 @@ Example: confluence_review_publish(reviewDraftId="123456")`,
                 }
             },
         },
-        confluence_review_discard: {
+        confluence_discard_review: {
             description: `Discard a review draft without applying changes to the original page.
 
 This tool:
@@ -1531,7 +1539,7 @@ This tool:
                             statusCode: 400,
                             details: {
                                 actualTitle: reviewDraft.title,
-                                hint: "Use confluence_draft_delete for non-review drafts",
+                                hint: "Use confluence_delete_draft for non-review drafts",
                             },
                         });
                     }
@@ -1552,7 +1560,7 @@ This tool:
                 }
             },
         },
-        confluence_review_list: {
+        confluence_list_reviews: {
             description: `List all "[jicon-mcp REVIEW]" drafts for cleanup or management.
 
 Returns review drafts with their linked original page IDs.
@@ -1589,7 +1597,7 @@ Use this to find abandoned review drafts or manage multiple review workflows.`,
                         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.`
+                            ? `Found ${reviews.length} review draft(s). Use confluence_publish_review or confluence_discard_review to manage.`
                             : "No review drafts found.",
                     });
                 }