@vinhnguyen/confluence-mcp 1.0.0 → 1.1.0

package/README.md

@@ -5,23 +5,39 @@ A Model Context Protocol (MCP) server that provides tools for interacting with C
 ## Features
 
 - **Page Operations**: Get, create, update, delete pages
+- **Page Hierarchy**: Move pages, list child pages, get page with children
 - **Space Operations**: List spaces, get space details, browse space content
 - **Search**: Full CQL support, search by text or title
-- **Labels**: Get, add, remove page labels
+- **Labels**: Get, add, remove, and batch manage page labels
 - **Comments**: Read and add page comments
 - **Attachments**: List page attachments
 - **Special**: Extract DONE sections from daily reports
 
 ## Installation
 
+### Using npx (recommended, no install required)
+
+No installation needed! Just configure Claude Desktop or Claude Code as shown below.
+
+### Global Installation
+
+```bash
+npm install -g @vinhnguyen/confluence-mcp
+```
+
+### From Source
+
 ```bash
+git clone https://github.com/vinhnguyen/confluence-mcp.git
 cd confluence-mcp
 npm install
 ```
 
 ## Configuration
 
-The MCP server requires three environment variables:
+### Prerequisites
+
+The MCP server requires Atlassian credentials:
 
 | Variable | Description | Example |
 |----------|-------------|---------|
@@ -35,9 +51,49 @@ The MCP server requires three environment variables:
 2. Click "Create API token"
 3. Give it a label and copy the token
 
-## Usage with Claude Code
+### Claude Desktop
+
+Add the server to your Claude Desktop configuration file:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Using npx (recommended, no install required):
+
+```json
+{
+  "mcpServers": {
+    "confluence": {
+      "command": "npx",
+      "args": ["-y", "@vinhnguyen/confluence-mcp"],
+      "env": {
+        "ATLASSIAN_EMAIL": "your.email@company.com",
+        "ATLASSIAN_API_TOKEN": "your_api_token",
+        "ATLASSIAN_DOMAIN": "your-domain.atlassian.net"
+      }
+    }
+  }
+}
+```
 
-Add to your Claude Code MCP settings (`~/.claude/claude_desktop_config.json` or project settings):
+Or if installed globally via npm:
+
+```json
+{
+  "mcpServers": {
+    "confluence": {
+      "command": "confluence-mcp",
+      "env": {
+        "ATLASSIAN_EMAIL": "your.email@company.com",
+        "ATLASSIAN_API_TOKEN": "your_api_token",
+        "ATLASSIAN_DOMAIN": "your-domain.atlassian.net"
+      }
+    }
+  }
+}
+```
+
+Or from source:
 
 ```json
 {
@@ -55,6 +111,55 @@ Add to your Claude Code MCP settings (`~/.claude/claude_desktop_config.json` or
 }
 ```
 
+### Claude Code
+
+Add to your `~/.claude.json` (project) or `~/.claude/settings.json` (global):
+
+Using npx (recommended):
+
+```json
+{
+  "mcpServers": {
+    "confluence": {
+      "command": "npx",
+      "args": ["-y", "@vinhnguyen/confluence-mcp"],
+      "env": {
+        "ATLASSIAN_EMAIL": "your.email@company.com",
+        "ATLASSIAN_API_TOKEN": "your_api_token",
+        "ATLASSIAN_DOMAIN": "your-domain.atlassian.net"
+      }
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "confluence": {
+      "command": "confluence-mcp",
+      "env": {
+        "ATLASSIAN_EMAIL": "your.email@company.com",
+        "ATLASSIAN_API_TOKEN": "your_api_token",
+        "ATLASSIAN_DOMAIN": "your-domain.atlassian.net"
+      }
+    }
+  }
+}
+```
+
+**Restart Claude Desktop or Claude Code after updating the config.**
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `ATLASSIAN_EMAIL` | Your Atlassian account email | Yes |
+| `ATLASSIAN_API_TOKEN` | API token from Atlassian | Yes |
+| `ATLASSIAN_DOMAIN` | Your Confluence domain (e.g., `company.atlassian.net`) | Yes |
+
 ## Available Tools
 
 ### Page Operations
@@ -64,8 +169,12 @@ Add to your Claude Code MCP settings (`~/.claude/claude_desktop_config.json` or
 | `confluence_get_page` | Get page details including content, version, metadata |
 | `confluence_get_page_content` | Get page content as text or HTML |
 | `confluence_get_child_pages` | Get all child pages of a parent (with pagination) |
+| `confluence_get_page_with_children` | Get a page along with all its immediate child pages |
+| `confluence_list_child_pages` | List immediate child pages (folder contents view) |
 | `confluence_create_page` | Create a new page in a space |
-| `confluence_update_page` | Update an existing page |
+| `confluence_update_page` | Update an existing page (requires version number) |
+| `confluence_update_page_auto` | Update a page with automatic version handling |
+| `confluence_move_page` | Move a page to a new parent (restructure hierarchy) |
 | `confluence_delete_page` | Delete a page (moves to trash) |
 
 ### Space Operations

package/index.js

@@ -204,6 +204,22 @@ class ConfluenceClient {
     };
   }
 
+  // Auto-versioning update: fetches current version automatically
+  async updatePageAuto(pageId, newTitle = null, newBody = null) {
+    // Fetch current page to get version and existing data
+    const currentPage = await this.getPage(pageId);
+
+    if (!currentPage) {
+      throw new Error(`Page with ID ${pageId} not found`);
+    }
+
+    const title = newTitle || currentPage.title;
+    const content = newBody || currentPage.content;
+    const currentVersion = currentPage.version;
+
+    return this.updatePage(pageId, title, content, currentVersion);
+  }
+
   async deletePage(pageId) {
     await this.request(`/wiki/rest/api/content/${pageId}`, {
       method: "DELETE",
@@ -211,6 +227,126 @@ class ConfluenceClient {
     return { success: true, deletedPageId: pageId };
   }
 
+  // List immediate child pages (using API v2 for better pagination)
+  async listChildPages(pageId, limit = 50) {
+    const allChildren = [];
+    let nextUrl = `/wiki/api/v2/pages/${pageId}/children?limit=${limit}`;
+
+    while (nextUrl) {
+      const url = nextUrl.startsWith("http")
+        ? nextUrl
+        : `${this.baseUrl}${nextUrl}`;
+      const data = await this.request(url);
+
+      if (data.results) {
+        allChildren.push(
+          ...data.results.map((page) => ({
+            id: page.id,
+            title: page.title,
+            status: page.status,
+            parentId: page.parentId,
+            spaceId: page.spaceId,
+          }))
+        );
+      }
+
+      nextUrl = data._links?.next || null;
+    }
+
+    return {
+      parentPageId: pageId,
+      childCount: allChildren.length,
+      children: allChildren,
+    };
+  }
+
+  // Move a page to a new parent (restructure hierarchy)
+  async movePage(pageId, newParentId) {
+    // First, get current page details
+    const currentPage = await this.request(
+      `/wiki/rest/api/content/${pageId}?expand=version,space,ancestors`
+    );
+
+    if (!currentPage) {
+      throw new Error(`Page with ID ${pageId} not found`);
+    }
+
+    // Update page with new parent (ancestors)
+    const body = {
+      type: "page",
+      title: currentPage.title,
+      ancestors: [{ id: newParentId }],
+      version: {
+        number: currentPage.version.number + 1,
+      },
+    };
+
+    const data = await this.request(`/wiki/rest/api/content/${pageId}`, {
+      method: "PUT",
+      body: JSON.stringify(body),
+    });
+
+    return {
+      id: data.id,
+      title: data.title,
+      newParentId: newParentId,
+      version: data.version?.number,
+      webUrl: data._links?.webui
+        ? `${this.baseUrl}/wiki${data._links.webui}`
+        : null,
+    };
+  }
+
+  // Manage labels: add or remove multiple labels at once
+  async manageLabels(pageId, action, labels) {
+    if (!Array.isArray(labels) || labels.length === 0) {
+      throw new Error("Labels must be a non-empty array");
+    }
+
+    const results = {
+      pageId,
+      action,
+      processed: [],
+      errors: [],
+    };
+
+    if (action === "add") {
+      // Add all labels at once
+      const labelData = labels.map((name) => ({ name, prefix: "global" }));
+      try {
+        const data = await this.request(
+          `/wiki/rest/api/content/${pageId}/label`,
+          {
+            method: "POST",
+            body: JSON.stringify(labelData),
+          }
+        );
+        results.processed = data.results.map((label) => label.name);
+      } catch (error) {
+        results.errors.push({ labels, error: error.message });
+      }
+    } else if (action === "remove") {
+      // Remove labels one by one (API limitation)
+      for (const labelName of labels) {
+        try {
+          await this.request(
+            `/wiki/rest/api/content/${pageId}/label/${labelName}`,
+            {
+              method: "DELETE",
+            }
+          );
+          results.processed.push(labelName);
+        } catch (error) {
+          results.errors.push({ label: labelName, error: error.message });
+        }
+      }
+    } else {
+      throw new Error(`Invalid action: ${action}. Use 'add' or 'remove'.`);
+    }
+
+    return results;
+  }
+
   // -------------------------------------------------------------------------
   // Space Operations
   // -------------------------------------------------------------------------
@@ -402,6 +538,77 @@ class ConfluenceClient {
       fullContent: content,
     };
   }
+
+  // -------------------------------------------------------------------------
+  // Get page with children
+  // -------------------------------------------------------------------------
+
+  async getPageWithChildren(pageId, includeFullContent = false) {
+    // Fetch the parent page
+    const parentPage = await this.getPage(pageId);
+
+    // Fetch child pages (using existing getChildPages method which handles pagination)
+    let childPages = [];
+    try {
+      childPages = await this.getChildPages(pageId);
+    } catch (error) {
+      // If fetching children fails (e.g., no children or permission issues), continue with empty array
+      childPages = [];
+    }
+
+    // If includeFullContent is true, fetch full content for each child page
+    let childPagesWithContent = [];
+    if (includeFullContent && childPages.length > 0) {
+      childPagesWithContent = await Promise.all(
+        childPages.map(async (child) => {
+          try {
+            const fullChild = await this.getPage(child.id);
+            return {
+              id: fullChild.id,
+              title: fullChild.title,
+              spaceKey: fullChild.spaceKey,
+              version: fullChild.version,
+              content: fullChild.content,
+              contentAsText: fullChild.contentAsText,
+              webUrl: fullChild.webUrl,
+            };
+          } catch (error) {
+            // If fetching a child fails, return basic info with error
+            return {
+              id: child.id,
+              title: child.title,
+              status: child.status,
+              error: `Failed to fetch content: ${error.message}`,
+            };
+          }
+        })
+      );
+    } else {
+      // Just return basic info (id, title, status)
+      childPagesWithContent = childPages.map((child) => ({
+        id: child.id,
+        title: child.title,
+        status: child.status,
+      }));
+    }
+
+    return {
+      parent: {
+        id: parentPage.id,
+        title: parentPage.title,
+        spaceKey: parentPage.spaceKey,
+        version: parentPage.version,
+        content: parentPage.content,
+        contentAsText: parentPage.contentAsText,
+        webUrl: parentPage.webUrl,
+      },
+      childPages: {
+        count: childPagesWithContent.length,
+        includeFullContent,
+        pages: childPagesWithContent,
+      },
+    };
+  }
 }
 
 // ============================================================================
@@ -550,6 +757,94 @@ const TOOLS = [
       required: ["pageId"],
     },
   },
+  {
+    name: "confluence_update_page_auto",
+    description:
+      "Update an existing Confluence page with automatic version handling. Fetches the current version automatically so you don't need to provide it. You can update title, body, or both.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pageId: {
+          type: "string",
+          description: "The ID of the page to update",
+        },
+        newTitle: {
+          type: "string",
+          description: "The new title for the page (optional - keeps existing title if not provided)",
+        },
+        newBody: {
+          type: "string",
+          description: "The new content in Confluence storage format (XHTML). Optional - keeps existing content if not provided.",
+        },
+      },
+      required: ["pageId"],
+    },
+  },
+  {
+    name: "confluence_list_child_pages",
+    description:
+      "List all immediate child pages of a parent page (folder contents view). Returns page IDs, titles, and status for each child.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pageId: {
+          type: "string",
+          description: "The ID of the parent page to list children from",
+        },
+        limit: {
+          type: "number",
+          description: "Maximum number of children per API request (default: 50). Pagination is handled automatically.",
+        },
+      },
+      required: ["pageId"],
+    },
+  },
+  {
+    name: "confluence_move_page",
+    description:
+      "Move a page to a new parent, restructuring the page hierarchy. The page will become a child of the specified new parent page.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pageId: {
+          type: "string",
+          description: "The ID of the page to move",
+        },
+        newParentId: {
+          type: "string",
+          description: "The ID of the new parent page",
+        },
+      },
+      required: ["pageId", "newParentId"],
+    },
+  },
+  {
+    name: "confluence_manage_labels",
+    description:
+      "Add or remove multiple labels from a page in a single operation. Use action 'add' to add labels or 'remove' to remove them.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pageId: {
+          type: "string",
+          description: "The ID of the page to manage labels on",
+        },
+        action: {
+          type: "string",
+          enum: ["add", "remove"],
+          description: "The action to perform: 'add' to add labels, 'remove' to remove labels",
+        },
+        labels: {
+          type: "array",
+          items: {
+            type: "string",
+          },
+          description: "Array of label names to add or remove",
+        },
+      },
+      required: ["pageId", "action", "labels"],
+    },
+  },
 
   // Space Operations
   {
@@ -795,6 +1090,26 @@ const TOOLS = [
       required: ["pageId"],
     },
   },
+  {
+    name: "confluence_get_page_with_children",
+    description:
+      "Get a Confluence page along with all its immediate child pages in a single request. Returns the parent page content followed by a list of child pages. Optionally fetches full content for each child page.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pageId: {
+          type: "string",
+          description: "The ID of the parent page to retrieve",
+        },
+        includeFullContent: {
+          type: "boolean",
+          description:
+            "If true, fetch full content for each child page. If false (default), only return child page IDs and titles.",
+        },
+      },
+      required: ["pageId"],
+    },
+  },
 ];
 
 // ============================================================================
@@ -847,6 +1162,26 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         result = await client.deletePage(args.pageId);
         break;
 
+      case "confluence_update_page_auto":
+        result = await client.updatePageAuto(
+          args.pageId,
+          args.newTitle,
+          args.newBody
+        );
+        break;
+
+      case "confluence_list_child_pages":
+        result = await client.listChildPages(args.pageId, args.limit);
+        break;
+
+      case "confluence_move_page":
+        result = await client.movePage(args.pageId, args.newParentId);
+        break;
+
+      case "confluence_manage_labels":
+        result = await client.manageLabels(args.pageId, args.action, args.labels);
+        break;
+
       // Space Operations
       case "confluence_list_spaces":
         result = await client.listSpaces(args.limit);
@@ -913,6 +1248,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         result = await client.extractDoneSections(args.pageId);
         break;
 
+      case "confluence_get_page_with_children":
+        result = await client.getPageWithChildren(
+          args.pageId,
+          args.includeFullContent || false
+        );
+        break;
+
       default:
         throw new Error(`Unknown tool: ${name}`);
     }

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "@vinhnguyen/confluence-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "MCP server for Confluence - read, create, update, delete pages and manage spaces",
   "main": "index.js",
   "type": "module",
   "bin": {
     "confluence-mcp": "./index.js"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/glorynguyen/confluence-mcp.git"
+  },
   "scripts": {
-    "start": "node index.js"
+    "start": "node index.js",
+    "semantic-release": "semantic-release"
   },
   "keywords": [
     "mcp",
@@ -19,25 +24,50 @@
     "ai",
     "llm"
   ],
-  "author": "vinhnguyen",
+  "author": "Vinh Nguyen",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/vinhnguyen/confluence-mcp"
-  },
-  "homepage": "https://github.com/vinhnguyen/confluence-mcp#readme",
+  "homepage": "https://github.com/glorynguyen/confluence-mcp#readme",
   "bugs": {
-    "url": "https://github.com/vinhnguyen/confluence-mcp/issues"
+    "url": "https://github.com/glorynguyen/confluence-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "html-to-text": "^9.0.5"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.3",
+    "semantic-release": "^25.0.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
   },
   "files": [
     "index.js",
     "README.md"
   ],
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "html-to-text": "^9.0.5"
+  "release": {
+    "branches": [
+      "main"
+    ],
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/changelog",
+      "@semantic-release/npm",
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "package.json",
+            "package-lock.json",
+            "CHANGELOG.md"
+          ],
+          "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+        }
+      ],
+      "@semantic-release/github"
+    ]
   }
 }