@satiyap/confluence-reader-mcp 0.1.2 → 0.1.3

package/README.md

@@ -3,13 +3,22 @@
 [![npm version](https://img.shields.io/npm/v/@satiyap/confluence-reader-mcp.svg)](https://www.npmjs.com/package/@satiyap/confluence-reader-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-An MCP server that lets AI assistants read Confluence pages, walk page trees, and diff Confluence content against local documentation.
+An MCP server that lets AI assistants read Confluence Cloud pages, walk page trees recursively, and diff Confluence content against local documentation.
+
+## Features
+
+- Fetch a single Confluence page as plain text
+- Recursively fetch entire page trees up to a configurable depth
+- Compare local content against a Confluence page with a unified diff
+- Parallel child-page fetching with error resilience
+- Supports scoped API tokens with Basic Auth
 
 ## Setup
 
 ### 1. Get a Confluence API Token
 
-Create a scoped API token at: https://support.atlassian.com/confluence/kb/scoped-api-tokens-in-confluence-cloud/
+Create a scoped API token from your Atlassian account:
+https://support.atlassian.com/confluence/kb/scoped-api-tokens-in-confluence-cloud/
 
 ### 2. Set Environment Variables
 
@@ -17,7 +26,7 @@ Add to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.):
 
 ```bash
 export CONFLUENCE_TOKEN="your_scoped_token"
-export CONFLUENCE_EMAIL="you@company.com"
+export CONFLUENCE_EMAIL="your_email@example.com"
 export CONFLUENCE_CLOUD_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
 ```
 
@@ -28,7 +37,7 @@ Reload your shell or open a new terminal.
 | `CONFLUENCE_TOKEN` | Yes | Scoped API token |
 | `CONFLUENCE_EMAIL` | Yes | Email tied to your Atlassian account |
 | `CONFLUENCE_CLOUD_ID` | One of these | Cloud ID — routes via `api.atlassian.com` |
-| `CONFLUENCE_BASE_URL` | is required | Direct tenant URL, e.g. `https://yourteam.atlassian.net` |
+| `CONFLUENCE_BASE_URL` | is required | Direct tenant URL, e.g. `https://your-org.atlassian.net` |
 
 ### 3. Add to MCP Config
 
@@ -49,15 +58,16 @@ Restart the MCP host to pick up the new server.
 
 ### `confluence.fetch_page`
 
-Fetches a single Confluence page by URL and returns its content as text. Also lists any direct child pages at the bottom of the response.
+Fetches a Confluence page by URL and returns its content as text. Optionally recurses into child pages.
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `url` | string | Confluence page URL |
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `url` | string | — | Confluence page URL |
+| `depth` | number | 0 | Levels of child pages to fetch recursively |
 
 ### `confluence.fetch_page_tree`
 
-Fetches a page and all its descendants recursively, up to a given depth. Returns a single markdown document with nested headings.
+Fetches a page and all its descendants recursively, up to a given depth. Returns a single document with nested headings.
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
@@ -85,6 +95,10 @@ Returns a JSON object with `additions`, `deletions`, `totalChanges`, and the ful
 - Credentials are read from environment variables only — never passed in config files.
 - Use scoped tokens with the minimum permissions needed.
 
+## Contributing
+
+Contributions are welcome. Please open an issue or submit a pull request.
+
 ## License
 
 MIT

package/dist/confluence/client.js

@@ -87,3 +87,57 @@ export async function fetchChildPages(cfg, pageId) {
     }
     return all;
 }
+/**
+ * Recursively fetch a page and its descendants up to the given depth.
+ *
+ * For each page it:
+ *  1. Fetches the full page content via fetchPageById
+ *  2. Discovers child page IDs via fetchChildPages
+ *  3. Recurses into each child (in parallel) until depth is exhausted
+ *
+ * Children at each level are fetched concurrently with a concurrency
+ * limit to avoid hammering the API. Pages that fail to load are
+ * included as stubs with an error message instead of aborting the
+ * entire tree.
+ *
+ * @param cfg - Client configuration
+ * @param pageId - Root page ID to start from
+ * @param depth - How many levels of children to fetch (0 = root only)
+ * @param concurrency - Max parallel requests per level (default 5)
+ * @returns A tree of PageNode objects
+ */
+export async function fetchPageTree(cfg, pageId, depth, concurrency = 5) {
+    const { storageToText } = await import("./transform.js");
+    const page = await fetchPageById(cfg, pageId);
+    const storage = page.body?.storage?.value ?? "";
+    const content = storage ? storageToText(storage) : "";
+    const children = [];
+    if (depth > 0) {
+        const childPages = await fetchChildPages(cfg, pageId);
+        // Fetch children in parallel, bounded by concurrency limit
+        const results = await parallelMap(childPages, (child) => fetchPageTree(cfg, child.id, depth - 1, concurrency).catch((err) => ({
+            id: child.id,
+            title: child.title ?? `Page ${child.id}`,
+            content: `[Error fetching page: ${err.message}]`,
+            children: [],
+        })), concurrency);
+        children.push(...results);
+    }
+    return { id: page.id, title: page.title, content, children };
+}
+/**
+ * Run an async mapper over items with a concurrency limit.
+ */
+async function parallelMap(items, fn, limit) {
+    const results = new Array(items.length);
+    let idx = 0;
+    async function worker() {
+        while (idx < items.length) {
+            const i = idx++;
+            results[i] = await fn(items[i]);
+        }
+    }
+    const workers = Array.from({ length: Math.min(limit, items.length) }, () => worker());
+    await Promise.all(workers);
+    return results;
+}

