amithgc/agc-todo-mcp-server

📋 AGC Todo MCP Server

A powerful Model Context Protocol (MCP) server for intelligent todo management with Claude Desktop

Transform your task management with smart lists, natural language processing, and seamless Claude integration. Perfect for personal productivity and team coordination.

✨ Features

🎯 Smart Task Organization

• 📝 DO List: Your personal tasks
• 👥 GET DONE: Tasks to follow up with others
• ✅ COMPLETED: Archive of finished tasks

🔢 Simple Task References

• Easy integer IDs (1, 2, 3...) - no complex UUIDs!
• Reference tasks naturally: "Add update to task 1"

📅 Intelligent Date Handling

• Natural language: "tomorrow", "12th Sep", "today and tomorrow"
• Smart date parsing and filtering
• Always knows current time and context

💬 Rich Comments & Updates

• Timestamped comments on every task
• Full comment history with dates
• Task timeline tracking

📊 Beautiful Table Display

All task lists display in organized, professional tables:

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/your-username/agc-todo-mcp-server.git
cd agc-todo-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Claude Desktop Setup

1. Open Claude Desktop configuration:

   cd ~/Library/Application\ Support/Claude/
   open -a TextEdit claude_desktop_config.json
   

2. Add the server configuration:

   {
     "mcpServers": {
       "agc-todo": {
         "command": "node",
         "args": ["/path/to/your/agc-todo-mcp-server/build/index.js"]
       }
     }
   }
   

3. Restart Claude Desktop and you're ready to go! 🎉

📖 Detailed setup guide: See

💡 Example Usage

Personal Task Management

🗣️ "Add a todo for me: Complete the quarterly report by Friday"
🗣️ "What are my tasks for today and tomorrow?"
🗣️ "Add an update to task 3: Making good progress, 80% done"
🗣️ "Mark task 1 as complete"

Team Coordination

🗣️ "Follow up with Sarah about the API review by next Tuesday"
🗣️ "Who should I follow up with?"
🗣️ "What are Sarah's tasks for this week?"
🗣️ "Search for tasks assigned to the development team"

Task Tracking

🗣️ "View task 2"  → Shows complete history with timestamps
🗣️ "Search for tasks containing 'API'"
🗣️ "What are all my completed tasks?"

🛠️ Configuration Options

Default Setup

Tasks are stored in ./todos.json in your server directory.

Custom Location

Choose your preferred storage location:

Method 1: Command Line Argument

{
  "mcpServers": {
    "agc-todo": {
      "command": "node",
      "args": [
        "/path/to/agc-todo-mcp-server/build/index.js",
        "--todo-file",
        "/path/to/your/custom-todos.json"
      ]
    }
  }
}

Method 2: Environment Variable

{
  "mcpServers": {
    "agc-todo": {
      "command": "node", 
      "args": ["/path/to/agc-todo-mcp-server/build/index.js"],
      "env": {
        "TODO_FILE_PATH": "/path/to/your/custom-todos.json"
      }
    }
  }
}

🎮 Available Commands

📁 Data Structure

{
  "do": [
    {
      "id": 1,
      "description": "Complete project proposal",
      "owner": "current-user",
      "eta": "2024-09-15T00:00:00Z",
      "status": "pending",
      "comments": [
        {
          "timestamp": "2024-09-10T10:30:00Z",
          "text": "Started initial draft"
        }
      ],
      "createdAt": "2024-09-10T09:00:00Z",
      "updatedAt": "2024-09-10T10:30:00Z"
    }
  ],
  "getDone": [...],
  "completed": [...],
  "nextId": 4
}

🔧 Development

Tech Stack

• TypeScript - Type-safe development
• Node.js - Runtime environment
• MCP SDK - Model Context Protocol integration
• Natural Language Processing - Smart date parsing

Scripts

npm run build    # Build TypeScript to JavaScript
npm start        # Start the MCP server
npm run dev      # Development mode with auto-reload

Project Structure

agc-todo-mcp-server/
├── src/
│   ├── index.ts          # Main MCP server
│   ├── todoManager.ts    # Core todo operations
│   ├── dateUtils.ts      # Smart date handling
│   └── types.ts          # TypeScript definitions
├── build/                # Compiled JavaScript
├── claude-desktop-setup.md
└── README.md

🤝 Contributing

We love contributions! Whether it's:

• 🐛 Bug reports - Found an issue? Let us know!
• 💡 Feature requests - Have an idea? Share it!
• 🔧 Code contributions - PRs welcome!
• 📖 Documentation - Help others get started

Getting Started

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 Example Prompts

Daily Productivity

• "Add a todo for me: Review and respond to team emails by 2 PM"
• "What are my tasks for today?"
• "Add an update to task 5: Contacted client, waiting for feedback"

Project Management

• "Follow up with Alex about the database migration by Thursday"
• "Search for tasks related to the mobile app project"
• "Mark the API documentation task as complete"

Team Coordination

• "What tasks do I need to follow up on this week?"
• "Add a todo: Schedule team meeting for project kickoff next Monday"
• "View task 7" (shows complete history and timeline)

Status Updates

• "Update task 3: Encountered a bug in the payment system, investigating"
• "Add update to task 1: First draft complete, needs review"
• "What are all my completed tasks from last week?"

📄 License

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

🙋‍♂️ Support

• 📖 Documentation: Check our
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions