19 mcp server skeleton wrapping rest api

.commitlintrc.json

@@ -1,3 +1,6 @@
 {
-  "extends": ["@commitlint/config-conventional"]
+  "extends": ["@commitlint/config-conventional"],
+  "rules": {
+    "header-max-length": [0, "always", 100]
+  }
 }

.env.example

@@ -57,3 +57,9 @@ FRONTEND_URL=http://localhost:5173
 # If unset, falls back to FRONTEND_URL.
 # Local dev: http://localhost:5173   Prod: https://app.your-domain.com,https://staging.your-domain.com
 TRUSTED_ORIGINS=
+
+# ── MCP SERVER ────────────────────────────────────────────────────────────
+
+# API key used by the MCP server to authenticate against the REST API (ak_ prefix)
+# Generate one in the web UI under Account → API Keys
+MCP_API_KEY=

README.md

@@ -91,6 +91,38 @@ Account management endpoints (`/v1/me/*`) use the session cookie set by [Better
 
 ---
 
+## MCP integration (LLM → Anki)
+
+The MCP server lets any LLM (Claude Desktop, API clients) manage your decks and notes directly:
+
+```
+User: "Create flashcards from this discussion"
+LLM:  "<calls create_notes_bulk> → cards appear in Anki instantly"
+```
+
+**Claude Desktop setup** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "anki-cloud": {
+      "command": "bun",
+      "args": ["run", "/path/to/anki-cloud/mcp/src/index.ts"],
+      "env": {
+        "API_URL": "http://localhost:3000",
+        "API_KEY": "ak_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Generate an API key in the web UI under **Account → API Keys**, replace the path and key, then restart Claude Desktop.
+
+Full setup guide, available tools, and Docker deployment: [docs/mcp-integration.md](docs/mcp-integration.md)
+
+---
+
 ## Connecting Anki Desktop
 
 In Anki: **Preferences → Syncing → Self-hosted sync server**, set the URL to:
@@ -151,8 +183,9 @@ cd e2e && bun test
 ## Project structure
 
 ```
-api/        REST API — TypeScript / Hono on Bun  (shared workspace with db/)
+api/        REST API — TypeScript / Hono on Bun  (shared workspace with db/ and mcp/)
 db/         Drizzle ORM + SQLite schema (@anki-cloud/db)
+mcp/        MCP server — wraps REST API, 8 tools for LLM integration
 web/        Account management UI (Vite + React)  (standalone — cd web && bun install)
 e2e/        End-to-end tests                      (standalone — cd e2e && bun install)
 docs/       Architecture decisions (ADRs) + narrative docs

api/Dockerfile

@@ -5,6 +5,7 @@ WORKDIR /app
 COPY package.json ./
 COPY api/package.json ./api/
 COPY db/package.json ./db/
+COPY mcp/package.json ./mcp/
 COPY bun.lock ./
 
 RUN bun install --frozen-lockfile

docker-compose.yml

@@ -39,5 +39,17 @@ services:
     depends_on:
       - anki-sync-server
 
+  mcp:
+    build:
+      context: .
+      dockerfile: mcp/Dockerfile
+    ports:
+      - "3001:3001"
+    environment:
+      API_URL: http://api:3000
+      API_KEY: ${MCP_API_KEY}
+    depends_on:
+      - api
+
 volumes:
   app-data: