repository·main·Indexed 42 days ago
https://github.com/kazuph/mcp-taskmanagerA Model Context Protocol (MCP) server for task management that enables Claude Desktop and other MCP clients to manage and execute tasks using a queue-based system. It supports a structured workflow consisting of planning, execution, and completion phases, requiring explicit user approval between tasks to ensure oversight.
The TaskManager operates in two distinct phases to manage a queue-based task system:
Used to initialize the queue. It accepts a list of tasks and returns an execution plan including a task overview, a unique taskId, and the current queue status.
Used to progress through the queue. It allows requesting the next task, receiving feedback on task completion, and removing completed tasks to prepare for the next step.
If you are developing or modifying the MCP TaskManager, you can run the server directly from the source using tsx.
tsx globally: npm install -g tsx.{
"tools": {
"taskmanager": {
"args": ["tsx", "/path/to/mcp-taskmanager/index.ts"]
}
}
}To use MCP TaskManager with Claude Desktop, ensure you have Node.js 18+ installed. Add the server to your Claude Desktop configuration file located at ~/Library/Application Support/Claude/claude_desktop_config.json.
{
"tools": {
"taskmanager": {
"command": "npx",
"args": ["-y", "@kazuph/mcp-taskmanager"]
}
}
}The MCP TaskManager follows a strict lifecycle designed to ensure user oversight during complex requests. An assistant should follow these steps:
request_planning to register a new user request and its associated tasks.get_next_task to retrieve the first pending task.mark_task_done to record its completion.approve_task_completion for that specific task.get_next_task again to fetch the next pending task. Repeat until all tasks are done.get_next_task indicates all_tasks_done, the assistant must wait for the user to call approve_request_completion to finalize the entire request.If the user is unsatisfied at any stage, they can use request_planning to add more tasks to the existing request or update_task to modify pending ones.
Below are examples of the JSON payloads used for the different phases of the TaskManager lifecycle.
// Planning phase
{
"action": "plan",
"tasks": ["Task 1", "Task 2", "Task 3"]
}
// Execution phase
{
"action": "execute",
"getNext": true
}
// Complete task
{
"action": "complete",
"taskId": "task-123"
}The server stores task data in a JSON file. By default, it uses ~/Documents/tasks.json. You can override this location by setting the TASK_MANAGER_FILE_PATH environment variable.
Default Path: path.join(os.homedir(), "Documents", "tasks.json")
The TaskManager uses an action parameter to determine the operation mode. Depending on the action, specific parameters are required:
| Parameter | Type | Description |
|---|---|---|
action | "plan" | "execute" |
tasks | Array<string> | Required when action is "plan". A list of task descriptions. |
taskId | string | Required when action is "complete". The identifier for the task being finished. |
getNext | boolean | Used when action is "execute" to request the next task in the queue. |
Use request_planning to initiate a new workflow. This tool creates a unique requestId (e.g., req-1) and generates unique taskIds for each task provided (e.g., task-1).
// Example tool call arguments
{
"originalRequest": "Setup a new development environment",
"tasks": [
{ "title": "Install Node.js", "description": "Download and install the latest LTS version" },
{ "title": "Configure Git", "description": "Set up user name and email" }
]
}The following tools are available for managing requests and tasks. All tool responses return a JSON object containing status information and often a Markdown progress table.
### Core Workflow Tools
- `request_planning`: Register a new user request and plan its associated tasks.
- Arguments: `originalRequest` (string), `tasks` (array of `{title, description}`), `splitDetails` (optional string).
- `get_next_task`: Retrieve the next pending task for a `requestId`.
- Arguments: `requestId` (string).
- `mark_task_done`: Mark a specific task as done.
- Arguments: `requestId` (string), `taskId` (string), `completedDetails` (optional string).
- `approve_task_completion`: User-driven tool to approve a completed task.
- Arguments: `requestId` (string), `taskId` (string).
- `approve_request_completion`: User-driven tool to finalize an entire request after all tasks are approved.
- Arguments: `requestId` (string).
### Management & Inspection Tools
- `list_requests`: List all requests and their summaries.
- Arguments: `{}`
- `open_task_details`: Inspect details of a specific task.
- Arguments: `taskId` (string).
- `add_tasks_to_request`: Extend an existing request with new tasks.
- Arguments: `requestId` (string), `tasks` (array of `{title, description}`).
- `update_task`: Modify the title or description of an uncompleted task.
- Arguments: `requestId` (string), `taskId` (string), `title` (optional string), `description` (optional string).
- `delete_task`: Remove an uncompleted task.
- Arguments: `requestId` (string), `taskId` (string).