TaskMateAI

AI/MCP TODO task management application

TaskMateAI is a simple task management application that enables AI to autonomously manage and execute tasks, and can be operated through MCP (Model Context Protocol).

README available here

Related MCP server: Gorev Task Management Server

Features

• Creating and managing tasks through MCP

• Subtask Support

• Priority-based task handling

• Task progress management and reporting function

• Add notes feature

• Data persistence via JSON files

• Task management for multiple AIs by agent ID

• Organizing tasks by project

install

Prerequisites

• Python 3.12 or higher

• uv (Python package manager)

• WSL (Windows Subsystem for Linux) *For Windows environments

Installation Instructions

1. Clone or download the repository:

git clone https://github.com/YourUsername/TaskMateAI.git
cd TaskMateAI

2. Install the required packages:

uv install -r requirements.txt

How to use

Application launch

In the WSL environment you can run your application like this:

cd /path/to/TaskMateAI/src/TaskMateAI
uv run TaskMateAI

MCP Configuration

Example of configuration for use with MCP:

{
    "mcpServers": {
      "TodoApplication": {
        "command": "uv",
        "args": [
          "--directory", 
          "/絶対パス/TaskMateAI",
          "run",
          "TaskMateAI"
        ],
        "env": {},
        "alwaysAllow": [
          "get_tasks", "get_next_task", "create_task", "update_progress", 
          "complete_task", "add_subtask", "update_subtask", "add_note",
          "list_agents", "list_projects"
        ],
        "defaultArguments": {
          "agent_id": "agent_123",
          "project_name": ""
        }
      }
    }
}

{
    "mcpServers": {
      "TodoApplication": {
        "command": "wsl.exe",
        "args": [
          "-e", 
          "bash", 
          "-c", 
          "cd /絶対パス/TaskMateAI && /home/ユーザー/.local/bin/uv run TaskMateAI"
        ],
        "env": {},
        "alwaysAllow": [
          "get_tasks", "get_next_task", "create_task", "update_progress", 
          "complete_task", "add_subtask", "update_subtask", "add_note",
          "list_agents", "list_projects"
        ],
        "defaultArguments": {
          "agent_id": "agent_123",
          "project_name": ""
        }
      }
    }
}

Available MCP Tools

TaskMateAI provides the following MCP tools:

1. get_tasks - Get a list of tasks (can be filtered by status and priority)

2. get_next_task - Get the next high priority task (automatically updates to in progress status)

3. create_task - Create a new task (with subtasks)

4. update_progress - Updates the progress of a task

5. complete_task - Mark a task as complete

6. add_subtask - Add a subtask to an existing task

7. update_subtask - Update the status of a subtask

8. add_note - Add a note to a task

9. list_agents - Get a list of available agent IDs

10. list_projects - Get a list of projects related to a specific agent

Data Format

Tasks are managed using the following structure:

{
  "id": 1,
  "title": "タスクのタイトル",
  "description": "タスクの詳細な説明",
  "priority": 3,
  "status": "todo",  // "todo", "in_progress", "done" のいずれか
  "progress": 0,     // 0-100 の進捗率
  "subtasks": [
    {
      "id": 1,
      "description": "サブタスクの説明",
      "status": "todo"  // "todo", "in_progress", "done" のいずれか
    }
  ],
  "notes": [
    {
      "id": 1,
      "content": "ノートの内容",
      "timestamp": "2025-02-28T09:22:53.532808"
    }
  ]
}

Data Storage

Task data is stored in a hierarchical structure:

output/
├── tasks.json                  # デフォルトのタスクファイル
├── agent1/
│   ├── tasks.json              # agent1のタスクファイル
│   ├── project1/
│   │   └── tasks.json          # agent1のproject1のタスクファイル
│   └── project2/
│       └── tasks.json          # agent1のproject2のタスクファイル
└── agent2/
    ├── tasks.json              # agent2のタスクファイル
    └── projectA/
        └── tasks.json          # agent2のprojectAのタスクファイル

Each task file is automatically generated and updated when the application is run.

Managing agents and projects

To manage tasks for a specific agent or project, you can:

1. Specify a default agent in your MCP settings : By specifying agent_id in defaultArguments , it will be used automatically in all requests.

2. Specify projects in AI conversations : You can specify projects in the conversation, such as "Add a new task to project X."

3. Directly specified by AI : You can include agent_id and project_name in the request parameters.

Project Structure

TaskMateAI/
├── src/
│   └── TaskMateAI/
│       ├── __init__.py      # パッケージ初期化
│       └── __main__.py      # メインアプリケーションコード
├── output/                  # データ保存ディレクトリ
│   └── tasks.json           # タスクデータ (自動生成)
├── tests/                   # テストコード
│   ├── unit/                # ユニットテスト
│   └── integration/         # 統合テスト
├── requirements.txt         # 依存パッケージリスト
└── README.md                # このファイル

test

TaskMateAI provides a comprehensive test suite to ensure functionality reliability.

Test Configuration

The tests are organized in the following directory structure:

tests/
├── __init__.py           # テストパッケージの初期化
├── conftest.py           # テスト用フィクスチャの定義
├── unit/                 # ユニットテスト
│   ├── __init__.py
│   ├── test_task_utils.py       # タスク関連ユーティリティのテスト
│   ├── test_mcp_tools.py        # MCPツール機能のテスト
│   └── test_agent_projects.py   # エージェントとプロジェクト管理のテスト
└── integration/          # 統合テスト
    └── __init__.py

Test types

1. Unit testing : Ensures that individual components of an application function correctly

   • test_task_utils.py : Tests basic functions such as reading and writing tasks, and generating IDs.

   • test_mcp_tools.py : Tests the functionality of MCP tools (creating, updating, completing tasks, etc.)

   • test_agent_projects.py : Tests agent ID and project management functionality

2. Integration testing : Ensure that multiple components work together correctly (future expansion planned)

How to run the test

You can run the test using the following command:

1. Run all tests:

cd /path/to/TaskMateAI
uv run python -m pytest -xvs

2. Run a specific test file:

uv run python -m pytest -xvs tests/unit/test_task_utils.py

3. Run a specific test class:

uv run python -m pytest -xvs tests/unit/test_mcp_tools.py::TestMCPTools

4. Run a specific test function:

uv run python -m pytest -xvs tests/unit/test_task_utils.py::TestTaskUtils::test_read_tasks_with_data

Explanation of test arguments:

• -x : Stops testing when an error occurs

• -v : Display verbose output

• -s : Display standard output during testing

Items to be fixed

• Implementing the task template function

• Building a dependency management system between tasks

• Addition of schedule function

• Introducing a tag-based task classification system

• Implementing milestone management function

license

MIT

author

New AI Tees