@satiyap/confluence-reader-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 satiyap
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+# Confluence Reader MCP Server
+
+[![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)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org/)
+
+MCP server for fetching and comparing Confluence documentation with local files. Enables AI assistants to read Confluence pages and generate git-style diffs against local documentation.
+
+## Features
+
+- **URL-based fetching**: Pass any Confluence page URL, automatically extracts page ID
+- **Clean text extraction**: Converts Confluence storage HTML to readable text/markdown
+- **Git-style diffs**: Generate unified diffs comparing Confluence docs with local documentation
+- **Flexible auth**: Supports scoped API tokens with Bearer authentication
+- **Dual routing**: Works with cloudId routing or direct baseUrl
+- **Zero install**: Use via `npx` for frictionless setup
+
+## Quick Start
+
+### 1. Set Environment Variables
+
+Get your scoped API token from: https://support.atlassian.com/confluence/kb/scoped-api-tokens-in-confluence-cloud/
+
+```bash
+export CONFLUENCE_TOKEN="your_scoped_token_here"
+export CONFLUENCE_CLOUD_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+```
+
+Or copy `.env.example` to `.env` and fill in your values.
+
+### 2. Install Dependencies & Build
+
+```bash
+npm install
+npm run build
+```
+
+### 3. Configure MCP
+
+Add to your MCP settings configuration file (e.g., `mcp.json` or similar):
+
+```json
+{
+  "mcpServers": {
+    "confluence-reader": {
+      "command": "npx",
+      "args": ["@satiyap/confluence-reader-mcp"],
+      "env": {
+        "CONFLUENCE_TOKEN": "${env:CONFLUENCE_TOKEN}",
+        "CONFLUENCE_CLOUD_ID": "${env:CONFLUENCE_CLOUD_ID}"
+      }
+    }
+  }
+}
+```
+
+### 4. Restart Your MCP Host
+
+Restart your MCP-compatible application to load the server.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CONFLUENCE_TOKEN` | Yes | [Scoped API token](https://support.atlassian.com/confluence/kb/scoped-api-tokens-in-confluence-cloud/) (Bearer auth only) |
+| `CONFLUENCE_CLOUD_ID` | Recommended | Atlassian Cloud ID for api.atlassian.com routing |
+| `CONFLUENCE_BASE_URL` | Optional | Fallback: `https://yourtenant.atlassian.net` |
+
+**Authentication:**
+- Only supports scoped API tokens with Bearer authentication
+- No email/password or Basic auth support
+
+**Routing:**
+- If `CONFLUENCE_CLOUD_ID` is set, uses `https://api.atlassian.com/ex/confluence/{cloudId}`
+- Otherwise uses `CONFLUENCE_BASE_URL`
+
+## Available Tools
+
+### `confluence.fetch_doc`
+
+Fetch a Confluence Cloud page by URL, returning clean text for analysis.
+
+**Parameters:**
+- `url` (string, required): Confluence page URL
+  - Supports: `/wiki/spaces/KEY/pages/123456789/Title`
+  - Supports: `/wiki/pages/viewpage.action?pageId=123456789`
+- `includeStorageHtml` (boolean, optional): If true, also returns original storage HTML
+
+**Returns:**
+```json
+{
+  "pageId": "123456789",
+  "title": "Page Title",
+  "status": "current",
+  "version": 42,
+  "webui": "/wiki/spaces/...",
+  "extractedText": "Clean text content...",
+  "storageHtml": "..." // if includeStorageHtml=true
+}
+```
+
+### `docs.build_comparison_bundle`
+
+Build a git-style unified diff comparing local documentation against Confluence content.
+
+**Parameters:**
+- `confluenceText` (string, required): Text from `confluence.fetch_doc.extractedText`
+- `prd` (string, optional): Local document text (e.g., PRD, requirements)
+- `systemOverview` (string, optional): Local document text (e.g., architecture overview)
+- `systemDesign` (string, optional): Local document text (e.g., technical design)
+- `lld` (string, optional): Local document text (e.g., detailed design, implementation notes)
+
+**Note:** Parameter names are flexible - use them for any type of documentation you want to compare.
+
+**Returns:**
+```json
+{
+  "totalComparisons": 2,
+  "diffs": [
+    {
+      "document": "PRD",
+      "additions": 15,
+      "deletions": 8,
+      "totalChanges": 23,
+      "diff": "--- a/confluence\n+++ b/prd\n@@ -1,5 +1,5 @@\n context line\n-removed line\n+added line\n context line"
+    },
+    {
+      "document": "System Design",
+      "additions": 42,
+      "deletions": 12,
+      "totalChanges": 54,
+      "diff": "..."
+    }
+  ]
+}
+```
+
+## Usage Example
+
+When a user provides a Confluence URL in their prompt:
+
+1. AI assistant detects the URL
+2. Calls `confluence.fetch_doc` with the URL
+3. Calls `docs.build_comparison_bundle` with:
+   - `confluenceText` from step 2
+   - Local documentation content from filesystem
+4. AI assistant analyzes the structured comparison and reports differences
+
+## Supported Confluence URL Formats
+
+- `/wiki/spaces/SPACEKEY/pages/123456789/Page+Title`
+- `/wiki/pages/viewpage.action?pageId=123456789`
+- Any URL containing `/pages/<numeric-id>/`
+
+## Project Structure
+
+```
+confluence-reader-mcp/
+├── src/
+│   ├── index.ts                    # MCP server + tool registrations
+│   ├── confluence/
+│   │   ├── client.ts               # HTTP client with scoped token auth
+│   │   ├── url.ts                  # URL → pageId parser
+│   │   ├── types.ts                # API response types
+│   │   └── transform.ts            # Storage HTML → text converter
+│   └── compare/
+│       └── diff.ts                 # Git-style unified diff generator
+├── dist/                           # Compiled output
+├── package.json                    # Binary: confluence-reader-mcp
+├── tsconfig.json
+├── .env.example
+├── .gitignore
+└── README.md
+```
+
+## Development
+
+```bash
+npm run dev     # Run with tsx (no build needed)
+npm run build   # Compile TypeScript
+npm start       # Run compiled server
+```
+
+## Security Notes
+
+- Never commit tokens to git (see `.gitignore`)
+- Use scoped API tokens with minimal permissions
+- Tokens are read from OS environment only
+- No tokens in config files
+
+## Publishing to npm (Optional)
+
+Once ready for public use:
+
+1. Build the package:
+   ```bash
+   npm run build
+   ```
+2. Publish to npm:
+   ```bash
+   npm publish --access public
+   ```
+
+## API References
+
+- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Confluence REST API v2](https://developer.atlassian.com/cloud/confluence/rest/v2/)
+- [Atlassian Scoped API Tokens](https://support.atlassian.com/confluence/kb/scoped-api-tokens-in-confluence-cloud/)
+
+## License
+
+MIT

package/dist/compare/diff.js

@@ -0,0 +1,122 @@
+/**
+ * Generate a git-style unified diff between two texts
+ * This is a simple line-based diff implementation
+ */
+function longestCommonSubsequence(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const dp = Array(m + 1).fill(0).map(() => Array(n + 1).fill(0));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            if (a[i - 1] === b[j - 1]) {
+                dp[i][j] = dp[i - 1][j - 1] + 1;
+            }
+            else {
+                dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1]);
+            }
+        }
+    }
+    return dp;
+}
+function buildDiff(a, b, dp) {
+    const result = [];
+    let i = a.length;
+    let j = b.length;
+    while (i > 0 || j > 0) {
+        if (i > 0 && j > 0 && a[i - 1] === b[j - 1]) {
+            result.unshift({ type: 'context', line: a[i - 1], oldLineNum: i, newLineNum: j });
+            i--;
+            j--;
+        }
+        else if (j > 0 && (i === 0 || dp[i][j - 1] >= dp[i - 1][j])) {
+            result.unshift({ type: 'add', line: b[j - 1], newLineNum: j });
+            j--;
+        }
+        else if (i > 0) {
+            result.unshift({ type: 'remove', line: a[i - 1], oldLineNum: i });
+            i--;
+        }
+    }
+    return result;
+}
+function formatUnifiedDiff(oldLabel, newLabel, diffLines, contextLines = 3) {
+    if (diffLines.length === 0) {
+        return `--- ${oldLabel}\n+++ ${newLabel}\n(no differences)\n`;
+    }
+    const output = [];
+    output.push(`--- ${oldLabel}`);
+    output.push(`+++ ${newLabel}`);
+    // Group changes into hunks
+    const hunks = [];
+    let currentHunk = [];
+    let lastChangeIndex = -1;
+    diffLines.forEach((line, idx) => {
+        const isChange = line.type !== 'context';
+        if (isChange) {
+            // Include context before and after
+            const start = Math.max(0, lastChangeIndex + 1, idx - contextLines);
+            const contextBefore = diffLines.slice(start, idx).filter(l => !currentHunk.includes(l));
+            currentHunk.push(...contextBefore, line);
+            lastChangeIndex = idx;
+        }
+        else if (lastChangeIndex >= 0 && idx - lastChangeIndex <= contextLines) {
+            // Context after a change
+            currentHunk.push(line);
+        }
+        else if (lastChangeIndex >= 0 && idx - lastChangeIndex > contextLines) {
+            // End current hunk
+            if (currentHunk.length > 0) {
+                hunks.push(currentHunk);
+                currentHunk = [];
+            }
+            lastChangeIndex = -1;
+        }
+    });
+    if (currentHunk.length > 0) {
+        hunks.push(currentHunk);
+    }
+    // Format each hunk
+    hunks.forEach(hunk => {
+        const firstLine = hunk[0];
+        const lastLine = hunk[hunk.length - 1];
+        const oldStart = firstLine.oldLineNum || 1;
+        const newStart = firstLine.newLineNum || 1;
+        const oldCount = hunk.filter(l => l.type !== 'add').length;
+        const newCount = hunk.filter(l => l.type !== 'remove').length;
+        output.push(`@@ -${oldStart},${oldCount} +${newStart},${newCount} @@`);
+        hunk.forEach(line => {
+            switch (line.type) {
+                case 'context':
+                    output.push(` ${line.line}`);
+                    break;
+                case 'add':
+                    output.push(`+${line.line}`);
+                    break;
+                case 'remove':
+                    output.push(`-${line.line}`);
+                    break;
+            }
+        });
+    });
+    return output.join('\n');
+}
+export function generateUnifiedDiff(oldText, newText, oldLabel = 'a/original', newLabel = 'b/modified') {
+    const oldLines = oldText.split('\n');
+    const newLines = newText.split('\n');
+    const dp = longestCommonSubsequence(oldLines, newLines);
+    const diffLines = buildDiff(oldLines, newLines, dp);
+    return formatUnifiedDiff(oldLabel, newLabel, diffLines);
+}
+export function generateDiffStats(oldText, newText) {
+    const oldLines = oldText.split('\n');
+    const newLines = newText.split('\n');
+    const dp = longestCommonSubsequence(oldLines, newLines);
+    const diffLines = buildDiff(oldLines, newLines, dp);
+    const additions = diffLines.filter(l => l.type === 'add').length;
+    const deletions = diffLines.filter(l => l.type === 'remove').length;
+    return {
+        additions,
+        deletions,
+        changes: additions + deletions
+    };
+}

