MCP Task Orchestrator

A Kotlin implementation of the Model Context Protocol (MCP) server for comprehensive task management, providing AI assistants with a structured, context-efficient way to interact with project data.

📚 Documentation

• 📖 Full Documentation - Complete guides and reference
• 🚀 Quick Start Guide - Get running in 2 minutes
• 🔧 API Reference - All 37 MCP tools detailed
• 📋 Workflow Prompts - 5 built-in workflow automations
• 📝 Templates - 9 built-in documentation templates
• 🗃️ Database Migrations - Schema change management for developers
• 💬 Community Wiki - Examples, tips, and community guides

Why Use MCP Task Orchestrator?

• 🤖 AI-Native: Designed specifically for AI assistant workflows
• 📊 Hierarchical Organization: Projects → Features → Tasks with dependencies
• 🎯 Context-Efficient: Progressive loading and token optimization
• 📋 Template-Driven: 9 built-in templates for consistent documentation
• 🔄 Workflow Automation: 5 comprehensive workflow prompts
• 🔗 Rich Relationships: Task dependencies with cycle detection
• 🔒 Concurrent Access Protection: Built-in sub-agent collision prevention
• ⚡ 37 MCP Tools: Complete task orchestration API

Quick Start (2 Minutes)

1. Pull or Build Docker Image

Option A: Production Image (Recommended)

# Pull latest release
docker pull ghcr.io/jpicklyk/task-orchestrator:latest

# Or specific version
docker pull ghcr.io/jpicklyk/task-orchestrator:1.0.1

# Or latest build from main branch
docker pull ghcr.io/jpicklyk/task-orchestrator:main

Option B: Build Locally (Development)

# Build locally
./scripts/docker-clean-and-build.bat  # Windows
# Or manually: docker build -t mcp-task-orchestrator:dev .

2. Configure Claude Desktop or Claude Code

For Claude Desktop

Add to your claude_desktop_config.json:

Production Configuration

{
  "mcpServers": {
    "task-orchestrator": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--volume", "mcp-task-data:/app/data",
        "ghcr.io/jpicklyk/task-orchestrator:latest"
      ]
    }
  }
}

Local Development Configuration

{
  "mcpServers": {
    "task-orchestrator": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--volume", "mcp-task-data:/app/data",
        "mcp-task-orchestrator:dev"
      ]
    }
  }
}

For Claude Code

Use the JSON configuration command:

# Production version (latest release)
claude mcp add-json task-orchestrator '{"type":"stdio","command":"docker","args":["run","--rm","-i","-v","mcp-task-data:/app/data","ghcr.io/jpicklyk/task-orchestrator:latest"]}'

# Specific version
claude mcp add-json task-orchestrator '{"type":"stdio","command":"docker","args":["run","--rm","-i","-v","mcp-task-data:/app/data","ghcr.io/jpicklyk/task-orchestrator:1.0.1"]}'

# Latest from main branch
claude mcp add-json task-orchestrator '{"type":"stdio","command":"docker","args":["run","--rm","-i","-v","mcp-task-data:/app/data","ghcr.io/jpicklyk/task-orchestrator:main"]}'

# Local development version (after building locally)
claude mcp add-json task-orchestrator '{"type":"stdio","command":"docker","args":["run","--rm","-i","-v","mcp-task-data:/app/data","mcp-task-orchestrator:dev"]}'

3. Test Connection (Optional)

# Test the Docker container runs correctly
docker run --rm -i -v mcp-task-data:/app/data ghcr.io/jpicklyk/task-orchestrator:latest

# Test MCP connection (requires Node.js)
node scripts/test-mcp-connection.js

4. Start Using

Ask Claude:

• "Create a new project for my web application"
• "Show me the project overview"
• "Apply the technical approach template to this task"

Core Concepts

Project (optional)
  └── Feature (optional)
      └── Task (required) ←→ Dependencies → Task
          └── Section (optional, detailed content)

• Projects: Top-level organizational containers
• Features: Group related tasks into functional units
• Tasks: Primary work units with status, priority, complexity
• Dependencies: Relationships between tasks (BLOCKS, IS_BLOCKED_BY, RELATES_TO)
• Sections: Rich content blocks for documentation
• Templates: Standardized documentation patterns

Key Features

Template System (9 Built-in Templates)

• AI Workflow Instructions: Git workflows, PR management, task implementation, bug investigation
• Documentation Properties: Technical approach, requirements, context & background
• Process & Quality: Testing strategy, definition of done

Workflow Prompts (5 Built-in Workflows)

• create_feature_workflow - Comprehensive feature creation
• task_breakdown_workflow - Complex task decomposition
• bug_triage_workflow - Systematic bug management
• project_setup_workflow - Complete project initialization
• implement_feature_workflow - Git-aware feature implementation with completion validation

MCP Tools (37 Total)

• 6 Task Management Tools - Core CRUD operations
• 5 Feature Management Tools - Group related work
• 5 Project Management Tools - Top-level organization
• 3 Dependency Management Tools - Model relationships
• 9 Section Management Tools - Rich documentation
• 9 Template Management Tools - Workflow automation

Alternative Installation Options

Option 1: Direct JAR (Without Docker)

# Build
./gradlew build

# Run
java -jar build/libs/mcp-task-orchestrator-*.jar

Option 2: Development Environment Variables

# Configure environment for local development
MCP_TRANSPORT=stdio
DATABASE_PATH=data/tasks.db
USE_FLYWAY=true
MCP_DEBUG=true  # Enable debug logging

Configuration

Variable	Description	Default
MCP_TRANSPORT	Transport type	stdio
DATABASE_PATH	SQLite database path	data/tasks.db
USE_FLYWAY	Enable Flyway database migrations	true
MCP_SERVER_NAME	Server name	mcp-task-orchestrator
MCP_DEBUG	Enable debug logging	false

Release Information

Version follows semantic versioning with git-based build numbers:

• Format: {major}.{minor}.{patch}.{git-commit-count}-{qualifier}
• Stable releases remove the qualifier (e.g., 1.0.0.123)
• Pre-releases include qualifier (e.g., 1.0.0.123-beta-01)

Current versioning defined in build.gradle.kts.

• 🔔 Watch for releases
• 📋 View changelog

Development & Testing

# Run tests
./gradlew test

# Test MCP connection
node scripts/test-mcp-connection.js

# Debug mode
MCP_DEBUG=true java -jar build/libs/mcp-task-orchestrator-*.jar

Troubleshooting

Common Issues

• JSON parsing errors: Enable MCP_DEBUG=true and check logs in logs/
• Docker issues: Ensure Docker Desktop is running and docker volume inspect mcp-task-data
• Connection problems: Test with the echo tool (see troubleshooting guide)

Getting Help

• 📖 Full troubleshooting guide
• 💬 Community discussions
• 🐛 Report issues

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

See contributing guidelines for details.

License

MIT License