# MCP Task Manager

A beginner-friendly local task manager built with Python and the Model Context Protocol (MCP). It exposes five MCP tools for task management and one read-only resource for pending tasks. All data is persisted locally in `tasks.json`.

## Features

- Create, list, retrieve, complete, and delete tasks
- Filter tasks by `all`, `pending`, or `completed`
- Read pending tasks through an MCP resource
- Persist task data in a local JSON file
- Return friendly validation and storage errors
- Verify behavior with automated pytest tests

## MCP Capabilities

| Type | Name | Purpose |
| --- | --- | --- |
| Tool | `add_task` | Create and save a pending task |
| Tool | `list_tasks` | List tasks with an optional status filter |
| Tool | `get_task` | Retrieve one task by ID |
| Tool | `complete_task` | Mark a task as completed |
| Tool | `delete_task` | Delete a task |
| Resource | `tasks://pending` | Return pending tasks as read-only JSON |

## Project Structure

```text
todo-mcp-server/
├── tests/
│   └── test_server.py
├── .gitignore
├── README.md
├── requirements.txt
├── server.py
└── tasks.json
```

## Requirements

- Python 3.11 recommended
- Node.js and npm for MCP Inspector
- `uv` for launching the server from Inspector
- Git for version control

## Installation on Windows

```cmd
git clone https://github.com/YOUR-USERNAME/todo-mcp-server.git
cd todo-mcp-server
python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install uv
```

Verify the installation:

```cmd
python --version
mcp version
uv --version
```

## Run the Tests

```cmd
python -m pytest tests -v
python -m py_compile server.py
```

The expected test result is `27 passed`.

## Run with MCP Inspector

From the activated virtual environment, run:

```cmd
mcp dev server.py
```

Keep the terminal open. In the browser:

1. Keep the transport type set to `STDIO`.
2. Click **Connect** once.
3. Open **Tools** to discover and run the five tools.
4. Open **Resources** to read `tasks://pending`.
5. Press `Ctrl+C` in the terminal when finished.

## Example Demo Flow

1. Call `add_task`:

   ```json
   {
     "title": "Learn MCP",
     "description": "Complete the beginner MCP project"
   }
   ```

2. Call `list_tasks` with `{"status": "all"}`.
3. Call `get_task` with `{"task_id": 1}`.
4. Call `complete_task` with `{"task_id": 1}`.
5. Read `tasks://pending`; the completed task should be excluded.
6. Call `delete_task` with `{"task_id": 1}`.
7. Call `get_task` with `{"task_id": 99}` to demonstrate a friendly error.

## Task Data Format

```json
{
  "id": 1,
  "title": "Learn MCP",
  "description": "Complete the beginner MCP project",
  "completed": false,
  "created_at": "2026-09-12T10:00:00+00:00"
}
```

## Troubleshooting

### `uv` is not recognized

```cmd
python -m pip install uv
uv --version
```

### Inspector shows `Request timed out`

- Confirm that `uv --version` works.
- Keep the `mcp dev server.py` terminal running.
- Do not repeatedly click **Connect**.
- Check the terminal for a server startup error.

### `ModuleNotFoundError: No module named 'mcp'`

```cmd
.venv\Scripts\activate
python -m pip install -r requirements.txt
```

### Tools do not appear

The **Tools** and **Resources** tabs appear only after a successful server connection.

## MCP Concepts Demonstrated

- An MCP **client**, such as Inspector, discovers and calls server capabilities.
- A **tool** performs an operation and may change persisted data.
- A **resource** provides read-only data.
- The **stdio transport** exchanges MCP JSON-RPC messages through standard input and output.
- Python type hints and docstrings help generate tool schemas.

> Do not use `print()` for diagnostics in a stdio MCP server because stdout carries protocol messages. Use Python logging, which writes to stderr.

## License

This project is intended for educational use.