Skip to main content
Glama
hanifalkauni

confluence-prd-converter

by hanifalkauni
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

📑 Confluence PRD Converter

Universal AI Agent Skill & Custom MCP Server for Automated, Zero-Loss Confluence PRD Conversion to Production Markdown (prd.md)

MCP Protocol Python Cross Agent License: MIT

English • Bahasa Indonesia

🌟 Overview & Problem Statement

In agile software development, PRD (Product Requirement Document) pages in Confluence contain complex, multi-layered information:

  • Jira Issue macros with dynamic status lozenges (IN PROGRESS, DONE, BACKLOG)

  • Nested tables (tables inside cells for acceptance criteria, data tracking schemas, and master config)

  • Embedded interactive prototypes from Figma and Miro

  • Dozens of mockup diagrams and architecture screenshots

  • Security matrices (ITPF / STRIDE Threat Modeling)

When exporting or migrating these documents to standard Markdown manually or via basic converters:

  1. ❌ Broken Tables: Markdown lacks native nested table syntax; cell linebreaks shatter outer table rows.

  2. ❌ Lost Metadata: Jira lozenges and macros turn into ugly HTML tags or disappear.

  3. ❌ Unclickable Embeds: Figma and Miro iframes fail to extract clean URLs.

  4. ❌ Broken Assets: Image links fail to resolve to local asset directories.

  5. ❌ Repetitive Scratch Scripts: Agents spend valuable context windows repeatedly writing Python scripts for conversion.

confluence-prd-converter solves this permanently by combining an Open FastMCP Server and a Universal Agent Skill that execute zero-loss, deterministic conversions in a single prompt across any AI assistant.

Related MCP server: Confluence MCP Server

🏗️ Architecture & Execution Flow

%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#7aa2f7', 'primaryBorderColor': '#3d59a1', 'actorBkg': '#24283b', 'actorBorder': '#7aa2f7', 'lineColor': '#bb9af7', 'altBkg': '#1f2335' }}}%%
graph TD
    UserReq["User Prompt: 'Fetch and convert Confluence PRD to prd.md'"] --> AgentSkill["Universal Agent Skill (SKILL.md)"]
    AgentSkill --> Platform{"Target Agent Platform:<br>• Google Antigravity<br>• Claude Code / Desktop<br>• Cursor / Windsurf<br>• Cline / Roo Code / Terminal"}
    
    Platform --> DetectInput{"Input Detection:<br>1. Live Confluence URL / Page ID<br>2. Local HTML Export<br>3. Confluence Storage XML"}
    
    DetectInput -->|URL / Page ID| LiveTool["fetch_and_convert_from_confluence"]
    DetectInput -->|Local HTML| HtmlTool["convert_confluence_html_to_prd"]
    DetectInput -->|Storage XML| XmlTool["convert_confluence_storage_to_prd"]

    subgraph "Custom MCP Server & Engine"
        LiveTool --> ConfluenceClient["Confluence REST Client<br>(Auth via CONFLUENCE_PAT)"]
        HtmlTool --> CoreParser["Core DOM & AST Parser"]
        XmlTool --> CoreParser
        ConfluenceClient --> CoreParser
        
        CoreParser --> DOMCleaner["DOM & UI Cleaner"]
        CoreParser --> TableEngine["Nested Table Formatter<br>(Compact Single-Line HTML)"]
        CoreParser --> MacroEngine["Jira, Miro, Figma Extractor"]
        CoreParser --> AssetMapper["Asset & Image Resolver"]
    end

    CoreParser --> FinalMD["Output: prd.md (Zero-Loss)"]
    AgentSkill --> Validator["validate_prd_markdown (Integrity Report)"]

✨ Key Capabilities & Zero-Loss Standards

1. 📊 Compact Nested Table Engine

Sub-tables inside table cells are converted into compact single-line HTML <table> elements with inner linebreaks converted to <br>, preserving strict Markdown table rows.

2. 🎫 Jira Macro & Lozenge Resolution

Extracts Jira keys, summaries, URLs, and status badges into clean Markdown:

• [CITA-1042](https://jira.../browse/CITA-1042) - Profile Revamp `IN PROGRESS`

3. 🎨 Figma & Miro Embed Extraction

Decodes complex iframe source URLs to direct links:

[Figma Design](https://www.figma.com/file/...)
[Miro Board](https://miro.com/app/board/...)

4. 🖼️ Smart Asset Mapping & Icon Filtering

Automatically downloads attachments from live pages or maps local ./[name]_files/ directories while stripping noisy system icons (epic.svg, viewavatar, default.svg).

5. 💡 GitHub Alert Panels

Transforms Confluence info/warning/note/tip panels into standard GitHub callouts:

> [!NOTE]
> **Document Status**
> This PRD is currently under active review.

6. 💬 Discussion & Comment Extraction

Automatically captures stakeholder feedback, reviewer comments, and architectural decisions into a structured ## 💬 Discussions & Page Comments section, preserving author names, timestamps, user mentions, and formatting.

🛠️ MCP Tool Reference

Tool Name

Description

Key Parameters

fetch_and_convert_from_confluence

Live fetch from Confluence by URL or Page ID, downloads image attachments, extracts comments, and outputs prd.md.

page_id_or_url, output_md_path, download_images, include_comments, assets_folder_name

convert_confluence_html_to_prd

Converts local Confluence exported .html file to structured Markdown.

html_file_path, output_md_path, preserve_nested_tables, assets_folder_name

convert_confluence_storage_to_prd

Converts raw XML/XHTML Storage Format (body.storage.value) directly to Markdown.

storage_xml_content, output_md_path, assets_folder_name

validate_prd_markdown

Inspects prd.md for broken tables, missing images, unparsed tags, and compiles statistics.

md_file_path

🔌 Multi-Agent Integration Guide

💬 Method A: Universal MCP Server (Recommended for Tool Calling)

Add confluence-prd-converter directly to your AI IDE (Google Antigravity, Claude Desktop, Cursor, Windsurf, Cline, Continue.dev, Kiro) via MCP:

{
  "mcpServers": {
    "confluence-prd-converter": {
      "command": "npx",
      "args": [
        "-y",
        "github:hanifalkauni/confluence-prd-converter",
        "--mcp"
      ],
      "env": {
        "CONFLUENCE_URL": "https://wiki.yourcompany.com",
        "CONFLUENCE_PAT": "YOUR_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}

📄 Method B: Pure Skill Agent / Rule File (No MCP Server Required)

If you prefer installing the skill instructions directly into your workspace for native agent reasoning:

🌐 Option 1: Automatic via skills.sh (Recommended — 30+ AI Agents)

Install with a single command into Cursor, Claude Code, Windsurf, Copilot, or Gemini CLI:

npx skills add hanifalkauni/confluence-prd-converter

⚡ Option 2: Automatic Adapter Injection via CLI

Export all agent adapter files into your current workspace root:

npx -y github:hanifalkauni/confluence-prd-converter init

📦 Option 3: Manual Installation per AI Agent

Copy adapter to local workspace skill directory:

mkdir -p .agents/skills/confluence-prd-converter
cp adapters/antigravity/SKILL.md .agents/skills/confluence-prd-converter/SKILL.md

Or install globally for all workspaces at: ~/.gemini/config/skills/confluence-prd-converter/SKILL.md.

Add to project root CLAUDE.md:

cp adapters/claude/CLAUDE.md ./CLAUDE.md

Add rule file to .cursor/rules/:

mkdir -p .cursor/rules
cp adapters/cursor/confluence-prd-converter.mdc .cursor/rules/confluence-prd-converter.mdc

Add rule to .windsurf/rules/:

mkdir -p .windsurf/rules
cp adapters/windsurf/windsurfrules.md .windsurf/rules/confluence-prd-converter.md

Add rule to .clinerules/:

mkdir -p .clinerules
cp adapters/cline/clinerules.md .clinerules/confluence-prd-converter.md

Add to .github/copilot-instructions.md:

mkdir -p .github
cp adapters/copilot/copilot-instructions.md .github/copilot-instructions.md

Add steering instructions to .kiro/steering/:

mkdir -p .kiro/steering
cp adapters/kiro/steering.md .kiro/steering/confluence-prd-converter.md

Add prompt rule to .continue/rules/:

mkdir -p .continue/rules
cp adapters/continue/prompt.md .continue/rules/confluence-prd-converter.md

💻 Method C: Standalone Terminal CLI Runner

Convert local HTML export:

npx -y github:hanifalkauni/confluence-prd-converter --input ./PRD_Export.html --output ./prd.md

Live fetch from Confluence URL:

npx -y github:hanifalkauni/confluence-prd-converter --input "https://wiki.yourcompany.com/pages/viewpage.action?pageId=1766097385" --output ./prd.md

Validate markdown integrity:

python scripts/validate_output.py --input ./prd.md

📂 Repository Layout

confluence-prd-converter/
├── server.py                        # FastMCP Server (stdio JSON-RPC for AI IDEs)
├── SKILL.md                         # Universal Agent Skill definition
├── core/                            # Core parsing & transformation engine
│   ├── confluence_client.py         # REST API client & attachment/comment fetcher
│   ├── parser.py                    # Unified AST parser (Storage XML & View HTML)
│   ├── formatters.py                # Nested tables, Jira lozenges, embeds, alert callouts
│   ├── clean.py                     # DOM sanitizer & system icon filter
│   └── validator.py                 # Structural Markdown integrity validator
├── adapters/                        # Rule & skill adapters for 8+ AI Agent IDEs
│   ├── antigravity/                 # Google Antigravity & Gemini CLI
│   ├── claude/                      # Claude Code & Claude Desktop
│   ├── cursor/                      # Cursor IDE (.cursor/rules/)
│   ├── windsurf/                    # Windsurf Cascade (.windsurf/rules/)
│   ├── cline/                       # Cline & Roo Code (.clinerules/)
│   ├── copilot/                     # GitHub Copilot (.github/)
│   ├── kiro/                        # Kiro Steering (.kiro/steering/)
│   └── continue/                    # Continue.dev (.continue/rules/)
├── evaluations/                     # Evaluation & Feedback Hub (RFCs & study cases)
├── scripts/                         # Standalone CLI tools (run_converter, validate_output)
├── tests/                           # Unit test suite & generalized sample fixtures
├── schema.json                      # Configuration JSON Schema
└── confluence-prd-converter.config.json # Project configuration file

🧪 Testing & Verification

Run the full unit test suite:

python tests/test_all.py

📄 License

SPDX-License-Identifier: MIT

This project is licensed under the MIT License.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers