### NPX Quick Start Configuration

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

Add this configuration to your Cursor or Claude Desktop settings for quick setup using NPX.

```json
{
  "mcpServers": {
    "mcp-tasks": {
      "command": "npx",
      "args": ["-y", "mcp-tasks"]
    }
  }
}
```

--------------------------------

### MCP Tasks CLI Setup and Task Management

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

Provides examples for setting up a task file, adding, searching, and updating tasks using the mcp-tasks command-line interface.

```bash
# Setup a task file
mcp-tasks setup tasks.md $PWD                      # Setup with workspace
```

```bash
# Add tasks
mcp-tasks add "Implement authentication"           # Defaults to "To Do" status
mcp-tasks add "Write tests" "Backlog"              # Add with specific status
mcp-tasks add "Fix critical bug" "In Progress" 0   # Add at top (index 0)
```

```bash
# Search tasks
mcp-tasks search                                    # All tasks
mcp-tasks search "" "auth,login"                   # Search for specific terms
mcp-tasks search "To Do,Done" ""                   # Filter by statuses
mcp-tasks search "In Progress" "bug"               # Filter by status and search terms
```

```bash
# Update task status (comma-separated IDs)
mcp-tasks update m3Qw,p9Lx Done
```

```bash
# Get summary
mcp-tasks summary
```

```bash
# Add a reminder (feature must be enabled with REMINDERS=true)
mcp-tasks add "Don't move to Done until you verified it works" Reminders
```

--------------------------------

### MCP Tasks Development Setup and Execution

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

Instructions for cloning the repository, installing dependencies, and running the tool in development mode with auto-restart.

```bash
# Clone and setup
git clone https://github.com/flesler/mcp-tasks
cd mcp-tasks
npm install
```

```bash
# Development mode (auto-restart)
npm run dev              # STDIO transport
npm run dev:http         # HTTP transport on port 4680
```

```bash
# Build and test
npm run build           # Compile TypeScript
npm run lint            # Check code style
npm run lint:full       # Build + lint
```

--------------------------------

### Install and Run Development Commands

Source: https://context7.com/flesler/mcp-tasks/llms.txt

Standard npm commands for cloning the repository, installing dependencies, running development servers (stdio or HTTP), linting, and executing test suites.

```bash
# Clone and install
git clone https://github.com/flesler/mcp-tasks
cd mcp-tasks
npm install

# Development (auto-rebuild + restart)
npm run dev          # stdio
npm run dev:http     # HTTP on port 4680

# Type-check + lint
npm run lint:full

# Run the full test suite (all 3 formats, error conditions, search, Notes/Reminders)
npm test

# Full release validation (clean build + lint + test + pack check)
npm run test:full

# Inspect tools interactively via fastmcp
npm run inspect

```

--------------------------------

### Docker Quick Start Configuration

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

Configure your settings to use MCP Tasks via Docker for a containerized environment.

```json
{
  "mcpServers": {
    "mcp-tasks": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "flesler/mcp-tasks"
      ]
    }
  }
}
```

--------------------------------

### HTTP Transport Server Start

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

Command to start the mcp-tasks server using HTTP transport on a specified port.

```bash
TRANSPORT=http PORT=4680 npx mcp-tasks
```

--------------------------------

### MCP Tasks Server Usage Examples

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

Demonstrates various ways to run the mcp-tasks server, including default stdio transport, HTTP transport, and custom configurations.

```bash
# Show help
mcp-tasks --help
```

```bash
# Default: stdio transport
mcp-tasks
```

```bash
# HTTP transport
TRANSPORT=http mcp-tasks
TRANSPORT=http PORT=8080 mcp-tasks
```

```bash
# Custom configuration
STATUS_WIP="Working" AUTO_WIP=false mcp-tasks
```

--------------------------------

### Full Configuration with Custom Environment

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

Example of a comprehensive mcp-tasks configuration, including custom environment variables for status management and operational behavior.

```json
{
  "mcpServers": {
    "mcp-tasks": {
      "command": "npx",
      "args": ["-y", "mcp-tasks"],
      "env": {
        "STATUS_WIP": "In Progress",
        "STATUS_TODO": "To Do",
        "STATUS_DONE": "Done",
        "STATUS_REMINDERS": "Reminders",
        "STATUS_NOTES": "Notes",
        "STATUSES": "In Progress,To Do,Done,Backlog,Reminders,Notes",
        "AUTO_WIP": "true",
        "PREFIX_TOOLS": "true",
        "KEEP_DELETED": "true",
        "TRANSPORT": "stdio",
        "PORT": "4680",
        "INSTRUCTIONS": "Use mcp-tasks tools when the user mentions new or updated tasks"
      }
    }
  }
}
```

