@neverprepared/mcp-markdown-to-confluence 1.0.1

package/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    name: Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+        env:
+          PUPPETEER_SKIP_DOWNLOAD: "true"
+
+      - name: Build
+        run: npm run build

package/.github/workflows/release-please.yml

@@ -0,0 +1,48 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+  packages: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          release-type: node
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true'
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          registry-url: https://registry.npmjs.org/
+
+      - name: Install dependencies
+        run: npm ci
+        env:
+          PUPPETEER_SKIP_DOWNLOAD: "true"
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [1.0.1](https://github.com/neverprepared/mcp-markdown-to-confluence/compare/v1.0.0...v1.0.1) (2026-04-01)
+
+
+### Bug Fixes
+
+* resolve packages from npm registry and fix API compatibility ([7b36bd7](https://github.com/neverprepared/mcp-markdown-to-confluence/commit/7b36bd78f9f0ad07c2e0e60658584b443215668e))
+* skip Puppeteer Chromium download in CI ([31da53d](https://github.com/neverprepared/mcp-markdown-to-confluence/commit/31da53d48ea88b5444df5715bf414a4d4d70cca5))
+
+## 1.0.0 (2026-04-01)
+
+
+### Bug Fixes
+
+* resolve packages from npm registry and fix API compatibility ([7b36bd7](https://github.com/neverprepared/mcp-markdown-to-confluence/commit/7b36bd78f9f0ad07c2e0e60658584b443215668e))

package/README.md

@@ -0,0 +1,134 @@
+# mcp-markdown-to-confluence
+
+An MCP (Model Context Protocol) server that converts Markdown files to Atlassian Document Format (ADF) and publishes them to Confluence. Mermaid diagrams are rendered to PNG images and uploaded as page attachments.
+
+## Features
+
+- Convert Markdown → Confluence ADF with full formatting support (tables, code blocks, callouts, TOC)
+- Render Mermaid diagrams to PNG via headless Chromium and attach them to pages
+- Preview content before publishing
+- Create new pages or update existing ones
+- Publish from inline Markdown or directly from a `.md` file using frontmatter
+
+## Installation
+
+### npm
+
+```bash
+npm install @neverprepared/mcp-markdown-to-confluence
+```
+
+### From source
+
+```bash
+git clone https://github.com/neverprepared/mcp-markdown-to-confluence.git
+cd mcp-markdown-to-confluence
+npm install
+npm run build
+```
+
+## Configuration
+
+Set the following environment variables:
+
+| Variable | Description |
+|---|---|
+| `CONFLUENCE_BASE_URL` | Your Confluence base URL, e.g. `https://your-org.atlassian.net` |
+| `CONFLUENCE_USERNAME` | Your Atlassian account email |
+| `CONFLUENCE_API_TOKEN` | Your Atlassian API token ([create one here](https://id.atlassian.com/manage-profile/security/api-tokens)) |
+
+## Claude Code Setup
+
+Add to your Claude Code MCP config (`.claude/.claude.json`):
+
+```json
+{
+  "mcpServers": {
+    "markdown-to-confluence": {
+      "command": "node",
+      "args": ["/path/to/mcp-markdown-to-confluence/dist/index.js"],
+      "env": {
+        "CONFLUENCE_BASE_URL": "https://your-org.atlassian.net",
+        "CONFLUENCE_USERNAME": "you@example.com",
+        "CONFLUENCE_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### `markdown_preview`
+
+Convert Markdown to ADF and return a text preview — no Confluence calls made.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `markdown` | string | yes | Markdown content to preview |
+| `title` | string | yes | Page title |
+
+### `markdown_publish`
+
+Publish Markdown to a Confluence page. By default shows a preview first.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `markdown` | string | yes | Markdown content |
+| `title` | string | yes | Confluence page title |
+| `spaceKey` | string | yes | Confluence space key (e.g. `ENG`) |
+| `pageId` | string | no | Existing page ID to update; omit to create a new page |
+| `parentId` | string | no | Parent page ID for new pages |
+| `skip_preview` | boolean | no | Set `true` to publish without preview (default: `false`) |
+
+### `markdown_publish_file`
+
+Read a `.md` file from disk and publish it. Page metadata is read from frontmatter.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `filePath` | string | yes | Absolute path to the Markdown file |
+| `skip_preview` | boolean | no | Set `true` to publish without preview (default: `false`) |
+
+**Supported frontmatter keys:**
+
+```yaml
+---
+connie-title: My Page Title
+connie-space-key: ENG
+connie-page-id: "123456"   # omit to create a new page
+title: Fallback title      # used if connie-title is absent
+---
+```
+
+## Preview Flow
+
+By default, `markdown_publish` and `markdown_publish_file` return a rendered preview and prompt you to confirm before publishing. To publish in one step, pass `skip_preview: true`.
+
+```
+# Step 1 — review
+markdown_publish(markdown: "...", title: "My Page", spaceKey: "ENG")
+→ returns preview text
+
+# Step 2 — publish
+markdown_publish(markdown: "...", title: "My Page", spaceKey: "ENG", skip_preview: true)
+→ returns page URL
+```
+
+## Mermaid Diagrams
+
+Mermaid code blocks are automatically detected, rendered to PNG via headless Chromium (bundled with Puppeteer), and uploaded as Confluence page attachments. The first run will download Chromium (~170 MB).
+
+````markdown
+```mermaid
+flowchart TD
+  A[Write Markdown] --> B[Preview]
+  B --> C{Looks good?}
+  C -- Yes --> D[Publish]
+  C -- No --> A
+```
+````
+
+## License
+
+MIT

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,357 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { ConfluenceClient } from 'confluence.js';
+import matter from 'gray-matter';
+import { readFile } from 'fs/promises';
+import { parseMarkdownToADF, renderADFDoc, executeADFProcessingPipeline, createPublisherFunctions, } from '@markdown-confluence/lib';
+import { MermaidRendererPlugin } from '@markdown-confluence/lib';
+import { PuppeteerMermaidRenderer } from '@markdown-confluence/mermaid-puppeteer-renderer';
+// ---------------------------------------------------------------------------
+// Environment
+// ---------------------------------------------------------------------------
+const CONFLUENCE_BASE_URL = process.env.CONFLUENCE_BASE_URL ?? '';
+const CONFLUENCE_USERNAME = process.env.CONFLUENCE_USERNAME ?? '';
+const CONFLUENCE_API_TOKEN = process.env.CONFLUENCE_API_TOKEN ?? '';
+// ---------------------------------------------------------------------------
+// Confluence client
+// ---------------------------------------------------------------------------
+const confluenceClient = new ConfluenceClient({
+    host: CONFLUENCE_BASE_URL,
+    authentication: {
+        basic: {
+            email: CONFLUENCE_USERNAME,
+            apiToken: CONFLUENCE_API_TOKEN,
+        },
+    },
+});
+// ---------------------------------------------------------------------------
+// Stub LoaderAdaptor — only uploadBuffer is called by the mermaid plugin
+// ---------------------------------------------------------------------------
+const stubAdaptor = {
+    readFile: async (_filePath) => undefined,
+    readBinary: async (_filePath) => false,
+    fileExists: async (_filePath) => false,
+    listFiles: async () => [],
+    uploadBuffer: async (_buffer, _fileName, _mimeType) => undefined,
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function countMermaidBlocks(adf) {
+    if (typeof adf !== 'object' || adf === null)
+        return 0;
+    const node = adf;
+    let count = 0;
+    if (node['type'] === 'codeBlock' &&
+        typeof node['attrs'] === 'object' &&
+        node['attrs'] !== null &&
+        node['attrs']['language'] === 'mermaid') {
+        count += 1;
+    }
+    for (const value of Object.values(node)) {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                count += countMermaidBlocks(item);
+            }
+        }
+        else if (typeof value === 'object' && value !== null) {
+            count += countMermaidBlocks(value);
+        }
+    }
+    return count;
+}
+// ---------------------------------------------------------------------------
+// Core publish logic
+// ---------------------------------------------------------------------------
+async function publishMarkdown(markdown, title, spaceKey, pageId, parentId, skipPreview = false) {
+    // Parse markdown → ADF
+    const adf = parseMarkdownToADF(markdown, CONFLUENCE_BASE_URL);
+    const mermaidCount = countMermaidBlocks(adf);
+    if (!skipPreview) {
+        const previewText = renderADFDoc(adf);
+        return { isPreview: true, previewText, mermaidCount };
+    }
+    // ----- Full publish -----
+    let currentVersion = 1;
+    let resolvedPageId = pageId;
+    if (resolvedPageId) {
+        // Fetch existing page to get current version
+        const existingPage = await confluenceClient.content.getContentById({
+            id: resolvedPageId,
+            expand: ['version'],
+        });
+        currentVersion = existingPage.version.number;
+    }
+    else {
+        // Create a placeholder page to obtain a pageId
+        const blankAdf = {
+            version: 1,
+            type: 'doc',
+            content: [],
+        };
+        const createParams = {
+            space: { key: spaceKey },
+            title,
+            type: 'page',
+            body: {
+                atlas_doc_format: {
+                    value: JSON.stringify(blankAdf),
+                    representation: 'atlas_doc_format',
+                },
+            },
+        };
+        if (parentId) {
+            createParams.ancestors = [{ id: parentId }];
+        }
+        const created = await confluenceClient.content.createContent(createParams);
+        resolvedPageId = created.id;
+        currentVersion = created.version.number;
+    }
+    // Fetch current attachments to build the map
+    const attachmentsResult = await confluenceClient.contentAttachments.getAttachments({
+        id: resolvedPageId,
+    });
+    const currentAttachments = {};
+    for (const att of attachmentsResult.results ?? []) {
+        const attTitle = att.title ?? '';
+        const fileId = att.extensions?.fileId ?? '';
+        const collectionName = att.extensions?.collectionName ?? '';
+        if (attTitle) {
+            currentAttachments[attTitle] = {
+                filehash: att.metadata?.comment ?? '',
+                attachmentId: fileId,
+                collectionName,
+            };
+        }
+    }
+    // Build publisher functions
+    const publisherFunctions = createPublisherFunctions(confluenceClient, stubAdaptor, resolvedPageId, title, currentAttachments);
+    // Run ADF processing pipeline (renders mermaid diagrams)
+    const finalAdf = await executeADFProcessingPipeline([new MermaidRendererPlugin(new PuppeteerMermaidRenderer())], adf, publisherFunctions);
+    // Update the page with the final ADF
+    const updateParams = {
+        id: resolvedPageId,
+        title,
+        type: 'page',
+        version: { number: currentVersion + 1 },
+        body: {
+            atlas_doc_format: {
+                value: JSON.stringify(finalAdf),
+                representation: 'atlas_doc_format',
+            },
+        },
+    };
+    if (parentId) {
+        updateParams.ancestors = [{ id: parentId }];
+    }
+    await confluenceClient.content.updateContent(updateParams);
+    const url = `${CONFLUENCE_BASE_URL}/wiki/spaces/${spaceKey}/pages/${resolvedPageId}`;
+    return {
+        isPreview: false,
+        pageId: resolvedPageId,
+        version: currentVersion + 1,
+        mermaidCount,
+        url,
+    };
+}
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+const server = new Server({ name: 'mcp-markdown-to-confluence', version: '1.0.0' }, { capabilities: { tools: {} } });
+// Tool definitions
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: 'markdown_preview',
+            description: 'Convert markdown to Confluence ADF and return a text preview. Does not publish to Confluence.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    markdown: { type: 'string', description: 'Markdown content to preview' },
+                    title: { type: 'string', description: 'Page title (used during ADF conversion)' },
+                },
+                required: ['markdown', 'title'],
+            },
+        },
+        {
+            name: 'markdown_publish',
+            description: 'Publish markdown to a Confluence page. By default runs a preview first; set skip_preview: true to publish immediately.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    markdown: { type: 'string', description: 'Markdown content to publish' },
+                    title: { type: 'string', description: 'Confluence page title' },
+                    spaceKey: { type: 'string', description: 'Confluence space key (e.g. "ENG")' },
+                    pageId: {
+                        type: 'string',
+                        description: 'Existing page ID to update (omit to create a new page)',
+                    },
+                    parentId: {
+                        type: 'string',
+                        description: 'Parent page ID for new page creation',
+                    },
+                    skip_preview: {
+                        type: 'boolean',
+                        description: 'Set to true to skip preview and publish immediately',
+                        default: false,
+                    },
+                },
+                required: ['markdown', 'title', 'spaceKey'],
+            },
+        },
+        {
+            name: 'markdown_publish_file',
+            description: 'Read a markdown file from disk and publish it to Confluence. Frontmatter keys: connie-title / title, connie-space-key, connie-page-id.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    filePath: { type: 'string', description: 'Absolute path to the markdown file' },
+                    skip_preview: {
+                        type: 'boolean',
+                        description: 'Set to true to skip preview and publish immediately',
+                        default: false,
+                    },
+                },
+                required: ['filePath'],
+            },
+        },
+    ],
+}));
+// Tool handlers
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        if (name === 'markdown_preview') {
+            const input = z
+                .object({ markdown: z.string(), title: z.string() })
+                .parse(args);
+            const adf = parseMarkdownToADF(input.markdown, CONFLUENCE_BASE_URL);
+            const mermaidCount = countMermaidBlocks(adf);
+            const previewText = renderADFDoc(adf);
+            const lines = [previewText];
+            if (mermaidCount > 0) {
+                lines.push(`\n[Note: ${mermaidCount} mermaid diagram(s) detected — they will be rendered as images when published.]`);
+            }
+            return { content: [{ type: 'text', text: lines.join('') }] };
+        }
+        if (name === 'markdown_publish') {
+            const input = z
+                .object({
+                markdown: z.string(),
+                title: z.string(),
+                spaceKey: z.string(),
+                pageId: z.string().optional(),
+                parentId: z.string().optional(),
+                skip_preview: z.boolean().default(false),
+            })
+                .parse(args);
+            const result = await publishMarkdown(input.markdown, input.title, input.spaceKey, input.pageId, input.parentId, input.skip_preview);
+            if (result.isPreview) {
+                const lines = ['=== PREVIEW ===\n', result.previewText ?? ''];
+                if ((result.mermaidCount ?? 0) > 0) {
+                    lines.push(`\n[Note: ${result.mermaidCount} mermaid diagram(s) detected — they will be rendered when published.]`);
+                }
+                lines.push('\n\nCall again with skip_preview: true to publish to Confluence.');
+                return { content: [{ type: 'text', text: lines.join('') }] };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: [
+                            `Successfully published to Confluence.`,
+                            `Title: ${input.title}`,
+                            `Page ID: ${result.pageId}`,
+                            `Version: ${result.version}`,
+                            `Mermaid diagrams rendered: ${result.mermaidCount}`,
+                            `URL: ${result.url}`,
+                        ].join('\n'),
+                    },
+                ],
+            };
+        }
+        if (name === 'markdown_publish_file') {
+            const input = z
+                .object({
+                filePath: z.string(),
+                skip_preview: z.boolean().default(false),
+            })
+                .parse(args);
+            const raw = await readFile(input.filePath, 'utf-8');
+            const parsed = matter(raw);
+            const title = parsed.data['connie-title'] ?? parsed.data['title'] ?? '';
+            const spaceKey = parsed.data['connie-space-key'] ?? '';
+            const pageId = parsed.data['connie-page-id']
+                ? String(parsed.data['connie-page-id'])
+                : undefined;
+            if (!title) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Error: Missing page title. Set "connie-title" or "title" in frontmatter.',
+                        },
+                    ],
+                };
+            }
+            if (!spaceKey) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Error: Missing space key. Set "connie-space-key" in frontmatter.',
+                        },
+                    ],
+                };
+            }
+            const result = await publishMarkdown(parsed.content, title, spaceKey, pageId, undefined, input.skip_preview);
+            if (result.isPreview) {
+                const lines = [
+                    `File: ${input.filePath}\n`,
+                    '=== PREVIEW ===\n',
+                    result.previewText ?? '',
+                ];
+                if ((result.mermaidCount ?? 0) > 0) {
+                    lines.push(`\n[Note: ${result.mermaidCount} mermaid diagram(s) detected — they will be rendered when published.]`);
+                }
+                lines.push('\n\nCall again with skip_preview: true to publish to Confluence.');
+                return { content: [{ type: 'text', text: lines.join('') }] };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: [
+                            `Successfully published "${title}" to Confluence.`,
+                            `File: ${input.filePath}`,
+                            `Page ID: ${result.pageId}`,
+                            `Version: ${result.version}`,
+                            `Mermaid diagrams rendered: ${result.mermaidCount}`,
+                            `URL: ${result.url}`,
+                        ].join('\n'),
+                    },
+                ],
+            };
+        }
+        return {
+            isError: true,
+            content: [{ type: 'text', text: `Error: Unknown tool "${name}"` }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            isError: true,
+            content: [{ type: 'text', text: `Error: ${message}` }],
+        };
+    }
+});
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@neverprepared/mcp-markdown-to-confluence",
+  "version": "1.0.1",
+  "description": "MCP server for converting markdown to Confluence ADF and publishing pages with mermaid diagram support",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-markdown-to-confluence": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "node --watch dist/index.js"
+  },
+  "dependencies": {
+    "@markdown-confluence/lib": "^5.5.2",
+    "@markdown-confluence/mermaid-puppeteer-renderer": "^5.5.2",
+    "@modelcontextprotocol/sdk": "^1.10.1",
+    "confluence.js": "^1.6.3",
+    "gray-matter": "^4.0.3",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverprepared/mcp-markdown-to-confluence.git"
+  },
+  "keywords": [
+    "mcp",
+    "confluence",
+    "markdown",
+    "atlassian",
+    "mermaid",
+    "model-context-protocol"
+  ],
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,482 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { ConfluenceClient } from 'confluence.js';
+import matter from 'gray-matter';
+import { readFile } from 'fs/promises';
+
+import {
+  parseMarkdownToADF,
+  renderADFDoc,
+  executeADFProcessingPipeline,
+  createPublisherFunctions,
+} from '@markdown-confluence/lib';
+import { MermaidRendererPlugin } from '@markdown-confluence/lib';
+import { PuppeteerMermaidRenderer } from '@markdown-confluence/mermaid-puppeteer-renderer';
+
+// ---------------------------------------------------------------------------
+// Environment
+// ---------------------------------------------------------------------------
+
+const CONFLUENCE_BASE_URL = process.env.CONFLUENCE_BASE_URL ?? '';
+const CONFLUENCE_USERNAME = process.env.CONFLUENCE_USERNAME ?? '';
+const CONFLUENCE_API_TOKEN = process.env.CONFLUENCE_API_TOKEN ?? '';
+
+// ---------------------------------------------------------------------------
+// Confluence client
+// ---------------------------------------------------------------------------
+
+const confluenceClient = new ConfluenceClient({
+  host: CONFLUENCE_BASE_URL,
+  authentication: {
+    basic: {
+      email: CONFLUENCE_USERNAME,
+      apiToken: CONFLUENCE_API_TOKEN,
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Stub LoaderAdaptor — only uploadBuffer is called by the mermaid plugin
+// ---------------------------------------------------------------------------
+
+const stubAdaptor = {
+  readFile: async (_filePath: string) => undefined,
+  readBinary: async (_filePath: string) => false as const,
+  fileExists: async (_filePath: string) => false,
+  listFiles: async () => [],
+  uploadBuffer: async (
+    _buffer: Buffer,
+    _fileName: string,
+    _mimeType: string
+  ) => undefined,
+} as unknown as import('@markdown-confluence/lib').LoaderAdaptor;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function countMermaidBlocks(adf: unknown): number {
+  if (typeof adf !== 'object' || adf === null) return 0;
+
+  const node = adf as Record<string, unknown>;
+  let count = 0;
+
+  if (
+    node['type'] === 'codeBlock' &&
+    typeof node['attrs'] === 'object' &&
+    node['attrs'] !== null &&
+    (node['attrs'] as Record<string, unknown>)['language'] === 'mermaid'
+  ) {
+    count += 1;
+  }
+
+  for (const value of Object.values(node)) {
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        count += countMermaidBlocks(item);
+      }
+    } else if (typeof value === 'object' && value !== null) {
+      count += countMermaidBlocks(value);
+    }
+  }
+
+  return count;
+}
+
+// ---------------------------------------------------------------------------
+// Core publish logic
+// ---------------------------------------------------------------------------
+
+async function publishMarkdown(
+  markdown: string,
+  title: string,
+  spaceKey: string,
+  pageId?: string,
+  parentId?: string,
+  skipPreview = false
+): Promise<{ isPreview: boolean; previewText?: string; mermaidCount?: number; pageId?: string; version?: number; url?: string }> {
+  // Parse markdown → ADF
+  const adf = parseMarkdownToADF(
+    markdown,
+    CONFLUENCE_BASE_URL
+  ) as unknown as any;
+
+  const mermaidCount = countMermaidBlocks(adf);
+
+  if (!skipPreview) {
+    const previewText = renderADFDoc(adf as unknown as any);
+    return { isPreview: true, previewText, mermaidCount };
+  }
+
+  // ----- Full publish -----
+
+  let currentVersion = 1;
+  let resolvedPageId = pageId;
+
+  if (resolvedPageId) {
+    // Fetch existing page to get current version
+    const existingPage = await confluenceClient.content.getContentById({
+      id: resolvedPageId,
+      expand: ['version'],
+    });
+    currentVersion = existingPage.version!.number!;
+  } else {
+    // Create a placeholder page to obtain a pageId
+    const blankAdf = {
+      version: 1,
+      type: 'doc',
+      content: [],
+    };
+
+    const createParams: Parameters<typeof confluenceClient.content.createContent>[0] = {
+      space: { key: spaceKey },
+      title,
+      type: 'page',
+      body: {
+        atlas_doc_format: {
+          value: JSON.stringify(blankAdf),
+          representation: 'atlas_doc_format',
+        },
+      },
+    };
+
+    if (parentId) {
+      createParams.ancestors = [{ id: parentId }];
+    }
+
+    const created = await confluenceClient.content.createContent(createParams);
+    resolvedPageId = created.id!;
+    currentVersion = created.version!.number!;
+  }
+
+  // Fetch current attachments to build the map
+  const attachmentsResult = await confluenceClient.contentAttachments.getAttachments({
+    id: resolvedPageId,
+  });
+
+  type CurrentAttachments = Record<
+    string,
+    { filehash: string; attachmentId: string; collectionName: string }
+  >;
+
+  const currentAttachments: CurrentAttachments = {};
+  for (const att of attachmentsResult.results ?? []) {
+    const attTitle = att.title ?? '';
+    const fileId = (att.extensions as any)?.fileId ?? '';
+    const collectionName = (att.extensions as any)?.collectionName ?? '';
+    if (attTitle) {
+      currentAttachments[attTitle] = {
+        filehash: (att.metadata as any)?.comment ?? '',
+        attachmentId: fileId,
+        collectionName,
+      };
+    }
+  }
+
+  // Build publisher functions
+  const publisherFunctions = createPublisherFunctions(
+    confluenceClient as unknown as any,
+    stubAdaptor,
+    resolvedPageId,
+    title,
+    currentAttachments
+  );
+
+  // Run ADF processing pipeline (renders mermaid diagrams)
+  const finalAdf = await executeADFProcessingPipeline(
+    [new MermaidRendererPlugin(new PuppeteerMermaidRenderer())],
+    adf as unknown as any,
+    publisherFunctions
+  );
+
+  // Update the page with the final ADF
+  const updateParams: Parameters<typeof confluenceClient.content.updateContent>[0] = {
+    id: resolvedPageId,
+    title,
+    type: 'page',
+    version: { number: currentVersion + 1 },
+    body: {
+      atlas_doc_format: {
+        value: JSON.stringify(finalAdf),
+        representation: 'atlas_doc_format',
+      },
+    },
+  };
+
+  if (parentId) {
+    updateParams.ancestors = [{ id: parentId }];
+  }
+
+  await confluenceClient.content.updateContent(updateParams);
+
+  const url = `${CONFLUENCE_BASE_URL}/wiki/spaces/${spaceKey}/pages/${resolvedPageId}`;
+
+  return {
+    isPreview: false,
+    pageId: resolvedPageId,
+    version: currentVersion + 1,
+    mermaidCount,
+    url,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+
+const server = new Server(
+  { name: 'mcp-markdown-to-confluence', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+// Tool definitions
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'markdown_preview',
+      description:
+        'Convert markdown to Confluence ADF and return a text preview. Does not publish to Confluence.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          markdown: { type: 'string', description: 'Markdown content to preview' },
+          title: { type: 'string', description: 'Page title (used during ADF conversion)' },
+        },
+        required: ['markdown', 'title'],
+      },
+    },
+    {
+      name: 'markdown_publish',
+      description:
+        'Publish markdown to a Confluence page. By default runs a preview first; set skip_preview: true to publish immediately.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          markdown: { type: 'string', description: 'Markdown content to publish' },
+          title: { type: 'string', description: 'Confluence page title' },
+          spaceKey: { type: 'string', description: 'Confluence space key (e.g. "ENG")' },
+          pageId: {
+            type: 'string',
+            description: 'Existing page ID to update (omit to create a new page)',
+          },
+          parentId: {
+            type: 'string',
+            description: 'Parent page ID for new page creation',
+          },
+          skip_preview: {
+            type: 'boolean',
+            description: 'Set to true to skip preview and publish immediately',
+            default: false,
+          },
+        },
+        required: ['markdown', 'title', 'spaceKey'],
+      },
+    },
+    {
+      name: 'markdown_publish_file',
+      description:
+        'Read a markdown file from disk and publish it to Confluence. Frontmatter keys: connie-title / title, connie-space-key, connie-page-id.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          filePath: { type: 'string', description: 'Absolute path to the markdown file' },
+          skip_preview: {
+            type: 'boolean',
+            description: 'Set to true to skip preview and publish immediately',
+            default: false,
+          },
+        },
+        required: ['filePath'],
+      },
+    },
+  ],
+}));
+
+// Tool handlers
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    if (name === 'markdown_preview') {
+      const input = z
+        .object({ markdown: z.string(), title: z.string() })
+        .parse(args);
+
+      const adf = parseMarkdownToADF(
+        input.markdown,
+        CONFLUENCE_BASE_URL
+      ) as unknown as any;
+
+      const mermaidCount = countMermaidBlocks(adf);
+      const previewText = renderADFDoc(adf as unknown as any);
+
+      const lines: string[] = [previewText];
+      if (mermaidCount > 0) {
+        lines.push(
+          `\n[Note: ${mermaidCount} mermaid diagram(s) detected — they will be rendered as images when published.]`
+        );
+      }
+
+      return { content: [{ type: 'text', text: lines.join('') }] };
+    }
+
+    if (name === 'markdown_publish') {
+      const input = z
+        .object({
+          markdown: z.string(),
+          title: z.string(),
+          spaceKey: z.string(),
+          pageId: z.string().optional(),
+          parentId: z.string().optional(),
+          skip_preview: z.boolean().default(false),
+        })
+        .parse(args);
+
+      const result = await publishMarkdown(
+        input.markdown,
+        input.title,
+        input.spaceKey,
+        input.pageId,
+        input.parentId,
+        input.skip_preview
+      );
+
+      if (result.isPreview) {
+        const lines: string[] = ['=== PREVIEW ===\n', result.previewText ?? ''];
+        if ((result.mermaidCount ?? 0) > 0) {
+          lines.push(
+            `\n[Note: ${result.mermaidCount} mermaid diagram(s) detected — they will be rendered when published.]`
+          );
+        }
+        lines.push(
+          '\n\nCall again with skip_preview: true to publish to Confluence.'
+        );
+        return { content: [{ type: 'text', text: lines.join('') }] };
+      }
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: [
+              `Successfully published to Confluence.`,
+              `Title: ${input.title}`,
+              `Page ID: ${result.pageId}`,
+              `Version: ${result.version}`,
+              `Mermaid diagrams rendered: ${result.mermaidCount}`,
+              `URL: ${result.url}`,
+            ].join('\n'),
+          },
+        ],
+      };
+    }
+
+    if (name === 'markdown_publish_file') {
+      const input = z
+        .object({
+          filePath: z.string(),
+          skip_preview: z.boolean().default(false),
+        })
+        .parse(args);
+
+      const raw = await readFile(input.filePath, 'utf-8');
+      const parsed = matter(raw);
+
+      const title: string =
+        parsed.data['connie-title'] ?? parsed.data['title'] ?? '';
+      const spaceKey: string = parsed.data['connie-space-key'] ?? '';
+      const pageId: string | undefined = parsed.data['connie-page-id']
+        ? String(parsed.data['connie-page-id'])
+        : undefined;
+
+      if (!title) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: 'text',
+              text: 'Error: Missing page title. Set "connie-title" or "title" in frontmatter.',
+            },
+          ],
+        };
+      }
+
+      if (!spaceKey) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: 'text',
+              text: 'Error: Missing space key. Set "connie-space-key" in frontmatter.',
+            },
+          ],
+        };
+      }
+
+      const result = await publishMarkdown(
+        parsed.content,
+        title,
+        spaceKey,
+        pageId,
+        undefined,
+        input.skip_preview
+      );
+
+      if (result.isPreview) {
+        const lines: string[] = [
+          `File: ${input.filePath}\n`,
+          '=== PREVIEW ===\n',
+          result.previewText ?? '',
+        ];
+        if ((result.mermaidCount ?? 0) > 0) {
+          lines.push(
+            `\n[Note: ${result.mermaidCount} mermaid diagram(s) detected — they will be rendered when published.]`
+          );
+        }
+        lines.push(
+          '\n\nCall again with skip_preview: true to publish to Confluence.'
+        );
+        return { content: [{ type: 'text', text: lines.join('') }] };
+      }
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: [
+              `Successfully published "${title}" to Confluence.`,
+              `File: ${input.filePath}`,
+              `Page ID: ${result.pageId}`,
+              `Version: ${result.version}`,
+              `Mermaid diagrams rendered: ${result.mermaidCount}`,
+              `URL: ${result.url}`,
+            ].join('\n'),
+          },
+        ],
+      };
+    }
+
+    return {
+      isError: true,
+      content: [{ type: 'text', text: `Error: Unknown tool "${name}"` }],
+    };
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      isError: true,
+      content: [{ type: 'text', text: `Error: ${message}` }],
+    };
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}