Confluence Markdown MCP Server

MCP server chuyên về xử lý Markdown với tài liệu Confluence - chuyển đổi page Confluence sang Markdown và ngược lại, hỗ trợ Mermaid, ảnh base64, bảng GFM.

Cài đặt nhanh từ npm

npm install -g confluence-markdown-mcp

Cấu hình MCP trong RooCode

Mở file cấu hình MCP settings của RooCode:

• Đường dẫn: c:/Users/[username]/AppData/Roaming/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json

Thêm cấu hình server:

{
  "mcpServers": {
    "confluence-markdown": {
      "command": "npx",
      "args": [
        "confluence-markdown-mcp"
      ],
      "env": {
        "CONFLUENCE_BASE_URL": "https://confluence.example.com",
        "CONFLUENCE_USERNAME": "your_username",
        "CONFLUENCE_PAT": "your_pat_token"
      }
    }
  }
}

Các biến môi trường cần thiết:

| Biến | Bắt buộc | Mô tả | |------|----------|-------| | CONFLUENCE_BASE_URL | ✅ | URL base của Confluence (VD: https://confluence.example.com) | | CONFLUENCE_USERNAME | ✅* | Username cho Basic Auth | | CONFLUENCE_PASSWORD | ✅* | Password cho Basic Auth | | CONFLUENCE_API_TOKEN | ✅* | API Token (thay thế password nếu dùng token nội bộ) | | CONFLUENCE_PAT | ✅* | Personal Access Token (Bearer Token) |

*Chỉ cần 1 trong 2 cách xác thực: Basic Auth (username + password/token) HOẶC Bearer Token (PAT)

2) Cấu hình biến môi trường

Copy file mẫu:

copy .env.example .env

Điền 1 trong 2 cách xác thực:

• Basic Auth (Data Center): CONFLUENCE_USERNAME + CONFLUENCE_PASSWORD (hoặc CONFLUENCE_API_TOKEN nếu hệ thống của bạn dùng token nội bộ)
• Bearer token: CONFLUENCE_PAT

3) Chạy server

npm start

Server chạy qua STDIO, phù hợp để cấu hình trong MCP client.

4) Các tools hiện có

4.1) confluence_page_to_markdown

Lấy full nội dung trang Confluence theo pageId và convert sang Markdown.

Input:

| Tham số | Kiểu | Bắt buộc | Mô tả | |---------|------|----------|-------| | pageId | string | ✅ | ID của trang Confluence | | expand | string | ❌ | Expand fields, mặc định body.storage,version,space. Ví dụ: body.storage,history,version | | saveRawXhtml | boolean | ❌ | Lưu raw XHTML ra file để đối soát (mặc định true) |

Ví dụ gọi tool:

{
  "name": "confluence_page_to_markdown",
  "arguments": {
    "pageId": "123456789",
    "expand": "body.storage,version,space",
    "saveRawXhtml": true
  }
}

Output:

• File Markdown trong thư mục stories/
• File XHTML gốc (nếu saveRawXhtml: true)
• Thông tin về page: ID, title, đường dẫn file output

4.2) confluence_markdown_to_page

Convert Markdown phức tạp (ảnh base64/mermaid/bảng) sang Confluence storage và tạo page con trực tiếp vào parent page ID.

Input:

| Tham số | Kiểu | Bắt buộc | Mô tả | |---------|------|----------|-------| | markdownFilePath | string | ✅ | Đường dẫn file Markdown cần convert. Có thể là relative trong workspace hoặc absolute path | | pageTitle | string | ❌ | Tiêu đề page sẽ tạo. Nếu bỏ trống sẽ dùng tên file Markdown | | pageParentId | string | ✅ | ID page cha. Tool sẽ tự resolve space key từ page cha rồi tạo page con | | saveDebugXhtml | boolean | ❌ | Lưu file storage XHTML output vào stories/*.debug.xhtml để debug |

Ví dụ gọi tool:

{
  "name": "confluence_markdown_to_page",
  "arguments": {
    "markdownFilePath": "stories/TQ9_Trung_dai_han_SMESN_tong_hop_gia_tri_tham_quyen.md",
    "pageTitle": "TQ9 - Trung dài hạn SMESN",
    "pageParentId": "653039535",
    "saveDebugXhtml": true
  }
}

Output:

• Thông tin page đã tạo: ID, title, links
• Đường dẫn file Markdown đã resolve
• Thông tin parent đã resolve: ID, title, space key

5) Đặc điểm xử lý Markdown

5.1) Hỗ trợ ảnh

• Ảnh local: Tự động đọc file và convert sang base64 inline.
• Ảnh http/https: Tự động tải về và convert sang base64.
• Ảnh base64: Giữ nguyên không đổi.
• Định dạng hỗ trợ: png, jpg, jpeg, gif, webp, bmp, svg, avif, ico.

5.2) Hỗ trợ bảng

• Bảng đơn giản: Render bình thường sang HTML table.
• Bảng phức tạp (nested table): Giữ nguyên cấu trúc HTML table, chỉ normalize phần XHTML để tránh lỗi parser.

5.3) Hỗ trợ Mermaid

• Nhận fenced code block mermaid và chuyển thành macro Confluence:
  • <ac:structured-macro ac:name="mermaid-cloud" ...>
  • kèm parameter toolbar, filename, format, zoom, revision
• Có hỗ trợ cả block HTML dạng <pre class="mermaid">....

5.4) Markdown extensions

• GFM (GitHub Flavored Markdown): strikethrough, tables, task lists, autolinks, etc.
• Code blocks với syntax highlighting.

6) Ví dụ cấu hình MCP client

Ví dụ mcpServers:

{
  "mcpServers": {
    "confluence": {
      "command": "node",
      "args": ["d:/projects/confluence_mcp/src/index.js"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://confluence.mbbank.com.vn",
        "CONFLUENCE_USERNAME": "your.username",
        "CONFLUENCE_PASSWORD": "your_password"
      }
    }
  }
}

Hoặc dùng PAT:

{
  "mcpServers": {
    "confluence": {
      "command": "node",
      "args": ["d:/projects/confluence_mcp/src/index.js"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://confluence.mbbank.com.vn",
        "CONFLUENCE_PAT": "your_personal_access_token"
      }
    }
  }
}

7) File mẫu

Thư mục stories/ chứa các file mẫu để test:

• TQ9_Story_Test.md - File Markdown mẫu với ảnh và bảng phức tạp
• TQ9_Demo_Story.md - Demo story
• TQ9_Story_No_Html.md - Story không có HTML

8) Development

Chạy test nhanh:

# Test load module
node --input-type=module -e "import('./src/tools/confluenceTools.js')"

# Test convert Markdown to storage
node --input-type=module -e "
import { promises as fs } from 'node:fs';
import path from 'node:path';
import { convertMarkdownToConfluenceStorage } from './src/utils/markdownToConfluenceStorage.js';
const p='./stories/TQ9_Story_Test.md';
const md=await fs.readFile(p,'utf8');
const html=await convertMarkdownToConfluenceStorage(md,{baseDir:path.dirname(path.resolve(p))});
console.log('storage length', html.length);
console.log('has table', /<table/i.test(html));
console.log('has img', /<img/i.test(html));
"