Skip to content

heygen-com/mcp-shrimp-task-manager

BranchesTags
 
 

Repository files navigation

HeyGen Task Runner

English | 中文

Note—HeyGen Fork: This is a fork of the original cjo4m06/mcp-shrimp-task-manager repository, managed by Heygen and potentially containing custom modifications.

Semantic Project Naming (New)

When creating a new project, always use a semantically meaningful, human-readable, and searchable name for the project folder and files.

  • The folder name should reflect the project's purpose or domain (e.g., translation_project, market_data_lake, ui_kit_deprecation), not a random or opaque ID.
  • The project's main JSON file will be stored in this folder.
  • If a unique identifier is needed, it will be appended after the semantic name (e.g., translation_project_xxxxx).
  • This makes it easy to search, manage, and understand projects in the filesystem and UI.
  • If you attempt to open a project by name and there is no direct match, the system will now search all projects for a semantic match by name, tags, or description, and open the best match if found.
  • If multiple possible matches are found, you will be shown a list to choose from.

Example Structure:

data/
  projects/
    translation_project_xxxxx/
      project.json
      context/
      reports/
      tasks/
    market_data_lake_yyyyy/
      project.json
      ...

External Tracker Integration & Project Metadata (New)

Projects now support integration with external tracking systems (JIRA, GitHub Issues, Linear, etc.) and rich metadata for better project management.

External Tracker Support

When creating a project, you'll be prompted to associate it with an external tracker:

  • Supported Trackers: JIRA, GitHub, GitLab, Linear, Asana, Trello, Notion
  • Issue Types: Epic, Story, Task, Bug, Subtask (for JIRA)
  • Automatic Linking: Store issue keys and URLs for easy reference

Example:

project create --name "Translation System" --trackerType jira --trackerIssueKey "TRANS-100" --trackerIssueType epic

Project Metadata

Projects can now store comprehensive metadata:

  • People & Teams: Owner, assignees, team, stakeholders
  • Time & Planning: Start date, deadline, estimated/actual hours
  • Technical Details: Repository URL, branch, environment, version
  • Documentation: Links to docs, designs, meeting notes
  • Business Context: Budget, business value, KPIs
  • Risk Management: Identified risks, dependencies, blockers

Project Classification

  • Priority Levels: Critical, High, Medium, Low
  • Categories: Feature, Bugfix, Refactor, Research, Infrastructure, Documentation, Prototype, Migration

Benefits

  • Better Organization: Projects are connected to real-world work items
  • Team Collaboration: Clear ownership and responsibility
  • Time Management: Track deadlines and effort
  • Risk Visibility: Surface blockers and dependencies early
  • Business Alignment: Connect technical work to business goals

When listing projects, you'll see this information at a glance:

- Translation System (ID: translation_system_xxxxx) [HIGH] | jira: TRANS-100 | Owner: John Doe | Due: 2024-02-15 (30 days)

目錄

MCP Shrimp Task Manager

Shrimp Task Manager Demo

smithery badge

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

Shrimp Task Manager MCP server

Shrimp Task Manager guides Agents through structured workflows for systematic programming, enhancing task memory management mechanisms, and effectively avoiding redundant and repetitive coding work.

✨ Features

  • Task Planning and Analysis: Deep understanding and analysis of complex task requirements
  • Intelligent Task Decomposition: Automatically break down large tasks into manageable smaller tasks
  • Dependency Management: Precisely handle dependencies between tasks, ensuring correct execution order
  • Execution Status Tracking: Real-time monitoring of task execution progress and status
  • Task Completeness Verification: Ensure task results meet expected requirements
  • Task Complexity Assessment: Automatically evaluate task complexity and provide optimal handling suggestions
  • Automatic Task Summary Updates: Automatically generate summaries upon task completion, optimizing memory performance
  • Task Memory Function: Automatically backup task history, providing long-term memory and reference capabilities
  • Thought Chain Process: Step-by-step reasoning to analyze complex problems systematically
  • Project Rules Initialization: Define 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.
  • Pull Request Analysis: Analyze GitHub, GitLab, and Bitbucket pull requests to generate comprehensive markdown reports for tracking feature development
  • Developer Chat Tools:
    • consult_expert - Ask for help when stuck. Note: This uses the OpenAI API and requires an OPENAI_API_KEY environment variable.
    • translate_content - Context-aware translations with learning capabilities and agent-to-agent dialog support. See Translation Tool Guide for details.
    • retranslate_i18n - Automatically retranslate i18n JSON files from English to multiple languages. See i18n Retranslation Guide for details.
    • check_browser_logs - Fetch console logs from browser tabs (requires mcp-devtools-bridge)
    • list_browser_tabs - List monitored browser tabs (requires mcp-devtools-bridge)
    • analyze_pr - Analyze GitHub pull requests for code quality
    • github_pr_context - Fetch comprehensive GitHub PR context including metadata, changed files, unresolved review comments, and merge blockers. See GitHub PR Context Tool for details.
    • architecture_snapshot - Create comprehensive architecture documentation with smart detection of existing snapshots. See Architecture Snapshot Guide for details.

