Todo for AI

中文版本 | English

🚀 A powerful task management system specifically designed for AI assistants, supporting intelligent project management, automated task tracking, and seamless team collaboration through MCP (Model Context Protocol) integration.

🚀 Try it now: Visit https://todo4ai.org/ to experience our product!

🤖 Why Todo for AI?

Todo for AI bridges the gap between AI assistants and human productivity workflows. Unlike traditional task management tools, our system is built from the ground up to work seamlessly with AI agents through the Model Context Protocol (MCP).

🎯 Core Value Propositions

• 🔗 Native AI Integration: First-class support for AI assistants through MCP, enabling natural language task management
• 🧠 Intelligent Automation: AI agents can create, update, and manage tasks autonomously based on context and user needs
• 📊 Smart Project Insights: AI-powered analytics and recommendations for better project planning and execution
• 🔄 Seamless Workflow: Bridge between AI capabilities and human oversight with intelligent task delegation
• 🌐 Universal Compatibility: Works with Claude, GPT, and other AI assistants through standardized MCP protocol
• ⚡ Real-time Collaboration: Instant synchronization between AI agents and human team members

🚀 Perfect For

• AI-First Teams building the future of work
• Developers integrating AI assistants into their workflows
• Product Managers coordinating between AI agents and human teams
• Researchers managing complex AI-driven projects
• Anyone looking to supercharge their productivity with AI assistance

📸 Screenshots & Demo

🖥️ Web Interface

Modern, intuitive dashboard for project and task management

Comprehensive task management with AI integration

Seamless AI assistant integration through MCP

🎬 Demo Video

Click to watch a full demo of Todo for AI in action

✨ Key Features in Action

• 🤖 AI-Powered Task Creation: Watch AI assistants create and organize tasks naturally
• 📊 Real-time Analytics: See project progress and insights update live
• 🔄 Seamless Collaboration: Experience smooth coordination between AI and human team members
• 🎯 Smart Prioritization: Observe AI-driven task prioritization and scheduling

📁 Project Structure

This project uses Git Submodule architecture, splitting different modules into independent repositories:

• todo-for-ai-api-server/: Backend API server → todo-for-ai-api-server
• todo-for-ai-webpage/: Frontend web application → todo-for-ai-webpage
• todo-for-ai-mcp/: MCP server → todo-for-ai-mcp

📚 Architecture & Specs

• Agent Platform Spec v1.0
• API Documentation
• Database Design

🚀 Installation & Quick Start

Choose your preferred installation method:

🐳 Option 1: Docker (Recommended)

The fastest way to get started - everything included in one container:

bashCopy code
# Pull and run the latest image
docker run -d --name todo-for-ai \
  -p 50111:80 \
  -p 50110:50110 \
  -e DATABASE_URL="mysql+pymysql://username:password@host.docker.internal:3306/todo_for_ai" \
  -e GMAIL_USER="your-email@gmail.com" \
  -e GMAIL_PASSWORD="your-app-password" \
  -e GITHUB_TOKEN="your-github-token" \
  -e SECRET_KEY="your-secret-key-here" \
  -e JWT_SECRET_KEY="your-jwt-secret-key-here" \
  --add-host=host.docker.internal:host-gateway \
  todoforai/todo-for-ai:latest

# Access the application
# Frontend: http://localhost:50111/todo-for-ai/pages/projects
# API: http://localhost:50110/todo-for-ai/api/v1/

📦 Option 2: MCP Package Only

If you only need the MCP server for AI assistant integration:

bashCopy code
# Install via npm
npm install -g @todo-for-ai/mcp

# Or install locally
npm install @todo-for-ai/mcp

# Configure and start
todo-for-ai-mcp --config config.json

🛠️ Option 3: Development Setup

For developers who want to contribute or customize:

bashCopy code
# 1. Clone the project (including submodules)
git clone --recursive https://github.com/todo-for-ai/todo-for-ai.git
cd todo-for-ai

# 2. Initialize submodules (if not using --recursive)
git submodule update --init --recursive

# 3. Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# 4. Start with Docker Compose
docker-compose up -d

# Or build and run manually
docker build -t todo-for-ai:latest .
docker run -d --name todo-for-ai [environment variables] todo-for-ai:latest

⚡ Option 4: Source Installation

For advanced users who prefer manual setup:

bashCopy code
# 1. Clone and setup
git clone --recursive https://github.com/todo-for-ai/todo-for-ai.git
cd todo-for-ai

# 2. Backend setup
cd todo-for-ai-api-server
pip install -r requirements.txt
python app.py

# 3. Frontend setup (new terminal)
cd ../todo-for-ai-webpage
npm install
npm run build
npm run preview

