mcp-shrimp-task-manager

# MCP Shrimp Task Manager

[![Shrimp Task Manager Demo](/docs/yt.png)](https://www.youtube.com/watch?v=Arzu0lV09so)

[![smithery badge](https://smithery.ai/badge/@cjo4m06/mcp-shrimp-task-manager)](https://smithery.ai/server/@cjo4m06/mcp-shrimp-task-manager)

> 🚀 An intelligent task management system based on the **Model Context Protocol (MCP)**, providing an efficient programming workflow framework for AI Agents.

<a href="https://glama.ai/mcp/servers/@cjo4m06/mcp-shrimp-task-manager">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@cjo4m06/mcp-shrimp-task-manager/badge" alt="Shrimp Task Manager MCP server" />
</a>

Shrimp Task Manager leverages the Model Context Protocol to guide Agents through structured workflows for systematic programming. It enhances task memory management, effectively avoiding redundant and repetitive coding.

**[English](README.md) | [中文](docs/zh/README.md)**

## Table of Contents

*   [✨ Features](#features)
*   [🧭 Usage Guide](#usage-guide)
*   [🔬 Research Mode](#research-mode)
*   [🧠 Task Memory Function](#task-memory-function)
*   [📋 Project Rules Initialization](#project-rules)
*   [🌐 Web GUI](#web-gui)
*   [🔌 Using with MCP-Compatible Clients](#clients)
    *   [ListRoots Protocol Support](#listroots-support)
    *   [Configuration in Cursor IDE](#configuration-cursor-ide)
        *   [Global Configuration](#global-configuration)
        *   [Project-Specific Configuration](#project-specific-configuration)
    *   [Important Configuration Notes](#important-configuration-notes)
    *   [Environment Variable Configuration](#environment-variable-configuration)
*   [💡 System Prompt Guidance](#prompt)
*   [🛠️ Available Tools Overview](#tools)
*   [📚 Documentation Resources](#documentation)
*   [🔧 Installation and Usage](#installation)
*   [📄 License](#license)
*   [🤖 Recommended Models](#recommended)
*   [Star History](#star-history)

## ✨ Features <a id="features"></a>

*   **Task Planning and Analysis:** Deep understanding and analysis of complex task requirements.
*   **Intelligent Task Decomposition:** Automatically breaks down large tasks into manageable smaller tasks.
*   **Dependency Management:** Precisely handles dependencies between tasks, ensuring correct execution order.
*   **Execution Status Tracking:** Real-time monitoring of task execution progress and status.
*   **Task Completeness Verification:** Ensures task results meet expected requirements.
*   **Task Complexity Assessment:** Automatically evaluates task complexity and provides optimal handling suggestions.
*   **Automatic Task Summary Updates:** Automatically generates summaries upon task completion, optimizing memory performance.
*   **Task Memory Function:** Automatically backs up task history, providing long-term memory and reference capabilities.
*   **Research Mode:** Systematic technical research capabilities with guided workflows for exploring technologies, best practices, and solution comparisons.
*   **Project Rules Initialization:** Defines project standards and rules to maintain consistency across large projects.
*   **Web GUI:** Provides an optional web-based graphical user interface for task management. Enable by setting `ENABLE_GUI=true` in your `.env` file. When enabled, a `WebGUI.md` file containing the access address will be created in your `DATA_DIR`. You can customize the web port by setting `WEB_PORT` (if not specified, an available port will be automatically selected).

## 🧭 Usage Guide <a id="usage-guide"></a>

Shrimp Task Manager offers a structured approach to AI-assisted programming through guided workflows and systematic task management, all powered by the Model Context Protocol (MCP).

### What is Shrimp?

Shrimp is a prompt template system designed to guide AI Agents to better understand and work with your project within the MCP framework. It uses a series of prompts to ensure the Agent aligns closely with your project's specific needs and conventions.

### Research Mode in Practice

Before diving into task planning, you can leverage the research mode for technical investigation and knowledge gathering. This is particularly useful when:

*   You need to explore new technologies or frameworks.
*   You want to compare different solution approaches.
*   You're investigating best practices for your project.
*   You need to understand complex technical concepts.

Simply tell the Agent "research [your topic]" or "enter research mode for [technology/problem]" to begin systematic investigation. The research findings will then inform your subsequent task planning and development decisions.

### First-Time Setup

When working with a new project, simply tell the Agent "init project rules". This will guide the Agent to generate a set of rules tailored to your project's specific requirements and structure.

### Task Planning Process

To develop or update features, use the command "plan task [your description]". The system will reference the previously established rules, attempt to understand your project, search for relevant code sections, and propose a comprehensive plan based on the current state of your project.

### Feedback Mechanism

During the planning process, Shrimp guides the Agent through multiple steps of thinking. You can review this process and provide feedback if you feel it's heading in the wrong direction. Simply interrupt and share your perspective - the Agent will incorporate your feedback and continue the planning process.

### Task Execution

When you're satisfied with the plan, use "execute task [task name or ID]" to implement it. If you don't specify a task name or ID, the system will automatically identify and execute the highest priority task.

### Continuous Mode

If you prefer to execute all tasks in sequence without manual intervention for each task, use "continuous mode" to automatically process the entire task queue.

### Token Limitation Note

Due to LLM token limits, context may be lost during lengthy conversations. If this occurs, simply open a new chat session and ask the Agent to continue execution. The system will pick up where it left off without requiring you to repeat the task details or context.

### Prompt Language and Customization

You can switch the language of system prompts by setting the `TEMPLATES_USE` environment variable. It supports `en` (English) and `zh` (Traditional Chinese) by default. Furthermore, you can copy an existing template directory (e.g., `src/prompts/templates_en`) to the location specified by `DATA_DIR`, modify it, and then point `TEMPLATES_USE` to your custom template directory name. This allows for deeper prompt customization. For detailed instructions, see the [Prompt Customization Guide](docs/en/prompt-customization.md).

## 🔬 Research Mode <a id="research-mode"></a>

Shrimp Task Manager includes a specialized research mode designed for systematic technical investigation and knowledge gathering, fully integrated with the Model Context Protocol.

### What is Research Mode?

Research Mode is a guided workflow system that helps AI Agents conduct thorough and systematic technical research. It provides structured approaches to exploring technologies, comparing solutions, investigating best practices, and gathering comprehensive information for programming tasks, all within the context of MCP.

### Key Features

*   **Systematic Investigation:** Structured workflows ensure comprehensive coverage of research topics.
*   **Multi-Source Research:** Combines web search and codebase analysis for complete understanding.
*   **State Management:** Maintains research context and progress across multiple sessions.
*   **Guided Exploration:** Prevents research from becoming unfocused or going off-topic.
*   **Knowledge Integration:** Seamlessly integrates research findings with task planning and execution.

### When to Use Research Mode

Research Mode is particularly valuable for:

*   **Technology Exploration:** Investigating new frameworks, libraries, or tools.
*   **Best Practices Research:** Finding industry standards and recommended approaches.
*   **Solution Comparison:** Evaluating different technical approaches or architectures.
*   **Problem Investigation:** Deep-diving into complex technical challenges.
*   **Architecture Planning:** Researching design patterns and system architectures.

### How to Use Research Mode

Simply tell the Agent to enter research mode with your topic:

*   **Basic usage:** "Enter research mode for [your topic]"
*   **Specific research:** "Research [specific technology/problem]"
*   **Comparative analysis:** "Research and compare [options A vs B]"

The system will guide the Agent through structured research phases, ensuring thorough investigation while maintaining focus on your specific needs.

### Research Workflow

1.  **Topic Definition:** Clearly define the research scope and objectives.
2.  **Information Gathering:** Systematic collection of relevant information.
3.  **Analysis and Synthesis:** Processing and organizing findings.
4.  **State Updates:** Regular progress tracking and context preservation.
5.  **Integration:** Applying research results to your project context.

> **💡 Recommendation:** For the best research mode experience, we recommend using **Claude 4 Sonnet**, which provides exceptional analytical capabilities and comprehensive research synthesis.

## 🧠 Task Memory Function <a id="task-memory-function"></a>

Shrimp Task Manager has long-term memory capabilities, automatically saving task execution history and providing reference experiences when planning new tasks. This leverages the MCP to maintain context across sessions.

### Key Features

*   The system automatically backs up tasks to the memory directory.
*