@satiyap/confluence-reader-mcp 0.1.3 → 0.2.0

package/README.md

@@ -3,14 +3,14 @@
 [![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 Cloud pages, walk page trees recursively, and diff Confluence content against local documentation.
+An MCP server that lets AI assistants read Confluence Cloud pages as markdown, browse page trees, download image attachments, and diff content against local documentation.
 
 ## Features
 
-- Fetch a single Confluence page as plain text
-- Recursively fetch entire page trees up to a configurable depth
+- Fetch a single Confluence page as proper GitHub-flavored markdown (headings, tables, lists, code blocks)
+- List child pages for recursive traversal
+- Download image attachments by filename
 - 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
@@ -58,21 +58,28 @@ Restart the MCP host to pick up the new server.
 
 ### `confluence.fetch_page`
 
-Fetches a Confluence page by URL and returns its content as text. Optionally recurses into child pages.
+Fetches a single Confluence page by URL and returns its content as markdown. Lists any direct child pages at the bottom so the caller can decide which to fetch next.
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `url` | string | — | Confluence page URL |
-| `depth` | number | 0 | Levels of child pages to fetch recursively |
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | string | Confluence page URL |
+
+### `confluence.list_children`
+
+Lists the direct child pages of a Confluence page without fetching their content. Useful for discovering page structure before fetching individual pages.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | string | Confluence page URL |
 
-### `confluence.fetch_page_tree`
+### `confluence.fetch_image`
 
-Fetches a page and all its descendants recursively, up to a given depth. Returns a single document with nested headings.
+Downloads an image attachment from a Confluence page by filename. Returns the image as base64-encoded data.
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `url` | string | — | Confluence page URL |
-| `depth` | number | 1 | How many levels of children to fetch |
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | string | Confluence page URL |
+| `filename` | string | Attachment filename (e.g. `architecture.png`) |
 
 ### `confluence.compare`
 

package/dist/confluence/client.js

@@ -88,56 +88,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
+ * Fetch attachments for a Confluence page.
+ * Returns all attachments (paginates automatically).
  */
-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);
+export async function fetchAttachments(cfg, pageId) {
+    const base = buildBase(cfg);
+    const all = [];
+    let cursor;
+    while (true) {
+        const url = new URL(`${base}/wiki/api/v2/pages/${pageId}/attachments`);
+        url.searchParams.set("limit", "50");
+        if (cursor)
+            url.searchParams.set("cursor", cursor);
+        const res = await fetch(url.toString(), {
+            method: "GET",
+            headers: {
+                ...buildAuthHeaders(cfg),
+                Accept: "application/json",
+            },
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Confluence API error ${res.status}: ${text.slice(0, 500)}`);
+        }
+        const data = (await res.json());
+        all.push(...data.results);
+        if (!data._links?.next)
+            break;
+        const nextUrl = new URL(data._links.next, base);
+        cursor = nextUrl.searchParams.get("cursor") ?? undefined;
+        if (!cursor)
+            break;
     }
-    return { id: page.id, title: page.title, content, children };
+    return all;
 }
 /**
- * Run an async mapper over items with a concurrency limit.
+ * Download an attachment binary by its download link.
+ * Returns the raw Buffer and content type.
  */
-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]);
-        }
+export async function downloadAttachment(cfg, downloadLink) {
+    const base = buildBase(cfg);
+    const url = `${base}/wiki${downloadLink}`;
+    const res = await fetch(url, {
+        method: "GET",
+        headers: buildAuthHeaders(cfg),
+        redirect: "follow",
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`Attachment download error ${res.status}: ${text.slice(0, 500)}`);
     }
-    const workers = Array.from({ length: Math.min(limit, items.length) }, () => worker());
-    await Promise.all(workers);
-    return results;
+    const contentType = res.headers.get("content-type") ?? "application/octet-stream";
+    const arrayBuffer = await res.arrayBuffer();
+    return { buffer: Buffer.from(arrayBuffer), contentType };
 }

package/dist/confluence/transform.js

@@ -1,35 +1,94 @@
+import TurndownService from "turndown";
+// @ts-expect-error — no type declarations available
+import { gfm } from "turndown-plugin-gfm";
+const turndown = new TurndownService({
+    headingStyle: "atx",
+    codeBlockStyle: "fenced",
+    bulletListMarker: "-",
+});
+turndown.use(gfm);
 /**
- * Convert Confluence storage HTML to plain text
- *
- * This is a lightweight HTML-to-text converter that:
- * - Strips HTML tags
- * - Preserves paragraph and heading breaks
- * - Decodes common HTML entities
- *
- * Note: Not a perfect HTML→Markdown converter; intentionally simple for MCP use.
+ * Pre-process Confluence storage format HTML into standard HTML
+ * that Turndown can handle. Confluence uses custom XML namespaces
+ * (ac:, ri:) that DOM parsers and Turndown don't understand.
+ */
+function normalizeConfluenceHtml(html) {
+    let out = html;
+    // Convert ac:layout-section / ac:layout-cell to divs
+    out = out.replace(/<ac:layout-section>/gi, "<div>");
+    out = out.replace(/<\/ac:layout-section>/gi, "</div>");
+    out = out.replace(/<ac:layout-cell>/gi, "<div>");
+    out = out.replace(/<\/ac:layout-cell>/gi, "</div>");
+    out = out.replace(/<ac:layout>/gi, "<div>");
+    out = out.replace(/<\/ac:layout>/gi, "</div>");
+    // Convert ac:structured-macro (panels, code blocks, etc.) to divs
+    // Preserve the macro name as a data attribute for potential future use
+    out = out.replace(/<ac:structured-macro[^>]*ac:name="code"[^>]*>([\s\S]*?)<\/ac:structured-macro>/gi, (_match, inner) => {
+        // Extract plain-text-body for code blocks
+        const bodyMatch = inner.match(/<ac:plain-text-body>\s*<!\[CDATA\[([\s\S]*?)\]\]>\s*<\/ac:plain-text-body>/i);
+        if (bodyMatch) {
+            return `<pre><code>${bodyMatch[1]}</code></pre>`;
+        }
+        return `<pre><code>${inner.replace(/<[^>]+>/g, "")}</code></pre>`;
+    });
+    // Convert info/note/warning/tip panels to blockquotes
+    out = out.replace(/<ac:structured-macro[^>]*ac:name="(info|note|warning|tip|panel)"[^>]*>([\s\S]*?)<\/ac:structured-macro>/gi, (_match, _type, inner) => {
+        const bodyMatch = inner.match(/<ac:rich-text-body>([\s\S]*?)<\/ac:rich-text-body>/i);
+        return bodyMatch ? `<blockquote>${bodyMatch[1]}</blockquote>` : `<blockquote>${inner}</blockquote>`;
+    });
+    // Generic: any remaining ac:structured-macro — unwrap to div
+    out = out.replace(/<ac:structured-macro[^>]*>/gi, "<div>");
+    out = out.replace(/<\/ac:structured-macro>/gi, "</div>");
+    // ac:rich-text-body → div
+    out = out.replace(/<ac:rich-text-body>/gi, "<div>");
+    out = out.replace(/<\/ac:rich-text-body>/gi, "</div>");
+    // ac:plain-text-body with CDATA → pre
+    out = out.replace(/<ac:plain-text-body>\s*<!\[CDATA\[([\s\S]*?)\]\]>\s*<\/ac:plain-text-body>/gi, (_match, content) => `<pre>${content}</pre>`);
+    out = out.replace(/<ac:plain-text-body>/gi, "<pre>");
+    out = out.replace(/<\/ac:plain-text-body>/gi, "</pre>");
+    // ac:parameter tags — remove entirely
+    out = out.replace(/<ac:parameter[^>]*>[\s\S]*?<\/ac:parameter>/gi, "");
+    // ac:image → img tag
+    out = out.replace(/<ac:image[^>]*>([\s\S]*?)<\/ac:image>/gi, (_match, inner) => {
+        const filenameMatch = inner.match(/ri:filename="([^"]+)"/i);
+        const filename = filenameMatch ? filenameMatch[1] : "image";
+        return `<img alt="${filename}" src="${filename}" />`;
+    });
+    // ac:link with ri:page → anchor
+    out = out.replace(/<ac:link>([\s\S]*?)<\/ac:link>/gi, (_match, inner) => {
+        const pageMatch = inner.match(/ri:content-title="([^"]+)"/i);
+        const bodyMatch = inner.match(/<ac:link-body>([\s\S]*?)<\/ac:link-body>/i)
+            || inner.match(/<ac:plain-text-link-body>\s*<!\[CDATA\[([\s\S]*?)\]\]>\s*<\/ac:plain-text-link-body>/i);
+        const title = pageMatch ? pageMatch[1] : "";
+        const text = bodyMatch ? bodyMatch[1].replace(/<[^>]+>/g, "") : title;
+        return `<a href="#">${text || title}</a>`;
+    });
+    // ac:emoticon → remove
+    out = out.replace(/<ac:emoticon[^>]*\/>/gi, "");
+    // ac:task-list / ac:task / ac:task-body → ul/li
+    out = out.replace(/<ac:task-list>/gi, "<ul>");
+    out = out.replace(/<\/ac:task-list>/gi, "</ul>");
+    out = out.replace(/<ac:task>([\s\S]*?)<\/ac:task>/gi, (_match, inner) => {
+        const statusMatch = inner.match(/<ac:task-status>([\s\S]*?)<\/ac:task-status>/i);
+        const bodyMatch = inner.match(/<ac:task-body>([\s\S]*?)<\/ac:task-body>/i);
+        const checked = statusMatch && statusMatch[1].trim() === "complete";
+        const body = bodyMatch ? bodyMatch[1] : inner;
+        return `<li>${checked ? "[x] " : "[ ] "}${body}</li>`;
+    });
+    // Remove any remaining ac:* or ri:* tags but keep their text content
+    out = out.replace(/<\/?(?:ac|ri):[^>]*>/gi, "");
+    // Clean up CDATA remnants
+    out = out.replace(/<!\[CDATA\[/g, "");
+    out = out.replace(/\]\]>/g, "");
+    return out;
+}
+/**
+ * Convert Confluence storage format HTML to GitHub-flavored markdown.
  *
  * @param storageHtml - Confluence storage format HTML
- * @returns Plain text representation
+ * @returns Markdown with headings, tables, lists, code blocks, etc.
  */
-export function storageToText(storageHtml) {
-    // Minimal, safe-ish conversion:
-    // - strip tags
-    // - preserve headings/paragraph-ish breaks
-    // Not a perfect HTML->MD converter; intentionally lightweight for an MCP tool.
-    const withBreaks = storageHtml
-        .replace(/<\/(p|h1|h2|h3|h4|li|tr|div)>/gi, "\n")
-        .replace(/<br\s*\/?>/gi, "\n");
-    const stripped = withBreaks.replace(/<[^>]+>/g, "");
-    const decoded = stripped
-        .replace(/&nbsp;/g, " ")
-        .replace(/&amp;/g, "&")
-        .replace(/&lt;/g, "<")
-        .replace(/&gt;/g, ">")
-        .replace(/&quot;/g, "\"")
-        .replace(/&#39;/g, "'");
-    return decoded
-        .split("\n")
-        .map((l) => l.trim())
-        .filter(Boolean)
-        .join("\n");
+export function storageToMarkdown(storageHtml) {
+    const normalized = normalizeConfluenceHtml(storageHtml);
+    return turndown.turndown(normalized);
 }

package/dist/index.js

@@ -3,12 +3,12 @@ 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, fetchPageTree, buildAuthHeaders, buildBase } from "./confluence/client.js";
-import { storageToText } from "./confluence/transform.js";
+import { fetchPageById, fetchChildPages, fetchAttachments, downloadAttachment, buildAuthHeaders, buildBase } from "./confluence/client.js";
+import { storageToMarkdown } from "./confluence/transform.js";
 import { generateUnifiedDiff, generateDiffStats } from "./compare/diff.js";
 const server = new McpServer({
     name: "confluence-reader-mcp",
-    version: "0.1.2"
+    version: "0.2.0"
 });
 function getEnv(name) {
     const v = process.env[name];
@@ -39,64 +39,101 @@ function validateEnvironment() {
         process.exit(1);
     }
 }
-server.tool("confluence.fetch_page", "Fetch a Confluence page and return it as markdown. Optionally recurse into child pages.", {
+/** Build config from env vars */
+function getCfg() {
+    return {
+        token: getEnv("CONFLUENCE_TOKEN"),
+        email: getEnv("CONFLUENCE_EMAIL"),
+        cloudId: getEnv("CONFLUENCE_CLOUD_ID"),
+        baseUrl: getEnv("CONFLUENCE_BASE_URL"),
+    };
+}
+server.tool("confluence.fetch_page", "Fetch a Confluence page as markdown. Returns the page content and lists any direct child pages so the caller can decide which children to fetch next.", {
     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 };
+}, async ({ url }) => {
+    const cfg = getCfg();
     const pageId = extractConfluencePageId(url);
-    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");
-    }
+    const page = await fetchPageById(cfg, pageId);
+    const children = await fetchChildPages(cfg, pageId);
+    const storage = page.body?.storage?.value ?? "";
+    const markdown = storage ? storageToMarkdown(storage) : "";
+    const childList = children.length > 0
+        ? `\n\n---\n## Child Pages\n${children.map(c => `- ${c.title} (id: ${c.id})`).join("\n")}`
+        : "";
     return {
-        content: [{ type: "text", text: renderNode(tree, 0) }]
+        content: [{
+                type: "text",
+                text: `# ${page.title}\n\n${markdown}${childList}`
+            }]
     };
 });
-server.tool("confluence.fetch_page_tree", "Fetch a Confluence page and all its child pages recursively up to a specified depth.", {
+server.tool("confluence.list_children", "List the direct child pages of a Confluence page without fetching their content. Useful for discovering page structure before fetching individual pages.", {
+    url: z.string().describe("Confluence page URL")
+}, async ({ url }) => {
+    const cfg = getCfg();
+    const pageId = extractConfluencePageId(url);
+    const children = await fetchChildPages(cfg, pageId);
+    const lines = children.map(c => `- ${c.title} (id: ${c.id})`);
+    const text = lines.length > 0
+        ? `Found ${lines.length} child page(s):\n\n${lines.join("\n")}`
+        : "No child pages found.";
+    return { content: [{ type: "text", text }] };
+});
+server.tool("confluence.fetch_image", "Download an image attachment from a Confluence page by filename. Returns the image as base64-encoded data.", {
     url: z.string().describe("Confluence page URL"),
-    depth: z.number().optional().default(1).describe("How many levels deep to fetch child pages (default: 1)")
-}, 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 };
+    filename: z.string().describe("Attachment filename (e.g. 'architecture.png')")
+}, async ({ url, filename }) => {
+    const cfg = getCfg();
     const pageId = extractConfluencePageId(url);
-    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];
-        for (const child of node.children) {
-            parts.push(renderTree(child, level + 1));
-        }
-        return parts.join("\n\n");
+    const attachments = await fetchAttachments(cfg, pageId);
+    const match = attachments.find(a => a.title.toLowerCase() === filename.toLowerCase());
+    if (!match) {
+        const available = attachments.map(a => a.title).join(", ");
+        return {
+            content: [{
+                    type: "text",
+                    text: `Attachment "${filename}" not found. Available: ${available || "none"}`
+                }]
+        };
     }
+    const downloadLink = match.downloadLink ?? match._links?.download;
+    if (!downloadLink) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `No download link available for "${filename}".`
+                }]
+        };
+    }
+    const { buffer, contentType } = await downloadAttachment(cfg, downloadLink);
+    const base64 = buffer.toString("base64");
+    // Return as base64 image content
+    if (contentType.startsWith("image/")) {
+        return {
+            content: [{
+                    type: "image",
+                    data: base64,
+                    mimeType: contentType,
+                }]
+        };
+    }
+    // Non-image attachment — return as base64 text
     return {
-        content: [{ type: "text", text: renderTree(tree, 0) }]
+        content: [{
+                type: "text",
+                text: `Downloaded "${filename}" (${contentType}, ${buffer.length} bytes).\nBase64: ${base64.slice(0, 200)}...`
+            }]
     };
 });
 server.tool("confluence.compare", "Compare a local markdown file or string with a Confluence page and show the differences.", {
     url: z.string().describe("Confluence page URL"),
     localContent: z.string().describe("Local markdown content to compare against")
 }, async ({ url, localContent }) => {
-    const token = getEnv("CONFLUENCE_TOKEN");
-    const email = getEnv("CONFLUENCE_EMAIL");
-    const cloudId = getEnv("CONFLUENCE_CLOUD_ID");
-    const baseUrl = getEnv("CONFLUENCE_BASE_URL");
+    const cfg = getCfg();
     const pageId = extractConfluencePageId(url);
-    const page = await fetchPageById({ token, email, cloudId, baseUrl }, pageId);
+    const page = await fetchPageById(cfg, pageId);
     const storage = page.body?.storage?.value ?? "";
-    const confluenceMarkdown = storage ? storageToText(storage) : "";
+    const confluenceMarkdown = storage ? storageToMarkdown(storage) : "";
     const diff = generateUnifiedDiff(confluenceMarkdown.trim(), localContent.trim(), `a/confluence/${page.title}`, `b/local`);
     const stats = generateDiffStats(confluenceMarkdown.trim(), localContent.trim());
     const result = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@satiyap/confluence-reader-mcp",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "MCP server for fetching and comparing Confluence documentation with local files",
   "author": "satiyap",
   "license": "MIT",
@@ -32,10 +32,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "turndown": "^7.2.2",
+    "turndown-plugin-gfm": "^1.0.2",
     "zod": "^3.25.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@types/turndown": "^5.0.6",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"
   },