# Todo MCP Server

A robust, persistent task management server built on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) using Python and FastMCP.

---

## Overview

The **Todo MCP Server** provides language models and AI agents with a persistent, stateful task management interface. Built using the official Python MCP SDK (`FastMCP`), it exposes tools that allow AI assistants to create, track, filter, and complete tasks directly within their workflow.

State is persisted locally to structured JSON storage (`tasks.json`), ensuring task data survives server restarts, client reconnections, and multi-turn agent sessions. Communication follows the MCP specification using JSON-RPC 2.0 over standard input/output (`stdio`).

---

## Architecture & Data Flow

```
+-------------------------------------------------------------------+
|                        MCP Host / AI Client                       |
|               (Claude Desktop, Cursor, Antigravity)               |
+-------------------------------------------------------------------+
                                  |
                   JSON-RPC 2.0 over stdin / stdout
                                  v
+-------------------------------------------------------------------+
|                       Todo MCP Server                             |
|                                                                   |
|   +-----------------------------------------------------------+   |
|   |                       FastMCP Engine                      |   |
|   |  - Protocol negotiation & schema reflection               |   |
|   |  - Tool dispatch & argument validation (Pydantic/Typing)  |   |
|   +-----------------------------------------------------------+   |
|                                 |                                 |
|   +-----------------------------+-----------------------------+   |
|   |                             |                             |   |
|   v                             v                             v   |
| [ add_task ]             [ list_tasks ]             [ complete_task ]
|   |                             |                             |   |
|   +-----------------------------+-----------------------------+   |
|                                 |                                 |
|                                 v                                 |
|   +-----------------------------------------------------------+   |
|   |                    Storage Controller                     |   |
|   |  - Atomic read/write operations                           |   |
|   |  - Schema serialization with ISO 8601 UTC timestamps      |   |
|   +-----------------------------------------------------------+   |
+-------------------------------------------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|                      Local Storage: tasks.json                    |
+-------------------------------------------------------------------+
```

---

## Tools Reference

The server exposes three distinct tools for full task lifecycle management.

### 1. `add_task`

Creates a new task item and appends it to persistent storage.

- **Description:** Add a new task to the todo list.
- **Parameters:**
  - `title` (*string*, required): Description of the task. Length must be between 1 and 200 characters.
  - `priority` (*string*, optional): Urgency level. Accepted values: `"low"`, `"medium"`, `"high"`. Default: `"medium"`.
- **Validation Rules:**
  - Empty or whitespace-only strings are rejected.
  - Titles exceeding 200 characters return an error.
  - Non-conforming priority values fail schema validation.

**Example Request:**
```json
{
  "title": "Implement integration test suite",
  "priority": "high"
}
```

**Example Response:**
```text
Task added!
  ID:       1
  Title:    Implement integration test suite
  Priority: high
  Status:   pending
```

---

### 2. `list_tasks`

Retrieves saved tasks with optional filtering by completion status.

- **Description:** List tasks from the todo list with optional status filtering.
- **Parameters:**
  - `status` (*string*, optional): Filter criteria. Accepted values: `"all"`, `"pending"`, `"done"`. Default: `"all"`.
- **Formatting:** Returns a formatted ASCII table summarizing task IDs, status indicators, priority levels, and titles.

**Example Request:**
```json
{
  "status": "pending"
}
```

**Example Response:**
```text
Tasks (pending) — 2 found:

  ID  Status    Priority Title
————  ————————— ———————— ————————————————————————————————————————
   1  pending   high     Implement integration test suite
   2  pending   medium   Update project documentation
```

---

### 3. `complete_task`

Marks an existing task as completed by its unique integer identifier.

- **Description:** Mark a task as done by its numeric ID.
- **Parameters:**
  - `task_id` (*integer*, required): The unique numeric identifier assigned to the task.
- **Behavior:**
  - Updates the task status to `"done"`.
  - Sets the `completed_at` field to the current ISO 8601 UTC timestamp.
  - Idempotent: If the task is already completed, the tool notifies the client without corrupting timestamps.
  - If the ID does not exist, an error response is returned with the list of currently valid IDs.

**Example Request:**
```json
{
  "task_id": 1
}
```

