@ankimcp/anki-mcp-server 0.18.5 → 0.19.1

package/README.md

@@ -1,16 +1,5 @@
 # Anki MCP Server
 
-> **⚠️ IMPORTANT: Project Renamed (v0.8.2+)**
->
-> This project has been renamed and moved:
-> - **Package**: `anki-mcp-http` → `@ankimcp/anki-mcp-server`
-> - **Commands**: `anki-mcp-http` → `ankimcp` or `anki-mcp-server`
-> - **Repository**: `anki-mcp/anki-mcp-desktop` → `ankimcp/anki-mcp-server`
->
-> The old `anki-mcp-http` package continues to be published for backward compatibility but is deprecated. Please migrate to the new package.
->
-> **[Read more about this change →](https://ankimcp.ai/blog/organization-and-naming-update/)**
-
 [![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)
 
@@ -46,38 +35,43 @@ Three representative prompts showing the tool flows this server enables:
 
 ## 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
-- `listDecks` - List all decks with optional statistics
-- `deckStats` - Get comprehensive deck statistics (counts, ease/interval distributions)
-- `createDeck` - Create a new empty deck (max 2 levels: "Parent::Child")
-- `changeDeck` - Move cards to a different deck
-
-### Note Management
-- `addNote` - Create a single note
-- `addNotes` - Create multiple notes in batch (up to 100, partial success supported)
-- `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
-
-### Tag Management
-- `getTags` - Discover all tags in the collection (use first to avoid duplication)
-- `addTags` - Add space-separated tags to notes
-- `removeTags` - Remove space-separated tags from notes
-- `replaceTags` - Rename a tag across notes
-- `clearUnusedTags` - Remove orphaned tags from the collection (destructive)
-
-### Media Management
-- `getMediaFilesNames` - List media files with optional pattern filtering
-- `retrieveMediaFile` - Download media as base64
-- `storeMediaFile` - Upload media from base64 data, file paths, or URLs
-- `deleteMediaFile` - Remove media files (destructive)
+The server exposes **42 MCP tools** — 31 essential tools for everyday Anki operations and 11 GUI tools that drive the Anki desktop interface for note editing/creation workflows.
+
+### Essential Tools
+
+#### Review & Study
+- `sync` - Sync with AnkiWeb to pull latest data and push changes
+- `get_due_cards` - Get cards that are due for review, optionally filtered by deck
+- `get_cards` - Get cards with flexible filtering by state (due, new, learning, suspended, buried) and deck
+- `present_card` - Show a card for review with its question/front side
+- `rate_card` - Rate card performance (Again, Hard, Good, Easy) and schedule the next review
+
+#### Deck Management
+- `listDecks` - List all decks, optionally with per-deck card-count statistics
+- `deckStats` - Get comprehensive statistics for a single deck (counts, ease/interval distributions)
+- `createDeck` - Create a new empty deck (supports `Parent::Child`, max 2 levels)
+- `changeDeck` - Move cards to a different deck (created if it doesn't exist)
+
+#### Note Management
+- `addNote` - Create a single note with specified fields and tags
+- `addNotes` - Batch-create up to 100 notes sharing a deck and model (partial success supported)
+- `findNotes` - Search for notes using Anki query syntax (`deck:`, `tag:`, `is:due`, etc.)
+- `notesInfo` - Get detailed information about notes (fields, tags, CSS styling)
+- `updateNoteFields` - Update existing note fields (CSS-aware, supports HTML content)
+- `deleteNotes` - Delete notes and all associated cards (destructive, requires confirmation)
+
+#### Tag Management
+- `getTags` - Get all tags in the collection (use first to avoid duplication)
+- `addTags` - Add space-separated tags to specified notes
+- `removeTags` - Remove space-separated tags from specified notes
+- `replaceTags` - Rename a tag across specified notes
+- `clearUnusedTags` - Remove orphaned tags not used by any notes (destructive)
+
+#### Media Management
+- `getMediaFilesNames` - List media files in `collection.media`, optionally filtered by pattern
+- `retrieveMediaFile` - Download a media file as base64 content
+- `storeMediaFile` - Upload media from base64 data, an absolute file path, or a URL
+- `deleteMediaFile` - Remove a media file from `collection.media` (destructive)
 
 **💡 Best Practice for Images:**
 - ✅ **Use file paths** (e.g., `/Users/you/image.png`) - Fast and efficient
@@ -86,31 +80,66 @@ Three representative prompts showing the tool flows this server enables:
 
 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
+#### Model/Template Management
+- `modelNames` - List all available note types/models
+- `modelFieldNames` - Get field names for a specific note type
+- `modelStyling` - Get CSS styling information for a note type
+- `createModel` - Create a new note type with custom fields, card templates, and CSS (e.g., RTL models)
+- `updateModelStyling` - Update the CSS styling for an existing note type (applies to all its cards)
+
+#### Statistics
+- `collection_stats` - Aggregated statistics across all decks with per-deck breakdown
+- `review_stats` - Review history analysis (temporal patterns, retention metrics, study streaks)
+
+### GUI Tools
+
+Tools that drive the Anki desktop interface. Intended for note editing/creation and deck-management workflows, **not** for review sessions.
+
+- `guiBrowse` - Open the Card Browser and search for cards
+- `guiSelectCard` - Select a specific card in the Card Browser
+- `guiSelectedNotes` - Get IDs of notes currently selected in the Card Browser
+- `guiAddCards` - Open the Add Cards dialog with preset note details
+- `guiEditNote` - Open the note editor for a specific note
+- `guiDeckOverview` - Open the Deck Overview dialog for a specific deck
+- `guiDeckBrowser` - Open the Deck Browser dialog
+- `guiCurrentCard` - Get info about the current card in review mode
+- `guiShowQuestion` - Show the question side of the current card
+- `guiShowAnswer` - Show the answer side of the current card
+- `guiUndo` - Undo the last action in Anki
 
 ## Prerequisites
 
 - [Anki](https://apps.ankiweb.net/) with [AnkiConnect](https://github.com/FooSoft/anki-connect) plugin installed
-- Node.js 20.19.0+
+- Node.js 22.12.0+
 
 ## Installation
 
-This server works in two modes:
+There are a few ways to get the server onto your machine. Once it's installed, head to [Connecting an AI Client](#connecting-an-ai-client) to wire it up to your AI assistant — locally or remotely.
+
+### npm (global or npx)
+
+The general-purpose way to install the server, suitable for any MCP client that launches it directly.
 
-- **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
+Install it globally for clients that run the `ankimcp` command:
+
+```bash
+npm install -g @ankimcp/anki-mcp-server
+```
+
+Or run it on demand with no install required:
+
+```bash
+npx @ankimcp/anki-mcp-server
+```
 
-### Option 1: MCPB Bundle (Recommended - Local Mode)
+### MCPB Bundle (Recommended for Claude Desktop)
 
 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
+    - **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
 
@@ -118,16 +147,39 @@ That's it! The bundle includes everything needed to run the server locally.
 
 > **For Anthropic MCP Directory reviewers:** a zero-to-integration walkthrough with a pre-populated sample deck lives in [`docs/reviewer-setup.md`](./docs/reviewer-setup.md).
 
-### Option 2: NPM Package with STDIO (For Other MCP Clients)
+### Install from Source (for development)
+
+For development or advanced usage:
+
+```bash
+npm install
+npm run build
+```
+
+## Connecting an AI Client
+
+There are two ways an AI assistant can reach this server, depending on where the assistant runs:
+
+- **[Local](#local)** — the server runs on the same machine as the AI client (Claude Desktop, Cursor, Cline, Zed, or a local browser session). Use **STDIO** for desktop MCP clients, **HTTP** for local web-based tools.
+- **[Remote](#remote)** — a hosted/remote AI (e.g. ChatGPT or Claude.ai in the cloud) needs to reach the Anki running on your local machine. Use the managed **Tunnel** (✅ recommended — authenticated) or, as a lighter-weight unauthenticated alternative, **ngrok**.
 
-Want to use Anki with MCP clients like **Cursor IDE**, **Cline**, or **Zed Editor**? Use the npm package with the `--stdio` flag:
+### Local
+
+The server runs on the same computer as your AI client and talks to AnkiConnect on `localhost`.
+
+#### STDIO (primary local integration)
+
+STDIO is the standard transport for local desktop MCP clients — **Claude Desktop**, **Cursor IDE**, **Cline**, **Zed Editor**, and others. The client launches the server as a subprocess and communicates over standard input/output.
 
 **Supported Clients:**
+- [Claude Desktop](https://claude.ai/download)
 - [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
 
+For Claude Desktop, the [MCPB bundle](#mcpb-bundle-recommended-for-claude-desktop) is the easiest path. For other clients, configure the npm package with the `--stdio` flag.
+
 **Configuration - Choose one method:**
 
 **Method 1: Using npx (recommended - no installation needed)**
@@ -173,19 +225,11 @@ Then configure:
 - **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.
+For client-specific features and troubleshooting, consult your MCP client's documentation. See also [Connect to Claude Desktop](#connect-to-claude-desktop-local-mode) for a config that points directly at a built `dist/main-stdio.js`.
 
-**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!
+#### HTTP (local web-based AI)
 
-**New in v0.8.0:** Integrated ngrok support with the `--ngrok` flag - no need to run ngrok separately!
+HTTP mode runs the server as a local web server speaking the MCP Streamable HTTP protocol. It's the transport a web-based AI tool talks to when pointed at your machine, and it's also what the [Remote](#remote) options expose to the outside world. On its own, HTTP mode binds to `localhost` only.
 
 **Setup - Choose one method:**
 
@@ -195,9 +239,6 @@ Want to use Anki with ChatGPT or Claude.ai in your browser? This mode lets you c
 # 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
@@ -212,9 +253,6 @@ npm install -g @ankimcp/anki-mcp-server
 # Run the server
 ankimcp
 
-# With ngrok tunnel (recommended for web-based AI)
-ankimcp --ngrok
-
 # With custom options
 ankimcp --port 8080 --host 0.0.0.0
 ankimcp --anki-connect http://localhost:8765
@@ -228,13 +266,76 @@ npm run build
 npm run start:prod:http
 ```
 
-**CLI Options:**
+To make a local HTTP server reachable by a cloud-hosted AI, use one of the [Remote](#remote) options below.
+
+### Remote
+
+A hosted/remote AI (such as ChatGPT or Claude.ai running in the cloud) can't reach `localhost` directly. These options expose your **local** Anki to the internet so a remote assistant can talk to it.
+
+#### Tunnel (✅ Recommended)
+
+> **Recommended remote path — authenticated & secure.** Unlike a raw public port, tunnel mode requires you to log in (OAuth 2.0 device flow), so the endpoint isn't open to anyone who guesses the URL.
+
+Tunnel mode lets web-based AI assistants reach your **local** Anki without running your own tunnel. The server connects out to the managed AnkiMCP tunnel service (`wss://tunnel.ankimcp.ai`) over a WebSocket and is assigned a public URL. Authentication is built in — no ngrok account or separate tunnel process required, and you log in once.
+
+**Log in (OAuth device flow):**
+
+Tunnel mode uses the OAuth 2.0 Device Authorization Grant. Logging in opens your browser automatically to an approval page with the code already embedded in the URL — nothing to type, just approve. (If the browser can't open, the terminal prints a verification URL and code to enter manually as a fallback.) On success, credentials are saved to `~/.ankimcp/credentials.json` (file permissions `0600`).
+
+```bash
+# Pre-authenticate (optional — --tunnel will trigger this automatically if needed)
+ankimcp --login
+npx @ankimcp/anki-mcp-server --login
+
+# Clear saved credentials
+ankimcp --logout
+```
+
+**Start the tunnel:**
+
+```bash
+# Connect to the managed tunnel service (wss://tunnel.ankimcp.ai)
+ankimcp --tunnel
+npx @ankimcp/anki-mcp-server --tunnel
+
+# Override the tunnel server URL (must be ws:// or wss://) — e.g. for self-hosting
+ankimcp --tunnel wss://my-tunnel.example.com
+```
+
+If no credentials exist, `--tunnel` automatically starts the login flow first, then continues to the tunnel. This auto-login requires an interactive terminal — when stdout is not a TTY (systemd, headless Docker, CI), the server fast-fails and asks you to run `ankimcp --login` first. Once connected, the public tunnel URL is printed; press Ctrl+C to disconnect. Share that URL with your AI assistant.
+
+**Tunnel-mode environment variables:**
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TUNNEL_SERVER_URL` | Tunnel server WebSocket URL (the `--tunnel`/`--login` flag value overrides this) | `wss://tunnel.ankimcp.ai` |
+| `TUNNEL_AUTH_CLIENT_ID` | OAuth client ID for the device flow. Advanced — only needed when pointing at a self-hosted tunnel/auth service. | (built-in) |
+
+The device-flow auth endpoints (`/auth/device`, `/auth/token`) are derived from `TUNNEL_SERVER_URL`, so pointing `--tunnel` (or `TUNNEL_SERVER_URL`) at a different host also moves authentication to that host.
+
+**How it works:** Tunnel mode runs the MCP server in-process behind an in-memory transport (`McpModule` is started with no built-in transport). `TunnelMcpService` connects that in-memory transport to the MCP server, and `TunnelClient` bridges it to the remote tunnel service over a WebSocket — relaying MCP requests in and responses out. AnkiConnect is still only ever reached on your local machine.
+
+#### ngrok (unauthenticated alternative)
+
+If you'd rather expose [local HTTP mode](#http-local-web-based-ai) publicly without an account on the managed tunnel, the built-in `--ngrok` flag launches an [ngrok](https://ngrok.com/) subprocess (`src/services/ngrok.service.ts`) and prints the public URL in the startup banner:
+
+```bash
+# One-time ngrok setup, then:
+ankimcp --ngrok
+```
+
+This route is **unauthenticated** — anyone with the URL can reach your Anki, so it's less secure than [Tunnel](#tunnel--recommended). Prefer Tunnel unless you have a specific reason to manage your own ngrok endpoint. (Requires a global ngrok install and authtoken; the manual two-terminal `ngrok http 3000` setup works too.)
+
+### CLI Options (all modes)
 
 ```bash
 ankimcp [options]
 
 Options:
   --stdio                        Run in STDIO mode (for MCP clients)
+  --tunnel [url]                 Connect via the managed tunnel (authenticated)
+  --login                        Authenticate for tunnel mode (OAuth device flow)
+  --logout                       Clear saved tunnel credentials
   -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)
@@ -246,6 +347,7 @@ 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 --tunnel               # Managed tunnel mode
   npx @ankimcp/anki-mcp-server --ngrok                # HTTP mode with ngrok tunnel
   npx @ankimcp/anki-mcp-server --read-only            # Read-only mode
 
@@ -254,11 +356,12 @@ Usage with global installation:
   ankimcp                                             # HTTP mode
   ankimcp --port 8080                                 # Custom port
   ankimcp --stdio                                     # STDIO mode
+  ankimcp --tunnel                                    # Managed tunnel mode
   ankimcp --ngrok                                     # HTTP mode with ngrok tunnel
   ankimcp --read-only                                 # Read-only mode
 ```
 
-**Read-Only Mode:**
+### Read-Only Mode (all modes)
 
 The `--read-only` flag prevents any modifications to your Anki collection. When enabled:
 - All read operations work normally (browsing decks, viewing cards, searching notes)
@@ -297,53 +400,6 @@ Or in MCP client configuration:
 }
 ```
 
-**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 --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
-
-# 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 --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:
@@ -387,6 +443,7 @@ For more details, see the [official MCP documentation](https://modelcontextproto
 | `ANKI_CONNECT_API_KEY` | API key if configured in AnkiConnect | - |
 | `ANKI_CONNECT_TIMEOUT` | Request timeout in ms | `5000` |
 | `READ_ONLY` | Enable read-only mode (`true` or `1`) | `false` |
+| `TUNNEL_SERVER_URL` | Tunnel server WebSocket URL (tunnel mode only) | `wss://tunnel.ankimcp.ai` |
 | `MEDIA_ALLOWED_TYPES` | Extra MIME types to allow for file path imports (comma-separated, e.g., `application/pdf`) | - |
 | `MEDIA_IMPORT_DIR` | Restrict file path imports to this directory | - |
 | `MEDIA_ALLOWED_HOSTS` | Allow specific private network hosts for URL imports (comma-separated, e.g., `192.168.1.50,my-nas`) | - |
@@ -493,22 +550,22 @@ If you see an error like:
 Error [ERR_REQUIRE_ESM]: require() of ES Module not supported
 ```
 
-This means your Node.js version is not supported. The server requires **Node.js 20.19.0+ or 22.12.0+**.
+This means your Node.js version is not supported. The server requires **Node.js 22.12.0+**.
 
-> **Note:** Node.js 21.x is not supported. The `require(esm)` feature was added in Node 22 and backported to Node 20.17+, but was never available in Node 21. See [#16](https://github.com/ankimcp/anki-mcp-server/issues/16) for details.
+> **Note:** The minimum supported runtime is Node.js 22.12.0. Node.js 20 (Iron) reached end-of-life on 2026-04-30 and is no longer supported.
 
 **Check your version:**
 ```bash
 node --version
 ```
 
-**Solution:** Update Node.js to version 20.19.0+ or 22.12.0+. You can download it from [nodejs.org](https://nodejs.org/) or use a version manager like [nvm](https://github.com/nvm-sh/nvm).
+**Solution:** Update Node.js to version 22.12.0+. You can download it from [nodejs.org](https://nodejs.org/) or use a version manager like [nvm](https://github.com/nvm-sh/nvm).
 
 ## Development
 
 ### Transport Modes
 
-This server supports two MCP transport modes via **separate entry points**:
+This server supports three MCP transport modes via **separate entry points**:
 
 #### STDIO Mode (Default)
 - For local MCP clients like Claude Desktop
@@ -526,13 +583,21 @@ This server supports two MCP transport modes via **separate entry points**:
 - **Default host**: `127.0.0.1` (configurable via `HOST` env var)
 - **MCP endpoint**: `http://127.0.0.1:3000/` (root path)
 
+#### Tunnel Mode (Managed WebSocket Tunnel)
+- For web-based AI assistants via the managed AnkiMCP tunnel service, with built-in authentication
+- The MCP server runs in-process behind an in-memory transport; `TunnelMcpService` wires it to the MCP server and `TunnelClient` bridges it to the tunnel service over a WebSocket
+- **Entry point**: `dist/main-tunnel.js`
+- **Run**: `node dist/main-tunnel.js --tunnel` (or `ankimcp --tunnel`)
+- **Auth**: `ankimcp --login` / `ankimcp --logout`; credentials stored at `~/.ankimcp/credentials.json` (`0600`)
+- **Dev**: `npm run start:dev:tunnel` (watch mode, runs `--tunnel --debug`)
+
 #### Building
 
 ```bash
-npm run build  # Builds once, creates dist/ with both entry points
+npm run build  # Builds once, creates dist/ with all three entry points
 ```
 
-Both `main-stdio.js` and `main-http.js` are in the same `dist/` directory. Choose which to run based on your needs.
+`main-stdio.js`, `main-http.js`, and `main-tunnel.js` are all built into the same `dist/` directory. Choose which to run based on your needs.
 
 #### HTTP Mode Configuration
 
@@ -586,7 +651,7 @@ The output file will be named `anki-mcp-server-X.X.X.mcpb` and can be distribute
 #### What Gets Bundled
 
 The MCPB bundle includes:
-- Compiled JavaScript (`dist/` directory - includes both entry points)
+- Compiled JavaScript (`dist/` directory - includes all three entry points)
 - Production dependencies only (`node_modules/` - devDependencies removed by `mcpb clean`)
 - Package metadata (`package.json`)
 - Manifest configuration (`manifest.json` - configured to use `main-stdio.js`)
@@ -721,10 +786,10 @@ After saving the config, restart Claude Desktop. The MCP server will now run wit
 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)
+    - **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
 
@@ -829,15 +894,15 @@ Coverage reports are generated in the `coverage/` directory.
 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
+    - **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.)
+    - Will be released when the API is stable and tested
+    - Breaking changes will require major version bumps (2.0.0, etc.)
 
-**Current Status**: `0.15.1` - Active beta development. Recent features include batch note creation (`addNotes`), integrated ngrok tunneling (`--ngrok` flag), media file management, model/template management, and comprehensive deck statistics. APIs may change based on feedback and testing.
+**Current Status**: `0.19.0` - Active beta development. Recent features include batch note creation (`addNotes`), integrated ngrok tunneling (`--ngrok` flag), media file management, model/template management, and comprehensive deck statistics. APIs may change based on feedback and testing.
 
 ### MCPB spec evolution
 

package/bin/ankimcp.js

@@ -16,12 +16,21 @@ if (
   process.exit(1);
 }
 
-// Check if --stdio flag is present
+// Determine mode based on CLI flags
 const isStdioMode = process.argv.includes('--stdio');
+const isTunnelMode = process.argv.some(arg =>
+  arg === '--tunnel' ||
+  arg.startsWith('--tunnel=') ||
+  arg === '--login' ||
+  arg === '--logout'
+);
 
 if (isStdioMode) {
   // STDIO mode - for MCP clients like Cursor, Cline, Zed, etc.
   require('../dist/main-stdio.js');
+} else if (isTunnelMode) {
+  // Tunnel mode - for remote MCP access via tunnel service
+  require('../dist/main-tunnel.js');
 } else {
   // HTTP mode (default) - for web-based AI assistants
   require('../dist/main-http.js');

package/dist/app-config.service.d.ts

@@ -0,0 +1,20 @@
+import { IAnkiConfig } from "./mcp/config/anki-config.interface";
+import type { AppConfig } from "./config";
+export declare class AppConfigService implements IAnkiConfig {
+    private readonly config;
+    constructor(config: AppConfig);
+    get port(): number;
+    get host(): string;
+    get nodeEnv(): "development" | "production" | "test";
+    get isDevelopment(): boolean;
+    get isProduction(): boolean;
+    get isTest(): boolean;
+    get ankiConnectUrl(): string;
+    get ankiConnectApiVersion(): number;
+    get ankiConnectApiKey(): string | undefined;
+    get ankiConnectTimeout(): number;
+    get readOnly(): boolean;
+    get authClientId(): string;
+    get tunnelServerUrl(): string;
+    get logLevel(): "debug" | "info" | "warn" | "error";
+}

package/dist/app-config.service.js

@@ -0,0 +1,73 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppConfigService = void 0;
+const common_1 = require("@nestjs/common");
+const config_1 = require("./config");
+const mcpb_workarounds_1 = require("./mcp/utils/mcpb-workarounds");
+let AppConfigService = class AppConfigService {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    get port() {
+        return this.config.port;
+    }
+    get host() {
+        return this.config.host;
+    }
+    get nodeEnv() {
+        return this.config.nodeEnv;
+    }
+    get isDevelopment() {
+        return this.nodeEnv === "development";
+    }
+    get isProduction() {
+        return this.nodeEnv === "production";
+    }
+    get isTest() {
+        return this.nodeEnv === "test";
+    }
+    get ankiConnectUrl() {
+        return this.config.ankiConnect.url;
+    }
+    get ankiConnectApiVersion() {
+        return this.config.ankiConnect.apiVersion;
+    }
+    get ankiConnectApiKey() {
+        return (0, mcpb_workarounds_1.sanitizeMcpbConfigValue)(this.config.ankiConnect.apiKey);
+    }
+    get ankiConnectTimeout() {
+        return this.config.ankiConnect.timeout;
+    }
+    get readOnly() {
+        return this.config.readOnly;
+    }
+    get authClientId() {
+        return this.config.auth.clientId;
+    }
+    get tunnelServerUrl() {
+        return this.config.tunnel.serverUrl;
+    }
+    get logLevel() {
+        return this.config.logLevel;
+    }
+};
+exports.AppConfigService = AppConfigService;
+exports.AppConfigService = AppConfigService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(config_1.APP_CONFIG)),
+    __metadata("design:paramtypes", [Object])
+], AppConfigService);
+//# sourceMappingURL=app-config.service.js.map

