# Task Manager MCP Server

A small [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server, built in Node.js, that lets an AI assistant like Claude manage a to-do list on your behalf.

It's intentionally minimal — meant as a clear, working example of how MCP tools and resources are wired up, not a production task manager.

## What it does

The server exposes:

**Tools** (actions the model can call):
- `add_task` — add a new task with an optional priority
- `list_tasks` — list tasks, optionally filtered by `open` / `done`
- `complete_task` — mark a task as done by ID
- `delete_task` — remove a task by ID

**Resources** (data the model can read):
- `tasks://all` — the full task list as JSON

Tasks are persisted to a local `tasks.json` file, so they survive restarts.

## Tech stack

- Node.js (ES modules)
- [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) — official MCP SDK
- [`zod`](https://www.npmjs.com/package/zod) — schema validation for tool inputs
- Transport: stdio (designed to be launched by an MCP host, not run standalone in a browser)

## Setup

```bash
git clone https://github.com/<your-username>/task-manager-mcp.git
cd task-manager-mcp
npm install
```

## Running it

MCP servers communicate over stdio and are meant to be launched by a host application (like Claude Desktop), not opened directly in a browser.

### Connect it to Claude Desktop

Add this to your Claude Desktop config file
(`%APPDATA%\Claude\claude_desktop_config.json` on Windows, or
`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "task-manager": {
      "command": "node",
      "args": ["/absolute/path/to/task-manager-mcp/index.js"]
    }
  }
}
```

Restart Claude Desktop, and you'll see the tools show up — you can then just ask Claude things like:

> "Add a task to finish the quarterly report, high priority"
> "What tasks do I still have open?"
> "Mark task 2 as done"

## Project structure

```
task-manager-mcp/
├── index.js        # The MCP server: tools, resources, and the stdio transport
├── package.json
├── .gitignore
└── README.md
```

## Why this is a useful showcase

This project demonstrates the two core building blocks of MCP:
- **Tools**, which let a model take actions with side effects (here: mutating a task list)
- **Resources**, which let a model read structured data directly (here: the current task list as JSON)

It's a good starting point to fork and adapt — swap the JSON file for a real database, add more tools, or extend it with prompts.

## License

MIT