Skip to content

AI-powered project management server. Guides LLM IDE tools for verifiable task completion; self-contained with TypeScript/Drizzle ORM and workflow based feedback control.

Notifications You must be signed in to change notification settings

omar391/taskpilot-mcp

Repository files navigation

TaskPilot MCP Server

A comprehensive Model Context Protocol server for task management, project documentation, and development workflow automation. TaskPilot provides an integrated solution combining MCP protocol support, REST API, and web UI in a single unified server.

πŸš€ Quick Start

Installation

git clone <repository-url>
cd taskpilot-mcp
npm install
npm run build

Launch Integrated Server

# Start on default port 8989
npm run serve

# Or specify custom port
npm start -- --port=9000

# For development with TypeScript watch mode
npm run dev

Access Points:

πŸ—οΈ Architecture

TaskPilot runs as a unified server supporting multiple interaction modes:

1. MCP Protocol Support

  • STDIO Mode: Full compatibility with MCP clients (Claude Desktop, etc.)
  • HTTP/SSE Mode: Server-Sent Events transport for web-based MCP clients
  • All 11 Tools Available: Complete feature parity across both transports

2. REST API

  • Workspace Management: /api/workspaces
  • Task Operations: /api/workspaces/{id}/tasks
  • Tool Flows: /api/workspaces/{id}/tool-flows
  • Feedback Steps: /api/workspaces/{id}/feedback-steps

3. Web UI

  • React-based Dashboard: Modern interface for task management
  • Real-time Updates: SSE integration for live task status
  • SPA Routing: Full client-side navigation support

πŸ› οΈ Usage Modes

MCP Client Integration (STDIO)

For Claude Desktop and other MCP clients:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "taskpilot": {
      "command": "/path/to/taskpilot-mcp/build/index.js",
      "args": ["--stdio"]
    }
  }
}

Direct Command Line Usage

# STDIO mode (for MCP clients)
node build/index.js --stdio

# HTTP mode with custom port
node build/index.js --port=8989

# Development mode (additional logging)
node build/index.js --port=8989 --dev

# Show help
node build/index.js --help

πŸ“‹ Available Tools

TaskPilot provides 11 comprehensive tools for project management:

  1. taskpilot_init - Initialize workspace with .task folder structure
  2. taskpilot_start - Begin TaskPilot session with project context
  3. taskpilot_add - Orchestrate task creation with validation
  4. taskpilot_create_task - Create validated tasks
  5. taskpilot_status - Generate project status reports
  6. taskpilot_update - Update task properties with audit trails
  7. taskpilot_audit - Perform comprehensive project audits
  8. taskpilot_focus - Focus on specific tasks with context
  9. taskpilot_github - GitHub integration for issues and PRs
  10. taskpilot_rule_update - Manage workspace-specific rules
  11. taskpilot_remote_interface - External system integrations

πŸ”§ Development

Build Process

# Full build (TypeScript + UI)
npm run build

# TypeScript watch mode
npm run dev

# UI development (separate terminal)
cd ui && npm run dev

Project Structure

.
β”œβ”€β”€ src/                  # TypeScript source code
β”‚   β”œβ”€β”€ tools/           # MCP tool implementations
β”‚   β”œβ”€β”€ services/        # Core business logic
β”‚   β”œβ”€β”€ database/        # Drizzle ORM setup
β”‚   β”œβ”€β”€ server/          # Express server integration
β”‚   β”œβ”€β”€ utils/           # Utility functions
β”‚   └── api/             # REST API endpoints
β”œβ”€β”€ ui/                  # React web interface
β”‚   β”œβ”€β”€ src/             # React components
β”‚   └── dist/            # Built UI assets
β”œβ”€β”€ build/               # Compiled JavaScript
└── .task/               # TaskPilot workspace data
    β”œβ”€β”€ todo/            # Task tracking
    β”œβ”€β”€ rules/           # Workspace rules
    └── project.md       # Project documentation

Database

TaskPilot uses SQLite with Drizzle ORM:

  • Global Database: ~/.taskpilot/global.db
  • Workspace Database: .task/workspace.db (per project)
  • Schema: Fully managed through TypeScript types

πŸš€ Deployment

Local Deployment

npm run build
npm run serve

Production Configuration

  1. Environment Variables:

    NODE_ENV=production
    TASKPILOT_PORT=8989
    TASKPILOT_HOST=0.0.0.0
  2. Process Management:

    # Using PM2
    pm2 start build/index.js --name "taskpilot" -- --port=8989
    
    # Using systemd (create service file)
    sudo systemctl enable taskpilot
    sudo systemctl start taskpilot
  3. Reverse Proxy (nginx example):

    server {
        listen 80;
        server_name taskpilot.example.com;
        
        location / {
            proxy_pass http://localhost:8989;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection 'upgrade';
            proxy_set_header Host $host;
            proxy_cache_bypass $http_upgrade;
        }
    }

πŸ” Troubleshooting

Port Conflicts

TaskPilot automatically detects and resolves port conflicts:

# Check what's using port 8989
lsof -i :8989

# TaskPilot will automatically kill existing processes
npm run serve  # Auto-cleanup enabled

STDIO Mode Issues

# Test STDIO directly
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | node build/index.js --stdio

# Expected: JSON response with 11 tools

HTTP Mode Issues

# Health check
curl http://localhost:8989/health

# Expected: {"status":"healthy",...}

Database Issues

# Reset global database
rm ~/.taskpilot/global.db
npm run serve  # Auto-recreates

# Reset workspace database
rm .task/workspace.db
# Run taskpilot_init tool to recreate

πŸ“š Documentation

Command Reference

Command Description Example
--stdio STDIO mode for MCP clients node build/index.js --stdio
--port=N HTTP mode on port N node build/index.js --port=8989
--http Force HTTP mode (default) node build/index.js --http
--dev Development mode node build/index.js --dev
--help Show help node build/index.js --help
--no-kill Don't kill existing processes node build/index.js --no-kill

API Reference

Base URL: http://localhost:8989/api

Endpoint Method Description
/workspaces GET List all workspaces
/workspaces/{id}/tasks GET, POST Manage tasks
/workspaces/{id}/tasks/{taskId} PUT Update specific task
/workspaces/{id}/tool-flows GET Get tool flows
/workspaces/{id}/feedback-steps GET Get feedback steps

Tool Schema

All tools accept JSON parameters and return structured responses:

interface ToolResult {
  content: Array<{type: "text", text: string}>;
  isError: boolean;
}

🀝 Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes
  4. Build and test: npm run build && npm run serve
  5. Commit your changes: git commit -m 'Add amazing feature'
  6. Push to the branch: git push origin feature/amazing-feature
  7. Open a Pull Request

πŸ“„ License

[Add your license information here]

πŸ†• Migration from Separate Servers

If migrating from a setup with separate MCP and UI servers:

  1. Update MCP Client Config: Change to single server endpoint
  2. Update API Calls: Base URL is now /api instead of separate port
  3. Port Configuration: Single port (8989) instead of multiple ports
  4. Process Management: Single process instead of multiple services

Built with: TypeScript, Express, Drizzle ORM, React, MCP SDK

About

AI-powered project management server. Guides LLM IDE tools for verifiable task completion; self-contained with TypeScript/Drizzle ORM and workflow based feedback control.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published