--------------------------------

### AI Integration Prompt Example

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

Use this prompt to instruct AI to manage tasks using mcp-tasks tools in a specified file.

```text
Use mcp-tasks tools to track our work in path/to/tasks.md
```

--------------------------------

### CLI Add Task Example

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

Safely add new tasks from a separate terminal using the mcp-tasks CLI.

```bash
npx mcp-tasks add "Your new task text" "To Do" 0
```

--------------------------------

### HTTP Transport Server Configuration

Source: https://context7.com/flesler/mcp-tasks/llms.txt

Start the mcp-tasks server with HTTP transport enabled and then configure your client to connect to the specified URL. This is useful for remote or multi-client setups.

```bash
TRANSPORT=http PORT=4680 npx mcp-tasks
```

```json
{
  "mcpServers": {
    "mcp-tasks": {
      "type": "streamableHttp",
      "url": "http://localhost:4680/mcp"
    }
  }
}
```

--------------------------------

### Docker Server Configuration

Source: https://context7.com/flesler/mcp-tasks/llms.txt

Configure mcp-tasks server using Docker by adding this JSON to your client configuration. This setup runs the mcp-tasks image directly.

```json
{
  "mcpServers": {
    "mcp-tasks": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "flesler/mcp-tasks"]
    }
  }
}
```

--------------------------------

### CLI Commands for MCP Tasks

Source: https://context7.com/flesler/mcp-tasks/llms.txt

The `mcp-tasks` CLI allows manual task management without race conditions. Use it for setup, adding, searching, updating, and summarizing tasks.

```bash
# Setup a task file (prints JSON with sourceId)
mcp-tasks setup tasks.md $PWD

# Add tasks (defaults to "To Do" status)
mcp-tasks add "Implement authentication"
mcp-tasks add "Write tests" "Backlog"
mcp-tasks add "Fix critical bug" "In Progress" 0   # index 0 = top of list

# Search (first arg = comma-separated statuses, second = comma-separated terms)
mcp-tasks search                                    # all tasks
mcp-tasks search "" "auth,login"                   # text search
mcp-tasks search "To Do,Done" ""                   # filter by statuses
mcp-tasks search "In Progress" "bug"               # status + text

# Update (comma-separated IDs)
mcp-tasks update m3Qw,p9Lx Done
mcp-tasks update xZ2b Deleted

# Get counts
mcp-tasks summary
```

--------------------------------

### Get Task Summary with tasks_summary

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

Use `tasks_summary` to retrieve counts of tasks by status and a list of tasks currently in progress.

```javascript
tasks_summary({
  source_id: "xK8p"         // From setup response
})
// Returns: {"source":{"id":"xK8p","path":"/absolute/path/to/tasks.md"},"Backlog":0,"To Do":0,"In Progress":1,"Done":2,"inProgress":[{"id":"r7Km","text":"Fix critical bug","status":"In Progress","index":0}]}
```

--------------------------------

### Custom Workflow with Renamed Statuses

Source: https://context7.com/flesler/mcp-tasks/llms.txt

Run mcp-tasks with custom environment variables to define your own status labels and workflow behavior. This example renames statuses and disables auto-WIP.

```bash
# Custom workflow with renamed statuses
STATUS_WIP="Working" \
STATUS_TODO="Pending" \
STATUS_DONE="Closed" \
STATUSES="Working,Pending,Closed,Waiting,Review" \
AUTO_WIP=false \
npx mcp-tasks
```

--------------------------------

### Get Task Status Counts with tasks_summary

Source: https://context7.com/flesler/mcp-tasks/llms.txt

Use `tasks_summary` to retrieve counts for each task status, the list of in-progress tasks, and reminders. This is redundant if called immediately after `tasks_add` or `tasks_update` as they return the same payload.

```javascript
tasks_summary({ source_id: "xK8p" })

// Response
{
  "source": { "id": "xK8p", "path": "/Users/alice/project/tasks.md" },
  "In Progress": 1,
  "To Do": 3,
  "Backlog": 2,
  "Done": 5,
  "Reminders": 2,
  "Notes": 1,
  "Deleted": 0,
  "total": 14,
  "inProgress": [
    { "id": "r7Km", "text": "Fix critical bug", "status": "In Progress", "index": 0 }
  ],
  "reminders": [
    { "id": "aB3c", "text": "Don't move to Done until verified", "status": "Reminders", "index": 0 },
    { "id": "dE4f", "text": "Commit changes with task name as message", "status": "Reminders", "index": 1 }
  ]
}

// CLI equivalent
mcp-tasks summary
```

--------------------------------

### Initialize Task File with tasks_setup

Source: https://context7.com/flesler/mcp-tasks/llms.txt

Use the `tasks_setup` tool to register a task file and obtain a `source_id`. This must be called once per conversation session. The tool creates the file if it doesn't exist and returns the file path and current task counts.

```javascript
// MCP tool call
tasks_setup({
  source_path: "tasks.md",        // relative (requires workspace) or absolute
  workspace: "/Users/alice/project"
})

// Response
{
  "source": { "id": "xK8p", "path": "/Users/alice/project/tasks.md" },
  "In Progress": 0,
  "To Do": 0,
  "Backlog": 0,
  "Done": 0,
  "Reminders": 0,
  "Notes": 0,
  "Deleted": 0,
  "total": 0,
  "inProgress": [],
  "instructions": "Use mcp-tasks tools when the user mentions new or updated tasks"
}

// CLI equivalent
mcp-tasks setup tasks.md /Users/alice/project
```

--------------------------------

### Initialize Task File with tasks_setup

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

Use `tasks_setup` to initialize a task file. It supports Markdown, JSON, and YAML formats. The function returns a source object with an ID used for subsequent operations.

```javascript
tasks_setup({
  workspace: "/path/to/project",
  source_path: "tasks.md"  // relative to workspace or absolute
  // source_path: "tasks.json"
  // source_path: "tasks.yml"
})
// Returns: {"source":{"id":"xK8p","path":"/path/to/project/tasks.md"},"Backlog":0,"To Do":0,"In Progress":0,"Done":0,"inProgress":[]}
// Source ID (4-char alphanumeric) is used for all subsequent operations
```

--------------------------------

### tasks_setup

Source: https://context7.com/flesler/mcp-tasks/llms.txt

Initializes a task file and returns a source_id for subsequent operations. This function must be called once per conversation session.

```APIDOC
## tasks_setup — Initialize a Task File

Registers a task file path and returns the `source_id` (a stable 4-character alphanumeric hash) needed for all subsequent calls. Creates the file if it does not exist. Must be called once per conversation session.

### Method

Not applicable (Tool Call)

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

- **source_path** (string) - Required - The path to the task file (relative or absolute).
- **workspace** (string) - Optional - The workspace directory.

### Request Example

```javascript
tasks_setup({
  source_path: "tasks.md",
  workspace: "/Users/alice/project"
})
```

### Response

#### Success Response (200)

- **source** (object) - Contains the `id` and `path` of the registered source.
  - **id** (string) - The stable 4-character alphanumeric hash.
  - **path** (string) - The absolute path to the task file.
- **[Status Count]** (integer) - The number of tasks in each status bucket (e.g., `In Progress`, `To Do`, `Backlog`, `Done`, `Reminders`, `Notes`, `Deleted`).
- **total** (integer) - The total number of tasks.
- **inProgress** (array) - A list of tasks currently in progress.
- **instructions** (string) - The instruction string injected into every tool response.

#### Response Example

```json
{
  "source": { "id": "xK8p", "path": "/Users/alice/project/tasks.md" },
  "In Progress": 0,
  "To Do": 0,
  "Backlog": 0,
  "Done": 0,
  "Reminders": 0,
  "Notes": 0,
  "Deleted": 0,
  "total": 0,
  "inProgress": [],
  "instructions": "Use mcp-tasks tools when the user mentions new or updated tasks"
}
```

### CLI Equivalent

```bash
mcp-tasks setup tasks.md /Users/alice/project
```
```

--------------------------------

### CLI equivalent for `tasks_add`

Source: https://context7.com/flesler/mcp-tasks/llms.txt

The command-line interface equivalent for adding a single task.

```bash
// CLI equivalent (single task)
mcp-tasks add "Fix critical login bug" "To Do" 0
```

--------------------------------

### CLI equivalent for `tasks_search`

Source: https://context7.com/flesler/mcp-tasks/llms.txt

The command-line interface equivalent for searching tasks.

```bash
// CLI equivalent
mcp-tasks search "To Do" "auth,login"
```

--------------------------------

### NPX Server Configuration for Cursor/Claude Desktop

Source: https://context7.com/flesler/mcp-tasks/llms.txt

Configure mcp-tasks server using NPX by adding this JSON to your Cursor or Claude Desktop configuration file. Environment variables can customize status labels, auto-WIP behavior, and tool prefixes.

```json
{
  "mcpServers": {
    "mcp-tasks": {
      "command": "npx",
      "args": ["-y", "mcp-tasks"],
      "env": {
        "STATUS_WIP": "In Progress",
        "STATUS_TODO": "To Do",
        "STATUS_DONE": "Done",
        "STATUSES": "In Progress,To Do,Done,Backlog",
        "AUTO_WIP": "true",
        "KEEP_DELETED": "true",
        "PREFIX_TOOLS": "true",
        "INSTRUCTIONS": "Use mcp-tasks tools when the user mentions new or updated tasks"
      }
    }
  }
}
```

--------------------------------

### YAML Task File Format

Source: https://context7.com/flesler/mcp-tasks/llms.txt

A configuration-friendly YAML format for tasks, mirroring the structure of the JSON format.

```yaml
groups:
  In Progress:
    - Implement authentication flow
  To Do:
    - Write unit tests
    - Update API documentation
  Backlog:
    - Plan v2 features
  Done:
    - Set up project repository
    - Configure CI/CD pipeline
  Reminders:
    - Don't move to Done until verified
```

--------------------------------

### Register and Require Sources

Source: https://context7.com/flesler/mcp-tasks/llms.txt

Sources (task files) are managed via a JSON registry. The `register` function stores source path and workspace, returning a Source object with an ID. `require` retrieves a source by ID or defaults to the most recent in a given workspace.

```typescript
// src/sources.ts — register() stores {path, workspace} and returns a Source
const source = sources.register("tasks.md", "/Users/alice/project")
// → { id: "xK8p", path: "/Users/alice/project/tasks.md", workspace: "/Users/alice/project" }

// require() resolves by ID or falls back to most recent in workspace
const source = sources.require("xK8p")
const source = sources.require(undefined, "/Users/alice/project")  // most recent

// sources.json contents (multiple registered files)
[
  { "path": "/Users/alice/project/tasks.md",    "workspace": "/Users/alice/project" },
  { "path": "/Users/alice/project/backlog.yml", "workspace": "/Users/alice/project" }
]

```

--------------------------------

### AI Integration - Triggering mcp-tasks

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

Append this to your prompt to signal the AI to use mcp-tasks when dealing with new or updated tasks.

```text
use mcp-tasks
```

--------------------------------

### Add Tasks in Batch with `tasks_add`

Source: https://context7.com/flesler/mcp-tasks/llms.txt

Use `tasks_add` to add one or more tasks. It prevents duplicates and supports automatic WIP management and positional insertion. The response includes details of added tasks.

```javascript
// Add multiple tasks at once (batch is cheaper)
tasks_add({
  source_id: "xK8p",
  texts: ["Implement authentication", "Write unit tests", "Update API docs"],
  status: "To Do"
})
```

```javascript
// Insert at top of To Do so it's the next task picked up
tasks_add({
  source_id: "xK8p",
  texts: ["Fix critical login bug"],
  status: "To Do",
  index: 0
})
```

```javascript
// Move a task directly to In Progress (AUTO_WIP pushes others out)
tasks_add({
  source_id: "xK8p",
  texts: ["Deploy hotfix to production"],
  status: "In Progress"
})
```

```javascript
// Response (same shape as tasks_summary)
{
  "source": { "id": "xK8p", "path": "/Users/alice/project/tasks.md" },
  "In Progress": 1,
  "To Do": 3,
  "Backlog": 0,
  "Done": 0,
  "total": 4,
  "added": [
    { "id": "m3Qw", "text": "Deploy hotfix to production", "status": "In Progress", "index": 0 }
  ],
  "inProgress": [
    { "id": "m3Qw", "text": "Deploy hotfix to production", "status": "In Progress", "index": 0 }
  ]
}
```

--------------------------------

### YAML Data Structure for Tasks

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

Configuration-friendly representation of task groups and their associated tasks in YAML format. Suitable for configuration files.

```yaml
groups:
  "In Progress":
    - Write user registration
  "To Do":
    - Implement authentication
    - Set up CI/CD pipeline
  Backlog:
    - Plan architecture
    - Design database schema
  Done:
    - Set up project structure
    - Initialize repository
  Reminders:
    - Don't move to Done until you verified it works
    - After you move to Done, commit all the changes, use the task name as the commit message
```

--------------------------------

### HTTP Transport Client Configuration

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

Client-side configuration to connect to a remotely running mcp-tasks server via HTTP.

```json
{
  "mcpServers": {
    "mcp-tasks": {
      "type": "streamableHttp",
      "url": "http://localhost:4680/mcp"
    }
  }
}
```

--------------------------------

### Markdown Task File Format

Source: https://context7.com/flesler/mcp-tasks/llms.txt

