Metadata-Version: 2.4
Name: iflow-mcp_firsthalfhero-openproject-mcp-server
Version: 0.1.0
Summary: A comprehensive FastMCP-powered server that enables AI assistants like Claude to interact with OpenProject installations
Project-URL: Homepage, https://github.com/firsthalfhero/openproject-mcp-server
Project-URL: Repository, https://github.com/firsthalfhero/openproject-mcp-server
Project-URL: Issues, https://github.com/firsthalfhero/openproject-mcp-server/issues
Author: firsthalfhero
License: MIT
Keywords: ai,fastmcp,mcp,openproject,project-management
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: fastmcp>=0.9.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: structlog>=23.0.0
Description-Content-Type: text/markdown

# OpenProject MCP Server

A comprehensive FastMCP-powered server that enables AI assistants like Claude to interact with OpenProject installations. This implementation provides full project management functionality including user management, dynamic configuration, and advanced Gantt chart creation.

## 🎯 Core Features

### MVP Functionality
- ✅ **Create projects** in OpenProject via AI assistant
- ✅ **Create work packages** with start/due dates for Gantt charts
- ✅ **Create dependencies** between work packages
- ✅ **Generate proper Gantt charts** in OpenProject
- ✅ **End-to-end workflow** from AI command to visual timeline

### Phase 1 Enhanced Features
- ✅ **User management** - Find and assign users by email address
- ✅ **Dynamic configuration** - Automatically load types, statuses, and priorities
- ✅ **Email-based assignment** - Assign work packages without knowing user IDs
- ✅ **Project member management** - View project members and their roles
- ✅ **Enhanced error handling** - Detailed validation and error messages
- ✅ **Performance optimization** - Intelligent caching and pagination

## 🚀 Quick Start

### Prerequisites

1. **OpenProject Instance**: You need a running OpenProject installation (local or cloud)
2. **API Key**: Generate an API key from your OpenProject profile
3. **Python 3.8+**: Required for running the MCP server

### Installation

1. **Clone or download** the project:
   ```bash
   cd openproject-mcp-server
   ```

2. **Create and activate virtual environment**:
   ```bash
   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

4. **Configure environment**:
   ```bash
   cp env.example .env
   # Edit .env with your OpenProject details
   ```

### Configuration

Edit the `.env` file with your OpenProject details:

```env
# OpenProject Instance URL (include protocol)
OPENPROJECT_URL=http://localhost:3000

# OpenProject API Key (from your user profile)
OPENPROJECT_API_KEY=your_40_character_api_key_here

# MCP Server Configuration (optional)
MCP_HOST=localhost
MCP_PORT=8080
MCP_LOG_LEVEL=INFO
```

#### Getting your OpenProject API Key:

1. Login to your OpenProject instance
2. Go to **My Account** → **Access Tokens**
3. Click **+ New token**
4. Enter a name (e.g., "MCP Server")
5. Copy the generated 40-character token

### Testing

Test your configuration before using with AI assistants:

```bash
python3 scripts/test_mvp.py
```

This will:
- ✅ Test OpenProject API connection
- ✅ Create a test project
- ✅ Create work packages with dates
- ✅ Create dependencies
- ✅ Verify Gantt chart readiness

### Running the Server

Start the MCP server:

```bash
python3 scripts/run_server.py
```

The server will start and be ready to accept AI assistant connections.

## 🐳 Docker Deployment

Docker deployment is the **recommended production method** for the OpenProject MCP Server.

### Prerequisites for Docker

1. **Docker installed** (version 20.10+)
2. **Docker Compose** (for easier management)
3. **Configure `.env` file** with your OpenProject details

### Quick Start with Docker

**Option 1: Automated deployment (Recommended)**
```bash
# Configure your environment first
cp env.example .env
# Edit .env with your OpenProject URL and API key

# Deploy on specific port (IMPORTANT: Must match Claude Desktop config)
./scripts/deploy.sh deploy 39127

# Alternative: Deploy on default port 8080
./scripts/deploy.sh deploy