🧭 Usage Guide

Shrimp Task Manager offers a structured approach to AI-assisted programming through guided workflows and systematic task management.

What is Shrimp?

Shrimp is essentially a prompt template that guides AI Agents to better understand and work with your project. It uses a series of prompts to ensure the Agent aligns closely with your project's specific needs and conventions.

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.

🧠 Task Memory Function

Shrimp Task Manager has long-term memory capabilities, automatically saving task execution history and providing reference experiences when planning new tasks.

Key Features

  • The system automatically backs up tasks to the memory directory
  • Backup files are named in chronological order, in the format tasks_backup_YYYY-MM-DDThh-mm-ss.json
  • Task planning Agents automatically receive guidance on how to use the memory function

Advantages and Benefits

  • Avoid Duplicate Work: Reference past tasks, no need to solve similar problems from scratch
  • Learn from Successful Experiences: Utilize proven effective solutions, improve development efficiency
  • Learning and Improvement: Identify past mistakes or inefficient solutions, continuously optimize workflows
  • Knowledge Accumulation: Form a continuously expanding knowledge base as system usage increases

Through effective use of the task memory function, the system can continuously accumulate experience, with intelligence level and work efficiency continuously improving.

🤔 Thought Chain Process

The Thought Chain feature enhances problem-solving through structured thinking:

  • Systematic Reasoning: Break down complex problems into logical steps
  • Assumption Testing: Challenge assumptions to validate solution approaches
  • Critical Analysis: Evaluate solution options with rigorous criteria
  • Improved Decision Making: Reach more reliable conclusions through deliberate thinking

When enabled (default setting), the system guides the Agent through step-by-step reasoning using the process_thought tool, ensuring thorough problem analysis before implementation.

📋 Project Rules Initialization

The Project Rules feature helps maintain consistency across your codebase:

  • Standardize Development: Establish consistent coding patterns and practices
  • Onboard New Developers: Provide clear guidelines for project contributions
  • Maintain Quality: Ensure all code meets established project standards

⚠️ Recommendation: Initialize project rules when your project grows larger or undergoes significant changes. This helps maintain consistency and quality as complexity increases.

Use the init_project_rules tool to set up or update project standards when:

  • Starting a new large-scale project
  • Onboarding new team members
  • Implementing major architectural changes
  • Adopting new development conventions

Usage Examples

You can easily access this feature with simple natural language commands:

  • For initial setup: Simply tell the Agent "init rules" or "init project rules"
  • For updates: When your project evolves, tell the Agent "Update rules" or "Update project rules"

This tool is particularly valuable when your codebase expands or undergoes significant structural changes, helping maintain consistent development practices throughout the project lifecycle.

📚 Documentation Resources

🔧 Installation and Usage

Installing via Smithery

To install Shrimp Task Manager for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @cjo4m06/mcp-shrimp-task-manager --client claude

Manual Installation

# Install dependencies
npm install

# Build and start service
npm run build

🔌 Using with MCP-Compatible Clients

Shrimp Task Manager can be used with any client that supports the Model Context Protocol, such as Cursor IDE.

Configuration in Cursor IDE

Shrimp Task Manager offers two configuration methods: global configuration and project-specific configuration.

Global Configuration

  1. Open the Cursor IDE global configuration file (usually located at ~/.cursor/mcp.json)
  2. Add the following configuration in the mcpServers section:
{
  "mcpServers": {
    "shrimp-task-manager": {
      "command": "node",
      "args": ["/mcp-shrimp-task-manager/dist/index.js"],
      "env": {
        "DATA_DIR": "/path/to/project/data", // 必須使用絕對路徑
        "ENABLE_THOUGHT_CHAIN": "true",
        "TEMPLATES_USE": "en",
        "ENABLE_GUI": "false"
      }
    }
  }
}


or

{
  "mcpServers": {
    "shrimp-task-manager": {
      "command": "npx",
      "args": ["-y", "mcp-shrimp-task-manager"],
      "env": {
        "DATA_DIR": "/mcp-shrimp-task-manager/data",
        "ENABLE_THOUGHT_CHAIN": "true",
        "TEMPLATES_USE": "en",
        "ENABLE_GUI": "false"
      }
    }
  }
}

⚠️ Please replace /mcp-shrimp-task-manager with your actual path.

Project-Specific Configuration

You can also set up dedicated configurations for each project to use independent data directories for different projects:

  1. Create a .cursor directory in the project root
  2. Create an mcp.json file in this directory with the following content:
{
  "mcpServers": {
    "shrimp-task-manager": {
      "command": "node",
      "args": ["/path/to/mcp-shrimp-task-manager/dist/index.js"],
      "env": {
        "DATA_DIR": "/path/to/project/data", // Must use absolute path
        "ENABLE_THOUGHT_CHAIN": "true",
        "TEMPLATES_USE": "en",
        "ENABLE_GUI": "false"
      }
    }
  }
}


or

{
  "mcpServers": {
    "shrimp-task-manager": {
      "command": "npx",
      "args": ["-y", "mcp-shrimp-task-manager"],
      "env": {
        "DATA_DIR": "/path/to/project/data", // 必須使用絕對路徑
        "ENABLE_THOUGHT_CHAIN": "true",
        "TEMPLATES_USE": "en",
        "ENABLE_GUI": "false"
      }
    }
  }
}

⚠️ Important Configuration Notes

The DATA_DIR parameter is the directory where Shrimp Task Manager stores task data, conversation logs, and other information. Setting this parameter correctly is crucial for the normal operation of the system. This parameter must use an absolute path; using a relative path may cause the system to incorrectly locate the data directory, resulting in data loss or function failure.

Warning: Using relative paths may cause the following issues:

  • Data files not found, causing system initialization failure
  • Task status loss or inability to save correctly
  • Inconsistent application behavior across different environments
  • System crashes or failure to start

🔧 Environment Variable Configuration

Shrimp Task Manager supports customizing prompt behavior through environment variables, allowing you to fine-tune AI assistant responses without modifying code. You can set these variables in the configuration or through an .env file:

{
  "mcpServers": {
    "shrimp-task-manager": {
      "command": "node",
      "args": ["/path/to/mcp-shrimp-task-manager/dist/index.js"],
      "env": {
        "DATA_DIR": "/path/to/project/data",
        "MCP_PROMPT_PLAN_TASK": "Custom planning guidance...",
        "MCP_PROMPT_EXECUTE_TASK_APPEND": "Additional execution instructions...",
        "ENABLE_THOUGHT_CHAIN": "true",
        "TEMPLATES_USE": "en",
        "ENABLE_GUI": "false"
      }
    }
  }
}

There are two customization methods:

  • Override Mode (MCP_PROMPT_[FUNCTION_NAME]): Completely replace the default prompt
  • Append Mode (MCP_PROMPT_[FUNCTION_NAME]_APPEND): Add content to the existing prompt

Additionally, there are other system configuration variables:

  • DATA_DIR: Specifies the directory where task data is stored
  • ENABLE_THOUGHT_CHAIN: Controls the thinking model in task planning workflow. When set to true (default), the system guides users to use the process_thought tool for step-by-step reasoning. When set to false, the system directly uses analyze_task to submit analysis results, skipping the detailed thinking process.
  • TEMPLATES_USE: Specifies the template set to use for prompts. Defaults to en. Currently available options are en and zh. To use custom templates, copy the src/prompts/templates_en directory to the location specified by DATA_DIR, rename the copied directory (e.g., to my_templates), and set TEMPLATES_USE to the new directory name (e.g., my_templates).

For detailed instructions on customizing prompts, including supported parameters and examples, see the Prompt Customization Guide.

💡 System Prompt Guidance

Cursor IDE Configuration

You can enable Cursor Settings => Features => Custom modes, and configure the following two modes:

TaskPlanner Mode

You are a professional task planning expert. You must interact with users, analyze their needs, and collect project-related information. Finally, you must use "plan_task" to create tasks. When the task is created, you must summarize it and inform the user to use the "TaskExecutor" mode to execute the task.
You must focus on task planning. Do not use "execute_task" to execute tasks.
Serious warning: you are a task planning expert, you cannot modify the program code directly, you can only plan tasks, and you cannot modify the program code directly, you can only plan tasks.

TaskExecutor Mode

You are a professional task execution expert. When a user specifies a task to execute, use "execute_task" to execute the task.
If no task is specified, use "list_tasks" to find unexecuted tasks and execute them.
When the execution is completed, a summary must be given to inform the user of the conclusion.
You can only perform one task at a time, and when a task is completed, you are prohibited from performing the next task unless the user explicitly tells you to.
If the user requests "continuous mode", all tasks will be executed in sequence.

💡 Choose the appropriate mode based on your needs:

  • Use TaskPlanner mode when planning tasks
  • Use TaskExecutor mode when executing tasks

Using with Other Tools

If your tool doesn't support Custom modes, you can:

  • Manually paste the appropriate prompts at different stages
  • Or directly use simple commands like Please plan the following task: ...... or Please start executing the task...

🛠️ Available Tools Overview

After configuration, you can use the following tools:

Category Tool Name Description
Task Planning plan_task Start planning tasks
Task Analysis analyze_task In-depth analysis of task requirements
process_thought Step-by-step reasoning for complex problems
Solution Assessment reflect_task Reflect and improve solution concepts
Project Management init_project_rules Initialize or update project standards and rules
project Unified project management - create, update, delete, list, open projects
project_context Project context management - add, search, analyze, export, delete context entries
Task Management split_tasks Break tasks into subtasks
list_tasks Display all tasks and status
query_task Search and list tasks
get_task_detail Display complete task details
delete_task Delete incomplete tasks
Task Execution execute_task Execute specific tasks
verify_task Verify task completion
complete_task Mark tasks as completed
Code Analysis analyze_pr Analyze pull requests and generate reports
github_pr_context Fetch raw GitHub PR context without analysis
architecture_snapshot Create comprehensive architecture documentation
Debugging log_data_dir Log the path to the tasks.json file

Note on Custom Tools (Heygen Fork): This fork may include additional custom tools not present in the original repository. Currently, it includes:

  • log_data_dir: A debugging tool to log the absolute path being used for tasks.json based on the DATA_DIR configuration.
  • analyze_pr: Analyze pull requests from GitHub, GitLab, or Bitbucket to generate structured markdown reports with code quality assessments, issues, and recommendations.

🔧 Technical Implementation

  • Node.js: High-performance JavaScript runtime environment
  • TypeScript: Provides type-safe development environment
  • MCP SDK: Interface for seamless interaction with large language models
  • UUID: Generate unique and reliable task identifiers

📄 License

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

Recommended Models

For the best experience, we recommend using the following models:

  • Claude 3.7: Offers strong understanding and generation capabilities.
  • Gemini 2.5: Google's latest model, performs excellently.

Due to differences in training methods and understanding capabilities across models, using other models might lead to varying results for the same prompts. This project has been optimized for Claude 3.7 and Gemini 2.5.

Star History

Star History Chart

Features

  • Task Planning & Management: Break down complex problems into manageable tasks
  • Dependency Tracking: Automatically manage task dependencies
  • Complexity Assessment: Evaluate task difficulty to optimize execution
  • Flexible Task Updates: Modify task details, dependencies, and related files
  • Progress Tracking: Monitor task completion with detailed status updates
  • File Association: Link tasks to specific files and code sections
  • Search & Query: Find tasks quickly with powerful search capabilities
  • Batch Operations: Create, update, or clear multiple tasks at once
  • Smart Context Loading: Automatically load relevant files when executing tasks
  • Memory System: AI agents can record and retrieve important discoveries, decisions, and patterns

Task Tools

  • consult_expert: Get help from human experts when stuck on complex problems
  • process_thought: Engage in structured thinking to solve complex problems

Memory Tools

  • record_memory: Record breakthroughs, decisions, feedback, errors, patterns, or preferences
  • query_memory: Search memories by type, project, tags, or content
  • get_memory_chain: Find related memories and their connections
  • memory_maintenance: Archive old memories, update relevance scores, get statistics
  • memory_analytics: Generate insights and reports about memory usage
  • export_memories/import_memories: Backup and restore memory data
  • consolidate_memories: Merge similar memories to reduce duplication

Memory System

The memory system helps AI agents build long-term knowledge across sessions:

  • 6 Memory Types: Breakthroughs, Decisions, Feedback, Error Recovery, Patterns, User Preferences
  • Automatic Triggers: Memories are suggested when completing tasks with certain keywords
  • Project Integration: Memories are automatically loaded when opening projects
  • Relevance Decay: Unused memories gradually become less prominent (30-day half-life)
  • Duplicate Detection: Prevents recording the same insight multiple times
  • Memory Chains: Link related memories to track evolving understanding
  • Web Interface: Visual memory explorer at /memory-explorer.html (when GUI enabled)

See Memory System Guide for detailed usage.

About

Shrimp Task Manager is a task tool built for AI Agents, emphasizing chain-of-thought, reflection, and style consistency. It converts natural language into structured dev tasks with dependency tracking and iterative refinement, enabling agent-like developer behavior in reasoning AI systems.

cjo4m06.github.io/mcp-shrimp-task-manager/

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • TypeScript 83.2%
  • JavaScript 12.1%
  • HTML 3.5%
  • Other 1.2%