# todo-tree MCP Server

Exposes your todo-tree task list as MCP tools so any MCP-compatible AI client (Claude Desktop, etc.) can read and manage your tasks. It supports both stdio transport (default) and SSE (HTTP) transport with dynamic client-side authentication.

## Modes of Operation

### 1. SSE (HTTP) Mode with Web Portal (Recommended)
By defining the `PORT` environment variable, the server will boot as an HTTP server supporting Server-Sent Events (SSE). It hosts a web interface allowing non-technical users to easily log in and connect.

#### Setup
1. Create a `.env` file based on `.env.example`:
   ```bash
   PORT=3001
   TODO_TREE_API_URL=http://localhost:1337
   ```
2. Start the server:
   ```bash
   npm start
   ```
3. Open `http://localhost:3001` in your browser.
4. Log in with your Todo Tree credentials to get your personalized connection URL and configuration block.

### 2. Deployed SSE Mode (No Local Repository Needed)
If the server has already been deployed to a cloud platform (such as Fly.io, Render, or a VPS), you do not need to clone the repository or run any code locally to connect your AI client.

#### Setup for Clients
1. Open the public URL of the deployed server in your browser (for example, `https://your-todo-tree-mcp.com`).
2. Log in with your Todo Tree credentials to access the connector dashboard.
3. The dashboard will automatically generate the required configuration for your client.
4. Copy the generated Claude Desktop configuration block.
5. Open your local Claude Desktop configuration file:
   * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
6. Paste the configuration block inside the `mcpServers` object:
   ```json
   {
     "mcpServers": {
       "todo-tree": {
         "url": "https://your-todo-tree-mcp.com/sse?token=YOUR_SECURE_TOKEN"
       }
     }
   }
   ```
7. Restart your Claude Desktop client.

### 3. Stdio Mode (Single User)
If no `PORT` is defined, the server runs in standard I/O mode. It uses a static token defined in the environment variables to authenticate all requests.

#### Setup for Claude Desktop
Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "todo-tree": {
      "command": "node",
      "args": ["C:\\Users\\davei\\Desktop\\todo-tree\\mcp-server\\dist\\index.js"],
      "env": {
        "TODO_TREE_API_URL": "http://localhost:1337",
        "TODO_TREE_TOKEN": "your-jwt-token-here"
      }
    }
  }
}
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PORT` | No | Port to run in SSE mode. If omitted, runs in stdio mode. |
| `TODO_TREE_API_URL` | No | Base URL of the Strapi backend (defaults to `http://localhost:1337`). |
| `TODO_TREE_TOKEN` | No | Static JWT/token (required only for Stdio mode). |

## Development

Run without a build step using `tsx`:

```bash
PORT=3001 npm run dev
```

Test interactively with the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector tsx src/index.ts
```

## Tools

### `get_tree`
Returns the full task tree as indented text. Each line shows the task ID in brackets, completion status, due date, and child progress. Use the IDs in subsequent tool calls.

```
[work] : Work
  [finish-report] : Finish report
  [review-pr] : Review PR - Due: Today
[buy-groceries] : Buy groceries - Due: May 30
[call-dentist] : Call dentist
```

### `add_task`
Creates a new task.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `text` | string | Yes | Task name |
| `parent_id` | string | No | ID of the parent task; omit for root level |
| `due_date` | string | No | Due date in `YYYY-MM-DD` format |

### `delete_task`
Permanently removes a task and all its children.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Task ID |

### `complete_task`
Marks a task done or undone. Completion propagates to all child tasks, same as clicking the checkbox in the UI.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Task ID |
| `completed` | boolean | No | `true` (default) to complete, `false` to uncomplete |

### `set_due_date`
Sets or clears the due date on a task.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Task ID |
| `due_date` | string | Yes | Date in `YYYY-MM-DD`, or `""` to clear |

### `move_task`
Moves a task to a new position in the tree.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Task to move |
| `target_id` | string | Yes | Reference task |
| `position` | `before` \| `after` \| `inside` | Yes | `before`/`after` makes it a sibling; `inside` makes it a child |