**Example Response:**
```text
Task 1 completed!
  Title:        Implement integration test suite
  Completed at: 2026-08-20T09:46:17.466797+00:00
```

---

## Tool Summary Table

| Tool | Purpose | Parameters | Return Type |
| --- | --- | --- | --- |
| `add_task` | Create a new task | `title` (str, required)<br>`priority` (`"low"` \| `"medium"` \| `"high"`, default: `"medium"`) | `string` (Confirmation details) |
| `list_tasks` | Query stored tasks | `status` (`"all"` \| `"pending"` \| `"done"`, default: `"all"`) | `string` (Formatted table) |
| `complete_task` | Mark a task as completed | `task_id` (int, required) | `string` (Completion status & timestamp) |

---

## Data Model & Persistence

Task records are serialized as UTF-8 encoded JSON arrays. By default, records are stored in `tasks.json` in the current working directory. The storage file path can be customized via the `TODO_FILE` environment variable.

### Schema Definition

```json
[
  {
    "id": 1,
    "title": "Implement integration test suite",
    "priority": "high",
    "status": "done",
    "created_at": "2026-08-20T09:46:17.362387+00:00",
    "completed_at": "2026-08-20T09:46:17.466797+00:00"
  },
  {
    "id": 2,
    "title": "Update project documentation",
    "priority": "medium",
    "status": "pending",
    "created_at": "2026-08-20T09:46:17.384689+00:00",
    "completed_at": null
  }
]
```

### Field Specifications

- `id` (*integer*): Auto-incrementing positive integer identifier.
- `title` (*string*): Task description string (1-200 chars).
- `priority` (*string*): Urgency classification (`"low"`, `"medium"`, `"high"`).
- `status` (*string*): Lifecycle stage (`"pending"` or `"done"`).
- `created_at` (*string*): ISO 8601 formatted UTC timestamp recorded at creation.
- `completed_at` (*string | null*): ISO 8601 formatted UTC timestamp recorded upon completion.

---

## Requirements

- **Python**: Version 3.10 or higher
- **Dependencies**:
  - `mcp[cli]>=1.28,<2`

---

## Installation & Setup

### 1. Clone the Repository

```bash
git clone https://github.com/moazhassan751/mcp-todo-server.git
cd mcp-todo-server
```

### 2. Create a Virtual Environment

```bash
# Linux/macOS
python3 -m venv .venv
source .venv/bin/activate

# Windows
python -m venv .venv
.venv\Scripts\activate
```

### 3. Install Dependencies

```bash
pip install -r requirements.txt
```

---

## Execution Modes

### Standard Execution (stdio)

Run the server directly for production or MCP host integration:

```bash
python server.py
```

### Developer Inspection (MCP Inspector)

The MCP Inspector provides an interactive browser-based interface to test tools, inspect schemas, and simulate requests:

```bash
mcp dev server.py
```

The inspector will launch and provide a local interface URL (typically `http://localhost:6274`).

---

## Client Integration Guide

To connect the Todo MCP Server to your preferred AI environment, configure the server in your client's MCP configuration file.

### Claude Desktop

Edit your Claude Desktop configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "todo-server": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-todo-server/server.py"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project or global directory:

```json
{
  "mcpServers": {
    "todo-server": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-todo-server/server.py"]
    }
  }
}
```

### Antigravity IDE

Add to `.agents/mcp_config.json` in your workspace:

```json
{
  "mcpServers": {
    "todo-server": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-todo-server/server.py"]
    }
  }
}
```

---

## Testing & Verification

The repository includes comprehensive automated test scripts:

### Standard Test Suite

Tests basic tool calls, parameter validations, and output formatting:

```bash
python test_server.py
```

### Multi-Session Audit Test

Simulates separate client connections, restarts the server process across sessions, and validates that persistent storage correctly retains state:

```bash
python audit_test.py
```

---

## Project Structure

```
mcp-todo-server/
├── server.py           # Core MCP server definition and tool implementations
├── test_server.py      # Automated stdio protocol unit tests
├── audit_test.py       # Multi-session persistence and edge-case verification
├── requirements.txt    # Package dependencies
├── .gitignore          # Version control ignore definitions
└── README.md           # Technical documentation and integration reference
```

---

## License

This project is open source and available under the [MIT License](LICENSE).