package/dist/app-config.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-config.service.js","sourceRoot":"","sources":["../src/app-config.service.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAAoD;AAEpD,qCAAsC;AAEtC,mEAAuE;AAOhE,IAAM,gBAAgB,GAAtB,MAAM,gBAAgB;IACsB;IAAjD,YAAiD,MAAiB;QAAjB,WAAM,GAAN,MAAM,CAAW;IAAG,CAAC;IAItE,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;IAC7B,CAAC;IAED,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,OAAO,KAAK,aAAa,CAAC;IACxC,CAAC;IAED,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,OAAO,KAAK,YAAY,CAAC;IACvC,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,KAAK,MAAM,CAAC;IACjC,CAAC;IAID,IAAI,cAAc;QAChB,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC;IACrC,CAAC;IAED,IAAI,qBAAqB;QACvB,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,UAAU,CAAC;IAC5C,CAAC;IAED,IAAI,iBAAiB;QACnB,OAAO,IAAA,0CAAuB,EAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IACjE,CAAC;IAED,IAAI,kBAAkB;QACpB,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC;IACzC,CAAC;IAID,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;IAC9B,CAAC;IAID,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;IACnC,CAAC;IAID,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC;IACtC,CAAC;IAID,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;IAC9B,CAAC;CACF,CAAA;AAtEY,4CAAgB;2BAAhB,gBAAgB;IAD5B,IAAA,mBAAU,GAAE;IAEE,WAAA,IAAA,eAAM,EAAC,mBAAU,CAAC,CAAA;;GADpB,gBAAgB,CAsE5B"}

package/dist/app.module.d.ts

@@ -1,5 +1,7 @@
 import { DynamicModule } from "@nestjs/common";
+import { ConfigInput, CliOverrides } from "./config";
 export declare class AppModule {
-    static forStdio(): DynamicModule;
-    static forHttp(): DynamicModule;
+    static forStdio(configInput: ConfigInput): DynamicModule;
+    static forHttp(configInput: ConfigInput): DynamicModule;
+    static forTunnel(cliOverrides?: CliOverrides): DynamicModule;
 }