An intelligent Model Context Protocol (MCP) server for task management with AI-powered complexity analysis and multi-agent orchestration support
npm install task-list-mcpAn intelligent Model Context Protocol (MCP) server that provides sophisticated task management capabilities for AI agents. Features automatic complexity analysis, task breakdown, persistent state management, and agent-friendly parameter preprocessing for seamless AI integration.
The MCP Task Manager is specifically designed to work seamlessly with AI agents like Claude Desktop and Kiro IDE, including multi-agent orchestration environments where multiple AI agents work together on complex projects.
All agents should review the Agent Best Practices Guide for proven methodologies that maximize effectiveness:
- Plan and Reflect: Thorough planning before action, reflection after completion
- Use Tools, Don't Guess: Always investigate using available tools rather than making assumptions
- Persist Until Complete: Ensure all exit criteria are met before marking tasks complete
Key agent-friendly improvements include:
- Automatic Type Conversion: Converts common agent input patterns before validation
- String numbers โ Numbers: "5" becomes 5
- JSON strings โ Arrays: '["tag1", "tag2"]' becomes ["tag1", "tag2"]
- Boolean strings โ Booleans: "true" becomes true, "yes" becomes true
- Backward Compatible: Existing integrations continue to work without changes
- Performance Optimized: <50ms overhead per request
- Visual Indicators: Clear error formatting with emojis (โ, ๐ก, ๐)
- Actionable Guidance: Specific suggestions on how to fix validation errors
- Tool-Specific Help: Context-aware error messages based on the tool being used
- Working Examples: Include actual usage examples in error responses
- Task Dependencies: Set up complex task relationships with prerequisite management
- Ready Task Discovery: Find tasks that are unblocked and ready for parallel execution
- Agent Assignment: Orchestration agents can identify and assign ready tasks to specialized agents
- Parallel Execution: Multiple agents can work on independent tasks simultaneously
- Progress Tracking: Monitor completion status across distributed agent workflows
``javascript`
// These all work seamlessly now:
{
"priority": "5", // String number โ 5
"tags": '["urgent", "important"]', // JSON string โ array
"includeCompleted": "true", // String boolean โ true
"estimatedDuration": "120" // String number โ 120
}
- 80%+ Success Rate: For valid agent input patterns requiring conversion
- Clear Error Guidance: Non-technical error messages with helpful suggestions
- Enum Suggestions: Provides valid options when invalid choices are made
- Multiple Error Handling: Clear formatting when multiple validation issues occur
Before Agent-Friendly Updates:
``
Error: Expected number, received string at priority
After Agent-Friendly Updates:
`
โ priority: Expected number, but received string
๐ก Use numbers 1-5, where 5 is highest priority
๐ Example: 5 (highest) to 1 (lowest)
๐ง Common fixes:
1. Use numbers 1-5 for priority
Example: {"priority": 5}
`
The easiest way to get started - no local installation required:
`bashTest the installation
npx task-list-mcp@latest --version
$3
For development or customization:
`bash
Clone and install
git clone https://github.com/keyurgolani/task-list-mcp.git
cd task-list-mcp
npm installBuild the project
npm run buildTest that everything works
npx task-list-mcp@latest --version
`โก Automatic MCP Client Setup
Use our setup script to automatically configure your MCP clients:
`bash
Install the package
npx task-list-mcp@latest
`This will automatically update your Claude Desktop or Kiro IDE configuration files.
๐ง Manual MCP Client Configuration
If you prefer manual configuration or the automatic setup doesn't work:
$3
Add to your Claude Desktop
mcp.json configuration file:macOS:
~/Library/Application Support/Claude/mcp.json
Windows: %APPDATA%/Claude/mcp.json
Linux: ~/.config/claude/mcp.json`json
{
"mcpServers": {
"task-manager": {
"command": "npx",
"args": ["task-list-mcp@latest"],
"env": {
"NODE_ENV": "production",
"MCP_LOG_LEVEL": "info",
"DATA_DIRECTORY": "~/.claude/task-manager-data"
}
}
}
}
`Environment Variables Explained:
-
NODE_ENV: Environment mode (development, production, test) - controls logging and error handling
- MCP_LOG_LEVEL: Logging verbosity (error, warn, info, debug) - set to "info" for normal operation
- DATA_DIRECTORY: Directory for persistent data storage - will be created if it doesn't existSetup Validation:
1. Save the configuration file
2. Restart Claude Desktop
3. Verify the task-manager server appears in available tools
4. Test with: "Create a simple todo list to test the connection"
$3
Add to your workspace
.kiro/settings/mcp.json:`json
{
"mcpServers": {
"task-manager": {
"command": "npx",
"args": ["task-list-mcp@latest"],
"env": {
"NODE_ENV": "production",
"MCP_LOG_LEVEL": "info",
"DATA_DIRECTORY": "/tmp/task-list-mcp-data"
},
"disabled": false,
"autoApprove": [
"create_list",
"get_list",
"list_all_lists",
"delete_list",
"add_task",
"update_task",
"remove_task",
"complete_task",
"set_task_priority",
"add_task_tags",
"search_tasks",
"filter_tasks",
"show_tasks",
"analyze_task",
"get_task_suggestions"
]
}
}
}
`Environment Variables Explained:
-
NODE_ENV: Environment mode (development, production, test) - controls logging and error handling
- MCP_LOG_LEVEL: Logging verbosity (error, warn, info, debug) - set to "info" for normal operation
- DATA_DIRECTORY: Directory for persistent data storage - will be created if it doesn't existAuto-Approve Tools: All 15 available MCP tools are included for seamless AI agent integration. Remove tools from this list if you want manual approval for specific operations.
Setup Validation:
1. Save the configuration file to
.kiro/settings/mcp.json
2. Check the MCP Server view in the Kiro feature panel
3. Verify the task-manager server shows as "Connected"
4. Test with: "Create a todo list for testing the MCP connection"$3
`bash
Using npx
npx task-list-mcp@latestWith options
npx task-list-mcp@latest --verbose
npx task-list-mcp@latest --config ./my-config.json
`๐ง Environment Configuration
$3
The MCP Task Manager supports several environment variables to customize its behavior:
| Variable | Required | Default | Description |
| ---------------- | -------- | ------------- | -------------------------------------------------------- |
|
NODE_ENV | No | development | Environment mode: development, production, or test |
| MCP_LOG_LEVEL | No | info | Logging verbosity: error, warn, info, or debug |
| DATA_DIRECTORY | No | ./data | Directory for persistent data storage |
| STORAGE_TYPE | No | file | Storage backend: file or memory |$3
#### Development Environment
`json
{
"mcpServers": {
"task-manager": {
"command": "npx",
"args": ["task-list-mcp@latest"],
"env": {
"NODE_ENV": "development",
"MCP_LOG_LEVEL": "debug",
"DATA_DIRECTORY": "./dev-data",
"STORAGE_TYPE": "file"
}
}
}
}
`Development Features:
- Verbose debug logging for troubleshooting
- Local data directory for easy access
- Enhanced error messages and stack traces
- Automatic data validation and consistency checks
#### Production Environment
`json
{
"mcpServers": {
"task-manager": {
"command": "npx",
"args": ["task-list-mcp@latest"],
"env": {
"NODE_ENV": "production",
"MCP_LOG_LEVEL": "warn",
"DATA_DIRECTORY": "/var/lib/task-manager",
"STORAGE_TYPE": "file"
}
}
}
}
`Production Features:
- Minimal logging for performance
- Secure data directory with proper permissions
- Optimized error handling
- Automatic backup and recovery mechanisms
#### Testing Environment
`json
{
"mcpServers": {
"task-manager": {
"command": "npx",
"args": ["task-list-mcp@latest"],
"env": {
"NODE_ENV": "test",
"MCP_LOG_LEVEL": "error",
"DATA_DIRECTORY": "/tmp/test-data",
"STORAGE_TYPE": "memory"
}
}
}
}
`Testing Features:
- Memory-only storage for fast test execution
- Minimal logging to reduce test noise
- Automatic cleanup between test runs
- Deterministic behavior for reliable testing
$3
####
NODE_ENVControls the overall behavior and optimization level:
-
development: Enhanced debugging, verbose logging, development-friendly error messages
- production: Optimized performance, minimal logging, production-ready error handling
- test: Fast execution, minimal output, deterministic behavior####
MCP_LOG_LEVELControls logging verbosity:
-
error: Only critical errors (recommended for production)
- warn: Errors and warnings (good balance for most use cases)
- info: Errors, warnings, and informational messages (default)
- debug: All messages including detailed debugging information (development only)####
DATA_DIRECTORYSpecifies where persistent data is stored:
- Must be writable by the process running the MCP server
- Will be created automatically if it doesn't exist
- Should be backed up regularly in production environments
- Use absolute paths for production deployments
####
STORAGE_TYPESelects the storage backend:
-
file: Persistent file-based storage with atomic operations (default)
- memory: In-memory storage for testing and development (data lost on restart)$3
#### Common Configuration Issues
Server Won't Start
`bash
Check if the command is accessible
npx task-list-mcp@latest --versionTest with minimal configuration
NODE_ENV=development npx task-list-mcp@latest
`Permission Errors
`bash
Check directory permissions
ls -la /path/to/data/directoryCreate directory with proper permissions
mkdir -p ~/.local/share/task-manager
chmod 755 ~/.local/share/task-manager
`Environment Variable Not Working
1. Verify JSON syntax in configuration file
2. Restart your MCP client after configuration changes
3. Check client logs for environment variable parsing errors
4. Test environment variables directly:
`bash
NODE_ENV=production MCP_LOG_LEVEL=debug npx task-list-mcp@latest --version
`Data Directory Issues
`bash
Verify directory exists and is writable
test -w /path/to/data/directory && echo "Writable" || echo "Not writable"Check disk space
df -h /path/to/data/directoryCheck for permission issues
ls -la /path/to/data/directory
`#### Validation Steps
1. Test Configuration Syntax
`bash
# Validate JSON syntax
cat ~/.config/claude/mcp.json | jq .
`2. Verify Server Startup
`bash
# Test server starts with your configuration
npx task-list-mcp@latest --version
`3. Check Environment Variables
`bash
# Test with explicit environment variables
NODE_ENV=production MCP_LOG_LEVEL=info npx task-list-mcp@latest --help
`4. Validate Data Directory
`bash
# Ensure directory is accessible
mkdir -p "$DATA_DIRECTORY" && echo "Directory OK" || echo "Directory Error"
`5. Test MCP Client Connection
- Restart your MCP client after configuration changes
- Look for the task-manager server in available tools
- Try creating a simple todo list to verify functionality
๐ ๏ธ Available MCP Tools
The MCP Task Manager provides 18 focused MCP tools organized into 5 categories for intelligent task management and multi-agent orchestration:
$3
1.
create_list - Create new todo lists with simple parameters
2. get_list - Retrieve a specific todo list by ID with optional filtering
3. list_all_lists - Get all todo lists with basic information and filtering
4. delete_list - Delete or archive a todo list (reversible by default)$3
5.
add_task - Add new tasks with priority, tags, and time estimates
6. update_task - Update task properties (title, description, duration)
7. remove_task - Remove tasks from lists
8. complete_task - Mark tasks as completed with automatic progress tracking
9. set_task_priority - Change task priority levels (1-5 scale)
10. add_task_tags - Add organizational tags to tasks$3
11.
search_tasks - Search tasks by text across titles and descriptions
12. filter_tasks - Filter tasks by status, priority, tags, and other criteria
13. show_tasks - Display formatted task lists with grouping and styling options$3
14.
analyze_task - AI-powered task complexity analysis with breakdown suggestions
15. get_task_suggestions - Generate AI-powered task recommendations for lists$3
16.
set_task_dependencies - Set task prerequisites and relationships for workflow management
17. get_ready_tasks - Find tasks ready for execution (no incomplete dependencies)
18. analyze_task_dependencies - Analyze project structure, critical paths, and bottlenecks with DAG visualization$3
####
create_listCreates a new todo list with simple parameters.
`json
{
"name": "create_list",
"arguments": {
"title": "My Project Tasks",
"description": "Tasks for the new project",
"projectTag": "project-alpha"
}
}
`####
add_taskAdds a new task to a todo list.
`json
{
"name": "add_task",
"arguments": {
"listId": "12345678-1234-1234-1234-123456789012",
"title": "Set up development environment",
"description": "Install Node.js, npm, and project dependencies",
"priority": 4,
"estimatedDuration": 60,
"tags": ["setup", "development"]
}
}
`####
get_listRetrieves a specific todo list by ID.
`json
{
"name": "get_list",
"arguments": {
"listId": "12345678-1234-1234-1234-123456789012",
"includeCompleted": false
}
}
`$3
For complete documentation:
- Installation Guide - Setup and configuration
- Getting Started - Basic usage tutorial
- API Reference - Complete tool documentation
- Examples - Usage examples and patterns
- Troubleshooting - Common issues and solutions
See: docs/README.md - Complete Documentation Index
๐ค Multi-Agent Orchestration
The MCP Task Manager is uniquely designed to support multi-agent environments where an orchestration agent coordinates multiple specialized agents working on different tasks in parallel.
$3
#### Task Dependency Management
- Set Prerequisites: Define which tasks must be completed before others can begin
- Prevent Conflicts: Automatic circular dependency detection and prevention
- Workflow Control: Ensure proper task sequencing across multiple agents
- DAG Visualization: Visual representation of task dependencies in multiple formats
#### Ready Task Discovery
- Find Available Work: Identify tasks with no incomplete dependencies
- Priority Sorting: Get ready tasks sorted by priority and creation time
- Parallel Execution: Multiple agents can work on independent ready tasks simultaneously
#### Project Analysis & Optimization
- Critical Path Analysis: Identify the longest chain of dependent tasks
- Bottleneck Detection: Find tasks that block multiple others
- Progress Monitoring: Track completion status across distributed workflows
- Visual DAG Analysis: ASCII, DOT (Graphviz), and Mermaid format dependency graphs
$3
`json
// 1. Orchestration agent sets up task dependencies
{
"name": "set_task_dependencies",
"arguments": {
"listId": "web-app-project",
"taskId": "deploy-frontend",
"dependencyIds": ["build-ui", "run-tests", "code-review"]
}
}// 2. Orchestration agent finds ready tasks for assignment
{
"name": "get_ready_tasks",
"arguments": {
"listId": "web-app-project",
"limit": 5
}
}
// Returns: ["setup-database", "write-docs", "design-api"]
// 3. Orchestration agent assigns tasks to specialized agents:
// - Database Agent โ "setup-database"
// - Documentation Agent โ "write-docs"
// - API Agent โ "design-api"
// 4. As tasks complete, more become ready for assignment
// 5. Process continues until all tasks are completed
`$3
- Increased Throughput: Multiple agents work in parallel on independent tasks
- Optimal Resource Utilization: No agent waits unnecessarily for blocked tasks
- Intelligent Scheduling: Automatic identification of the most impactful work
- Scalable Coordination: Handles complex projects with hundreds of interdependent tasks
- Fault Tolerance: Failed tasks don't block unrelated work streams
$3
- Specialized Agent Teams: Different agents for frontend, backend, testing, documentation
- Pipeline Processing: Sequential stages with parallel work within each stage
- Feature Teams: Multiple agents working on different features simultaneously
- Quality Gates: Dependency-based approval workflows with multiple reviewers
This makes the MCP Task Manager ideal for:
- Large Development Projects with multiple specialized AI agents
- Content Creation Pipelines with writers, editors, and publishers
- Research Projects with data collection, analysis, and reporting agents
- Business Process Automation with multiple workflow participants
For complete multi-agent orchestration documentation, see: docs/guides/multi-agent.md
๐งช Testing Your Installation
$3
`bash
Test npx installation
npx task-list-mcp@latest --versionExpected output:
MCP Task Manager v1.0.0
Node.js v18.x.x
Platform: darwin arm64
`$3
`bash
Start the server and test basic functionality
npx task-list-mcp@latest --help
`$3
After configuring your MCP client:
1. Claude Desktop: Restart Claude Desktop and look for the task-manager server in the available tools
2. Kiro IDE: Check the MCP Server view in the Kiro feature panel
3. Custom client: Send a
tools/list request to verify the server responds$3
`bash
Run health check
node dist/health-check.jsRun integration tests
npm test -- --testPathPattern=integration
`๐ Usage Examples
$3
Once configured in your MCP client, you can use natural language:
In Claude Desktop:
> "Create a todo list called 'Website Redesign' with tasks for planning, design, and development"
In Kiro IDE:
> "I need a todo list for my API project with initial setup tasks"
The MCP server will automatically:
- Create structured todo lists with proper metadata
- Generate unique IDs for tracking
- Calculate progress and completion statistics
- Store data persistently using file-based storage with atomic operations
$3
> "Show me the todo list with ID abc-123-def"
> "Get my project tasks but exclude completed items"
๐ง Development
$3
`bash
Build the project
npm run buildStart the server
npm start
`$3
1. Make changes to source code in
src/
2. Build for production: npm run build
3. Test MCP integration: Use manual protocol test with your MCP client๐ Project Structure
`
src/
โโโ handlers/ # MCP tool implementations (15 tools)
โโโ managers/ # Business logic and system managers
โโโ core/ # Core functionality and utilities
โโโ storage/ # Data persistence backends (file/memory)
โโโ intelligence/ # AI-powered analysis and suggestions
โโโ monitoring/ # Performance and health monitoring
โโโ types/ # TypeScript interfaces and schemas
โโโ utils/ # Pure utility functions
โโโ config/ # Configuration management
โโโ cli.ts # Command-line interface
โโโ index.ts # Main server entry pointexamples/
โโโ 01-list-management-examples.md # List management examples
โโโ 02-task-management-examples.md # Task management examples
โโโ 03-search-display-examples.md # Search and display examples
โโโ 04-advanced-features-examples.md # AI-powered features
โโโ 05-configuration-examples.md # Configuration examples
โโโ README.md # Examples overview
docs/
โโโ api/ # Complete API documentation
โโโ configuration/ # Setup and configuration guides
โโโ examples/ # Usage examples and patterns
โโโ reference/ # Reference materials
โโโ tutorials/ # Step-by-step tutorials
โโโ mcp-tools.md # Complete MCP tools reference
โโโ mcp-tool-usage.md # Practical usage guide
โโโ README.md # Documentation overview
`Quality Standards
This project follows production-ready standards:
- Zero TypeScript errors: Strict mode enabled with comprehensive checks
- MCP Protocol Compliance: All tools follow MCP specification
- Production Ready: Optimized for performance and reliability
๐จ Troubleshooting
$3
#### npx Installation Problems
`bash
Check npm version (npm 7.0.0+ recommended)
npm --versionClear npm cache
npm cache clean --forceTry with explicit version
npx task-list-mcp@latest --versionIf still failing, check Node.js version
node --version # Must be 18.0.0+
`$3
#### Server Won't Start
`bash
Test the server directly
npx task-list-mcp@latest --versionCheck with verbose logging
npx task-list-mcp@latest --verboseFor local development
npm run build && node dist/cli.js --version
`#### MCP Client Can't Connect
1. Check configuration syntax: Ensure JSON is valid
2. Verify command paths:
npx must be in PATH
3. Test server manually: Run the command from terminal first
4. Check client logs: Look for connection errors in MCP client
5. Restart client: Restart Claude Desktop or Kiro after config changes#### Permission Errors
`bash
For npx (may need to fix npm permissions)
npm config get prefix
npm config set prefix ~/.npm-globalFor local development
chmod +x dist/cli.js
`$3
#### Automatic Setup Fails
`bash
Check if config directories exist
ls -la ~/Library/Application\ Support/Claude/ # macOS
ls -la ~/.kiro/settings/ # Kiro workspaceCopy example configs manually
cp examples/mcp-config-npx.json ~/.config/claude/mcp.json
`#### Server Not Found in MCP Client
1. Restart the MCP client after configuration changes
2. Check server name matches configuration (should be "task-manager")
3. Verify command accessibility: Run
npx task-list-mcp@latest --version in terminal
4. Check environment variables in the configuration$3
1. Test installation:
npx task-list-mcp@latest --version
2. Check verbose logs: Add --verbose flag to see detailed output
3. Validate configuration: Use the setup script to regenerate configs
4. Check prerequisites: Ensure Node.js 18+ and npm are installed
5. Review client logs: Check your MCP client's log files for connection errors$3
- "command not found: npx" โ Install Node.js and npm
- "EACCES: permission denied" โ Fix npm permissions or use sudo
- "Module not found" โ Clear cache and reinstall:
npm cache clean --force
- "Connection refused" โ Check if server starts manually before configuring client๐ Performance & Limitations
$3
- File-based storage: Persistent storage with atomic operations and backup capabilities
- Memory storage option: Available for development and testing
- Complete CRUD operations: Full create, read, update, delete functionality
- No authentication: Open access (suitable for development only)
$3
- Response time: ~5ms for create operations, ~2ms for read operations
- Complex operations: ~10-50ms for AI analysis and bulk operations
- Concurrent operations: Supports 100+ simultaneous requests
- Memory usage: Stable under load, ~145MB typical usage
- Data volume: Supports 1000+ items per todo list, unlimited lists
- Throughput: ~900 operations per second sustained
- Storage: Atomic file operations with backup and recovery
๐ฃ๏ธ Roadmap
$3
- Complete: 15 focused MCP tools for comprehensive task management
- Complete: AI-powered complexity analysis and task suggestions
- Complete: File-based storage with atomic operations and backup
- Complete: Comprehensive error handling and recovery systems
- Complete: Performance monitoring and health checking
- Complete: Production-ready CLI interface and configuration
$3
- Advanced natural language processing for task analysis
- Improved complexity scoring algorithms with machine learning
- Better task generation with context awareness
- Predictive task completion estimates
$3
- Database backend support (PostgreSQL, MongoDB)
- Authentication and authorization systems
- Rate limiting and security hardening
- Real-time collaboration features
- REST API interface alongside MCP
$3
- Advanced analytics and reporting dashboards
- Multi-tenant support with data isolation
- API rate limiting and monitoring
- Integration with external project management tools
๐ฆ Installation Methods Summary
| Method | Command | Use Case | Prerequisites |
| --------- | -------------------------- | -------------------------- | ---------------- |
| npx |
npx task-list-mcp@latest | Quick start, always latest | Node.js 18+, npm |
| Local | git clone && npm install | Development, customization | Node.js 18+, git |$3
- โ
15 MCP Tools: Complete tool set organized in 4 categories
- โ
MCP Protocol: Fully compliant with MCP SDK 1.0.0+
- โ
CLI Interface: Complete command-line interface with help and version
- โ
Storage Systems: File and memory storage with atomic operations
- โ
AI Intelligence: Task complexity analysis and intelligent suggestions
- โ
Error Handling: Comprehensive error handling with recovery mechanisms
- โ
Monitoring: Performance monitoring, health checks, and metrics
- โ
TypeScript: Strict TypeScript with zero
any types
- โ
Production Ready: Optimized for performance and reliability
- โ
Documentation: Complete API documentation and examples๐ License
MIT License - see LICENSE file for details
๐ค Contributing
1. Fork the repository
2. Create a feature branch:
git checkout -b feature/amazing-feature
3. Make your changes and ensure they build: npm run build
4. Commit your changes: git commit -m 'feat: add amazing feature'
5. Push to the branch: git push origin feature/amazing-feature
6. Open a Pull Request$3
- TypeScript strict mode: No
any` types allowed