Generate project reports from OpenProject data

OpenProject MCP Server

🎯 Intelligent project reporting generation tool for team leaders

✨ Core Features

• 📊 Intelligent Report Generation - Automatically generate weekly reports, monthly reports, and progress reports
• 🎯 Risk Assessment - Real-time project risk identification and evaluation
• 👥 Workload Analysis - Team member workload analysis and optimization recommendations
• 🎨 Template System - Support for custom report templates, including professional Japanese business reports
• 🔌 MCP Protocol - Standard protocol for easy integration with Claude Desktop, Cursor, and other AI tools

🚀 Quick Start

📋 Solution Selection Guide

HTTP solution recommended for production environments

1. Start OpenProject (Optional)

# Start OpenProject using Docker (if you don't have an OpenProject instance yet)
docker-compose up -d

# Access OpenProject: http://localhost:8090
# Default credentials: admin / admin

2. Choose and Start a Solution

🎯 Solution One: HTTP Solution (Recommended for Production)

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

# Configure environment variables
cp .env.example .env
# Edit .env file to set OpenProject URL and API Key

# Start the service
python3 -m src.main

🚀 Solution Two: FastAPI Solution (Recommended for Development)

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

# Configure environment variables
cp .env.example .env
# Edit .env file to set OpenProject URL and API Key

# Start the service
python app/main.py

💡 Detailed startup instructions: See Service Startup Manual

3. Access the Service

HTTP Solution (Port 8010)

• 🌐 Web Interface: http://localhost:8010/web/template_editor.html
• 🔌 MCP Endpoint: http://localhost:8010/mcp
• ❤️ Health Check: http://localhost:8010/health
• 📋 Service Info: http://localhost:8010/

FastAPI Solution (Port 8020)

• 🌐 Web Interface: http://localhost:8020/web/template_editor.html
• 🔌 MCP Endpoint: http://localhost:8020/mcp
• 📖 API Documentation: http://localhost:8020/docs
• ❤️ Health Check: http://localhost:8020/health
• 📋 Service Info: http://localhost:8020/

🎨 Template System

Support for multiple professional report templates:

• Japanese Weekly Report - Detailed weekly report aligned with Japanese business culture
• Japanese Monthly Report - Comprehensive monthly summary report
• Japanese Progress Report - Professional progress status report
• Custom Templates - Create and edit templates through the web interface

🔧 Integration with AI Tools

Claude Desktop

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

Cursor

Add MCP server configuration in Cursor, pointing to http://localhost:8020/mcp

📚 Usage Examples

Generate Weekly Report (Using HTTP Solution)

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

Assess Project Risks

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

📖 More usage examples: See Service Startup Manual

🔧 Configuration

Environment Variables

# OpenProject Configuration (Required)
OPENPROJECT_URL=https://your-openproject.com
OPENPROJECT_API_KEY=your-api-key-here

# Server Configuration (HTTP Solution)
HOST=0.0.0.0
PORT=8010
LOG_LEVEL=INFO

# Server Configuration (FastAPI Solution)  
PORT=8020  # Note: different port

🔧 Detailed configuration instructions: See Service Startup Manual

Getting an API Key

1. Log in to OpenProject
2. Go to "My Account" → "Access Tokens"
3. Create a new API key
4. Copy the key to your .env file

🆘 Troubleshooting

Common Issues

Q: Service startup fails with port already in use error

# Find and terminate the process using the port
lsof -ti:8010 | xargs kill -9  # HTTP Solution port
lsof -ti:8020 | xargs kill -9  # FastAPI Solution port

# Or modify configuration to use a different port
# Edit PORT setting in .env file

Q: Cannot connect to OpenProject

• Check if OpenProject is running
• Verify that the API Key is correct
• Confirm network connectivity is working
• Check server logs for detailed error messages

Q: Template preview generation fails

• Check if the project ID exists
• Confirm you have access to the project
• Check server logs for detailed error messages

🔧 More troubleshooting: See Service Startup Manual

📄 License

MIT License - See LICENSE file for details

🤝 Contributing

Issues and pull requests are welcome!

📖 Extended Documentation

See docs/ directory for detailed documentation:

• 🚀 Service Startup Manual - Detailed installation, configuration, and usage guide
• 🏗️ Architecture Optimization Plan - Project architecture optimization and implementation roadmap
• 📚 Documentation Index - Categorized documentation and navigation guide
• 🔌 FastAPI Integration Sample - How to integrate with other applications

Service Links:

• HTTP Solution: http://localhost:8010
• FastAPI Solution: http://localhost:8020/docs
• Web Template Editor: http://localhost:8010/web/template_editor.html