# Checklist MCP Server

An MCP (Model Context Protocol) server for managing hierarchical checklists and tracking work context, designed to help AI agents manage long-running tasks and maintain state across sessions.

## Features

- **Hierarchical Task Management**: Create and manage nested checklists.
- **Multi-tenancy Support**: Built-in support for multiple isolated environments using namespaces.
- **HTTP/SSE Transport**: Uses the standard MCP HTTP transport with Server-Sent Events (SSE).

## Tools

| Tool Name | Description |
|-----------|-------------|
| `init_tasks` | Initialize a new checklist session. Requires the `sessionId` to NOT exist. If it exists, provides steering advice with a recommended available `sessionId`. |
| `update_tasks` | Create new tasks or overwrite existing tasks at a specific hierarchical path for an **existing** session. |
| `mark_task_as_done` | Mark specific tasks as completed in an **existing** session. |
| `get_all_tasks` | Retrieve the complete hierarchical list of tasks for an **existing** session. |

### Session Lifecycle & Steering Guidance
- **Session Initialization**: Call `init_tasks` first with a unique `sessionId` to create a checklist session.
- **Session Isolation**: Calling `update_tasks`, `mark_task_as_done`, or `get_all_tasks` with a non-existent `sessionId` will return non-error Steering guidance asking you to initialize the session first.
- **Conflict Prevention**: Calling `init_tasks` with an already existing `sessionId` will return non-error Steering guidance with a suggested alternative `sessionId` (e.g. `my-session_1`).

## Quick Start

### Running Locally (Node.js)

You can run the server directly using `npx` or `npm`.

**Using npx:**
```bash
npx checklist-mcp-server
```

**Using npm:**
```bash
git clone https://github.com/chene/checklist-mcp-server.git
cd checklist-mcp-server
npm install
npm run build
npm run start:http
```

The server will start on port `8585` by default.

### Running with Docker

```bash
docker run -d -p 8585:8585 --name checklist-mcp-server checklist-mcp-server:latest
```

For more detailed Docker instructions, see [DOCKER.md](DOCKER.md).

## Configuration

### MCP Client Configuration

Configure your MCP client (e.g., Claude Desktop, custom agent) to connect to the HTTP endpoint.

```json
{
  "mcpServers": {
    "checklist": {
      "transport": "http",
      "url": "http://localhost:8585/mcp"
    }
  }
}
```

### Multi-tenancy (Namespaces)

This server supports multi-tenancy via the `namespace` query parameter. This allows multiple agents or users to store distinct data within the same server instance.

To use a specific namespace, append `?namespace=<your_namespace>` to the server URL.

**Example Client Config for a specific namespace:**

```json
{
  "mcpServers": {
    "project-alpha": {
      "transport": "http",
      "url": "http://localhost:8585/mcp?namespace=project-alpha"
    },
    "project-beta": {
      "transport": "http",
      "url": "http://localhost:8585/mcp?namespace=project-beta"
    }
  }
}
```

If no namespace is provided, the server defaults to the `default` namespace.

## License

MIT