# Todo MCP

Demo project for learning [Model Context Protocol (MCP)](https://modelcontextprotocol.io).

A small Next.js todo app exposes the same list as an MCP server over Streamable HTTP. Use it to see how agents call tools against a real app — either on your machine or against a hosted deployment.

## What you get

- **Web UI** at `/` — add, complete, and purge todos
- **MCP server** at `/api/mcp` — tools that operate on the same shared store

| Tool                 | What it does                                                  |
| -------------------- | ------------------------------------------------------------- |
| `list_todos`         | List todos (optional filter: `active`, `completed`, `purged`) |
| `add_todo`           | Create an active todo                                         |
| `set_todo_completed` | Mark completed or return to active                            |
| `delete_todo`        | Move a todo to purged (not restored)                          |

## Storage

- **Local (no env):** in-memory store. UI and MCP share it in one Node process. Resets on restart.
- **Local or Vercel (with KV env):** [Vercel KV](https://vercel.com/docs/storage/vercel-kv) via `@upstash/redis`. UI and MCP stay in sync across serverless instances.
- **Vercel without KV env:** fails fast with a clear config error.

Copy `.env.example` to `.env.local` when you want KV locally:

```bash
KV_REST_API_URL=
KV_REST_API_TOKEN=
```

## Prerequisites

- Node.js 20+
- An MCP client (e.g. [Cursor](https://cursor.com))

```bash
npm install
```

## Option A — Hosted MCP (default)

This repo’s `.cursor/mcp.json` points at the deployed demo:

```json
{
  "mcpServers": {
    "todo-mcp": {
      "type": "http",
      "url": "https://todo-mcp-playground.vercel.app/api/mcp"
    }
  }
}
```

Enable / refresh `todo-mcp` in Cursor MCP settings, then ask the agent to list or add todos. Open [https://todo-mcp-playground.vercel.app/](https://todo-mcp-playground.vercel.app/) — the UI polls every few seconds, so MCP changes show up without a hard refresh.

Hosted deploys need a KV database connected to the Vercel project so `KV_REST_API_URL` and `KV_REST_API_TOKEN` are injected.

**Before exposing private data:** add auth. The demo has none.

## Option B — Run locally

1. Start the app:

```bash
npm run dev
```

2. Open [http://localhost:3000](http://localhost:3000) for the UI.

3. Point your MCP client at the local server (override `.cursor/mcp.json` or add a second entry):

```json
{
  "mcpServers": {
    "todo-local": {
      "type": "http",
      "url": "http://localhost:3000/api/mcp"
    }
  }
}
```

4. Enable / refresh `todo-local` in Cursor MCP settings, then ask the agent to list or add todos.

No KV env required. Optional: set the vars from `.env.example` to exercise the same Redis path as production.

## Project layout

```
app/              # Next.js UI + /api/mcp route
components/       # Todo UI
lib/todos.ts      # In-memory local store + Vercel KV persistence
lib/redis.ts      # KV client (null locally when env is unset)
mcp/server.ts     # Tool registration (mcp-handler)
.cursor/mcp.json  # Cursor MCP config (hosted by default)
```

More MCP detail: [`mcp/README.md`](mcp/README.md).

## Learn by doing

1. Use the hosted MCP config, ask the agent to add a todo, watch it appear on the site.
2. Or run locally, open the UI, add a todo, then ask the agent to list it.
3. Deploy your own copy with KV connected, switch the MCP URL, confirm tools still work.

That loop is the point of the demo: MCP tools as another interface to your app.