TAMA MCP

🚀 Tama-MCP

An AI-driven task management CLI tool with MCP server functionality

Contact me on WeChat:

🚀 Quick Start

Tama-MCP is an AI-based task management CLI tool that offers powerful task tracking, dependency management, and report generation capabilities. It also supports running as an MCP (Model Context Protocol) server, allowing other applications to interact with it through a programming interface.

✨ Features

• Task Management: Create, view, edit, and delete tasks and subtasks.
• Dependency Handling: Add and remove dependencies between tasks and automatically resolve dependency conflicts.
• Report Generation: Output task structure reports in Markdown or Mermaid chart format.
• AI-driven: Support parsing requirements from PRD files and automatically generating task breakdowns.
• MCP Server: Provide a RESTful API that allows other applications to interact with Tama-MCP.

📦 Installation

Install using pip

uv pip install .

Clone the repository

git clone https://github.com/yourusername/TAMA-MCP.git
cd TAMA-MCP
uv pip install .

💻 Usage Examples

Basic Usage

Create a new task

tama add_task "完成项目文档"

Add a subtask

tama add_subtask 1 --name "整理需求文档" --description "完成项目需求部分的编写"

Set task status

tama set_status 1 -s "已完成"

View task list

tama list_tasks --status "未完成"

Add a dependency

tama add_dependency 1 2 --description "任务 2 依赖于任务 1 的完成"

Advanced Usage

Generate a report

Markdown format

tama report markdown

Mermaid chart

tama report mermaid

Output to a file

tama report markdown --output report.md

Automatically generate placeholder files

tama gen-file 1 --output-dir src/generated

📚 Documentation

MCP Server Usage Instructions

Tama-MCP can run as an MCP server, providing the following functions:

• list_tasks: List all tasks, supporting filtering by status or priority.
• show_task: Display detailed information about a specific task.
• set_status: Update the task status and automatically propagate the changes.
• next_task: Find the next executable task.
• add_task: Create a new main task.
• add_subtask: Create a new subtask.
• remove_item: Delete a task or subtask and clean up dependencies.
• add_dependency: Add a dependency between tasks.
• remove_dependency: Remove a dependency between tasks.
• check_dependencies: Check for circular dependencies.

Start the server

uv --directory /path/to/your/TAMA_MCP run python -m src.mcp_server

Client configuration (example)

In your MCP client:

{
  "mcpServers": {
    "TAMA-MCP-Server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/TAMA_MCP",
        "run",
        "python",
        "-m",
        "src.mcp_server"
      ]
    }
  }
}

Frequently Asked Questions

How to resolve circular dependencies?

Tama-MCP provides the check_dependencies command to detect and handle circular dependencies, ensuring the rationality of task execution order.

tama check_dependencies

How to generate a Mermaid chart?

Run the following command to generate a task structure diagram in Mermaid format:

tama report mermaid > diagram.md

Contribution Guidelines

Welcome to contribute code! Please refer to the CONTRIBUTING file in the GitHub repository to learn how to participate in the development.

📄 License

Tama-MCP is licensed under the MIT license. See the LICENSE file for details.