package/dist/index.js

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { extractConfluencePageId } from "./confluence/url.js";
-import { fetchPageById, fetchChildPages, buildAuthHeaders, buildBase } from "./confluence/client.js";
+import { fetchPageById, fetchPageTree, buildAuthHeaders, buildBase } from "./confluence/client.js";
 import { storageToText } from "./confluence/transform.js";
 import { generateUnifiedDiff, generateDiffStats } from "./compare/diff.js";
 const server = new McpServer({
@@ -39,25 +39,27 @@ function validateEnvironment() {
         process.exit(1);
     }
 }
-server.tool("confluence.fetch_page", "Fetch a Confluence page and return it as markdown.", {
-    url: z.string().describe("Confluence page URL")
-}, async ({ url }) => {
+server.tool("confluence.fetch_page", "Fetch a Confluence page and return it as markdown. Optionally recurse into child pages.", {
+    url: z.string().describe("Confluence page URL"),
+    depth: z.number().optional().default(0).describe("Levels of child pages to fetch recursively (default: 0, root page only)")
+}, async ({ url, depth }) => {
     const token = getEnv("CONFLUENCE_TOKEN");
     const email = getEnv("CONFLUENCE_EMAIL");
     const cloudId = getEnv("CONFLUENCE_CLOUD_ID");
     const baseUrl = getEnv("CONFLUENCE_BASE_URL");
     const cfg = { token, email, cloudId, baseUrl };
     const pageId = extractConfluencePageId(url);
-    const page = await fetchPageById(cfg, pageId);
-    const children = await fetchChildPages(cfg, pageId);
-    const storage = page.body?.storage?.value ?? "";
-    const markdown = storage ? storageToText(storage) : "";
-    const childLinks = children.map(c => `- [${c.title}] (id: ${c.id})`).join("\n");
-    const body = childLinks
-        ? `${markdown}\n\n## Child Pages\n${childLinks}`
-        : markdown;
+    const tree = await fetchPageTree(cfg, pageId, depth);
+    function renderNode(node, level) {
+        const heading = "#".repeat(Math.min(level + 1, 6));
+        const parts = [`${heading} ${node.title}`, node.content];
+        for (const child of node.children) {
+            parts.push(renderNode(child, level + 1));
+        }
+        return parts.join("\n\n");
+    }
     return {
-        content: [{ type: "text", text: body }]
+        content: [{ type: "text", text: renderNode(tree, 0) }]
     };
 });
 server.tool("confluence.fetch_page_tree", "Fetch a Confluence page and all its child pages recursively up to a specified depth.", {
@@ -70,20 +72,7 @@ server.tool("confluence.fetch_page_tree", "Fetch a Confluence page and all its c
     const baseUrl = getEnv("CONFLUENCE_BASE_URL");
     const cfg = { token, email, cloudId, baseUrl };
     const pageId = extractConfluencePageId(url);
-    async function buildTree(id, remaining) {
-        const page = await fetchPageById(cfg, id);
-        const storage = page.body?.storage?.value ?? "";
-        const content = storage ? storageToText(storage) : "";
-        const children = [];
-        if (remaining > 0) {
-            const childPages = await fetchChildPages(cfg, id);
-            for (const child of childPages) {
-                children.push(await buildTree(child.id, remaining - 1));
-            }
-        }
-        return { id: page.id, title: page.title, content, children };
-    }
-    const tree = await buildTree(pageId, depth);
+    const tree = await fetchPageTree(cfg, pageId, depth);
     function renderTree(node, level) {
         const heading = "#".repeat(Math.min(level + 1, 6));
         const parts = [`${heading} ${node.title}`, node.content];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@satiyap/confluence-reader-mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "MCP server for fetching and comparing Confluence documentation with local files",
   "author": "satiyap",
   "license": "MIT",