MCP Readme To Jira Page

README 至 Confluence/Jira 同步 - MCP 服务器

持久的MCP（模型上下文协议）服务器，支持通过AI驱动的转换功能将README.md文件同步到Confluence和Jira。

🌟 特点/功能

• ✅ 持久化MCP服务器 作为Docker服务运行
• ✅ 多项目在Cursor中使用它于所有项目
• ✅ 人工智能转型将Markdown转换为原生的Confluence（存储HTML）和Jira（维基标记）格式
• ✅ 3种可用工具：

- sync_to_confluence将README文件同步到Confluence页面 - sync_to_jira将 README 同步到 Jira 问题（描述或评论中） - transform_readme仅转换不上传（适用于预览）

📋 要求

• Docker 和 Docker Compose
• Python 3.11+（用于本地开发/测试）
• 带有以下内容的 Atlassian Cloud 帐户：

- 在Confluence/Jira中编辑权限 - API Token（在此创建）

• OpenAI API密钥

🚀 安装

快速入门（使用 Docker Hub 镜像）

开始的最简单方法是使用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

该图片可访问于： sauay/readme-sync-mcp:latest

备选方案：从源代码构建

如果你想在本地构建镜像：

# 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. 配置环境变量

编辑 .env 使用您的凭据：

# 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. 验证服务器是否正在运行

docker-compose ps
docker-compose logs -f

⚙️ 光标配置

在Cursor中编辑你的MCP配置文件（通常 ~/.cursor/mcp.json 或者从设置 → MCP（多点控制单元）：

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

重启光标以加载配置。

📖 从光标处开始使用

工具1： sync_to_confluence

将 README 文件同步到 Confluence 页面：

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

参数：

• readme_path （必需）：README.md 文件的路径
• page_id （必填）：Confluence 页面 ID
• title （可选）：为页面设置新标题
• dry_run （可选）： true 仅转换而不上传

工具2： sync_to_jira

将README文件与Jira问题同步：

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

参数：

• readme_path （必需）：README.md 文件的路径
• issue_key （必填）：问题密钥（例如，PROJ-123）
• action （可选）： "description" （默认）或 "comment"
• dry_run （可选）： true 仅转换而不上传

工具3： transform_readme

仅转换README文件而不上传（便于预览）：

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

参数：

• readme_path （必填）：README.md 文件的路径
• target_format （必填）： "confluence" 或者 "jira"

🛠️ 本地开发（不使用Docker）

对于不使用 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

配置 Cursor 使用本地服务器：

{
  "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"
      }
    }
  }
}

🔍 故障排除

错误：“缺少 Atlassian 凭证”

• 验证是否 .env 所有变量都已配置
• 重启容器： docker-compose restart

错误：“缺少OpenAI API密钥”

• 验证 OPENAI_API_KEY 在 .env
• 验证API密钥是否有效

错误：“未找到 README 文件”

• 验证路径是否正确且为绝对路径
• 记住，容器已挂载 /home/carlos 在 /workspace
• 使用类似这样的路径 /workspace/Work/project/README.md

错误：在 Confluence/Jira 上出现“401/403”

• 验证电子邮件和API令牌是否正确
• 验证页面/问题上的编辑权限
• 对于Confluence，请确保 ATLASSIAN_BASE_URL 包含正确的域名

服务器在光标处未响应

• 验证容器是否正在运行： docker-compose ps
• 检查日志： docker-compose logs -f
• 更改MCP配置后重启光标

📝 自定义提示

人工智能转型的提示位于：

• server/prompts/readme_to_confluence.md - 适用于Confluence
• server/prompts/readme_to_jira.md - 适用于Jira

您可以根据需要进行编辑，然后重启容器：

docker-compose restart

🗺️ 路线图

• \[ \] 支持按部分（或章节）进行部分更新
• \[ \] 在Confluence中以评论形式附加差异文件（diff）
• \[ \] Slack通知
• \[ \] 支持其他输入格式（AsciiDoc、reStructuredText）
• \[ \] 转换缓存以避免重复调用OpenAI
• \[ \] Webhooks 用于在 git push 时自动同步

🐳 Docker Hub（中文可译为“Docker 镜像仓库”或保持原名“Docker Hub”，根据语境选择）

这个项目提供预构建的Docker镜像：

• Docker Hub: sauay/readme-sync-mcp
• 标签：

- latest - 最新稳定版本 - 1.0.0 - 特定版本

拉取镜像：

docker pull sauay/readme-sync-mcp:latest

📦 项目结构

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

📄 许可证

麻省理工学院（MIT）

🤝 贡献

欢迎贡献代码。请提出问题或提交拉取请求。

______________________________________________________________________

由卡洛斯创作 - 用于Cursor和MCP