# For development with different ports
./scripts/deploy.sh deploy 9876
```

**🔑 Important**: The port MUST match your Claude Desktop MCP configuration in `~/.cursor/mcp.json` or `claude_desktop_config.json`!

**Option 2: Docker Compose (Alternative)**
```bash
# Build and start the container
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the container
docker-compose down
```

**🔧 Port Configuration & Conflicts:**

**Step 1: Choose your port (must be consistent)**
```bash
# Check your current MCP configuration
cat ~/.cursor/mcp.json | grep openproject -A 5

# Or check Claude Desktop config
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

**Step 2: Deploy on the SAME port as your MCP config**
```bash
# Deploy on the port specified in your MCP config
./scripts/deploy.sh deploy 39127
```

**Step 3: If port conflicts occur:**
- Stop conflicting services: `docker stop container_using_port`
- Or update BOTH MCP config AND deployment port consistently
- Check what's using port: `docker ps | grep 39127`

### Manual Docker Commands

For advanced users who want full control:

1. **Build the image**:
   ```bash
   docker build -t openproject-mcp-server .
   ```

2. **Run the container**:
   ```bash
   docker run -d \
     --name openproject-mcp-server \
     --env-file .env \
     -p 39127:8080 \
     -v ./logs:/app/logs \
     -v ./data:/app/data \
     --restart unless-stopped \
     openproject-mcp-server
   ```

3. **Health check**:
   ```bash
   # Check if container is healthy
   docker ps
   
   # View container logs
   docker logs openproject-mcp-server
   
   # Test API endpoint (Note: No health endpoint in MCP server)
   curl http://localhost:39127/sse
   ```

### Deployment Script Commands

The `scripts/deploy.sh` script provides comprehensive deployment management:

```bash
# Deploy on standard MCP port (recommended)
./scripts/deploy.sh deploy 39127

# Deploy on default port 8080 (may conflict with OpenProject)
./scripts/deploy.sh deploy

# Deploy on alternative ports if needed
./scripts/deploy.sh deploy 9876

# View container logs
./scripts/deploy.sh logs

# Check status and port information
./scripts/deploy.sh status

# Stop the server
./scripts/deploy.sh stop

# Restart the server (keeps same port)
./scripts/deploy.sh restart

# Clean up (stop and remove container/image)
./scripts/deploy.sh clean
```

**💡 Port Selection Tips:**
- **Port 39127**: Recommended MCP standard port, matches default config
- **Port 8080**: Default HTTP port, but often conflicts with OpenProject
- **Port 9876**: Good alternative, rarely conflicts
- **Port 8090**: Common development port

### Environment Variables for Docker

When using Docker, configure these environment variables in your `.env` file:

```env
# OpenProject Instance URL (where your OpenProject runs, typically port 8080)
OPENPROJECT_URL=http://localhost:8080

# OpenProject API Key (from your user profile)
OPENPROJECT_API_KEY=your_40_character_api_key_here

# MCP Server Configuration (internal container port, mapped to 39127)
MCP_HOST=0.0.0.0
MCP_PORT=8080
MCP_LOG_LEVEL=INFO

# Optional: Performance tuning (Phase 1 features)
OPENPROJECT_CACHE_TIMEOUT_MINUTES=5
OPENPROJECT_PAGINATION_SIZE=100
OPENPROJECT_MAX_RETRIES=3
```

### Docker Deployment Best Practices

- **Always use `.env` file** - Never hardcode credentials in commands
- **Volume mapping** - Map logs and data directories for persistence
- **Health checks** - Container includes built-in health monitoring
- **Auto-restart** - Use `--restart unless-stopped` for production
- **Resource limits** - Consider adding memory/CPU limits for production

## 🤖 AI Assistant Integration

### Claude Desktop Integration

Add to your `claude_desktop_config.json`:

**Option 1: Local Python execution**
```json
{
  "mcpServers": {
    "openproject": {
      "command": "python3",
      "args": ["/full/path/to/openproject-mcp-server/scripts/run_server.py"],
      "env": {
        "OPENPROJECT_URL": "http://localhost:8080",
        "OPENPROJECT_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

**Option 2: Docker deployment (recommended)**
```json
{
  "mcpServers": {
    "openproject": {
      "transport": "sse",
      "url": "http://localhost:39127/sse"
    }
  }
}
```

**Environment Setup:** Configure OpenProject credentials in Docker deployment `.env` file instead of MCP config.

**Important Notes**: 
- Use the full absolute path to the `run_server.py` script for Option 1
- Ensure the Docker container is running before using Option 2
- OPENPROJECT_URL should point to your OpenProject instance (typically port 8080)
- MCP server URL (port 39127) is configured separately in the transport URL

### Usage Examples

Once integrated with Claude, you can ask:

#### Create a Project with Team Members
```
Create a new project called "Website Redesign" with description "Complete redesign of company website". 
Then show me the available users and add john@example.com and sarah@example.com to the project.
```

#### Create Work Packages with Email-based Assignment
```
In project ID 5, create these work packages:
1. "Requirements Analysis" from 2024-01-15 to 2024-01-20, assign to john@example.com
2. "UI Design" from 2024-01-21 to 2024-02-05, assign to sarah@example.com
3. "Development" from 2024-02-06 to 2024-02-28, assign to mike@example.com
4. "Testing & Launch" from 2024-03-01 to 2024-03-10, assign to alice@example.com
```

#### Create Dependencies for Gantt Chart
```
Create dependencies so that:
- UI Design follows Requirements Analysis
- Development follows UI Design  
- Testing follows Development
```

#### User Management Examples
```
Show me all users in the system
Find the user with email "john@example.com"
Show me all members of project ID 5 and their roles
```

#### Dynamic Configuration Examples
```
What work package types are available in this OpenProject instance?
Show me all possible work package statuses
What priority levels can I use for work packages?
```

The AI will use the enhanced MCP tools to create everything and you'll get a proper Gantt chart in OpenProject with proper user assignments!

## 🛠️ Available Tools

The OpenProject MCP Server provides comprehensive tools for AI assistants:

### Core Tools (MVP)

#### `create_project`
- **Purpose**: Create a new project in OpenProject
- **Parameters**: 
  - `name` (required): Project name
  - `description` (optional): Project description
- **Returns**: Project details with ID and URL

#### `create_work_package`
- **Purpose**: Create work packages with dates for Gantt charts
- **Parameters**:
  - `project_id` (required): Target project ID
  - `subject` (required): Work package title
  - `description` (optional): Detailed description
  - `start_date` (optional): Start date in YYYY-MM-DD format
  - `due_date` (optional): Due date in YYYY-MM-DD format
  - `parent_id` (optional): Parent work package ID
  - `assignee_id` (optional): User ID to assign to
  - `estimated_hours` (optional): Estimated completion time

#### `create_work_package_dependency`
- **Purpose**: Create dependencies between work packages for Gantt charts
- **Parameters**:
  - `from_work_package_id` (required): Source work package ID
  - `to_work_package_id` (required): Target work package ID
  - `relation_type` (optional): Type of relation (follows, precedes, blocks, blocked, relates, duplicates, duplicated)
  - `description` (optional): Description of the relation
  - `lag` (optional): Working days between finish of predecessor and start of successor

#### `get_work_package_relations`
- **Purpose**: Get all relations for a specific work package
- **Parameters**:
  - `work_package_id` (required): Work package ID to get relations for
- **Returns**: List of relations with detailed information

#### `delete_work_package_relation`
- **Purpose**: Delete a work package relation
- **Parameters**:
  - `relation_id` (required): ID of the relation to delete
- **Returns**: Confirmation of deletion

### Phase 1 Enhanced Tools (User Management & Dynamic Configuration)

#### `get_users`
- **Purpose**: Get list of users with optional email filtering
- **Parameters**:
  - `email_filter` (optional): Email address to search for specific user
- **Returns**: List of users with full details (name, email, roles, etc.)

#### `assign_work_package_by_email`
- **Purpose**: Assign work package to user by email address
- **Parameters**:
  - `work_package_id` (required): Work package ID to assign
  - `assignee_email` (required): Email address of user to assign to
- **Returns**: Assignment confirmation with user and work package details

#### `get_project_members`
- **Purpose**: Get list of project members with their roles
- **Parameters**:
  - `project_id` (required): Project ID to get members from
- **Returns**: List of project members with roles and permissions

#### `get_work_package_types`
- **Purpose**: Get available work package types from OpenProject instance
- **Parameters**: None
- **Returns**: List of work package types (Task, Bug, Feature, etc.) with configuration

#### `get_work_package_statuses`
- **Purpose**: Get available work package statuses from OpenProject instance
- **Parameters**: None  
- **Returns**: List of statuses (New, In Progress, Closed, etc.) with configuration

#### `get_priorities`
- **Purpose**: Get available work package priorities from OpenProject instance
- **Parameters**: None
- **Returns**: List of priorities (Low, Normal, High, etc.) with configuration

### Additional Enhanced Tools

#### `get_projects`
- **Purpose**: List all projects in OpenProject
- **Parameters**: None
- **Returns**: List of all projects with details

#### `get_work_packages`
- **Purpose**: Get work packages for a specific project
- **Parameters**:
  - `project_id` (required): Project ID to get work packages from
- **Returns**: List of work packages with full details

#### `update_work_package`
- **Purpose**: Update an existing work package
- **Parameters**:
  - `work_package_id` (required): Work package ID to update
  - `subject` (optional): New title
  - `description` (optional): New description
  - `start_date` (optional): New start date
  - `due_date` (optional): New due date
  - `assignee_id` (optional): New assignee
  - `estimated_hours` (optional): New time estimate

#### `get_project_summary`
- **Purpose**: Get comprehensive project overview
- **Parameters**:
  - `project_id` (required): Project ID to summarize
- **Returns**: Detailed project analysis with metrics

## 📊 Available Resources

Resources provide read-only access to OpenProject data:

- `openproject://projects` - List all projects
- `openproject://project/{project_id}` - Get specific project details
- `openproject://work-packages/{project_id}` - Get work packages for a project
- `openproject://work-package/{work_package_id}` - Get specific work package details
- `openproject://work-package-relations/{work_package_id}` - Get relations for a work package

