@satiyap/confluence-reader-mcp 0.1.2 → 0.2.0

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 as markdown, browse page trees, download image attachments, and diff content against local documentation.
+
+## Features
+
+- 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
+- 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,20 +58,28 @@ 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 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 | Description |
 |-----------|------|-------------|
 | `url` | string | Confluence page URL |
 
-### `confluence.fetch_page_tree`
+### `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 |
 
-Fetches a page and all its descendants recursively, up to a given depth. Returns a single markdown document with nested headings.
+### `confluence.fetch_image`
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `url` | string | — | Confluence page URL |
-| `depth` | number | 1 | How many levels of children to fetch |
+Downloads an image attachment from a Confluence page by filename. Returns the image as base64-encoded data.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | string | Confluence page URL |
+| `filename` | string | Attachment filename (e.g. `architecture.png`) |
 
 ### `confluence.compare`
 
@@ -85,6 +102,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,58 @@ export async function fetchChildPages(cfg, pageId) {
     }
     return all;
 }
+/**
+ * Fetch attachments for a Confluence page.
+ * Returns all attachments (paginates automatically).
+ */
+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 all;
+}
+/**
+ * Download an attachment binary by its download link.
+ * Returns the raw Buffer and content type.
+ */
+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 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, fetchChildPages, 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,75 +39,101 @@ 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")
+/** 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"),
 }, async ({ url }) => {
-    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 cfg = getCfg();
     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 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: body }]
+        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);
-    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 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 tree = await buildTree(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 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.2",
+  "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"
   },