# MCP Todo Server

A simple Model Context Protocol (MCP) server that provides todo list management functionality to Claude Desktop and other MCP clients.

## Features

- **Create todos** with optional due dates
- **List all todos** sorted by creation date
- **Toggle todo completion** status
- **Delete todos** by ID
- **Search todos** by title
- **SQLite database** with Prisma ORM for reliable concurrent operations

## Installation

```bash
npm install
```

## Setup

1. Create a `.env` file in the project root:
```env
DATABASE_URL="file:./dev.db"
```

2. Initialize the database:
```bash
npx prisma migrate dev
```

3. Configure Claude Desktop by adding this to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "todo": {
      "command": "bash",
      "args": ["/absolute/path/to/mcp-todo/mcp/run-todo.sh"],
      "env": {
        "DATABASE_URL": "file:/absolute/path/to/mcp-todo/data/todos.db"
      }
    }
  }
}
```

4. Restart Claude Desktop

## Project Structure

```
mcp-todo/
├── mcp/
│   ├── todo-server.ts       # MCP server implementation
│   └── run-todo.sh          # Server startup script
├── lib/
│   └── todos.ts             # Todo business logic with Prisma
├── prisma/
│   ├── schema.prisma        # Database schema
│   └── migrations/          # Database migrations
├── data/
│   └── todos.db             # SQLite database file
└── src/                     # Next.js app (optional UI)
```

## Available MCP Tools

### `list_todos`
Returns all todos sorted by creation date (newest first).

### `add_todo`
Creates a new todo item.
- `title` (string, required): The todo title
- `due` (string, optional): Due date

### `toggle_todo`
Toggles or sets the completion status of a todo.
- `id` (string, required): Todo ID
- `done` (boolean, optional): Set specific state, or omit to toggle

### `delete_todo`
Deletes a todo by ID.
- `id` (string, required): Todo ID

### `search_todos`
Search todos by title substring.
- `q` (string, required): Search query

## Development

Run the MCP server directly:
```bash
npm run mcp:todo
```

Test with a JSON-RPC message:
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | npm run mcp:todo
```

### Debug with MCP Inspector

Use the MCP Inspector to test and debug your server interactively:
```bash
npx @modelcontextprotocol/inspector npm run mcp:todo
```

This opens a web interface where you can test all available tools and see real-time request/response data.

## Database

The project uses SQLite with Prisma ORM. The database file is stored at `data/todos.db`.

### Schema
```prisma
model Todo {
  id        String   @id @default(uuid())
  title     String
  done      Boolean  @default(false)
  due       String?
  createdAt DateTime @default(now())
}
```

### Migrations
```bash
# Create a new migration
npx prisma migrate dev --name migration_name

# Reset database
npx prisma migrate reset

# View database in Prisma Studio
npx prisma studio
```

## Next.js Web UI (Optional)

This project also includes a Next.js web interface for managing todos.

### Getting Started

Run the development server:

```bash
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.

You can start editing the page by modifying `src/app/page.tsx`. The page auto-updates as you edit the file.

### Deploy on Vercel

The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.

Check out the [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

## Tech Stack

- **MCP SDK**: [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk)
- **Database**: SQLite + Prisma
- **Runtime**: Node.js with tsx for TypeScript execution
- **Frontend** (optional): Next.js 15, React 19, Tailwind CSS

## License

MIT