@ankimcp/anki-mcp-server 0.8.0

package/README.md

@@ -0,0 +1,756 @@
+# Anki MCP Server
+
+[![Tests](https://github.com/ankimcp/anki-mcp-server/actions/workflows/test.yml/badge.svg)](https://github.com/ankimcp/anki-mcp-server/actions/workflows/test.yml)
+[![npm version](https://badge.fury.io/js/@ankimcp%2Fanki-mcp-server.svg)](https://www.npmjs.com/package/@ankimcp/anki-mcp-server)
+
+<div align="center">
+  <img src="./docs/images/ankimcp.png" alt="Anki + MCP Integration" width="600" />
+
+  <p><strong>Seamlessly integrate <a href="https://apps.ankiweb.net">Anki</a> with AI assistants through the <a href="https://modelcontextprotocol.io">Model Context Protocol</a></strong></p>
+</div>
+
+**Beta** - This project is in active development. APIs and features may change.
+
+A Model Context Protocol (MCP) server that enables AI assistants to interact with Anki, the spaced repetition flashcard application.
+
+Transform your Anki experience with natural language interaction - like having a private tutor. The AI assistant doesn't just present questions and answers; it can explain concepts, make the learning process more engaging and human-like, provide context, and adapt to your learning style. It can create and edit notes on the fly, turning your study sessions into dynamic conversations. More features coming soon!
+
+## Examples and Tutorials
+
+For comprehensive guides, real-world examples, and step-by-step tutorials on using this MCP server with Claude Desktop, visit:
+
+**[ankimcp.ai](https://ankimcp.ai)** - Complete documentation with practical examples and use cases
+
+## Available Tools
+
+### Review & Study
+- `sync` - Sync with AnkiWeb
+- `get_due_cards` - Get cards for review
+- `present_card` - Show card for review
+- `rate_card` - Rate card performance
+
+### Deck Management
+- `list_decks` - Show available decks
+- `createDeck` - Create new decks
+
+### Note Management
+- `addNote` - Create new notes
+- `findNotes` - Search for notes using Anki query syntax
+- `notesInfo` - Get detailed information about notes (fields, tags, CSS)
+- `updateNoteFields` - Update existing note fields (CSS-aware, supports HTML)
+- `deleteNotes` - Delete notes and their cards
+
+### Media Management
+- `mediaActions` - Manage media files (audio/images)
+  - `storeMediaFile` - Upload media from base64 data, file paths, or URLs
+  - `retrieveMediaFile` - Download media as base64
+  - `getMediaFilesNames` - List media files with optional pattern filtering
+  - `deleteMediaFile` - Remove media files
+
+**💡 Best Practice for Images:**
+- ✅ **Use file paths** (e.g., `/Users/you/image.png`) - Fast and efficient
+- ✅ **Use URLs** (e.g., `https://example.com/image.jpg`) - Direct download
+- ❌ **Avoid base64** - Extremely slow and token-inefficient
+
+Just tell Claude where the image is, and it will handle the upload automatically using the most efficient method.
+
+### Model/Template Management
+- `modelNames` - List note types
+- `modelFieldNames` - Get fields for a note type
+- `modelStyling` - Get CSS styling for a note type
+
+## Prerequisites
+
+- [Anki](https://apps.ankiweb.net/) with [AnkiConnect](https://github.com/FooSoft/anki-connect) plugin installed
+- Node.js 20+
+
+## Installation
+
+This server works in two modes:
+
+- **Local mode (STDIO)** - For Claude Desktop on your computer (recommended for most users)
+- **Remote mode (HTTP)** - For web-based AI assistants like ChatGPT or Claude.ai
+
+### Option 1: MCPB Bundle (Recommended - Local Mode)
+
+The easiest way to install this MCP server for Claude Desktop:
+
+1. Download the latest `.mcpb` bundle from the [Releases](https://github.com/ankimcp/anki-mcp-server/releases) page
+2. In Claude Desktop, install the extension:
+   - **Method 1**: Go to Settings → Extensions, then drag and drop the `.mcpb` file
+   - **Method 2**: Go to Settings → Developer → Extensions → Install Extension, then select the `.mcpb` file
+3. Configure AnkiConnect URL if needed (defaults to `http://localhost:8765`)
+4. Restart Claude Desktop
+
+That's it! The bundle includes everything needed to run the server locally.
+
+### Option 2: NPM Package with STDIO (For Other MCP Clients)
+
+Want to use Anki with MCP clients like **Cursor IDE**, **Cline**, or **Zed Editor**? Use the npm package with the `--stdio` flag:
+
+**Supported Clients:**
+- [Cursor IDE](https://www.cursor.com/) - AI-powered code editor
+- [Cline](https://github.com/cline/cline) - VS Code extension for AI assistance
+- [Zed Editor](https://zed.dev/) - Fast, modern code editor
+- Other MCP clients that support STDIO transport
+
+**Configuration - Choose one method:**
+
+**Method 1: Using npx (recommended - no installation needed)**
+
+```json
+{
+  "mcpServers": {
+    "anki-mcp": {
+      "command": "npx",
+      "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio"],
+      "env": {
+        "ANKI_CONNECT_URL": "http://localhost:8765"
+      }
+    }
+  }
+}
+```
+
+**Method 2: Using global installation**
+
+First, install globally:
+```bash
+npm install -g @ankimcp/anki-mcp-server
+```
+
+Then configure:
+```json
+{
+  "mcpServers": {
+    "anki-mcp": {
+      "command": "@ankimcp/anki-mcp-server",
+      "args": ["--stdio"],
+      "env": {
+        "ANKI_CONNECT_URL": "http://localhost:8765"
+      }
+    }
+  }
+}
+```
+
+**Configuration file locations:**
+- **Cursor IDE**: `~/.cursor/mcp.json` (macOS/Linux) or `%USERPROFILE%\.cursor\mcp.json` (Windows)
+- **Cline**: Accessible via settings UI in VS Code
+- **Zed Editor**: Install as MCP extension through extension marketplace
+
+For client-specific features and troubleshooting, consult your MCP client's documentation.
+
+### Option 3: HTTP Mode (For Remote AI Assistants)
+
+Want to use Anki with ChatGPT or Claude.ai in your browser? This mode lets you connect web-based AI tools to your local Anki.
+
+**How it works (simple explanation):**
+1. You run a small server on your computer (where Anki is installed)
+2. Use the built-in `--ngrok` flag to automatically create a public tunnel URL
+3. Share that URL with ChatGPT or Claude.ai
+4. Now the AI can talk to your Anki through the internet!
+
+**New in v0.8.0:** Integrated ngrok support with the `--ngrok` flag - no need to run ngrok separately!
+
+**Setup - Choose one method:**
+
+**Method 1: Using npx (recommended - no installation needed)**
+
+```bash
+# Quick start
+npx @ankimcp/anki-mcp-server
+
+# With ngrok tunnel (recommended for web-based AI)
+npx @ankimcp/anki-mcp-server --ngrok
+
+# With custom options
+npx @ankimcp/anki-mcp-server --port 8080 --host 0.0.0.0
+npx @ankimcp/anki-mcp-server --anki-connect http://localhost:8765
+```
+
+**Method 2: Using global installation**
+
+```bash
+# Install once
+npm install -g @ankimcp/anki-mcp-server
+
+# Run the server
+@ankimcp/anki-mcp-server
+
+# With ngrok tunnel (recommended for web-based AI)
+@ankimcp/anki-mcp-server --ngrok
+
+# With custom options
+@ankimcp/anki-mcp-server --port 8080 --host 0.0.0.0
+@ankimcp/anki-mcp-server --anki-connect http://localhost:8765
+```
+
+**Method 3: Install from source (for development)**
+
+```bash
+npm install
+npm run build
+npm run start:prod:http
+```
+
+**CLI Options:**
+
+```bash
+@ankimcp/anki-mcp-server [options]
+
+Options:
+  --stdio                        Run in STDIO mode (for MCP clients)
+  -p, --port <port>              Port to listen on (HTTP mode, default: 3000)
+  -h, --host <host>              Host to bind to (HTTP mode, default: 127.0.0.1)
+  -a, --anki-connect <url>       AnkiConnect URL (default: http://localhost:8765)
+  --ngrok                        Start ngrok tunnel (requires global ngrok installation)
+  --help                         Show help message
+
+Usage with npx (no installation needed):
+  npx @ankimcp/anki-mcp-server                        # HTTP mode
+  npx @ankimcp/anki-mcp-server --port 8080            # Custom port
+  npx @ankimcp/anki-mcp-server --stdio                # STDIO mode
+  npx @ankimcp/anki-mcp-server --ngrok                # HTTP mode with ngrok tunnel
+
+Usage with global installation:
+  npm install -g @ankimcp/anki-mcp-server             # Install once
+  @ankimcp/anki-mcp-server                            # HTTP mode
+  @ankimcp/anki-mcp-server --port 8080                # Custom port
+  @ankimcp/anki-mcp-server --stdio                    # STDIO mode
+  @ankimcp/anki-mcp-server --ngrok                    # HTTP mode with ngrok tunnel
+```
+
+**Using with ngrok:**
+
+**Method 1: Integrated (Recommended - One Command)**
+
+```bash
+# One-time setup (if you haven't already):
+npm install -g ngrok
+ngrok config add-authtoken <your-token>  # Get token from https://dashboard.ngrok.com
+
+# Start server with ngrok tunnel in one command:
+@ankimcp/anki-mcp-server --ngrok
+
+# The tunnel URL will be displayed in the startup banner
+# Example output:
+# 🌐 Ngrok tunnel: https://abc123.ngrok-free.app
+```
+
+**Method 2: Manual (Two Terminals)**
+
+```bash
+# Terminal 1: Start the server
+@ankimcp/anki-mcp-server
+
+# Terminal 2: Create tunnel
+ngrok http 3000
+
+# Copy the ngrok URL (looks like: https://abc123.ngrok-free.app)
+# Share this URL with your AI assistant
+```
+
+**Benefits of `--ngrok` flag:**
+- ✅ One command instead of two terminals
+- ✅ Automatic cleanup when you press Ctrl+C
+- ✅ URL displayed directly in the startup banner
+- ✅ Works with custom ports: `@ankimcp/anki-mcp-server --port 8080 --ngrok`
+
+**Security note:** Anyone with your ngrok URL can access your Anki, so keep that URL private!
+
+### Option 4: Manual Installation from Source (Local Mode)
+
+For development or advanced usage:
+
+```bash
+npm install
+npm run build
+```
+
+## Connect to Claude Desktop (Local Mode)
+
+You can configure the server in Claude Desktop by either:
+- Going to: Settings → Developer → Edit Config
+- Or manually editing the config file
+
+### Configuration
+
+Add the following to your Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "anki-mcp": {
+      "command": "node",
+      "args": ["/path/to/anki-mcp-server/dist/main-stdio.js"],
+      "env": {
+        "ANKI_CONNECT_URL": "http://localhost:8765"
+      }
+    }
+  }
+}
+```
+
+Replace `/path/to/anki-mcp-server` with your actual project path.
+
+### Config File Locations
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+For more details, see the [official MCP documentation](https://modelcontextprotocol.io/docs/develop/connect-local-servers).
+
+## Environment Variables (Optional)
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ANKI_CONNECT_URL` | AnkiConnect URL | `http://localhost:8765` |
+| `ANKI_CONNECT_API_VERSION` | API version | `6` |
+| `ANKI_CONNECT_API_KEY` | API key if configured in AnkiConnect | - |
+| `ANKI_CONNECT_TIMEOUT` | Request timeout in ms | `5000` |
+
+## Usage Examples
+
+### Searching and Updating Notes
+
+```
+# Search for notes in a specific deck
+findNotes(query: "deck:Spanish")
+
+# Get detailed information about notes
+notesInfo(notes: [1234567890, 1234567891])
+
+# Update a note's fields (HTML content supported)
+updateNoteFields(note: {
+  id: 1234567890,
+  fields: {
+    "Front": "<b>¿Cómo estás?</b>",
+    "Back": "How are you?"
+  }
+})
+
+# Delete notes (requires confirmation)
+deleteNotes(notes: [1234567890], confirmDeletion: true)
+```
+
+### Anki Query Syntax Examples
+
+The `findNotes` tool supports Anki's powerful query syntax:
+
+- `"deck:DeckName"` - All notes in a specific deck
+- `"tag:important"` - Notes with the "important" tag
+- `"is:due"` - Cards that are due for review
+- `"is:new"` - New cards that haven't been studied
+- `"added:7"` - Notes added in the last 7 days
+- `"front:hello"` - Notes with "hello" in the front field
+- `"flag:1"` - Notes with red flag
+- `"prop:due<=2"` - Cards due within 2 days
+- `"deck:Spanish tag:verb"` - Spanish deck notes with verb tag (AND)
+- `"deck:Spanish OR deck:French"` - Notes from either deck
+
+### Important Notes
+
+#### CSS and HTML Handling
+- The `notesInfo` tool returns CSS styling information for proper rendering awareness
+- The `updateNoteFields` tool supports HTML content in fields and preserves CSS styling
+- Each note model has its own CSS styling - use `modelStyling` to get model-specific CSS
+
+#### Update Warning
+⚠️ **IMPORTANT**: When using `updateNoteFields`, do NOT view the note in Anki's browser while updating, or the fields will not update properly. Close the browser or switch to a different note before updating.
+
+#### Deletion Safety
+The `deleteNotes` tool requires explicit confirmation (`confirmDeletion: true`) to prevent accidental deletions. Deleting a note removes ALL associated cards permanently.
+
+## Development
+
+### Transport Modes
+
+This server supports two MCP transport modes via **separate entry points**:
+
+#### STDIO Mode (Default)
+- For local MCP clients like Claude Desktop
+- Uses standard input/output for communication
+- **Entry point**: `dist/main-stdio.js`
+- **Run**: `npm run start:prod:stdio` or `node dist/main-stdio.js`
+- **MCPB bundle**: Uses STDIO mode
+
+#### HTTP Mode (Streamable HTTP)
+- For remote MCP clients and web-based integrations
+- Uses MCP Streamable HTTP protocol
+- **Entry point**: `dist/main-http.js`
+- **Run**: `npm run start:prod:http` or `node dist/main-http.js`
+- **Default port**: 3000 (configurable via `PORT` env var)
+- **Default host**: `127.0.0.1` (configurable via `HOST` env var)
+- **MCP endpoint**: `http://127.0.0.1:3000/` (root path)
+
+#### Building
+
+```bash
+npm run build  # Builds once, creates dist/ with both entry points
+```
+
+Both `main-stdio.js` and `main-http.js` are in the same `dist/` directory. Choose which to run based on your needs.
+
+#### HTTP Mode Configuration
+
+**Environment Variables:**
+- `PORT` - HTTP server port (default: 3000)
+- `HOST` - Bind address (default: 127.0.0.1 for localhost-only)
+- `ALLOWED_ORIGINS` - Comma-separated list of allowed origins for CORS (default: localhost)
+- `LOG_LEVEL` - Logging level (default: info)
+
+**Security:**
+- Origin header validation (prevents DNS rebinding attacks)
+- Binds to localhost (127.0.0.1) by default
+- No authentication in current version (OAuth support planned)
+
+**Example: Running Modes**
+```bash
+# Development - STDIO mode (watch mode with auto-rebuild)
+npm run start:dev:stdio
+
+# Development - HTTP mode (watch mode with auto-rebuild)
+npm run start:dev:http
+
+# Production - STDIO mode
+npm run start:prod:stdio
+# or
+node dist/main-stdio.js
+
+# Production - HTTP mode
+npm run start:prod:http
+# or
+PORT=8080 HOST=0.0.0.0 node dist/main-http.js
+```
+
+### Building an MCPB Bundle
+
+To create a distributable MCPB bundle:
+
+```bash
+npm run mcpb:bundle
+```
+
+This command will:
+1. Sync version from `package.json` to `manifest.json`
+2. Remove old `.mcpb` files
+3. Build the TypeScript project
+4. Package `dist/` and `node_modules/` into an `.mcpb` file
+
+The output file will be named based on the current version (e.g., `@ankimcp/anki-mcp-server-0.5.0.mcpb`) and can be distributed for one-click installation.
+
+#### What Gets Bundled
+
+The MCPB package includes:
+- Compiled JavaScript (`dist/` directory - includes both entry points)
+- All dependencies (`node_modules/`)
+- Package metadata (`package.json`)
+- Manifest configuration (`manifest.json` - configured to use `main-stdio.js`)
+- Icon (`icon.png`)
+
+Source files, tests, and development configs are automatically excluded via `.mcpbignore`.
+
+### Logging in Claude Desktop
+
+When running as an MCPB extension in Claude Desktop, logs are written to:
+
+**Log Location**: `~/Library/Logs/Claude/` (macOS)
+
+The logs are split across multiple files:
+- **main.log** - General Claude Desktop application logs
+- **mcp-server-Anki MCP Server.log** - MCP protocol messages for this extension
+- **mcp.log** - Combined MCP logs from all servers
+
+**Note**: The pino logger output (INFO, ERROR, WARN messages from the server code) goes to stderr and appears in the MCP-specific log files. Claude Desktop determines which log file receives which messages, but generally:
+- Application startup and MCP protocol communication → MCP-specific log
+- Server internal logging (pino) → Both MCP-specific log and sometimes main.log
+
+To view logs in real-time:
+```bash
+tail -f ~/Library/Logs/Claude/mcp-server-Anki\ MCP\ Server.log
+```
+
+### Debugging the MCP Server
+
+You can debug the MCP server using the MCP Inspector and attaching a debugger from your IDE (WebStorm, VS Code, etc.).
+
+**Note for HTTP Mode:** When testing HTTP mode (Streamable HTTP) with MCP Inspector, use "Connection Type: Via Proxy" to avoid CORS errors.
+
+#### Step 1: Configure Debug Server in MCP Inspector
+
+The `mcp-inspector-config.json` already includes a debug server configuration:
+
+```json
+{
+  "mcpServers": {
+    "stdio-server-debug": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["--inspect-brk=9229", "dist/main-stdio.js"],
+      "env": {
+        "MCP_SERVER_NAME": "anki-mcp-stdio-debug",
+        "MCP_SERVER_VERSION": "1.0.0",
+        "LOG_LEVEL": "debug"
+      },
+      "note": "Anki MCP server with debugging enabled on port 9229"
+    }
+  }
+}
+```
+
+#### Step 2: Start the Debug Server
+
+Run the MCP Inspector with the debug server:
+
+```bash
+npm run inspector:debug
+```
+
+This will start the server with Node.js debugging enabled on port 9229 and pause execution at the first line.
+
+#### Step 3: Attach Debugger from Your IDE
+
+##### WebStorm
+1. Go to **Run → Edit Configurations**
+2. Add a new **Attach to Node.js/Chrome** configuration
+3. Set the port to `9229`
+4. Click **Debug** to attach
+
+##### VS Code
+1. Open the Debug panel (Ctrl+Shift+D / Cmd+Shift+D)
+2. Select **Debug MCP Server (Attach)** configuration
+3. Press F5 to attach
+
+#### Step 4: Set Breakpoints and Debug
+
+Once attached, you can:
+- Set breakpoints in your TypeScript source files
+- Step through code execution
+- Inspect variables and call stack
+- Use the debug console for evaluating expressions
+
+The debugger will work with source maps, allowing you to debug the original TypeScript code rather than the compiled JavaScript.
+
+### Debugging with Claude Desktop
+
+You can also debug the MCP server while it runs inside Claude Desktop by enabling the Node.js debugger and attaching your IDE.
+
+#### Step 1: Configure Claude Desktop for Debugging
+
+Update your Claude Desktop config to enable debugging:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+**Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "anki-mcp": {
+      "command": "node",
+      "args": [
+        "--inspect=9229",
+        "<path_to_project>/anki-mcp-server/dist/main-stdio.js"
+      ],
+      "env": {
+        "ANKI_CONNECT_URL": "http://localhost:8765"
+      }
+    }
+  }
+}
+```
+
+**Key change**: Add `--inspect=9229` before the path to `dist/main-stdio.js`
+
+**Debug options**:
+- `--inspect=9229` - Start debugger immediately, doesn't block (recommended)
+- `--inspect-brk=9229` - Pause execution until debugger attaches (for debugging startup issues)
+
+#### Step 2: Restart Claude Desktop
+
+After saving the config, restart Claude Desktop. The MCP server will now run with debugging enabled on port 9229.
+
+#### Step 3: Attach Debugger from Your IDE
+
+##### WebStorm
+
+1. Go to **Run → Edit Configurations**
+2. Click the **+** button and select **Attach to Node.js/Chrome**
+3. Configure:
+   - **Name**: `Attach to Anki MCP (Claude Desktop)`
+   - **Host**: `localhost`
+   - **Port**: `9229`
+   - **Attach to**: `Node.js < 8` or `Chrome or Node.js > 6.3` (depending on WebStorm version)
+4. Click **OK**
+5. Click **Debug** (Shift+F9) to attach
+
+##### VS Code
+
+1. Add to `.vscode/launch.json`:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "attach",
+      "name": "Attach to Anki MCP (Claude Desktop)",
+      "port": 9229,
+      "skipFiles": ["<node_internals>/**"],
+      "sourceMaps": true,
+      "outFiles": ["${workspaceFolder}/dist/**/*.js"]
+    }
+  ]
+}
+```
+
+2. Open the Debug panel (Ctrl+Shift+D / Cmd+Shift+D)
+3. Select **Attach to Anki MCP (Claude Desktop)**
+4. Press F5 to attach
+
+#### Step 4: Debug in Real-Time
+
+Once attached, you can:
+- Set breakpoints in your TypeScript source files (e.g., `src/mcp/primitives/essential/tools/create-model.tool.ts`)
+- Use Claude Desktop normally - breakpoints will hit when tools are invoked
+- Step through code execution
+- Inspect variables and call stack
+- Use the debug console
+
+**Example**: Set a breakpoint in `create-model.tool.ts` at line 119, then ask Claude to create a new model. The debugger will pause at your breakpoint!
+
+**Note**: The debugger stays attached as long as Claude Desktop is running. You can detach/reattach anytime without restarting Claude Desktop.
+
+### Build Commands
+
+```bash
+npm run build              # Build the project (compile TypeScript to JavaScript)
+npm run start:dev:stdio    # STDIO mode with watch (auto-rebuild)
+npm run start:dev:http     # HTTP mode with watch (auto-rebuild)
+npm run type-check         # Run TypeScript type checking
+npm run lint               # Run ESLint
+npm run mcpb:bundle        # Sync version, clean, build, and create MCPB bundle
+```
+
+### NPM Package Testing (Local)
+
+Test the npm package locally before publishing:
+
+```bash
+# 1. Create local package
+npm run pack:local         # Builds and creates @ankimcp/anki-mcp-server-*.tgz
+
+# 2. Install globally from local package
+npm run install:local      # Installs from ./@ankimcp/anki-mcp-server-*.tgz
+
+# 3. Test the command
+ankimcp                    # Runs HTTP server on port 3000
+
+# 4. Uninstall when done testing
+npm run uninstall:local    # Removes global installation
+```
+
+**How it works:**
+- `npm pack` creates a `.tgz` file identical to what npm publish would create
+- Installing from `.tgz` simulates what users get from `npm install -g ankimcp`
+- This lets you test the full user experience before publishing to npm
+
+### Testing Commands
+
+```bash
+npm test              # Run all tests
+npm run test:unit     # Run unit tests only
+npm run test:tools    # Run tool-specific tests
+npm run test:workflows # Run workflow integration tests
+npm run test:e2e      # Run end-to-end tests
+npm run test:cov      # Run tests with coverage report
+npm run test:watch    # Run tests in watch mode
+npm run test:debug    # Run tests with debugger
+npm run test:ci       # Run tests for CI (silent, with coverage)
+```
+
+### Test Coverage
+
+The project maintains 70% minimum coverage thresholds for:
+- Branches
+- Functions
+- Lines
+- Statements
+
+Coverage reports are generated in the `coverage/` directory.
+
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/) with a pre-1.0 development approach:
+
+- **0.x.x** - Beta/Development versions (current phase)
+  - **0.1.x** - Bug fixes and patches
+  - **0.2.0+** - New features or minor improvements
+  - **Breaking changes** are acceptable in 0.x versions
+
+- **1.0.0** - First stable release
+  - Will be released when the API is stable and tested
+  - Breaking changes will require major version bumps (2.0.0, etc.)
+
+**Current Status**: `0.8.0` - Active beta development. New features include integrated ngrok tunneling (`--ngrok` flag), the `twenty_rules` prompt for evidence-based flashcard creation, media file management, and improved prompt system. APIs may change based on feedback and testing.
+
+## Similar Projects
+
+If you're exploring Anki MCP integrations, here are other projects in this space:
+
+### [scorzeth/anki-mcp-server](https://github.com/scorzeth/anki-mcp-server)
+- **Status**: Appears to be abandoned (no recent updates)
+- Early implementation of Anki MCP integration
+
+### [nailuoGG/anki-mcp-server](https://github.com/nailuoGG/anki-mcp-server)
+- **Approach**: Lightweight, single-file implementation
+- **Architecture**: Procedural code structure with all tools in one file
+- **Good for**: Simple use cases, minimal dependencies
+
+**Why this project differs:**
+- **Enterprise-grade architecture**: Built on NestJS with dependency injection
+- **Modular design**: Each tool is a separate class with clear separation of concerns
+- **Maintainability**: Easy to extend with new features without touching existing code
+- **Testing**: Comprehensive test suite with 70% coverage requirement
+- **Type safety**: Strict TypeScript with Zod validation
+- **Error handling**: Robust error handling with helpful user feedback
+- **Production-ready**: Proper logging, progress reporting, and MCPB bundle support
+- **Scalability**: Can easily grow from basic tools to complex workflows
+
+**Use case**: If you need a solid foundation for building advanced Anki integrations or plan to extend functionality significantly, this project's architectural approach makes it easier to maintain and scale over time.
+
+## Useful Links
+
+- [Model Context Protocol Documentation](https://modelcontextprotocol.io/docs)
+- [AnkiConnect API Documentation](https://git.sr.ht/~foosoft/anki-connect)
+- [Claude Desktop Download](https://claude.ai/download)
+- [Building Desktop Extensions (Anthropic Blog)](https://www.anthropic.com/engineering/desktop-extensions)
+- [MCP Servers Repository](https://github.com/modelcontextprotocol/servers)
+- [NestJS Documentation](https://docs.nestjs.com)
+- [Anki Official Website](https://apps.ankiweb.net/)
+
+## License & Attribution
+
+This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).
+
+### Why AGPL-3.0?
+
+This license was chosen to maintain compatibility with Anki's AGPL-3.0 license for potential future integration scenarios.
+
+**What this means:**
+- **Personal use**: Use the software freely
+- **Running as a service for others**: You must provide source code access (AGPL Section 13)
+- **Modifying and distributing**: Share your improvements under AGPL-3.0-or-later
+
+For complete license terms, see the [LICENSE](LICENSE) file.
+
+### Third-Party Attributions
+
+- **Anki®** is a registered trademark of Ankitects Pty Ltd. This project is an unofficial third-party tool and is not affiliated with, endorsed by, or sponsored by Ankitects Pty Ltd. The Anki logo is used under the alternative license for referencing Anki with a link to [https://apps.ankiweb.net](https://apps.ankiweb.net). For the official Anki application, visit [https://apps.ankiweb.net](https://apps.ankiweb.net).
+
+- **Model Context Protocol (MCP)** is an open standard by Anthropic. The MCP logo is from the official [MCP documentation repository](https://github.com/modelcontextprotocol/docs) and is used under the MIT License. For more information about MCP, visit [https://modelcontextprotocol.io](https://modelcontextprotocol.io).
+
+- This is an independent project that bridges Anki and MCP technologies. All trademarks, service marks, trade names, product names, and logos are the property of their respective owners.