package/dist/confluence/client.js

@@ -0,0 +1,47 @@
+/**
+ * Build authorization headers for Confluence API requests
+ * Only supports scoped API tokens with Bearer authentication
+ *
+ * @see https://support.atlassian.com/confluence/kb/scoped-api-tokens-in-confluence-cloud/
+ */
+function buildAuthHeaders(cfg) {
+    return { Authorization: `Bearer ${cfg.token}` };
+}
+/**
+ * Build base URL for Confluence API requests
+ * Prefers cloudId routing over direct baseUrl
+ */
+function buildBase(cfg) {
+    // Prefer cloudId routing (works well with scoped token access patterns)
+    if (cfg.cloudId)
+        return `https://api.atlassian.com/ex/confluence/${cfg.cloudId}`;
+    if (cfg.baseUrl)
+        return cfg.baseUrl;
+    throw new Error("Set CONFLUENCE_CLOUD_ID or CONFLUENCE_BASE_URL.");
+}
+/**
+ * Fetch a Confluence page by ID using the v2 REST API
+ *
+ * @param cfg - Client configuration with token and routing info
+ * @param pageId - Numeric page ID
+ * @returns Page data including title, content, and metadata
+ * @throws Error if API request fails
+ */
+export async function fetchPageById(cfg, pageId) {
+    const base = buildBase(cfg);
+    // v2 endpoint with body-format=storage to get HTML content
+    const url = new URL(`${base}/wiki/api/v2/pages/${pageId}`);
+    url.searchParams.set("body-format", "storage");
+    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)}`);
+    }
+    return (await res.json());
+}

package/dist/confluence/transform.js

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ *
+ * @param storageHtml - Confluence storage format HTML
+ * @returns Plain text representation
+ */
+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");
+}

package/dist/confluence/types.js

@@ -0,0 +1 @@
+export {};

package/dist/confluence/url.js

@@ -0,0 +1,32 @@
+/**
+ * Extract Confluence page ID from various URL formats
+ *
+ * Supported formats:
+ * - /wiki/spaces/KEY/pages/123456789/Title
+ * - /wiki/pages/viewpage.action?pageId=123456789
+ *
+ * @param url - Full Confluence page URL
+ * @returns Page ID as string
+ * @throws Error if URL format is not recognized
+ */
+export function extractConfluencePageId(url) {
+    // Common Confluence Cloud patterns:
+    // 1) /wiki/spaces/KEY/pages/123456789/Title
+    // 2) /wiki/pages/viewpage.action?pageId=123456789
+    // 3) Some short links redirect, but the final URL usually matches one of the above.
+    try {
+        const u = new URL(url);
+        // Pattern 2: viewpage.action?pageId=...
+        const pageId = u.searchParams.get("pageId");
+        if (pageId && /^\d+$/.test(pageId))
+            return pageId;
+        // Pattern 1: .../pages/<id>/...
+        const m = u.pathname.match(/\/pages\/(\d+)(\/|$)/);
+        if (m?.[1])
+            return m[1];
+        throw new Error("Unsupported Confluence URL format (no pageId found).");
+    }
+    catch (e) {
+        throw new Error(`Invalid URL: ${e.message}`);
+    }
+}

package/dist/index.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+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 } from "./confluence/client.js";
+import { storageToText } from "./confluence/transform.js";
+import { generateUnifiedDiff, generateDiffStats } from "./compare/diff.js";
+const server = new McpServer({
+    name: "confluence-reader-mcp",
+    version: "0.1.0"
+});
+function getEnv(name) {
+    const v = process.env[name];
+    return v && v.trim().length > 0 ? v.trim() : undefined;
+}
+server.tool("confluence.fetch_doc", "Fetch a Confluence Cloud page by URL using env-scoped credentials, returning clean text for analysis.", {
+    url: z.string().describe("Confluence page URL (e.g. /wiki/spaces/.../pages/<id>/...)"),
+    includeStorageHtml: z.boolean().optional().describe("If true, also return original storage HTML")
+}, async ({ url, includeStorageHtml }) => {
+    const token = getEnv("CONFLUENCE_TOKEN");
+    const cloudId = getEnv("CONFLUENCE_CLOUD_ID");
+    const baseUrl = getEnv("CONFLUENCE_BASE_URL");
+    if (!token)
+        throw new Error("Missing CONFLUENCE_TOKEN env var (scoped API token required).");
+    const pageId = extractConfluencePageId(url);
+    const page = await fetchPageById({ token, cloudId, baseUrl }, pageId);
+    const storage = page.body?.storage?.value ?? "";
+    const text = storage ? storageToText(storage) : "";
+    const payload = {
+        pageId: page.id,
+        title: page.title,
+        status: page.status,
+        version: page.version?.number,
+        webui: page._links?.webui,
+        extractedText: text,
+        ...(includeStorageHtml ? { storageHtml: storage } : {})
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+    };
+});
+// Helper tool to generate git-style diffs between Confluence and local docs
+server.tool("docs.build_comparison_bundle", "Build a git-style unified diff comparing PRD/System Overview/System Design/LLD against a Confluence page text.", {
+    confluenceText: z.string().describe("Text extracted from Confluence (output of confluence.fetch_doc.extractedText)"),
+    prd: z.string().optional().describe("Local PRD text"),
+    systemOverview: z.string().optional().describe("Local System Overview text"),
+    systemDesign: z.string().optional().describe("Local System Design text"),
+    lld: z.string().optional().describe("Local LLD text")
+}, async (args) => {
+    const diffs = [];
+    const sections = [
+        ["PRD", args.prd],
+        ["System Overview", args.systemOverview],
+        ["System Design", args.systemDesign],
+        ["LLD", args.lld]
+    ].filter(([, v]) => !!v && v.trim().length > 0);
+    for (const [name, localText] of sections) {
+        const docName = name;
+        const diff = generateUnifiedDiff(args.confluenceText.trim(), localText.trim(), `a/confluence`, `b/${docName.toLowerCase().replace(/\s+/g, '-')}`);
+        const stats = generateDiffStats(args.confluenceText.trim(), localText.trim());
+        diffs.push({ name: docName, diff, stats });
+    }
+    const summary = {
+        totalComparisons: diffs.length,
+        diffs: diffs.map(d => ({
+            document: d.name,
+            additions: d.stats.additions,
+            deletions: d.stats.deletions,
+            totalChanges: d.stats.changes,
+            diff: d.diff
+        }))
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("MCP server failed:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@satiyap/confluence-reader-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for fetching and comparing Confluence documentation with local files",
+  "author": "satiyap",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "confluence",
+    "documentation",
+    "model-context-protocol"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/satiyap/confluence-reader-mcp.git"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "confluence-reader-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}