The recommended Markdown format uses `##` headers for status groups and `- [ ]` or `- [x]` for tasks. Lines before the first header default to 'To Do'. Notes and Reminders are written without checkboxes.

```markdown
# Tasks - My Project

## In Progress
- [ ] Implement authentication flow

## To Do
- [ ] Write unit tests
- [ ] Update API documentation

## Backlog
- [ ] Plan v2 features

## Done
- [x] Set up project repository
- [x] Configure CI/CD pipeline

## Reminders
- Don't move to Done until verified in staging
- Commit with task name as commit message

## Notes
- Team prefers JWT over sessions
```

--------------------------------

### CLI equivalent for `tasks_update`

Source: https://context7.com/flesler/mcp-tasks/llms.txt

The command-line interface equivalent for updating tasks.

```bash
// CLI equivalent
mcp-tasks update m3Qw,p9Lx Done
```

--------------------------------

### AUTO_WIP Behavior with tasks_add and tasks_update

Source: https://context7.com/flesler/mcp-tasks/llms.txt

When `AUTO_WIP` is true (default), the server enforces a single active task. Adding to 'To Do' moves the first task to 'In Progress'. Completing the 'In Progress' task promotes the next 'To Do' task. Adding directly to 'In Progress' pushes existing WIP tasks to 'To Do'. Disable by setting `AUTO_WIP=false`.

```javascript
// Initial state: To Do has ["Task A", "Task B", "Task C"], In Progress is empty

// Adding "Task A" to To Do triggers AUTO_WIP → moves Task A to In Progress
tasks_add({ source_id: "xK8p", texts: ["Task A"], status: "To Do" })
// Result: In Progress: ["Task A"], To Do: ["Task B", "Task C"]

// Completing the WIP task promotes the next To Do automatically
tasks_update({ source_id: "xK8p", ids: ["taskA_id"], status: "Done" })
// Result: In Progress: ["Task B"], To Do: ["Task C"], Done: ["Task A"]

// Adding directly to In Progress pushes existing WIP tasks to To Do
tasks_add({ source_id: "xK8p", texts: ["Urgent fix"], status: "In Progress" })
// Result: In Progress: ["Urgent fix"], To Do: ["Task B", "Task C"], Done: ["Task A"]

// Disable for manual control
// Set AUTO_WIP=false in environment
```

--------------------------------

### JSON Task File Format

Source: https://context7.com/flesler/mcp-tasks/llms.txt

A structured JSON format for tasks, organizing them into groups based on their status.

```json
{
  "groups": {
    "In Progress": ["Implement authentication flow"],
    "To Do": ["Write unit tests", "Update API documentation"],
    "Backlog": ["Plan v2 features"],
    "Done": ["Set up project repository", "Configure CI/CD pipeline"],
    "Reminders": ["Don't move to Done until verified"],
    "Notes": ["Team prefers JWT over sessions"],
    "Deleted": []
  }
}
```

--------------------------------

### Configure Custom Workflow Statuses

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

This JSON configuration allows customization of workflow statuses, including the names for WIP, ToDo, and Done states, and disabling auto-WIP functionality.

```json
{
  "env": {
    "STATUSES": "WIP,Pending,Archived,Done,To Review",
    "STATUS_WIP": "WIP",
    "STATUS_TODO": "Pending",
    "AUTO_WIP": "false"
  }
}
```

--------------------------------

### Add Tasks with tasks_add

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

Use `tasks_add` to add new tasks to a specified status in a task file. You can optionally specify the index to insert the tasks.

```javascript
tasks_add({
  source_id: "xK8p", // From setup response
  texts: ["Implement authentication", "Write tests"],
  status: "To Do",
  index: 0  // Add at top (optional)
})
// Returns: {"source":{"id":"xK8p","path":"/absolute/path/to/tasks.md"},"Backlog":0,"To Do":2,"In Progress":0,"Done":0,"inProgress":[],"tasks":[{"id":"m3Qw","text":"Implement authentication","status":"To Do","index":0},{"id":"p9Lx","text":"Write tests","status":"To Do","index":1}]}
```

--------------------------------

### tasks_add

Source: https://context7.com/flesler/mcp-tasks/llms.txt

Adds new tasks to the task list. Tasks can be assigned a specific status and index. AUTO_WIP behavior may automatically move tasks.

```APIDOC
## `tasks_add` — Add Tasks

### Description
Adds new tasks to the task list. Tasks can be assigned a specific status and index. AUTO_WIP behavior may automatically move tasks.

### Method
```javascript
tasks_add({ source_id: "xK8p", texts: ["Task A"], status: "To Do" })
```

### Notes
When `AUTO_WIP=true` (default), adding a task to 'To Do' may move it to 'In Progress' if it becomes the active WIP task. Adding directly to 'In Progress' may push existing WIP tasks to 'To Do'.
```

