@ecubelabs/atlassian-mcp 1.4.0-next.1 → 1.4.0

package/dist/confluence-tools/add-labels-to-page.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+export const registerAddLabelsToPage = (server, confluenceService) => {
+    server.tool('add-labels-to-page', 'Add one or more labels to a Confluence page', {
+        pageId: z.string().describe('ID of the page to add labels to'),
+        labels: z
+            .array(z.object({
+            name: z.string().describe('Name of the label'),
+            prefix: z
+                .string()
+                .optional()
+                .describe('Optional prefix for the label (e.g., "global", "team")'),
+        }))
+            .describe('Array of labels to add to the page'),
+    }, async ({ pageId, labels }) => {
+        try {
+            const result = await confluenceService.addLabelsToPage(pageId, labels);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to add labels to page: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    });
+};

package/dist/confluence-tools/confluence-storage-format-help.js

@@ -0,0 +1,257 @@
+import { z } from 'zod';
+export const registerConfluenceStorageFormatHelp = (server) => {
+    server.tool('confluence-storage-format-help', '⚠️ MANDATORY: ALWAYS use this tool BEFORE creating/updating Confluence pages. 🚫 CRITICAL: All examples use storage format XML ONLY - NEVER use wiki markup ({info}, {code}), NEVER use placeholder text ([Panel], [Code Block]), NEVER use plain text for Jira/dates/users. ✅ This tool provides ONLY valid storage format syntax that will work in Confluence. Copy examples exactly.', {
+        topic: z
+            .enum([
+            'overview',
+            'best-practices',
+            'common-patterns',
+            'headings',
+            'text-formatting',
+            'lists',
+            'tables',
+            'code-blocks',
+            'panels',
+            'links',
+            'images',
+            'macros',
+            'layout',
+            'complete-example',
+        ])
+            .optional()
+            .describe('Specific topic to get help on. Use "overview" for mandatory rules, "macros" for Jira/date/user mention requirements, "best-practices" for enforcement guidelines, "common-patterns" for document templates. ALWAYS check this tool before writing Confluence content to ensure correct syntax.'),
+    }, async ({ topic = 'overview' }) => {
+        const examples = {
+            overview: `# Confluence Storage Format - Critical Rules
+
+## ❌ FORBIDDEN Syntax
+1. Wiki Markup: {info}, {warning}, {code}, {jira:KEY-123}
+2. Placeholders: [Info Panel], [Code Block], [Table]
+3. Plain text: "HA-2584", "2025-12-03", "@username"
+
+## ✅ MANDATORY Macros
+1. **Jira**: <ac:structured-macro ac:name="jira"><ac:parameter ac:name="key">HA-2584</ac:parameter></ac:structured-macro>
+2. **Date**: <time datetime="2025-12-03" />
+3. **User**: <ac:link><ri:user ri:account-id="ACCOUNT_ID" /></ac:link>
+
+## Key Rules
+- Use h2/h3 for headings (not h1)
+- Put text directly in <li> tags (NO <p> wrapper)
+- Always use storage format XML, never wiki markup
+- Check specific topics for detailed syntax`,
+            headings: `# Headings
+<h2>Main Section</h2>
+<h3>Subsection</h3>
+
+Rules: Use h2 for main sections, h3 for subsections. Don't skip levels.`,
+            'text-formatting': `# Text Formatting
+<strong>Bold</strong>, <em>Italic</em>, <u>Underline</u>, <s>Strikethrough</s>
+
+Use sparingly for emphasis.`,
+            lists: `# Lists
+
+## 🚫 CRITICAL: NO <p> tags inside <li>
+❌ WRONG: <li><p>Item</p></li>
+✅ CORRECT: <li>Item</li>
+
+## Syntax
+**Simple list:**
+<ul>
+  <li>Item 1</li>
+  <li>Item 2</li>
+</ul>
+
+**Nested list:**
+<ul>
+  <li>Parent item
+    <ul>
+      <li>Child item</li>
+    </ul>
+  </li>
+</ul>
+
+**Ordered list:**
+<ol>
+  <li>Step 1</li>
+  <li>Step 2</li>
+</ol>`,
+            tables: `# Tables
+<table>
+  <tbody>
+    <tr>
+      <th>Header 1</th>
+      <th>Header 2</th>
+    </tr>
+    <tr>
+      <td>Cell 1</td>
+      <td>Cell 2</td>
+    </tr>
+  </tbody>
+</table>`,
+            'code-blocks': `# Code Blocks
+<ac:structured-macro ac:name="code" ac:schema-version="1">
+  <ac:parameter ac:name="language">javascript</ac:parameter>
+  <ac:plain-text-body><![CDATA[const x = 1;]]></ac:plain-text-body>
+</ac:structured-macro>
+
+Languages: javascript, typescript, python, bash, json, yaml, etc.`,
+            panels: `# Panels
+
+**Info Panel:**
+<ac:structured-macro ac:name="info" ac:schema-version="1">
+  <ac:parameter ac:name="icon">true</ac:parameter>
+  <ac:rich-text-body>
+    <p>Information message</p>
+  </ac:rich-text-body>
+</ac:structured-macro>
+
+**Warning Panel:**
+<ac:structured-macro ac:name="warning" ac:schema-version="1">
+  <ac:parameter ac:name="icon">true</ac:parameter>
+  <ac:rich-text-body>
+    <p>Warning message</p>
+  </ac:rich-text-body>
+</ac:structured-macro>
+
+**Note Panel:**
+<ac:structured-macro ac:name="note" ac:schema-version="1">
+  <ac:parameter ac:name="icon">true</ac:parameter>
+  <ac:rich-text-body>
+    <p>Note message</p>
+  </ac:rich-text-body>
+</ac:structured-macro>`,
+            links: `# Links
+
+## User Mention (MANDATORY for people)
+❌ NEVER: "@username" or "John Doe"
+✅ ALWAYS:
+<ac:link>
+  <ri:user ri:account-id="ACCOUNT_ID" />
+</ac:link>
+
+## External Link
+<a href="https://example.com">Link text</a>
+
+## Page Link
+<ac:link>
+  <ri:page ri:content-title="Page Title" />
+</ac:link>`,
+            images: `# Images
+<ac:image>
+  <ri:attachment ri:filename="image.png" />
+</ac:image>
+
+Attach images to page first, then reference by filename.`,
+            macros: `# Macros
+
+## Table of Contents (TOC)
+<ac:structured-macro ac:name="toc" ac:schema-version="1">
+  <ac:parameter ac:name="maxLevel">3</ac:parameter>
+  <ac:parameter ac:name="style">none</ac:parameter>
+</ac:structured-macro>
+
+## Jira Issue (MANDATORY for Jira keys)
+❌ NEVER: "HA-2584" or plain text
+✅ ALWAYS:
+<ac:structured-macro ac:name="jira" ac:schema-version="1">
+  <ac:parameter ac:name="key">HA-2584</ac:parameter>
+</ac:structured-macro>
+
+## Date (MANDATORY for dates)
+❌ NEVER: "2025-12-03" or plain text
+✅ ALWAYS:
+<time datetime="2025-12-03" />
+
+## Status Chip
+<ac:structured-macro ac:name="status" ac:schema-version="1">
+  <ac:parameter ac:name="colour">Green</ac:parameter>
+  <ac:parameter ac:name="title">완료</ac:parameter>
+</ac:structured-macro>
+
+Colors: Green, Yellow, Red, Blue, Grey, Purple`,
+            layout: `# Layout
+<ac:layout>
+  <ac:layout-section ac:type="two_equal">
+    <ac:layout-cell>
+      <p>Left column</p>
+    </ac:layout-cell>
+    <ac:layout-cell>
+      <p>Right column</p>
+    </ac:layout-cell>
+  </ac:layout-section>
+</ac:layout>
+
+Types: two_equal, three_equal. Use sparingly.`,
+            'best-practices': `# Best Practices
+
+## MANDATORY Rules
+1. Jira keys → MUST use Jira macro
+2. Dates → MUST use <time> element
+3. People → MUST use user mention link
+4. Lists → NEVER use <p> inside <li>
+
+## Document Structure
+- Start with h2 (not h1)
+- Use panels for important info only
+- Keep lists concise
+- Use storage format XML only`,
+            'common-patterns': `# Common Patterns
+
+## Meeting Notes
+<h2>참여자</h2>
+<ul>
+  <li><ac:link><ri:user ri:account-id="ACCOUNT_ID" /></ac:link></li>
+</ul>
+<h2>WIP</h2>
+<ul><li>Task 1</li></ul>
+<h2>ISSUE</h2>
+
+## Specification Document
+<ac:structured-macro ac:name="info">
+  <ac:rich-text-body>
+    <p><strong>이슈:</strong> <ac:structured-macro ac:name="jira"><ac:parameter ac:name="key">KEY-123</ac:parameter></ac:structured-macro></p>
+    <p><strong>작성일:</strong> <time datetime="2025-12-03" /></p>
+  </ac:rich-text-body>
+</ac:structured-macro>
+<ac:structured-macro ac:name="toc">
+  <ac:parameter ac:name="maxLevel">3</ac:parameter>
+</ac:structured-macro>
+<h2>배경 및 현황</h2>`,
+            'complete-example': `# Complete Example
+
+<h2>참여자</h2>
+<ul>
+  <li><ac:link><ri:user ri:account-id="ACCOUNT_ID" /></ac:link></li>
+</ul>
+
+<h2>WIP</h2>
+<ac:structured-macro ac:name="info" ac:schema-version="1">
+  <ac:parameter ac:name="icon">true</ac:parameter>
+  <ac:rich-text-body>
+    <p>Sprint deadline: <time datetime="2025-12-15" /></p>
+  </ac:rich-text-body>
+</ac:structured-macro>
+
+<ul>
+  <li>Task 1</li>
+  <li>Task 2</li>
+</ul>
+
+<h2>ISSUE</h2>
+<ac:structured-macro ac:name="warning" ac:schema-version="1">
+  <ac:parameter ac:name="icon">true</ac:parameter>
+  <ac:rich-text-body>
+    <p>Critical issue: <ac:structured-macro ac:name="jira" ac:schema-version="1"><ac:parameter ac:name="key">KEY-123</ac:parameter></ac:structured-macro></p>
+  </ac:rich-text-body>
+</ac:structured-macro>`,
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: examples[topic] || examples.overview,
+                },
+            ],
+        };
+    });
+};

