npm install
npm run build
npm start

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

POST /api/todos
Content-Type: application/json

{ "title": "Buy milk", "description": "From the corner store" }

{
  "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"
  }
}

{
  "data": [ { "id": "...", "title": "...", "completed": false, ... } ],
  "count": 1
}

{ "error": "title is required" }

{
  "mcpServers": {
    "todo": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

{
  "servers": {
    "todo": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

{
  "mcp": {
    "servers": {
      "todo": {
        "type": "http",
        "url": "http://localhost:3001/mcp"
      }
    }
  }
}

{
  "mcpServers": {
    "todo": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

claude mcp add --transport http todo http://localhost:3001/mcp

{
  "mcpServers": {
    "todo": {
      "serverUrl": "http://localhost:3001/mcp"
    }
  }
}

npm run studio

npm test          # run once
npm run test:watch  # watch mode

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

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."

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)

{
  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"],
  },
}

todos://all     →  all todos as a JSON array
todos://active  →  only active todos as a JSON array

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: "..." }] }

{
  "content": [
    { "type": "text", "text": "Your result here" }
  ]
}