--------------------------------

### Update Task Status with tasks_update

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

Use `tasks_update` to change the status of one or more tasks. Use 'Deleted' as the status to remove tasks.

```javascript
tasks_update({
  source_id: "xK8p",        // From setup response
  ids: ["m3Qw", "p9Lx"],    // Task IDs from add/search responses
  status: "Done"            // Use "Deleted" to remove
})
// Returns: {"source":{"id":"xK8p","path":"/absolute/path/to/tasks.md"},"Backlog":0,"To Do":0,"In Progress":0,"Done":2,"inProgress":[],"tasks":[{"id":"m3Qw","text":"Implement authentication","status":"Done","index":0},{"id":"p9Lx","text":"Write tests","status":"Done","index":1}]}
```

--------------------------------

### Clearing NPX Cache for Dependency Resolution

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

Provides the command to clear the npx cache, which can resolve 'ERR_MODULE_NOT_FOUND' errors when running npx-tasks.

```bash
npx clear-npx-cache
npx mcp-tasks
```

--------------------------------

### Generate Deterministic Task IDs

Source: https://context7.com/flesler/mcp-tasks/llms.txt

Task IDs are generated using an MD5 hash of the task text, ensuring idempotency and stability. The last 4 characters of the base64url encoded hash are used. IDs are used for mutation operations and can be provided directly or inferred from raw task text.

```typescript
// Internal implementation (src/util.ts)
generateId(text: string): string {
  const hash = crypto.createHash('md5').update(text).digest('base64url')
  return hash.replace(/\W+/, '').slice(-ID_LENGTH)  // last 4 chars
}

// Example: "Implement authentication" → "m3Qw"
// Example: "Write unit tests"        → "p9Lx"

// IDs are used for all mutation operations:
tasks_update({ source_id: "xK8p", ids: ["m3Qw"], status: "Done" })

// The update tool also accepts raw text as a fallback (treated as a new task)
tasks_update({ source_id: "xK8p", ids: ["Some new task text"], status: "To Do" })

```

--------------------------------

### JSON Data Structure for Tasks

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

Represents task groups and their associated tasks in JSON format. Useful for structured data exchange and storage.

```json
{
  "groups": {
    "In Progress": [
      "Write user registration"
    ],
    "To Do": [
      "Implement authentication",
      "Set up CI/CD pipeline"
    ],
    "Backlog": [
      "Plan architecture",
      "Design database schema"
    ],
    "Done": [
      "Set up project structure",
      "Initialize repository"
    ],
    "Reminders": [
      "Don't move to Done until you verified it works",
      "After you move to Done, commit all the changes, use the task name as the commit message"
    ],
    "Notes": [
      "The task tools were really great to use!"
    ]
  }
}
```

--------------------------------

### tasks_update

Source: https://context7.com/flesler/mcp-tasks/llms.txt

Updates one or more tasks to a new status identified by their 4-character IDs. Use `"Deleted"` as the target status for soft-deletes. When `AUTO_WIP=true`, completing a WIP task automatically promotes the next `To Do` item.

```APIDOC
## `tasks_update` — Move Tasks by ID

Updates one or more tasks to a new status identified by their 4-character IDs (obtained from `tasks_add` or `tasks_search`). This is the only safe way for the AI to change tasks — it cannot accidentally rename or delete content. Use `"Deleted"` as the target status for soft-deletes. When `AUTO_WIP=true`, completing a WIP task automatically promotes the next `To Do` item.

### Parameters

- **source_id** (string) - Required - The ID of the source containing the tasks.
- **ids** (array of strings) - Required - An array of task IDs to update.
- **status** (string) - Required - The new status to assign to the tasks (e.g., "Done", "Deleted").
- **index** (number) - Optional - The position to insert the tasks at if changing status to "To Do" or "In Progress".

### Response

Returns an object similar to `tasks_summary` with an added `updated` field listing the modified tasks.

### Request Example

```javascript
// Bulk move multiple tasks in one call
tasks_update({
  source_id: "xK8p",
  ids: ["m3Qw", "p9Lx", "r7Km"],
  status: "Done"
})
```

### Response Example

```json
{
  "source": { "id": "xK8p", "path": "/Users/alice/project/tasks.md" },
  "In Progress": 1,
  "To Do": 2,
  "Backlog": 0,
  "Done": 1,
  "total": 4,
  "updated": [
    { "id": "m3Qw", "text": "Implement authentication", "status": "Done", "index": 0 }
  ],
  "inProgress": [
    { "id": "p9Lx", "text": "Write unit tests", "status": "In Progress", "index": 0 }
  ]
}
```
```