## 🎯 Available Prompts

Prompts provide AI assistance for project management:

#### `project_status_report`
- **Purpose**: Generate comprehensive project status analysis
- **Parameters**: `project_id` (required)
- **Returns**: Structured prompt for project health analysis

#### `work_package_summary`
- **Purpose**: Summarize work packages with filtering
- **Parameters**: 
  - `project_id` (required)
  - `status_filter` (optional): Filter by status
- **Returns**: Organized work package summary

#### `project_planning_assistant`
- **Purpose**: Help plan new project structure
- **Parameters**:
  - `project_name` (required): Name of project to plan
  - `work_package_count` (optional): Suggested number of work packages
- **Returns**: Project planning guidance

#### `team_workload_analysis`
- **Purpose**: Analyze team workload across projects
- **Parameters**: `project_ids` (optional): List of projects to analyze
- **Returns**: Team workload and capacity analysis

## 📊 Gantt Chart Workflow

The MVP is specifically designed to create proper Gantt charts:

1. **Create Project** → Get project ID
2. **Create Work Packages** → Add tasks with start/due dates
3. **Create Dependencies** → Link tasks in logical order
4. **View Gantt Chart** → OpenProject automatically generates timeline

**Gantt Chart URL**: `http://your-openproject/projects/{project_id}/work_packages?view=gantt`

## 🧪 Troubleshooting

### Connection Issues
- Verify OpenProject URL is accessible
- Check API key is correct (40 characters)
- Ensure OpenProject API is enabled

### Permission Issues
- Verify your user has project creation permissions
- Check work package creation permissions in target project

### Date Format Issues
- Use YYYY-MM-DD format for all dates
- Ensure due_date is after start_date

### Dependency Issues
- Ensure both work packages exist before creating relation
- Check work packages are in same project for relations

## 🔍 Testing Commands

### Basic Testing
```bash
# Test basic connection
python3 scripts/test_mvp.py

# Run server in debug mode
OPENPROJECT_LOG_LEVEL=DEBUG python3 scripts/run_server.py

# Test specific functionality
python3 -c "
import asyncio
from src.openproject_client import OpenProjectClient
async def test():
    client = OpenProjectClient()
    result = await client.test_connection()
    print(result)
    await client.close()
asyncio.run(test())
"
```

### Phase 1 Comprehensive Testing
```bash
# Run all Phase 1 tests
python3 tests/run_tests.py

# Run specific test categories
python3 -m pytest tests/test_api_compliance.py -v
python3 -m pytest tests/test_integration.py -v

# Run tests with coverage
python3 -m pytest --cov=src --cov-report=html tests/

# Install test dependencies
pip install -r requirements-test.txt
```

