# Local Task Manager MCP Server

A beginner-friendly Model Context Protocol server built with Python and FastMCP.

This project demonstrates how an MCP server can expose structured tools that allow an AI application to create, read, update, and delete tasks stored in a local JSON file.

## Features

* Add a task
* List all tasks
* Filter completed or incomplete tasks
* Mark a task as completed
* Delete a task
* Persist task data in `tasks.json`
* Return structured MCP responses
* Handle invalid task IDs and input errors

## MCP Tools

### `add_task`

Creates a new task.

Inputs:

* `title`: Required task title
* `description`: Optional task description

### `list_tasks`

Lists saved tasks.

Optional input:

* `completed`: Filter by completion status

### `complete_task`

Marks a task as completed.

Input:

* `task_id`: ID of the task

### `delete_task`

Deletes a task.

Input:

* `task_id`: ID of the task

## Project Structure

```text
task-manager-mcp/
├── main.py
├── tasks.json
├── pyproject.toml
├── uv.lock
└── README.md
```

## Requirements

* Python 3.10 or later
* `uv`
* Node.js and npm for MCP Inspector

## Install Dependencies

```powershell
uv sync
```

## Run with MCP Inspector

```powershell
uv run mcp dev main.py
```

The Inspector should display these tools:

```text
add_task
list_tasks
complete_task
delete_task
```

## Example Task

```json
{
  "id": 1,
  "title": "Prepare Day 5 MCP article",
  "description": "Connect the Task Manager MCP Server to Trello",
  "completed": false
}
```

## Example Flow

```text
User request
    ↓
MCP client
    ↓
Local Task Manager MCP Server
    ↓
Python tool
    ↓
tasks.json
    ↓
Structured response
```

## What This Project Teaches

* Creating an MCP server with FastMCP
* Exposing Python functions using `@mcp.tool()`
* Generating tool schemas from type hints
* Returning structured data
* Validating tool inputs
* Handling expected errors
* Persisting data in a local JSON file
* Testing MCP tools with MCP Inspector

## Roadmap

The next version will connect the same task-management capabilities to Trello:

```text
add_task → Create a Trello card
list_tasks → List Trello cards
complete_task → Move a card to Done
delete_task → Archive a Trello card
```

## Author

**Akbar Shaik**

Machine Learning Engineer teaching MCP servers and AI agents from scratch.