--------------------------------

### Search and Filter Tasks with tasks_search

Source: https://github.com/flesler/mcp-tasks/blob/main/README.md

Use `tasks_search` to find tasks based on terms, statuses, or specific IDs. The `source_id` is required to specify the task file.

```javascript
tasks_search({
  source_id: "xK8p",        // From setup response
  terms: ["auth", "deploy"],          // Search terms (text or status, OR logic)
  statuses: ["To Do"],      // Filter by status
  ids: ["m3Qw", "p9Lx"]     // Filter by specific task IDs
})
// Returns: [{"id":"m3Qw","text":"Implement authentication","status":"To Do","index":0}]
```

--------------------------------

### Move Tasks by ID with `tasks_update`

Source: https://context7.com/flesler/mcp-tasks/llms.txt

Use `tasks_update` to change the status of tasks identified by their IDs. It supports bulk updates, soft-deletes, and positional insertion. When `AUTO_WIP=true`, completing a WIP task automatically promotes the next `To Do` item.

```javascript
// Move a single task to Done
tasks_update({
  source_id: "xK8p",
  ids: ["m3Qw"],
  status: "Done"
})
```

```javascript
// Bulk move multiple tasks in one call
tasks_update({
  source_id: "xK8p",
  ids: ["m3Qw", "p9Lx", "r7Km"],
  status: "Done"
})
```

```javascript
// Soft-delete a task (moved to Deleted bucket, recoverable)
tasks_update({
  source_id: "xK8p",
  ids: ["xZ2b"],
  status: "Deleted"
})
```

```javascript
// Move to In Progress and insert at a specific position
tasks_update({
  source_id: "xK8p",
  ids: ["q1Np"],
  status: "In Progress",
  index: 0
})
```

```javascript
// Response (same shape as tasks_summary with "updated" field)
{
  "source": { "id": "xK8p", "path": "/Users/alice/project/tasks.md" },
  "In Progress": 1,
  "To Do": 2,
  "Backlog": 0,
  "Done": 1,
  "total": 4,
  "updated": [
    { "id": "m3Qw", "text": "Implement authentication", "status": "Done", "index": 0 }
  ],
  "inProgress": [
    { "id": "p9Lx", "text": "Write unit tests", "status": "In Progress", "index": 0 }
  ]
}
```

--------------------------------

### tasks_summary

Source: https://context7.com/flesler/mcp-tasks/llms.txt

Retrieves per-status task counts, the current in-progress task list, and the full reminders array if enabled. This function is redundant immediately after tasks_add or tasks_update as those operations already return the same payload.

```APIDOC
## `tasks_summary` — Get Status Counts

### Description
Returns per-status task counts, the current `inProgress` task list, and the full `reminders` array (if enabled). Redundant immediately after `tasks_add` or `tasks_update` since those already return the same payload.

### Method
```javascript
tasks_summary({ source_id: "xK8p" })
```

### Response Example
```json
{
  "source": { "id": "xK8p", "path": "/Users/alice/project/tasks.md" },
  "In Progress": 1,
  "To Do": 3,
  "Backlog": 2,
  "Done": 5,
  "Reminders": 2,
  "Notes": 1,
  "Deleted": 0,
  "total": 14,
  "inProgress": [
    { "id": "r7Km", "text": "Fix critical bug", "status": "In Progress", "index": 0 }
  ],
  "reminders": [
    { "id": "aB3c", "text": "Don't move to Done until verified", "status": "Reminders", "index": 0 },
    { "id": "dE4f", "text": "Commit changes with task name as message", "status": "Reminders", "index": 1 }
  ]
}
```
```

--------------------------------

### tasks_add

Source: https://context7.com/flesler/mcp-tasks/llms.txt

Adds one or more tasks to a specific status bucket. Automatically prevents duplicates by removing any existing task with the same text before inserting. Supports positional insertion via `index`.