### Testing Phase 1 Features
```bash
# Test user management
python3 -c "
import asyncio
import json
from src.mcp_server import get_users, assign_work_package_by_email
async def test():
    # Test user listing
    users = await get_users()
    print('Users:', json.loads(users))
    
    # Test assignment (replace with real IDs)
    # result = await assign_work_package_by_email(123, 'user@example.com')
    # print('Assignment:', json.loads(result))
asyncio.run(test())
"

# Test dynamic configuration
python3 -c "
import asyncio
import json
from src.mcp_server import get_work_package_types, get_work_package_statuses, get_priorities
async def test():
    types = await get_work_package_types()
    statuses = await get_work_package_statuses()
    priorities = await get_priorities()
    print('Types:', json.loads(types))
    print('Statuses:', json.loads(statuses))
    print('Priorities:', json.loads(priorities))
asyncio.run(test())
"
```

## 🔧 Features Overview

This comprehensive OpenProject MCP Server implementation provides:

**✅ Core Features:**
- ✅ Project creation and management
- ✅ Work package creation with dates and dependencies
- ✅ Work package dependencies for Gantt charts
- ✅ Comprehensive project and work package browsing
- ✅ Project status reporting and analysis
- ✅ Team workload analysis
- ✅ Project planning assistance
- ✅ Structured logging with JSON output
- ✅ Docker deployment with health checks
- ✅ FastMCP framework integration
- ✅ Comprehensive error handling
- ✅ Input validation and sanitization

**✅ Phase 1 Enhanced Features:**
- ✅ User management with email-based assignment
- ✅ Dynamic configuration loading (types, statuses, priorities)
- ✅ Enhanced error handling with HAL+JSON support
- ✅ Pagination support for large datasets
- ✅ Intelligent caching layer for performance
- ✅ Advanced request validation with business rules
- ✅ Comprehensive test suite with 95%+ coverage

**✅ Advanced Features:**
- ✅ MCP Resources for data browsing
- ✅ MCP Prompts for AI-assisted project management
- ✅ RESTful-style resource URIs
- ✅ Structured JSON logging
- ✅ Production-ready Docker deployment
- ✅ Health checks and monitoring
- ✅ Comprehensive tool validation

**🔄 Limited Implementation:**
- ⚠️ Project membership management (partial support)
- ⚠️ Time tracking and billing (not implemented)
- ⚠️ Categories and custom fields (not implemented)
- ⚠️ Real-time updates and webhooks (not implemented)
- ⚠️ File attachments and documents (not implemented)

## 🚀 Next Steps

### Phase 2 Roadmap (Future Development)
1. **Project membership management** - Add/remove team members programmatically
2. **Time tracking integration** - Create and manage time entries
3. **Categories and versions** - Enhanced project organization
4. **File attachments** - Document and file management
5. **Custom fields support** - Instance-specific field handling

### Immediate Next Steps
1. **Deploy with Docker** for production use
2. **Integrate with Claude Desktop** for daily workflow
3. **Test with real projects** and team workflows
4. **Monitor performance** and optimize as needed

## 📝 Support

### Troubleshooting Steps
1. **Check connection** - Run `python3 scripts/test_mvp.py`
2. **Verify configuration** - Ensure `.env` file is correct
3. **Review logs** - Check container logs or local logs
4. **Test API access** - Verify OpenProject API is accessible
5. **Check permissions** - Ensure API key has required permissions

### Getting Help
- **Documentation** - Review this README and troubleshooting section
- **Test scripts** - Use provided test commands to isolate issues
- **OpenProject logs** - Check your OpenProject instance logs
- **Container logs** - `docker logs openproject-mcp-server`

---

## ✅ Success Criteria

**✅ MVP Success**: Create projects, work packages, and dependencies through Claude, see proper Gantt charts in OpenProject

**✅ Phase 1 Success**: Use email-based assignment, dynamic configuration, and enhanced error handling - all implemented and tested!

**🎯 Production Ready**: Deploy with Docker, integrate with Claude Desktop, use for real project management workflows