# 4. MCP server setup (new terminal)
cd ../todo-for-ai-mcp
npm install
npm run build
npm start

✅ Runtime E2E Validation (Local)

From repository root, you can run one-shot runtime validation:

bashCopy code
# auto-create one AI task and verify commit -> DONE
./scripts/runtime_e2e_once.sh

# strict mode: first observed commit must match the target task
TARGET_TASK_ID=123456 STRICT_TARGET_ONLY=true ./scripts/runtime_e2e_once.sh

This wrapper calls agent-runtime/scripts/run_docker_e2e_once.sh and works with Colima/Docker local environments.

🎯 Quick Start Examples

🤖 Using with AI Assistants (MCP)

Once installed, you can immediately start using Todo for AI with your favorite AI assistant:

javascriptCopy code
// Example: Claude Desktop MCP Configuration
{
  "mcpServers": {
    "todo-for-ai": {
      "command": "npx",
      "args": ["@todo-for-ai/mcp"],
      "env": {
        "TODO_API_URL": "http://localhost:50110/todo-for-ai/api/v1",
        "TODO_API_KEY": "your-api-key"
      }
    }
  }
}

bashCopy code
# Example AI Commands (Natural Language)
"Create a new project called 'Website Redesign'"
"Add a task 'Design homepage mockup' to the Website Redesign project"
"List all my pending tasks"
"Mark the homepage mockup task as completed"
"Show me project progress for this week"

🌐 Web Interface Usage

bashCopy code
# 1. Access the web interface
open http://localhost:50111/todo-for-ai/pages/projects

# 2. Login with GitHub OAuth or create account
# 3. Create your first project
# 4. Add tasks and start collaborating with AI assistants

🔧 API Integration

javascriptCopy code
// Example: Creating a project via API
const response = await fetch('http://localhost:50110/todo-for-ai/api/v1/projects', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-jwt-token'
  },
  body: JSON.stringify({
    name: 'My AI Project',
    description: 'A project managed by AI assistants'
  })
});

// Example: Adding a task
const taskResponse = await fetch('http://localhost:50110/todo-for-ai/api/v1/tasks', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-jwt-token'
  },
  body: JSON.stringify({
    project_id: 1,
    title: 'Implement user authentication',
    content: 'Add OAuth integration for secure user login',
    priority: 'high',
    is_ai_task: true
  })
});

📱 MCP Server Configuration

jsonCopy code
// config.json for MCP server
{
  "server": {
    "host": "localhost",
    "port": 3001
  },
  "api": {
    "baseUrl": "http://localhost:50110/todo-for-ai/api/v1",
    "timeout": 30000
  },
  "auth": {
    "type": "jwt",
    "token": "your-jwt-token"
  },
  "features": {
    "autoCreateProjects": true,
    "smartTaskBreakdown": true,
    "contextualInsights": true
  }
}

🚀 Docker Deployment

1. Build image

bashCopy code
docker build -t todo-for-ai:latest .

2. Start container

bashCopy code
docker run -d --name todo-for-ai \
  -p 50111:80 \
  -p 50110:50110 \
  -e DATABASE_URL="mysql+pymysql://username:password@host.docker.internal:3306/todo_for_ai" \
  -e GMAIL_USER="your-email@gmail.com" \
  -e GMAIL_PASSWORD="your-app-password" \
  -e GITHUB_TOKEN="your-github-token" \
  -e SECRET_KEY="your-secret-key-here" \
  -e JWT_SECRET_KEY="your-jwt-secret-key-here" \
  --add-host=host.docker.internal:host-gateway \
  todo-for-ai:latest

3. Access URLs

• Frontend: http://localhost:50111/todo-for-ai/pages/projects
• API: http://localhost:50110/todo-for-ai/api/v1/

4. Environment Variables

🔧 Configuration

GitHub OAuth App Setup

1. Visit GitHub Developer Settings
2. Click "New OAuth App"
3. Fill in application information:
   • Application name: Todo for AI
   • Homepage URL: http://localhost:50111
   • Authorization callback URL: http://localhost:50110/todo-for-ai/api/v1/auth/callback
4. Get Client ID and Client Secret after creation

Gmail App Password Setup

1. Login to Gmail account
2. Go to "Manage your Google Account"
3. Select "Security" → "2-Step Verification"
4. Generate "App passwords"

GitHub Token Setup

1. Login to GitHub
2. Go to Settings → Developer settings → Personal access tokens
3. Generate new token with appropriate permissions

✨ Key Features

🎯 Core Task Management

• 📋 Smart Project Organization - Hierarchical project and task structure with AI-powered categorization
• ✅ Intelligent Task Tracking - Real-time status updates with automated progress monitoring
• 🏷️ Dynamic Tagging System - Flexible labeling with AI-suggested tags for better organization
• ⏰ Smart Scheduling - AI-assisted deadline management and priority optimization
• 📊 Progress Analytics - Visual dashboards with AI-generated insights and recommendations

