todo-mcp-server
README.md
# todo-mcp-server
A Todo REST API built with **Express + Drizzle ORM + SQLite**. The MCP server is an add-on mounted at `/mcp`, allowing AI editors (Cursor, VS Code Copilot, Claude Code, etc.) to query and manage your todos directly from chat.
> **What makes this interesting:** the REST API and the MCP server share the same database layer. Add a todo from the UI and your AI editor sees it instantly — no sync, no duplication.
---
## Stack
| Layer | Tech |
|---|---|
| Runtime | Node.js + TypeScript |
| API | Express 5 |
| ORM | Drizzle ORM |
| Database | SQLite (via better-sqlite3) |
| MCP | `@modelcontextprotocol/sdk` (Streamable HTTP) |
| Tests | Vitest + Supertest |
| DB UI | Drizzle Studio |
---
## Setup
```bash
npm install
npm run build
npm start
```
Server starts on `http://localhost:3001`.
### Environment variables
| Variable | Default | Description |
|---|---|---|
| `PORT` | `3001` | HTTP port |
| `DB_PATH` | `./todos.db` | SQLite database file path |
---
## REST API
Base URL: `http://localhost:3001/api/todos`
### Endpoints
```
GET /api/todos List all todos
GET /api/todos?filter=active Filter: active | completed | all
GET /api/todos/:id Get a single todo
POST /api/todos Create a todo
PATCH /api/todos/:id Update title / description / completed
PATCH /api/todos/:id/complete Mark as completed (convenience)
DELETE /api/todos/:id Delete a todo
GET /health Health check
```
### Request / Response shapes
**Create todo**
```http
POST /api/todos
Content-Type: application/json
{ "title": "Buy milk", "description": "From the corner store" }
```
```json
{
"data": {
"id": "m1k3abc",
"title": "Buy milk",
"description": "From the corner store",
"completed": false,
"createdAt": "2026-04-04T12:00:00.000Z",
"updatedAt": "2026-04-04T12:00:00.000Z"
}
}
```
**List todos**
```json
{
"data": [ { "id": "...", "title": "...", "completed": false, ... } ],
"count": 1
}
```
**Error response**
```json
{ "error": "title is required" }
```
---
## MCP Server
The MCP server is mounted at `/mcp` on the same port as the REST API. It uses the **Streamable HTTP** transport (stateful sessions).
### Tools available
| Tool | Description |
|---|---|
| `list_todos` | List todos, optional `filter: all\|active\|completed` |
| `get_todo` | Get details by `id` |
| `add_todo` | Create with `title` + optional `description` |
| `complete_todo` | Mark as done by `id` |
| `update_todo` | Update `title` / `description` by `id` |
| `delete_todo` | Delete by `id` |
### Resources
| URI | Description |
|---|---|
| `todos://all` | All todos as JSON |
| `todos://active` | Active todos as JSON |
---
## Connecting to AI editors
The server must be running before the editor connects.
### Cursor
Create `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
```json
{
"mcpServers": {
"todo": {
"url": "http://localhost:3001/mcp"
}
}
}
```
### VS Code (GitHub Copilot)
Create `.vscode/mcp.json` in your workspace:
```json
{
"servers": {
"todo": {
"type": "http",
"url": "http://localhost:3001/mcp"
}
}
}
```
Or add to **User Settings** (`settings.json`):
```json
{
"mcp": {
"servers": {
"todo": {
"type": "http",
"url": "http://localhost:3001/mcp"
}
}
}
}
```
### Claude Code
Add to `~/.claude/settings.json`:
```json
{
"mcpServers": {
"todo": {
"type": "http",
"url": "http://localhost:3001/mcp"
}
}
}
```
Or run in the Claude Code terminal:
```bash
claude mcp add --transport http todo http://localhost:3001/mcp
```
### Windsurf
Create `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"todo": {
"serverUrl": "http://localhost:3001/mcp"
}
}
}
```
---
## Database UI (Drizzle Studio)
```bash
npm run studio
```
Opens a visual SQLite browser at `https://local.drizzle.studio`. You can view, edit, insert, and delete rows directly.
---
## Tests
```bash
npm test # run once
npm run test:watch # watch mode
```
Tests use an **in-memory SQLite** database — no test database setup needed.
| File | What it covers |
|---|---|
| `tests/api.test.ts` | All REST endpoints (Supertest) |
| `tests/mcp.test.ts` | All MCP tools and resources (InMemoryTransport) |
---
## Project structure
```
src/
db/
schema.ts Drizzle table schema
client.ts SQLite + Drizzle setup
repository/
todo.repository.ts CRUD data access layer
api/
app.ts Express app factory
routes/todos.ts /api/todos router
middleware/error.ts Error handler
mcp/
tools.ts MCP tool definitions (JSON schema)
server.ts MCP Server factory
index.ts HTTP server entry point
tests/
api.test.ts
mcp.test.ts
drizzle.config.ts
vitest.config.ts
```
---
## How MCP Works
### The problem MCP solves
Without MCP, an AI assistant in your editor (Copilot, Cursor, Claude) only knows what you show it — open files, pasted text, maybe your repo. It has no connection to the outside world.
With MCP, the AI can **call your server** during a conversation and get real data or trigger real actions.
Ask Cursor "what are my open todos?" and it will actually query your database and tell you. Ask it to "mark the Buy milk todo as done" and it will. This is MCP.
### What MCP actually is
MCP (Model Context Protocol) is an open standard created by Anthropic. It defines a common language between:
- **MCP Clients** — AI editors (Cursor, VS Code Copilot, Claude Code, Windsurf)
- **MCP Servers** — your code, exposing capabilities the AI can use
The protocol defines how a client discovers what a server can do, and how it calls those capabilities. Think of it like REST, but designed to be consumed by an AI model rather than a human-built app.
### The flow, step by step
```
You type in editor chat:
"What todos do I have?"
│
▼
AI Model (Copilot / Cursor / Claude)
- has a list of available tools from your MCP server
- decides list_todos is relevant
- decides to call it
│
▼
MCP Client (inside the editor)
- sends the request to your server
- POST http://localhost:3001/mcp
- body: { method: "tools/call", name: "list_todos", arguments: {} }
│
▼
Your MCP Server (src/mcp/server.ts)
- receives the call
- runs: repo.findAll()
- queries SQLite
│
▼
Response travels back up through the same chain
│
▼
AI model reads the result and answers:
"You have 3 todos: Buy milk, Fix the login bug, Write tests."
```
The user never sees any of the middle steps. It feels like the AI just knows.
### How this repo is structured around it
The MCP server is not the whole app — it is an add-on layer over an existing API.
```
SQLite database
│
▼
TodoRepository ← single source of truth (src/repository/)
│
├──────────────────────────────────┐
▼ ▼
REST API (/api/todos) MCP Server (/mcp)
src/api/ src/mcp/
│ │
▼ ▼
Browser / frontend AI editors
(humans use this) (Copilot, Cursor, Claude use this)
```
The same `TodoRepository` powers both. The data never duplicates. The only difference is the interface on top.
### Tools vs Resources
MCP exposes two types of things:
**Tools** — actions the AI can invoke. A tool is a function the AI calls when it decides the tool is relevant. Each tool has a name, a description (plain English the AI reads to decide when to use it), and an input schema.
```typescript
{
name: "add_todo",
description: "Create a new todo item.",
inputSchema: {
type: "object",
properties: {
title: { type: "string", description: "Short title for the todo" },
description: { type: "string", description: "Optional longer description" },
},
required: ["title"],
},
}
```
The description is not documentation for humans — it is the signal the AI uses to decide *whether* and *how* to call the tool. Good descriptions = better AI decisions.
**Resources** — read-only data the AI can fetch, identified by a URI.
```
todos://all → all todos as a JSON array
todos://active → only active todos as a JSON array
```
### The session handshake
MCP over HTTP is stateful. Before any tool can be called, a session must be established:
```
1. Client → initialize
{ protocolVersion, clientInfo, capabilities }
2. Server → 200 OK
mcp-session-id: <uuid> ← in response header
{ protocolVersion, serverInfo, capabilities }
3. Client → notifications/initialized
(tells the server "I received your response, I'm ready")
4. Client → tools/list
(asks "what tools do you have?")
5. Server → { tools: [...] }
(returns all tool definitions with descriptions and schemas)
6+. Client → tools/call (repeated as needed during the conversation)
Server → { content: [{ type: "text", text: "..." }] }
```
The session ID from step 2 must be sent as the `mcp-session-id` header on every subsequent request. In this repo, sessions are tracked in a `Map` in `src/index.ts`.
### Why the response format looks different from REST
REST returns whatever JSON shape you want. MCP tool responses always follow this shape:
```json
{
"content": [
{ "type": "text", "text": "Your result here" }
]
}
```
The AI model reads the `text` field and incorporates it into its reply to the user. You never return raw JSON from a tool — you return text the AI can reason about.
### What the AI does with tool descriptions
When an editor connects, it calls `tools/list` once and gets back all your tool definitions. From that point on, when a user asks something, the model decides on its own:
- Does any tool seem relevant to this request?
- If yes, what arguments should I pass based on what the user said?
- Do I need to call multiple tools in sequence?
You never hardcode "call list_todos when the user asks about todos." The model figures it out from the description you wrote.
### Concept glossary
| Concept | What it is |
|---|---|
| MCP | A protocol for AI models to call external tools and read data |
| MCP Server | Your code, exposing tools and resources the AI can use |
| MCP Client | The editor (Cursor, Copilot, Claude) that connects to your server |
| Tool | A function the AI can call — has a name, description, and input schema |
| Resource | Read-only data the AI can fetch, identified by a URI |
| Session | One connected editor instance, tracked by a session ID |
| `tools/list` | The handshake step where the AI discovers what your server can do |
| `tools/call` | The AI actually invoking one of your tools |
| Description | Plain English the AI reads to decide when and how to use a tool |
This server cannot be deployed
Maintenance
ActivityInactive
ResponsivenessNo issues