Package Exports

taskdriver-mcp
taskdriver-mcp/dist/cli.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (taskdriver-mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

TaskDriver MCP

A Model Context Protocol (MCP) server for managing and orchestrating LLM agents as task runners.

Installation

# Install globally
npm install -g taskdriver-mcp

# Or use directly with npx/bunx
npx taskdriver-mcp --help
bunx taskdriver-mcp --help

Quick Start

CLI Usage

# Create a new project
npx taskdriver-mcp create-project "my-project" "My first project"

# List projects
npx taskdriver-mcp list-projects

# Get project details
npx taskdriver-mcp get-project "my-project"

# Create a task type template
npx taskdriver-mcp create-task-type "my-project" "analysis"

# Create tasks
npx taskdriver-mcp create-task "my-project"

# Get next task for an agent
npx taskdriver-mcp get-next-task "my-project" "my-agent"

# Complete a task
npx taskdriver-mcp complete-task "my-agent" "my-project" "task-id" "Task completed"

MCP Server Mode

Run TaskDriver as an MCP server for stdio transport:

npx taskdriver-mcp mcp

HTTP Server Mode

Run TaskDriver as an HTTP REST API server:

npx taskdriver-mcp server

Features

Multi-Mode Deployment: MCP server (stdio), HTTP REST API, and CLI interface
Project-Based Organization: Isolate tasks, agents, and configurations by project
Template-Based Task Types: Create reusable task templates with variable substitution
Atomic Task Assignment: Race-condition-free task distribution to agents
Lease Management: Automatic cleanup of expired tasks and failed agents
Multiple Storage Backends: File, MongoDB, and Redis storage providers
Comprehensive Monitoring: Health checks, metrics, and detailed project statistics
Batch Processing: Group related tasks and track batch completion
Retry Logic: Configurable retry policies for failed tasks

Deployment Modes

1. MCP Server (stdio)

Perfect for integration with LLM frameworks that support the Model Context Protocol:

bun run mcp

The MCP server provides 19 tools for complete task management:

Project management (create, list, update, delete)
Task lifecycle (create, assign, complete, fail)
Agent operations (register, status)
Monitoring (status, metrics, health)

2. HTTP REST API

For web applications and services:

bun run http

Access the API at http://localhost:3000 with full REST endpoints for all operations.

3. CLI Interface

For direct command-line usage and automation:

taskdriver --help

Core Concepts

Projects

Projects provide isolated environments for tasks and agents:

# Create a project
taskdriver create-project "ai-analysis" "AI-powered code analysis project" \\
  --instructions "@project-instructions.md" \\
  --max-retries 3 \\
  --lease-duration 15

# List projects
taskdriver list-projects

# Get project details
taskdriver get-project "ai-analysis"

Task Types

Task types are templates for creating similar tasks:

# Create a task type with template
taskdriver create-task-type "ai-analysis" "code-review" \\
  --template "@review-template.md" \\
  --variables "repository_url" "branch_name" "focus_area"

# List task types
taskdriver list-task-types "ai-analysis"

Tasks

Tasks are specific work items executed by agents:

# Create a task
taskdriver create-task "ai-analysis" "task-type-id" "Review security vulnerabilities" \\
  --variables '{"repository_url": "https://github.com/user/repo", "focus_area": "security"}'

# List tasks
taskdriver list-tasks "ai-analysis" --status queued

# Get task details
taskdriver get-task "task-id"

Agents

Agents are workers that execute tasks:

# Register an agent
taskdriver register-agent "ai-analysis" "security-agent"

# Get next task for agent
taskdriver get-next-task "security-agent" "ai-analysis"

# Complete a task
taskdriver complete-task "security-agent" "ai-analysis" "task-id" \\
  --result '{"status": "completed", "findings": ["vulnerability1", "vulnerability2"]}'

File Reading Support

Both descriptions and templates support reading from files using the @ prefix:

# Project description from file
taskdriver create-project "my-project" "@project-description.txt"

# Project instructions from file
taskdriver create-project "my-project" "Short description" --instructions "@instructions.md"

# Task template from file
taskdriver create-task-type "my-project" "analysis" --template "@analysis-template.md"

Configuration

Environment Variables

Core Configuration

# Server Configuration
TASKDRIVER_HOST=localhost                    # Server host (default: localhost)
TASKDRIVER_PORT=3000                        # Server port (default: 3000)
TASKDRIVER_MODE=auto                        # Server mode: auto, mcp, http, cli

# Storage Provider
TASKDRIVER_STORAGE_PROVIDER=file            # Storage provider: file, mongodb, redis
TASKDRIVER_STORAGE_CONNECTION_STRING=       # Connection string for mongodb/redis

File Storage Configuration

TASKDRIVER_FILE_DATA_DIR=./data             # Data directory for file storage
TASKDRIVER_FILE_LOCK_TIMEOUT=30000          # File lock timeout in milliseconds

MongoDB Configuration

TASKDRIVER_MONGODB_DATABASE=taskdriver      # MongoDB database name
TASKDRIVER_MONGODB_OPTIONS={}               # MongoDB connection options (JSON)

Redis Configuration

TASKDRIVER_REDIS_DATABASE=0                 # Redis database number
TASKDRIVER_REDIS_KEY_PREFIX=taskdriver:     # Redis key prefix
TASKDRIVER_REDIS_OPTIONS={}                 # Redis connection options (JSON)

Logging Configuration

TASKDRIVER_LOG_LEVEL=info                   # Log level: debug, info, warn, error
TASKDRIVER_LOG_PRETTY=false                 # Pretty print logs (true/false)
TASKDRIVER_LOG_CORRELATION=true             # Enable correlation IDs (true/false)

Security Configuration

TASKDRIVER_ENABLE_AUTH=true                 # Enable authentication (true/false)
TASKDRIVER_API_KEY_LENGTH=32                # API key length in characters
TASKDRIVER_SESSION_TIMEOUT=3600             # Session timeout in seconds

Default Task Configuration

TASKDRIVER_DEFAULT_MAX_RETRIES=3            # Default maximum retries for tasks
TASKDRIVER_DEFAULT_LEASE_DURATION=10        # Default lease duration in minutes
TASKDRIVER_REAPER_INTERVAL=1                # Reaper interval in minutes

Storage Providers

File Storage (Development)

TASKDRIVER_STORAGE_PROVIDER=file
TASKDRIVER_FILE_DATA_DIR=./data

MongoDB (Production)

TASKDRIVER_STORAGE_PROVIDER=mongodb
TASKDRIVER_MONGODB_URI=mongodb://localhost:27017/taskdriver

Redis (High Performance)

TASKDRIVER_STORAGE_PROVIDER=redis
TASKDRIVER_REDIS_URI=redis://localhost:6379

API Reference

REST API

Full REST API documentation available at /api/docs when running the HTTP server.

Key endpoints:

GET /api/projects - List projects
POST /api/projects - Create project
GET /api/projects/:id - Get project details
POST /api/projects/:id/tasks - Create task
GET /api/projects/:id/tasks - List tasks
POST /api/agents/:name/tasks/assign - Assign task to agent

MCP Tools

When running as an MCP server, 19 tools are available:

Project Management:

create_project - Create new project
list_projects - List all projects
get_project - Get project details
update_project - Update project properties

Task Management:

create_task_type - Create task template
list_task_types - List task types
create_task - Create new task
list_tasks - List tasks with filtering
get_task - Get task details

Agent Operations:

register_agent - Register new agent
list_agents - List agents
assign_task - Assign task to agent
complete_task - Mark task as completed
fail_task - Mark task as failed

Monitoring:

get_project_stats - Get project statistics
health_check - System health check
get_lease_stats - Get lease statistics
extend_task_lease - Extend task lease
cleanup_expired_leases - Clean up expired tasks

Monitoring and Operations

Health Checks

# Check system health
taskdriver health-check

# Get project statistics
taskdriver get-project-stats "my-project"

# Clean up expired leases
taskdriver cleanup-leases "my-project"

Metrics

When running the HTTP server, Prometheus metrics are available at /metrics.

Development

Testing

# Run all tests
bun test

# Run specific test suites
bun test test/services/
bun test test/storage/
bun test test/integration/

# Run with coverage
bun test --coverage

# E2E testing
./test/e2e/run-all-tests.sh

Development Commands

# Development mode with hot reload
bun run dev

# Build TypeScript
bun run build

# Clean build artifacts
bun run clean

Examples

See the docs/examples/ directory for complete usage examples:

Documentation

CLI Reference - Complete CLI command documentation
MCP Tools Reference - MCP server tool documentation
HTTP API Reference - REST API documentation
Configuration Guide - Detailed configuration options
Deployment Guide - Production deployment instructions
Architecture Overview - Technical architecture details

Contributing

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.