@satiyap/confluence-reader-mcp 0.1.1 → 0.1.2

package/README.md

@@ -2,39 +2,35 @@
 
 [![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.
+An MCP server that lets AI assistants read Confluence pages, walk page trees, and diff Confluence content against local documentation.
 
-## Features
+## Setup
 
-- **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
+### 1. Get a Confluence API Token
 
-## Quick Start
+Create a scoped API token at: https://support.atlassian.com/confluence/kb/scoped-api-tokens-in-confluence-cloud/
 
-### 1. Set Environment Variables
+### 2. Set Environment Variables
 
-Add these to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.):
+Add to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.):
 
 ```bash
-export CONFLUENCE_TOKEN="your_scoped_token_here"
-export CONFLUENCE_EMAIL="your.email@company.com"
+export CONFLUENCE_TOKEN="your_scoped_token"
+export CONFLUENCE_EMAIL="you@company.com"
 export CONFLUENCE_CLOUD_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
 ```
 
-Then reload your shell (`source ~/.zshrc`) or open a new terminal.
+Reload your shell or open a new terminal.
 
-Get your scoped API token from: https://support.atlassian.com/confluence/kb/scoped-api-tokens-in-confluence-cloud/
-
-### 2. Configure MCP
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `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` |
 
-Add to your MCP settings (`mcp.json`). No `env` block needed — credentials come from `.env`:
+### 3. Add to MCP Config
 
 ```json
 {
@@ -47,173 +43,47 @@ Add to your MCP settings (`mcp.json`). No `env` block needed — credentials com
 }
 ```
 
-### 3. Restart Your MCP Host
+Restart the MCP host to pick up the new server.
 
-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/) |
-| `CONFLUENCE_EMAIL` | ✅ Yes | Email address associated with your Atlassian account |
-| `CONFLUENCE_CLOUD_ID` | Recommended | Atlassian Cloud ID for api.atlassian.com routing |
-| `CONFLUENCE_BASE_URL` | Optional | Fallback: `https://yourtenant.atlassian.net` |
+## Tools
 
-**Authentication:**
-- Uses scoped API tokens with Basic authentication (email:token)
-- Scoped tokens provide granular access control and better security than legacy API tokens
+### `confluence.fetch_page`
 
-**Routing:**
-- If `CONFLUENCE_CLOUD_ID` is set → Uses `https://api.atlassian.com/ex/confluence/{cloudId}`
-- Otherwise uses `CONFLUENCE_BASE_URL`
+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.
 
-## Available Tools
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | string | Confluence page URL |
 
-### `confluence.fetch_doc`
+### `confluence.fetch_page_tree`
 
-Fetch a Confluence Cloud page by URL, returning clean text for analysis.
+Fetches a page and all its descendants recursively, up to a given depth. Returns a single markdown document with nested headings.
 
-**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
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `url` | string | — | Confluence page URL |
+| `depth` | number | 1 | How many levels of children to fetch |
 
-**Returns:**
-```json
-{
-  "pageId": "123456789",
-  "title": "Page Title",
-  "status": "current",
-  "version": 42,
-  "webui": "/wiki/spaces/...",
-  "extractedText": "Clean text content...",
-  "storageHtml": "..." // if includeStorageHtml=true
-}
-```
+### `confluence.compare`
 
-### `docs.build_comparison_bundle`
+Generates a git-style unified diff between a Confluence page and a local markdown string.
 
-Build a git-style unified diff comparing local documentation against Confluence content.
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | string | Confluence page URL |
+| `localContent` | string | Local markdown to compare against |
 
-**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)
+Returns a JSON object with `additions`, `deletions`, `totalChanges`, and the full `diff`.
 
-**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
+## Supported 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
-├── .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
-
-- ✅ Credentials read from OS environment variables only — never in config files
-- ✅ Never commit tokens to git
-- ✅ Use scoped API tokens with minimal permissions
-
-## Publishing to npm (Optional)
-
-Once ready for public use:
-
-1. Update `package.json` with your repository URL and author info
-2. Build the package:
-   ```bash
-   npm run build
-   ```
-3. Publish to npm:
-   ```bash
-   npm publish --access public
-   ```
-
-Then users can use this minimal config (no env block needed):
-```json
-{
-  "mcpServers": {
-    "confluence-reader": {
-      "command": "npx",
-      "args": ["@satiyap/confluence-reader-mcp"]
-    }
-  }
-}
-```
-
-**Note:** Users must set `CONFLUENCE_TOKEN`, `CONFLUENCE_EMAIL`, and `CONFLUENCE_CLOUD_ID` as OS environment variables.
 
-## API References
+## Security
 
-- [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/)
+- Credentials are read from environment variables only — never passed in config files.
+- Use scoped tokens with the minimum permissions needed.
 
 ## License
 

package/dist/confluence/client.js

@@ -51,3 +51,39 @@ export async function fetchPageById(cfg, pageId) {
     }
     return (await res.json());
 }
+/**
+ * Fetch direct child pages of a Confluence page using the v2 REST API.
+ * Returns all children (paginates automatically).
+ */
+export async function fetchChildPages(cfg, pageId) {
+    const base = buildBase(cfg);
+    const all = [];
+    let cursor;
+    while (true) {
+        const url = new URL(`${base}/wiki/api/v2/pages/${pageId}/children`);
+        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;
+        // The next link contains the cursor parameter
+        const nextUrl = new URL(data._links.next, base);
+        cursor = nextUrl.searchParams.get("cursor") ?? undefined;
+        if (!cursor)
+            break;
+    }
+    return all;
+}

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, buildAuthHeaders, buildBase } from "./confluence/client.js";
+import { fetchPageById, fetchChildPages, buildAuthHeaders, buildBase } 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.1"
+    version: "0.1.2"
 });
 function getEnv(name) {
     const v = process.env[name];
@@ -46,20 +46,55 @@ server.tool("confluence.fetch_page", "Fetch a Confluence page and return it as m
     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({ token, email, cloudId, baseUrl }, pageId);
+    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;
     return {
-        content: [{ type: "text", text: markdown }]
+        content: [{ type: "text", text: body }]
     };
 });
 server.tool("confluence.fetch_page_tree", "Fetch a Confluence page and all its child pages recursively up to a specified depth.", {
     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 }) => {
-    // TODO: Implement recursive child page fetching
-    throw new Error("Not yet implemented - coming soon!");
+    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);
+    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);
+    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");
+    }
+    return {
+        content: [{ type: "text", text: renderTree(tree, 0) }]
+    };
 });
 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"),

package/package.json

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