pereyra-carlos/mcp-readme-to-jira-page

README to Confluence/Jira Sync - MCP Server

Persistent MCP (Model Context Protocol) server that allows you to sync README.md files to Confluence and Jira using AI-powered transformation.

🌟 Features

• ✅ Persistent MCP Server running as Docker service
• ✅ Multi-project: use it from all your projects in Cursor
• ✅ AI Transformation: converts Markdown to native Confluence (storage HTML) and Jira (wiki markup) formats
• ✅ 3 available tools:
  • sync_to_confluence: syncs README to Confluence page
  • sync_to_jira: syncs README to Jira issue (description or comment)
  • transform_readme: only transforms without uploading (useful for preview)

📋 Requirements

• Docker and Docker Compose
• Python 3.11+ (for local development/testing)
• Atlassian Cloud account with:
  • Edit permissions on Confluence/Jira
  • API Token (create here)
• OpenAI API Key

🚀 Installation

Quick Start (Using Docker Hub Image)

The easiest way to get started is using the pre-built image from Docker Hub:

# Clone repository
git clone https://github.com/pereyra-carlos/mcp-readme-to-jira-page.git
cd mcp-readme-to-jira-page

# Copy example .env
cp env.example .env

# Edit with your credentials
nano .env

# Start the server (pulls image from Docker Hub automatically)
docker-compose up -d

The image is available at: sauay/readme-sync-mcp:latest

Alternative: Build from Source

If you want to build the image locally:

# Clone repository
git clone https://github.com/pereyra-carlos/mcp-readme-to-jira-page.git
cd mcp-readme-to-jira-page

# Copy example .env
cp env.example .env

# Edit with your credentials
nano .env

# Build and start
docker build -t sauay/readme-sync-mcp:latest .
docker-compose up -d

2. Configure environment variables

Edit .env with your credentials:

# OpenAI Configuration
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_MODEL=gpt-4o-mini

# Atlassian Configuration
ATLASSIAN_BASE_URL=https://your-site.atlassian.net
ATLASSIAN_EMAIL=your-email@company.com
ATLASSIAN_API_TOKEN=your-atlassian-token

# Optional: Default values
DEFAULT_CONFLUENCE_PAGE_ID=
DEFAULT_CONFLUENCE_SPACE_KEY=
DEFAULT_JIRA_PROJECT_KEY=

# Server Configuration
LOG_LEVEL=INFO

3. Verify the server is running

docker-compose ps
docker-compose logs -f

⚙️ Cursor Configuration

Edit your MCP configuration file in Cursor (usually ~/.cursor/mcp.json or from Settings → MCP):

{
  "mcpServers": {
    "readme-sync": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "readme-sync-mcp",
        "python",
        "server/main.py"
      ]
    }
  }
}

Restart Cursor to load the configuration.

📖 Usage from Cursor

Tool 1: sync_to_confluence

Sync a README to a Confluence page:

Use sync_to_confluence to update Confluence page with ID "123456789" 
using the README at /path/to/project/README.md

Parameters:

• readme_path (required): Path to README.md file
• page_id (required): Confluence page ID
• title (optional): New title for the page
• dry_run (optional): true to only transform without uploading

Tool 2: sync_to_jira

Sync a README to a Jira issue:

Use sync_to_jira to update description of issue CTBA-2356 
using the README at /path/to/project/README.md

Parameters:

• readme_path (required): Path to README.md file
• issue_key (required): Issue key (e.g., PROJ-123)
• action (optional): "description" (default) or "comment"
• dry_run (optional): true to only transform without uploading

Tool 3: transform_readme

Only transform the README without uploading (useful for preview):

Use transform_readme to see how my README would look in Confluence format

Parameters:

• readme_path (required): Path to README.md file
• target_format (required): "confluence" or "jira"

🛠️ Local Development (without Docker)

For development or testing without Docker:

# Create virtualenv
python3.11 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the server
cd server
python main.py

Configure Cursor to use the local server:

{
  "mcpServers": {
    "readme-sync": {
      "command": "/home/carlos/Laboratorio/AI/mcp-readme-to-jira-page/venv/bin/python",
      "args": [
        "/home/carlos/Laboratorio/AI/mcp-readme-to-jira-page/server/main.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

🔍 Troubleshooting

Error: "Missing Atlassian credentials"

• Verify that .env has all variables configured
• Restart container: docker-compose restart

Error: "Missing OpenAI API key"

• Verify OPENAI_API_KEY in .env
• Verify that the API key is valid

Error: "README not found"

• Verify the path is correct and absolute
• Remember that the container mounts /home/carlos at /workspace
• Use paths like /workspace/Work/project/README.md

Error: "401/403" on Confluence/Jira

• Verify that email and API token are correct
• Verify edit permissions on the page/issue
• For Confluence, ensure ATLASSIAN_BASE_URL includes the correct domain

Server doesn't respond in Cursor

• Verify container is running: docker-compose ps
• Check logs: docker-compose logs -f
• Restart Cursor after changing MCP configuration

📝 Customizing Prompts

The prompts for AI transformation are located at:

• server/prompts/readme_to_confluence.md - For Confluence
• server/prompts/readme_to_jira.md - For Jira

You can edit them according to your needs and restart the container:

docker-compose restart

🗺️ Roadmap

• Support for partial updates by sections
• Attach diff as comment in Confluence
• Slack notifications
• Support for other input formats (AsciiDoc, reStructuredText)
• Transformation caching to avoid repeated OpenAI calls
• Webhooks for automatic sync on git push

🐳 Docker Hub

This project is available as a pre-built Docker image:

• Docker Hub: sauay/readme-sync-mcp
• Tags:
  • latest - Latest stable version
  • 1.0.0 - Specific version

Pull the image:

docker pull sauay/readme-sync-mcp:latest

📦 Project Structure

mcp-readme-to-jira-page/
├── server/              # MCP server source code
│   ├── main.py         # Server entry point
│   ├── ai_transformer.py
│   ├── confluence.py
│   ├── jira.py
│   └── prompts/        # AI transformation prompts
├── docker-compose.yml   # Docker Compose configuration
├── Dockerfile          # Docker image definition
├── requirements.txt    # Python dependencies
├── README.md           # This file
├── INSTALL.md          # Quick installation guide
├── Makefile            # Useful commands
└── env.example         # Environment variables template

📄 License

MIT

🤝 Contributions

Contributions are welcome. Please open an issue or PR.

Created by Carlos - For use with Cursor and MCP