```APIDOC
## `tasks_add` — Add Tasks in Batch

Adds one or more tasks to a specific status bucket. Automatically prevents duplicates by removing any existing task with the same text before inserting. When `AUTO_WIP=true`, adding to `In Progress` pushes all current WIP tasks to `To Do`, and adding to `To Do` promotes the first item to `In Progress` when none are active. Supports positional insertion via `index`.

### Parameters

- **source_id** (string) - Required - The ID of the source to add tasks to.
- **texts** (array of strings) - Required - An array of task texts to add.
- **status** (string) - Required - The status bucket to add the tasks to (e.g., "To Do", "In Progress").
- **index** (number) - Optional - The position to insert the tasks at. If not provided, tasks are appended.

### Response

Returns an object similar to `tasks_summary`, including a list of added tasks.

### Request Example

```javascript
tasks_add({
  source_id: "xK8p",
  texts: ["Implement authentication", "Write unit tests", "Update API docs"],
  status: "To Do"
})
```

### Response Example

```json
{
  "source": { "id": "xK8p", "path": "/Users/alice/project/tasks.md" },
  "In Progress": 1,
  "To Do": 3,
  "Backlog": 0,
  "Done": 0,
  "total": 4,
  "added": [
    { "id": "m3Qw", "text": "Deploy hotfix to production", "status": "In Progress", "index": 0 }
  ],
  "inProgress": [
    { "id": "m3Qw", "text": "Deploy hotfix to production", "status": "In Progress", "index": 0 }
  ]
}
```
```

--------------------------------

### Search and Filter Tasks with `tasks_search`

Source: https://context7.com/flesler/mcp-tasks/llms.txt

Use `tasks_search` to retrieve tasks with flexible filtering by status, text terms, or IDs. It supports full-text search across task text and status labels.

```javascript
// Get all tasks across all statuses
tasks_search({ source_id: "xK8p" })
```

```javascript
// Filter to a single status
tasks_search({
  source_id: "xK8p",
  statuses: ["To Do"]
})
```

```javascript
// Text search with OR logic (finds tasks matching "auth" OR "login")
tasks_search({
  source_id: "xK8p",
  terms: ["auth", "login"]
})
```

```javascript
// Search by status label (useful when the AI searches by mistake)
tasks_search({
  source_id: "xK8p",
  terms: ["Done"]
})
```

```javascript
// Lookup specific tasks by ID
tasks_search({
  source_id: "xK8p",
  ids: ["m3Qw", "p9Lx"]
})
```

```javascript
// Combined: To Do tasks mentioning "deploy", max 5 results
tasks_search({
  source_id: "xK8p",
  statuses: ["To Do", "In Progress"],
  terms: ["deploy"],
  limit: 5
})
```

```javascript
// Response — array of Task objects
[
  { "id": "m3Qw", "text": "Implement authentication", "status": "To Do", "index": 0 },
  { "id": "p9Lx", "text": "Deploy hotfix to production", "status": "In Progress", "index": 0 }
]
```

--------------------------------

### tasks_update

Source: https://context7.com/flesler/mcp-tasks/llms.txt

Updates the status of existing tasks. This operation can trigger AUTO_WIP behavior, potentially promoting the next task.

```APIDOC
## `tasks_update` — Update Tasks

### Description
Updates the status of existing tasks. This operation can trigger AUTO_WIP behavior, potentially promoting the next task.

### Method
```javascript
tasks_update({ source_id: "xK8p", ids: ["taskA_id"], status: "Done" })
```

### Notes
Completing a WIP task via `tasks_update` to 'Done' can automatically promote the next task from 'To Do' if AUTO_WIP is enabled.
```

--------------------------------

### tasks_search

Source: https://context7.com/flesler/mcp-tasks/llms.txt

Retrieves tasks with optional filtering by status, text terms (case-insensitive OR logic), or explicit task IDs. Returns an array of `Task` objects.

```APIDOC
## `tasks_search` — Search and Filter Tasks

Retrieves tasks with optional filtering by status, text terms (case-insensitive OR logic), or explicit task IDs. Returns an array of `Task` objects. Use `statuses` to restrict the scope and `terms` to full-text search across task text and status label simultaneously.

### Parameters

- **source_id** (string) - Required - The ID of the source to search within.
- **statuses** (array of strings) - Optional - An array of status buckets to filter tasks by.
- **terms** (array of strings) - Optional - An array of terms to perform a full-text search on.
- **ids** (array of strings) - Optional - An array of specific task IDs to retrieve.
- **limit** (number) - Optional - The maximum number of results to return.

### Response

Returns an array of `Task` objects matching the search criteria.

### Request Example

```javascript
// Combined: To Do tasks mentioning "deploy", max 5 results
tasks_search({
  source_id: "xK8p",
  statuses: ["To Do", "In Progress"],
  terms: ["deploy"],
  limit: 5
})
```

### Response Example

```json
[
  { "id": "m3Qw", "text": "Implement authentication", "status": "To Do", "index": 0 },
  { "id": "p9Lx", "text": "Deploy hotfix to production", "status": "In Progress", "index": 0 }
]
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.