🤖 AI Integration

• 🔌 MCP Protocol Support - Native integration with Claude, GPT, and other AI assistants
• 🗣️ Natural Language Interface - Create and manage tasks using conversational commands
• 🧠 Intelligent Automation - AI agents can autonomously manage tasks based on context
• 📝 Smart Task Generation - AI-powered task breakdown and subtask creation
• 🔍 Contextual Insights - AI-driven project analysis and optimization suggestions

👥 Collaboration & Communication

• 🔐 Secure Authentication - Multi-factor authentication with GitHub OAuth integration
• 📧 Smart Notifications - Intelligent email alerts with customizable triggers
• 🔄 Real-time Sync - Instant updates across all connected AI agents and team members
• 💬 Integrated Feedback - Seamless communication between AI assistants and human users
• 🌐 Cross-platform Access - Web interface with API access for custom integrations

🛠️ Developer Experience

• 🐳 Docker Ready - One-command deployment with full containerization
• 🔧 RESTful API - Comprehensive API for custom integrations and extensions
• 📚 Rich Documentation - Detailed guides for setup, usage, and customization
• 🔒 Enterprise Security - Production-ready security features and compliance
• 🚀 Scalable Architecture - Microservices design for high-performance deployments

🔍 Troubleshooting

Common Issues

1. Database Connection Failed

bashCopy code
# Check if database is running
mysql -u username -p -h localhost

# Check container logs
docker logs todo-for-ai

2. Port Already in Use

bashCopy code
# Check port usage
lsof -i :50110
lsof -i :50111

# Kill process
kill -9 <PID>

3. Frontend Page Cannot Load

bashCopy code
# Check nginx configuration
docker exec todo-for-ai nginx -t

# Restart nginx
docker exec todo-for-ai supervisorctl restart nginx

4. API Authentication Failed

• Check if environment variables are set correctly
• Confirm Gmail app password format is correct
• Verify GitHub Token permissions

Log Viewing

bashCopy code
# View all logs
docker logs todo-for-ai

# View Flask logs
docker exec todo-for-ai tail -f /var/log/supervisor/flask.out.log

# View Nginx logs
docker exec todo-for-ai tail -f /var/log/nginx/access.log

🧪 Testing

API Testing

bashCopy code
# Test backend health
curl http://localhost:50110/

# Test API proxy
curl http://localhost:50111/todo-for-ai/api/v1/projects

# Test frontend page
curl http://localhost:50111/todo-for-ai/pages/projects

Functional Testing

1. Access frontend page
2. Try login functionality
3. Create projects and tasks
4. Test email notifications

🚀 Production Deployment

Security Configuration

1. Use Strong Passwords: Ensure database and application keys are complex enough
2. HTTPS Configuration: Configure SSL certificates for production environment
3. Firewall Settings: Restrict unnecessary port access
4. Regular Backups: Set up automatic database backups

Performance Optimization

1. Resource Limits: Set memory and CPU limits for containers
2. Load Balancing: Configure load balancing for multi-instance deployment
3. Cache Configuration: Consider adding Redis cache
4. Monitoring & Alerting: Configure application monitoring and alerting

🤝 Contributing

Issues and Pull Requests are welcome!

Development Workflow

1. Fork the project
2. Create a feature branch
3. Commit your changes
4. Create a Pull Request

Git and File Management

.gitignore Configuration

The project uses comprehensive .gitignore files to prevent sensitive data and build artifacts from being committed:

• Root .gitignore: Main project-level ignore rules
• Subproject .gitignore: Each subproject (api-server, mcp, webpage) has its own rules

Verify .gitignore:

bashCopy code
# Run verification script
./scripts/verify-gitignore.sh

# Check if a file is ignored
git check-ignore -v <file>

Common ignored files:

• Environment variables (.env, .env.local)
• SSL certificates (*.key, *.pem, *.crt)
• Build outputs (dist/, build/, lib/)
• Dependencies (node_modules/, venv/)
• Logs (*.log, logs/)
• User uploads (uploads/, media/)
• Deployment scripts (deploy.sh, setup-*.sh)

Documentation:

• See .gitignore-quickref.md for quick reference
• See .gitignore-improvements.md for detailed changes

Clean up accidentally tracked files:

bashCopy code
# Remove from git but keep locally
git rm --cached <file>

# Or use the cleanup script (for sensitive files)
./scripts/cleanup-git-cache.sh

📄 License

MIT License

🌟 Ready to get started? Visit https://todo4ai.org/ and experience the power of AI-driven task management!