OpenProject MCP 服务器

🎯 为团队领导者提供智能化的项目报告生成工具

✨ 核心功能

• 📊 智能报告生成 - 自动生成周报、月报、进度报告
• 🎯 风险评估 - 实时项目风险识别和评估
• 👥 工作负载分析 - 团队成员工作量分析和优化建议
• 🎨 模板系统 - 支持自定义报告模板，包含专业的日本式商务报告
• 🔌 MCP 协议 - 标准协议，易于集成到 Claude Desktop、Cursor 等 AI 工具

🚀 快速开始

📋 解决方案选择指南

生产环境推荐使用 HTTP 解决方案

1. 启动 OpenProject (可选)

# 使用 Docker 启动 OpenProject (如果还没有 OpenProject 实例)
docker-compose up -d

# 访问 OpenProject: http://localhost:8090
# 默认账号: admin / admin

2. 选择并启动解决方案

🎯 方案一：HTTP 解决方案 (推荐生产使用)

cd solution-http
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -e ../mcp-core

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，设置 OpenProject URL 和 API Key

# 启动服务
python3 -m src.main

🚀 方案二：FastAPI 解决方案 (推荐开发使用)

cd solution-fastapi
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -e ../mcp-core

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，设置 OpenProject URL 和 API Key

# 启动服务
python app/main.py

💡 详细启动说明: 查看 服务启动操作手册

3. 访问服务

HTTP 解决方案 (端口 8010)

• 🌐 Web 界面: http://localhost:8010/web/template_editor.html
• 🔌 MCP 端点: http://localhost:8010/mcp
• ❤️ 健康检查: http://localhost:8010/health
• 📋 服务信息: http://localhost:8010/

FastAPI 解决方案 (端口 8020)

• 🌐 Web 界面: http://localhost:8020/web/template_editor.html
• 🔌 MCP 端点: http://localhost:8020/mcp
• 📖 API 文档: http://localhost:8020/docs
• ❤️ 健康检查: http://localhost:8020/health
• 📋 服务信息: http://localhost:8020/

🎨 模板系统

支持多种专业报告模板：

• 日本式週報 - 符合日本商务文化的详细周报
• 日本式月報 - 综合的月度总结报告
• 日本式進捗報告 - 专业的进度状况报告
• 自定义模板 - 通过 Web 界面创建和编辑

🔧 集成到 AI 工具

Claude Desktop

{
  "mcpServers": {
    "openproject": {
      "command": "curl",
      "args": ["-X", "POST", "http://localhost:8020/mcp"]
    }
  }
}

Cursor

在 Cursor 中添加 MCP 服务器配置，指向 http://localhost:8020/mcp

📚 使用示例

生成周报 (使用 HTTP 解决方案)

curl -X POST http://localhost:8010/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "generate_report_from_template",
      "arguments": {
        "template_id": "japanese_weekly_report",
        "project_id": "1"
      }
    }
  }'

评估项目风险

curl -X POST http://localhost:8010/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "assess_project_risks",
      "arguments": {
        "project_id": "1"
      }
    }
  }'

📖 更多使用示例: 查看 服务启动操作手册

🔧 配置

环境变量

# OpenProject 配置（必需）
OPENPROJECT_URL=https://your-openproject.com
OPENPROJECT_API_KEY=your-api-key-here

# 服务器配置 (HTTP 解决方案)
HOST=0.0.0.0
PORT=8010
LOG_LEVEL=INFO

# 服务器配置 (FastAPI 解决方案)  
PORT=8020  # 注意端口不同

🔧 详细配置说明: 查看 服务启动操作手册

获取 API Key

1. 登录 OpenProject
2. 进入 "我的账户" → "访问令牌"
3. 创建新的 API 密钥
4. 复制密钥到 .env 文件

🆘 故障排除

常见问题

Q: 服务启动失败，提示端口被占用

# 查找占用端口的进程并终止
lsof -ti:8010 | xargs kill -9  # HTTP 解决方案端口
lsof -ti:8020 | xargs kill -9  # FastAPI 解决方案端口

# 或者修改配置使用其他端口
# 在 .env 文件中修改 PORT 设置

Q: 无法连接到 OpenProject

• 检查 OpenProject 是否正在运行
• 验证 API Key 是否正确
• 确认网络连接正常
• 查看服务器日志获取详细错误信息

Q: 模板预览生成失败

• 检查项目 ID 是否存在
• 确认有访问该项目的权限
• 查看服务器日志获取详细错误信息

🔧 更多故障排除: 查看 服务启动操作手册

📄 许可证

MIT License - 详见 LICENSE 文件

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📖 扩展文档

查看 docs/ 目录获取详细文档：

• 🚀 服务启动操作手册 - 详细的安装、配置和使用指南
• 🏗️ 架构优化计划 - 项目架构优化和实施路线图
• 📚 文档索引 - 所有文档的分类和导航指南
• 🔌 FastAPI 集成示例 - 如何集成到其他应用

服务链接:

• HTTP 解决方案: http://localhost:8010
• FastAPI 解决方案: http://localhost:8020/docs
• Web 模板编辑器: http://localhost:8010/web/template_editor.html