package/dist/confluence-tools/create-page.js

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+export const registerCreatePage = (server, confluenceService) => {
+    server.tool('create-page', '⚠️ Create a new Confluence page. 🚫 CRITICAL: NEVER use wiki markup ({info}, {code}), placeholder text ([Info Panel]), or plain text for Jira/dates/users. ✅ MANDATORY: MUST use confluence-storage-format-help tool BEFORE calling this. ONLY use storage format XML: <ac:structured-macro> for macros, <time> for dates, <ac:link> for users.', {
+        spaceId: z.string().describe('ID of the space where the page will be created'),
+        title: z.string().describe('Title of the new page'),
+        bodyRepresentation: z
+            .enum(['storage', 'atlas_doc_format', 'view'])
+            .default('storage')
+            .describe('Format of the page body content (default: storage)'),
+        bodyValue: z
+            .string()
+            .describe('🚫 NEVER use wiki markup ({info}, {code}) or placeholders ([Panel]). ✅ ONLY use storage format XML. MUST check confluence-storage-format-help tool first. Example: Panels use <ac:structured-macro ac:name="info"><ac:rich-text-body><p>text</p></ac:rich-text-body></ac:structured-macro>, Jira uses <ac:structured-macro ac:name="jira"><ac:parameter ac:name="key">KEY-123</ac:parameter></ac:structured-macro>, dates use <time datetime="YYYY-MM-DD"/>, users use <ac:link><ri:user ri:account-id="ID"/></ac:link>.'),
+        status: z
+            .enum(['current', 'draft'])
+            .optional()
+            .default('current')
+            .describe('Status of the page (default: current)'),
+        parentId: z.string().optional().describe('ID of the parent page (optional, for creating child pages)'),
+    }, async ({ spaceId, title, bodyRepresentation, bodyValue, status = 'current', parentId }) => {
+        try {
+            const result = await confluenceService.createPage({
+                spaceId,
+                title,
+                body: {
+                    representation: bodyRepresentation,
+                    value: bodyValue,
+                },
+                status,
+                parentId,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to create page: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    });
+};

package/dist/confluence-tools/delete-page.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+export const registerDeletePage = (server, confluenceService) => {
+    server.tool('delete-page', 'Delete a Confluence page (moves to trash by default, or permanently deletes)', {
+        pageId: z.string().describe('ID of the page to delete'),
+        purge: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('If true, permanently delete the page. If false, move to trash (default: false)'),
+        draft: z.boolean().optional().describe('If true, delete a draft page (default: false)'),
+    }, async ({ pageId, purge = false, draft }) => {
+        try {
+            await confluenceService.deletePage(pageId, {
+                purge,
+                draft,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: purge
+                            ? `Page ${pageId} has been permanently deleted`
+                            : `Page ${pageId} has been moved to trash`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to delete page: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    });
+};

package/dist/confluence-tools/find-label-by-name.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+export const registerFindLabelByName = (server, confluenceService) => {
+    server.tool('find-label-by-name', 'Find a specific label by its name', {
+        labelName: z.string().describe('Name of the label to find'),
+    }, async ({ labelName }) => {
+        try {
+            const label = await confluenceService.findLabelByName(labelName);
+            if (label) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(label),
+                        },
+                    ],
+                };
+            }
+            else {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Label "${labelName}" not found`,
+                        },
+                    ],
+                };
+            }
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to find label "${labelName}": ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    });
+};

package/dist/confluence-tools/find-pages-by-label-name.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+export const registerFindPagesByLabelName = (server, confluenceService) => {
+    server.tool('find-pages-by-label-name', 'Find pages by label name (convenience tool that combines label search and page retrieval)', {
+        labelName: z
+            .string()
+            .describe('Name of the label to search for (e.g., "business-kb", "api", "documentation")'),
+        bodyFormat: z
+            .array(z.enum(['storage', 'atlas_doc_format', 'view']))
+            .optional()
+            .describe('Format of the page body to retrieve'),
+        sort: z
+            .enum([
+            'id',
+            '-id',
+            'created-date',
+            '-created-date',
+            'modified-date',
+            '-modified-date',
+            'title',
+            '-title',
+        ])
+            .optional()
+            .describe('Sort order for results'),
+        cursor: z.string().optional().describe('Cursor for pagination'),
+        limit: z
+            .number()
+            .min(1)
+            .max(250)
+            .optional()
+            .describe('Maximum number of results to return (default: 25, max: 250)'),
+    }, async ({ labelName, bodyFormat, sort, cursor, limit }) => {
+        try {
+            const result = await confluenceService.getPagesByLabelName(labelName, {
+                bodyFormat,
+                sort,
+                cursor,
+                limit,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to find pages for label "${labelName}": ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    });
+};

package/dist/confluence-tools/find-space-by-name.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+export const registerFindSpaceByName = (server, confluenceService) => {
+    server.tool('find-space-by-name', 'Find a space by its name', {
+        spaceName: z.string().describe('Name of the space to find'),
+    }, async ({ spaceName }) => {
+        try {
+            const space = await confluenceService.findSpaceByName(spaceName);
+            if (space) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(space),
+                        },
+                    ],
+                };
+            }
+            else {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Space with name "${spaceName}" not found`,
+                        },
+                    ],
+                };
+            }
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to find space with name "${spaceName}": ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    });
+};

package/dist/confluence-tools/get-labels.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+export const registerGetLabels = (server, confluenceService) => {
+    server.tool('get-labels', 'Get list of labels from Confluence', {
+        ids: z.array(z.string()).optional().describe('Filter labels by IDs'),
+        prefix: z.array(z.string()).optional().describe('Filter labels by prefix'),
+        cursor: z.string().optional().describe('Cursor for pagination'),
+        limit: z
+            .number()
+            .min(1)
+            .max(250)
+            .optional()
+            .describe('Maximum number of results to return (default: 25, max: 250)'),
+        sort: z
+            .enum(['id', '-id', 'name', '-name', 'created-date', '-created-date'])
+            .optional()
+            .describe('Sort order for results'),
+    }, async ({ ids, prefix, cursor, limit, sort }) => {
+        try {
+            const result = await confluenceService.getLabels({
+                ids,
+                prefix,
+                cursor,
+                limit,
+                sort,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to retrieve labels: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    });
+};

package/dist/confluence-tools/get-page-by-id.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+export const registerGetPageById = (server, confluenceService) => {
+    server.tool('get-page-by-id', 'Get a specific page by its ID', {
+        pageId: z.string().describe('ID of the page to retrieve'),
+        bodyFormat: z
+            .array(z.enum(['storage', 'atlas_doc_format', 'view']))
+            .optional()
+            .describe('Format of the page body to retrieve'),
+        getDraft: z.boolean().optional().describe('Whether to get the draft version of the page'),
+        version: z.number().optional().describe('Specific version of the page to retrieve'),
+    }, async ({ pageId, bodyFormat, getDraft, version }) => {
+        try {
+            const page = await confluenceService.getPageById(pageId, {
+                bodyFormat,
+                getDraft,
+                version,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(page),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to retrieve page: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    });
+};

package/dist/confluence-tools/get-page-children-tree.js

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+export const registerGetPageChildrenTree = (server, confluenceService) => {
+    server.tool('get-page-children-tree', 'Get the complete hierarchical tree of child pages for a specific page (recursive)', {
+        pageId: z.string().describe('ID of the root page'),
+        limit: z
+            .number()
+            .min(1)
+            .max(250)
+            .optional()
+            .describe('Maximum number of results per level (default: 25, max: 250)'),
+        sort: z
+            .enum([
+            'id',
+            '-id',
+            'created-date',
+            '-created-date',
+            'modified-date',
+            '-modified-date',
+            'title',
+            '-title',
+        ])
+            .optional()
+            .describe('Sort order for results'),
+        maxDepth: z
+            .number()
+            .min(-1)
+            .max(20)
+            .optional()
+            .default(10)
+            .describe('Maximum depth to traverse (default: 10, unlimited: -1, max: 20)'),
+    }, async ({ pageId, limit, sort, maxDepth = 10 }) => {
+        try {
+            const result = await confluenceService.getPageChildrenTree(pageId, {
+                limit,
+                sort,
+            }, maxDepth);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to retrieve page children tree: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    });
+};