Task / To-Do Manager — MCP Server

A small MCP server that gives an AI assistant a menu of 5 things it can do with a personal to-do list: add a task, list tasks, look one up, mark it done, and delete it. Built for the "Building an MCP Server" beginner lab.

What it does

The server exposes:

• 5 tools — the actions the AI assistant can trigger

• 1 bonus resource — a read-only view of pending tasks

• Storage — a single JSON file (tasks.json), created automatically the first time you add a task. No database.

• Transport — stdio (standard input/output), the simplest option, as used throughout this lab.

Related MCP server: Task MCP Server

Setup

# 1. Create and activate a virtual environment
python -m venv venv
source venv/bin/activate      # Mac/Linux
venv\Scripts\activate         # Windows

# 2. Install dependencies
pip install -r requirements.txt

Note on SDK version: this server is written against MCP Python SDK v2 (mcp>=2.0.0), which is what pip install mcp gives you today. If you followed an older guide that uses from mcp.server.fastmcp import FastMCP, that class was renamed — this server uses the current equivalent, from mcp.server.mcpserver import MCPServer. The tool and resource decorators (@mcp.tool(), @mcp.resource()) work the same way either version.

Running it

python server.py

The server communicates over stdio, so it's meant to be launched by an MCP client (like MCP Inspector or an AI assistant), not run and watched directly.

To test it by hand, point MCP Inspector at it:

npx @modelcontextprotocol/inspector python server.py

Then open the URL Inspector prints, and you'll see all 5 tools plus the resource listed — click into any of them to call it and see the result.

Tools

1. add_task(title, notes="")

Adds a new task. title is required and cannot be empty.

Example call:

{ "title": "Buy milk", "notes": "Get 2% not whole" }

Returns:

{ "status": "created", "task": { "id": "1", "title": "Buy milk", "notes": "Get 2% not whole", "done": false, "created_at": "..." } }

2. list_tasks(only_pending=False)

Lists all tasks, newest first. Set only_pending: true to see just the tasks that aren't done yet.

Example call:

{ "only_pending": true }

Returns:

{ "count": 1, "tasks": [ { "id": "2", "title": "Write report", "...": "..." } ] }

3. get_task(task_id)

Fetches the full details of one task by its ID.

Example call:

{ "task_id": "1" }

Returns: { "task": { ... } } or { "error": "No task found with id '1'." }

4. complete_task(task_id)

Marks a task as done and stamps it with completed_at.

Example call:

{ "task_id": "1" }

Returns: { "status": "completed", "task": { ... } }

5. delete_task(task_id)

Permanently removes a task.

Example call:

{ "task_id": "1" }

Returns: { "status": "deleted", "task": { ... } }

Bonus resource

tasks://pending

A read-only JSON snapshot of every task that hasn't been completed yet. Unlike a tool, this doesn't do anything — it just hands over data.

Error handling

• add_task with an empty/missing title → a clear JSON error, not a crash ({"error": "title is required and cannot be empty."}).

• get_task, complete_task, delete_task with an unknown task_id → a clear JSON error naming the missing ID.

• complete_task called twice on the same task → returns {"status": "already_done", ...} instead of a duplicate-completion error.

• Missing required fields entirely (e.g. calling add_task with no title key at all) are caught automatically by the tool's input schema before the code even runs, and reported back as a validation error.

• If tasks.json is ever manually corrupted, the server treats it as an empty list instead of crashing on startup.

Example end-to-end walkthrough

A realistic request like "add a task and then show me all my pending tasks" looks like this:

1. add_task({"title": "Finish lab report"}) → task 1 created.

2. list_tasks({"only_pending": true}) → returns [task 1].

3. complete_task({"task_id": "1"}) → task 1 marked done.

4. list_tasks({"only_pending": true}) → returns [].

Project structure

todo-mcp-server/
├── server.py         # the MCP server: tools, resource, entry point
├── tasks.json         # created automatically on first add_task call
├── requirements.txt
└── README.md