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.
git clone <repository-url>
cd taskpilot-mcp
npm install
npm run build
# 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:
- Web UI: http://localhost:8989/
- REST API: http://localhost:8989/api/
- Health Check: http://localhost:8989/health
- MCP: http://localhost:8989/mcp
TaskPilot runs as a unified server supporting multiple interaction modes:
- 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
- Workspace Management:
/api/workspaces
- Task Operations:
/api/workspaces/{id}/tasks
- Tool Flows:
/api/workspaces/{id}/tool-flows
- Feedback Steps:
/api/workspaces/{id}/feedback-steps
- React-based Dashboard: Modern interface for task management
- Real-time Updates: SSE integration for live task status
- SPA Routing: Full client-side navigation support
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"]
}
}
}
# 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
TaskPilot provides 11 comprehensive tools for project management:
taskpilot_init
- Initialize workspace with .task folder structuretaskpilot_start
- Begin TaskPilot session with project contexttaskpilot_add
- Orchestrate task creation with validationtaskpilot_create_task
- Create validated taskstaskpilot_status
- Generate project status reportstaskpilot_update
- Update task properties with audit trailstaskpilot_audit
- Perform comprehensive project auditstaskpilot_focus
- Focus on specific tasks with contexttaskpilot_github
- GitHub integration for issues and PRstaskpilot_rule_update
- Manage workspace-specific rulestaskpilot_remote_interface
- External system integrations
# Full build (TypeScript + UI)
npm run build
# TypeScript watch mode
npm run dev
# UI development (separate terminal)
cd ui && npm run dev
.
βββ 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
TaskPilot uses SQLite with Drizzle ORM:
- Global Database:
~/.taskpilot/global.db
- Workspace Database:
.task/workspace.db
(per project) - Schema: Fully managed through TypeScript types
npm run build
npm run serve
-
Environment Variables:
NODE_ENV=production TASKPILOT_PORT=8989 TASKPILOT_HOST=0.0.0.0
-
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
-
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; } }
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
# Test STDIO directly
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | node build/index.js --stdio
# Expected: JSON response with 11 tools
# Health check
curl http://localhost:8989/health
# Expected: {"status":"healthy",...}
# 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
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 |
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 |
All tools accept JSON parameters and return structured responses:
interface ToolResult {
content: Array<{type: "text", text: string}>;
isError: boolean;
}
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature
- Make your changes
- Build and test:
npm run build && npm run serve
- Commit your changes:
git commit -m 'Add amazing feature'
- Push to the branch:
git push origin feature/amazing-feature
- Open a Pull Request
[Add your license information here]
If migrating from a setup with separate MCP and UI servers:
- Update MCP Client Config: Change to single server endpoint
- Update API Calls: Base URL is now
/api
instead of separate port - Port Configuration: Single port (8989) instead of multiple ports
- Process Management: Single process instead of multiple services
Built with: TypeScript, Express, Drizzle ORM, React, MCP SDK