anki-mcp-http 0.7.1 → 0.8.1

package/LICENSE

@@ -1,21 +1,7 @@
-MIT License
+Anki MCP Server is licensed under the GNU Affero General Public License,
+version 3 or later.
 
-Copyright (c) 2025 Anatoly Tarnavsky
+Copyright (C) 2025 Anatoly Tarnavsky
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+For the full text of the AGPL-3.0 license, see:
+https://www.gnu.org/licenses/agpl-3.0.txt

package/README.md

@@ -1,4 +1,13 @@
-# Anki MCP Desktop
+# 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.
 
@@ -38,6 +47,13 @@ For comprehensive guides, real-world examples, and step-by-step tutorials on usi
   - `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
@@ -59,7 +75,7 @@ This server works in two modes:
 
 The easiest way to install this MCP server for Claude Desktop:
 
-1. Download the latest `.mcpb` bundle from the [Releases](https://github.com/anki-mcp-organization/anki-mcp-desktop/releases) page
+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
@@ -78,16 +94,38 @@ Want to use Anki with MCP clients like **Cursor IDE**, **Cline**, or **Zed Edito
 - [Zed Editor](https://zed.dev/) - Fast, modern code editor
 - Other MCP clients that support STDIO transport
 
-**Basic Configuration:**
+**Configuration - Choose one method:**
 
-Add this to your MCP client's configuration file:
+**Method 1: Using npx (recommended - no installation needed)**
 
 ```json
 {
   "mcpServers": {
     "anki-mcp": {
       "command": "npx",
-      "args": ["-y", "anki-mcp-http", "--stdio"],
+      "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"
       }
@@ -109,21 +147,48 @@ Want to use Anki with ChatGPT or Claude.ai in your browser? This mode lets you c
 
 **How it works (simple explanation):**
 1. You run a small server on your computer (where Anki is installed)
-2. You use [ngrok](https://ngrok.com) to create a public URL that forwards to your local server
-3. You share that URL with ChatGPT or Claude.ai
+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!
 
-**Setup:**
+**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
-# Quick start (using npx - no installation needed)
-npx anki-mcp-http
+# 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
-npx anki-mcp-http --port 8080 --host 0.0.0.0
-npx anki-mcp-http --anki-connect http://localhost:8765
+@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)**
 
-# Or install from source
+```bash
 npm install
 npm run build
 npm run start:prod:http
@@ -132,37 +197,66 @@ npm run start:prod:http
 **CLI Options:**
 
 ```bash
-ankimcp [options]
+@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
 
-Examples - HTTP Mode:
-  ankimcp                        # Use all defaults (HTTP mode)
-  ankimcp --port 8080            # Custom port
-  ankimcp --host 0.0.0.0         # Listen on all network interfaces
-
-Examples - STDIO Mode:
-  ankimcp --stdio                # For use with npx in MCP clients
+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
-# 1. Start ankimcp
-npx anki-mcp-http
+# 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)**
 
-# 2. In another terminal, create a tunnel
+```bash
+# Terminal 1: Start the server
+@ankimcp/anki-mcp-server
+
+# Terminal 2: Create tunnel
 ngrok http 3000
 
-# 3. Copy the ngrok URL (looks like: https://abc123.ngrok.io)
-# 4. Share this URL with your AI assistant
+# 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)
@@ -189,7 +283,7 @@ Add the following to your Claude Desktop config:
   "mcpServers": {
     "anki-mcp": {
       "command": "node",
-      "args": ["/path/to/anki-mcp-desktop/dist/main-stdio.js"],
+      "args": ["/path/to/anki-mcp-server/dist/main-stdio.js"],
       "env": {
         "ANKI_CONNECT_URL": "http://localhost:8765"
       }
@@ -198,7 +292,7 @@ Add the following to your Claude Desktop config:
 }
 ```
 
-Replace `/path/to/anki-mcp-desktop` with your actual project path.
+Replace `/path/to/anki-mcp-server` with your actual project path.
 
 ### Config File Locations
 
@@ -345,7 +439,7 @@ This command will:
 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., `anki-mcp-http-0.5.0.mcpb`) and can be distributed for one-click installation.
+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
 
@@ -458,7 +552,7 @@ Update your Claude Desktop config to enable debugging:
       "command": "node",
       "args": [
         "--inspect=9229",
-        "/Users/anatoly/Developer/git/anki-mcp-organization/anki-mcp-desktop/dist/main-stdio.js"
+        "<path_to_project>/anki-mcp-server/dist/main-stdio.js"
       ],
       "env": {
         "ANKI_CONNECT_URL": "http://localhost:8765"
@@ -547,10 +641,10 @@ Test the npm package locally before publishing:
 
 ```bash
 # 1. Create local package
-npm run pack:local         # Builds and creates anki-mcp-http-*.tgz
+npm run pack:local         # Builds and creates @ankimcp/anki-mcp-server-*.tgz
 
 # 2. Install globally from local package
-npm run install:local      # Installs from ./anki-mcp-http-*.tgz
+npm run install:local      # Installs from ./@ankimcp/anki-mcp-server-*.tgz
 
 # 3. Test the command
 ankimcp                    # Runs HTTP server on port 3000
@@ -601,7 +695,7 @@ This project follows [Semantic Versioning](https://semver.org/) with a pre-1.0 d
   - Will be released when the API is stable and tested
   - Breaking changes will require major version bumps (2.0.0, etc.)
 
-**Current Status**: `0.6.0` - Active beta development. New features include the `twenty_rules` prompt for evidence-based flashcard creation, media file management, and improved prompt system. APIs may change based on feedback and testing.
+**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
 
@@ -616,7 +710,7 @@ If you're exploring Anki MCP integrations, here are other projects in this space
 - **Architecture**: Procedural code structure with all tools in one file
 - **Good for**: Simple use cases, minimal dependencies
 
-**Why this project (anki-mcp-desktop) differs:**
+**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
@@ -636,4 +730,27 @@ If you're exploring Anki MCP integrations, here are other projects in this space
 - [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/)
+- [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.

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

@@ -1,5 +1,5 @@
-import { ConfigService } from '@nestjs/config';
-import { IAnkiConfig } from './mcp/config/anki-config.interface';
+import { ConfigService } from "@nestjs/config";
+import { IAnkiConfig } from "./mcp/config/anki-config.interface";
 export declare class AnkiConfigService implements IAnkiConfig {
     private configService;
     constructor(configService: ConfigService);

package/dist/anki-config.service.js

@@ -19,18 +19,18 @@ let AnkiConfigService = class AnkiConfigService {
         this.configService = configService;
     }
     get ankiConnectUrl() {
-        return this.configService.get('ANKI_CONNECT_URL', 'http://localhost:8765');
+        return this.configService.get("ANKI_CONNECT_URL", "http://localhost:8765");
     }
     get ankiConnectApiVersion() {
-        const version = this.configService.get('ANKI_CONNECT_API_VERSION', '6');
+        const version = this.configService.get("ANKI_CONNECT_API_VERSION", "6");
         return parseInt(version, 10);
     }
     get ankiConnectApiKey() {
-        const apiKey = this.configService.get('ANKI_CONNECT_API_KEY');
+        const apiKey = this.configService.get("ANKI_CONNECT_API_KEY");
         return (0, mcpb_workarounds_1.sanitizeMcpbConfigValue)(apiKey);
     }
     get ankiConnectTimeout() {
-        const timeout = this.configService.get('ANKI_CONNECT_TIMEOUT', '5000');
+        const timeout = this.configService.get("ANKI_CONNECT_TIMEOUT", "5000");
         return parseInt(timeout, 10);
     }
 };

package/dist/app.module.d.ts

@@ -1,4 +1,4 @@
-import { DynamicModule } from '@nestjs/common';
+import { DynamicModule } from "@nestjs/common";
 export declare class AppModule {
     static forStdio(): DynamicModule;
     static forHttp(): DynamicModule;

package/dist/app.module.js

@@ -22,11 +22,11 @@ let AppModule = AppModule_1 = class AppModule {
                 config_1.ConfigModule.forRoot({
                     isGlobal: true,
                     cache: true,
-                    envFilePath: ['.env.local', '.env'],
+                    envFilePath: [".env.local", ".env"],
                 }),
                 mcp_nest_1.McpModule.forRoot({
-                    name: process.env.MCP_SERVER_NAME || 'anki-mcp-desktop',
-                    version: process.env.MCP_SERVER_VERSION || '1.0.0',
+                    name: process.env.MCP_SERVER_NAME || "anki-mcp-server",
+                    version: process.env.MCP_SERVER_VERSION || "1.0.0",
                     transport: mcp_nest_1.McpTransportType.STDIO,
                 }),
                 essential_1.McpPrimitivesAnkiEssentialModule.forRoot({
@@ -52,13 +52,13 @@ let AppModule = AppModule_1 = class AppModule {
                 config_1.ConfigModule.forRoot({
                     isGlobal: true,
                     cache: true,
-                    envFilePath: ['.env.local', '.env'],
+                    envFilePath: [".env.local", ".env"],
                 }),
                 mcp_nest_1.McpModule.forRoot({
-                    name: process.env.MCP_SERVER_NAME || 'anki-mcp-desktop',
-                    version: process.env.MCP_SERVER_VERSION || '1.0.0',
+                    name: process.env.MCP_SERVER_NAME || "anki-mcp-server",
+                    version: process.env.MCP_SERVER_VERSION || "1.0.0",
                     transport: mcp_nest_1.McpTransportType.STREAMABLE_HTTP,
-                    mcpEndpoint: '/',
+                    mcpEndpoint: "/",
                 }),
                 essential_1.McpPrimitivesAnkiEssentialModule.forRoot({
                     ankiConfigProvider: {

package/dist/app.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.module.js","sourceRoot":"","sources":["../src/app.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAuD;AACvD,2CAA8C;AAC9C,8CAA8D;AAC9D,0DAGoC;AACpC,8CAAkE;AAClE,+DAA0D;AAGnD,IAAM,SAAS,iBAAf,MAAM,SAAS;IAIpB,MAAM,CAAC,QAAQ;QACb,OAAO;YACL,MAAM,EAAE,WAAS;YACjB,OAAO,EAAE;gBAEP,qBAAY,CAAC,OAAO,CAAC;oBACnB,QAAQ,EAAE,IAAI;oBACd,KAAK,EAAE,IAAI;oBACX,WAAW,EAAE,CAAC,YAAY,EAAE,MAAM,CAAC;iBACpC,CAAC;gBAGF,oBAAS,CAAC,OAAO,CAAC;oBAChB,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,kBAAkB;oBACvD,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,OAAO;oBAClD,SAAS,EAAE,2BAAgB,CAAC,KAAK;iBAClC,CAAC;gBAGF,4CAAgC,CAAC,OAAO,CAAC;oBACvC,kBAAkB,EAAE;wBAClB,OAAO,EAAE,uBAAW;wBACpB,QAAQ,EAAE,uCAAiB;qBAC5B;iBACF,CAAC;gBAGF,gCAA0B,CAAC,OAAO,CAAC;oBACjC,kBAAkB,EAAE;wBAClB,OAAO,EAAE,uBAAW;wBACpB,QAAQ,EAAE,uCAAiB;qBAC5B;iBACF,CAAC;aACH;YACD,SAAS,EAAE,CAAC,uCAAiB,CAAC;SAC/B,CAAC;IACJ,CAAC;IAKD,MAAM,CAAC,OAAO;QACZ,OAAO;YACL,MAAM,EAAE,WAAS;YACjB,OAAO,EAAE;gBAEP,qBAAY,CAAC,OAAO,CAAC;oBACnB,QAAQ,EAAE,IAAI;oBACd,KAAK,EAAE,IAAI;oBACX,WAAW,EAAE,CAAC,YAAY,EAAE,MAAM,CAAC;iBACpC,CAAC;gBAGF,oBAAS,CAAC,OAAO,CAAC;oBAChB,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,kBAAkB;oBACvD,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,OAAO;oBAClD,SAAS,EAAE,2BAAgB,CAAC,eAAe;oBAC3C,WAAW,EAAE,GAAG;iBACjB,CAAC;gBAGF,4CAAgC,CAAC,OAAO,CAAC;oBACvC,kBAAkB,EAAE;wBAClB,OAAO,EAAE,uBAAW;wBACpB,QAAQ,EAAE,uCAAiB;qBAC5B;iBACF,CAAC;gBAGF,gCAA0B,CAAC,OAAO,CAAC;oBACjC,kBAAkB,EAAE;wBAClB,OAAO,EAAE,uBAAW;wBACpB,QAAQ,EAAE,uCAAiB;qBAC5B;iBACF,CAAC;aACH;YACD,SAAS,EAAE,CAAC,uCAAiB,CAAC;SAC/B,CAAC;IACJ,CAAC;CACF,CAAA;AAnFY,8BAAS;oBAAT,SAAS;IADrB,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,SAAS,CAmFrB"}
+{"version":3,"file":"app.module.js","sourceRoot":"","sources":["../src/app.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAuD;AACvD,2CAA8C;AAC9C,8CAA8D;AAC9D,0DAGoC;AACpC,8CAAkE;AAClE,+DAA0D;AAGnD,IAAM,SAAS,iBAAf,MAAM,SAAS;IAIpB,MAAM,CAAC,QAAQ;QACb,OAAO;YACL,MAAM,EAAE,WAAS;YACjB,OAAO,EAAE;gBAEP,qBAAY,CAAC,OAAO,CAAC;oBACnB,QAAQ,EAAE,IAAI;oBACd,KAAK,EAAE,IAAI;oBACX,WAAW,EAAE,CAAC,YAAY,EAAE,MAAM,CAAC;iBACpC,CAAC;gBAGF,oBAAS,CAAC,OAAO,CAAC;oBAChB,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,iBAAiB;oBACtD,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,OAAO;oBAClD,SAAS,EAAE,2BAAgB,CAAC,KAAK;iBAClC,CAAC;gBAGF,4CAAgC,CAAC,OAAO,CAAC;oBACvC,kBAAkB,EAAE;wBAClB,OAAO,EAAE,uBAAW;wBACpB,QAAQ,EAAE,uCAAiB;qBAC5B;iBACF,CAAC;gBAGF,gCAA0B,CAAC,OAAO,CAAC;oBACjC,kBAAkB,EAAE;wBAClB,OAAO,EAAE,uBAAW;wBACpB,QAAQ,EAAE,uCAAiB;qBAC5B;iBACF,CAAC;aACH;YACD,SAAS,EAAE,CAAC,uCAAiB,CAAC;SAC/B,CAAC;IACJ,CAAC;IAKD,MAAM,CAAC,OAAO;QACZ,OAAO;YACL,MAAM,EAAE,WAAS;YACjB,OAAO,EAAE;gBAEP,qBAAY,CAAC,OAAO,CAAC;oBACnB,QAAQ,EAAE,IAAI;oBACd,KAAK,EAAE,IAAI;oBACX,WAAW,EAAE,CAAC,YAAY,EAAE,MAAM,CAAC;iBACpC,CAAC;gBAGF,oBAAS,CAAC,OAAO,CAAC;oBAChB,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,iBAAiB;oBACtD,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,OAAO;oBAClD,SAAS,EAAE,2BAAgB,CAAC,eAAe;oBAC3C,WAAW,EAAE,GAAG;iBACjB,CAAC;gBAGF,4CAAgC,CAAC,OAAO,CAAC;oBACvC,kBAAkB,EAAE;wBAClB,OAAO,EAAE,uBAAW;wBACpB,QAAQ,EAAE,uCAAiB;qBAC5B;iBACF,CAAC;gBAGF,gCAA0B,CAAC,OAAO,CAAC;oBACjC,kBAAkB,EAAE;wBAClB,OAAO,EAAE,uBAAW;wBACpB,QAAQ,EAAE,uCAAiB;qBAC5B;iBACF,CAAC;aACH;YACD,SAAS,EAAE,CAAC,uCAAiB,CAAC;SAC/B,CAAC;IACJ,CAAC;CACF,CAAA;AAnFY,8BAAS;oBAAT,SAAS;IADrB,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,SAAS,CAmFrB"}

package/dist/bootstrap.d.ts

@@ -1,3 +1,3 @@
-import { LoggerService } from '@nestjs/common';
+import { LoggerService } from "@nestjs/common";
 export declare function createPinoLogger(destination: 1 | 2): import("pino").Logger<never, boolean>;
 export declare function createLoggerService(pinoLogger: any): LoggerService;

package/dist/bootstrap.js

@@ -5,14 +5,14 @@ exports.createLoggerService = createLoggerService;
 const pino_1 = require("pino");
 function createPinoLogger(destination) {
     return (0, pino_1.pino)({
-        level: process.env.LOG_LEVEL || 'info',
+        level: process.env.LOG_LEVEL || "info",
         transport: {
-            target: 'pino-pretty',
+            target: "pino-pretty",
             options: {
                 destination,
                 colorize: true,
-                translateTime: 'HH:MM:ss Z',
-                ignore: 'pid,hostname',
+                translateTime: "HH:MM:ss Z",
+                ignore: "pid,hostname",
             },
         },
     });

package/dist/cli.d.ts

@@ -2,7 +2,8 @@ export interface CliOptions {
     port: number;
     host: string;
     ankiConnect: string;
+    ngrok: boolean;
 }
 export declare function checkForUpdates(): void;
 export declare function parseCliArgs(): CliOptions;
-export declare function displayStartupBanner(options: CliOptions): void;
+export declare function displayStartupBanner(options: CliOptions, ngrokUrl?: string): void;

package/dist/cli.js

@@ -12,10 +12,10 @@ const path_1 = require("path");
 const update_notifier_1 = __importDefault(require("update-notifier"));
 function getPackageJson() {
     try {
-        return JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(__dirname, '../package.json'), 'utf-8'));
+        return JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(__dirname, "../package.json"), "utf-8"));
     }
     catch {
-        return { version: '0.0.0', name: 'anki-mcp-http' };
+        return { version: "0.0.0", name: "anki-mcp-http" };
     }
 }
 function getVersion() {
@@ -27,26 +27,32 @@ function checkForUpdates() {
 function parseCliArgs() {
     const program = new commander_1.Command();
     program
-        .name('ankimcp')
-        .description('AnkiMCP Server - Model Context Protocol server for Anki')
+        .name("ankimcp")
+        .description("AnkiMCP Server - Model Context Protocol server for Anki")
         .version(getVersion())
-        .option('--stdio', 'Run in STDIO mode (for MCP clients like Cursor, Cline, Zed)')
-        .option('-p, --port <number>', 'Port to listen on (HTTP mode)', '3000')
-        .option('-h, --host <address>', 'Host to bind to (HTTP mode)', '127.0.0.1')
-        .option('-a, --anki-connect <url>', 'AnkiConnect URL', 'http://localhost:8765')
-        .addHelpText('after', `
+        .option("--stdio", "Run in STDIO mode (for MCP clients like Cursor, Cline, Zed)")
+        .option("-p, --port <number>", "Port to listen on (HTTP mode)", "3000")
+        .option("-h, --host <address>", "Host to bind to (HTTP mode)", "127.0.0.1")
+        .option("-a, --anki-connect <url>", "AnkiConnect URL", "http://localhost:8765")
+        .option("--ngrok", "Start ngrok tunnel (requires global ngrok installation)")
+        .addHelpText("after", `
 Transport Modes:
   HTTP Mode (default):  For web-based AI assistants (ChatGPT, Claude.ai)
   STDIO Mode:           For desktop MCP clients (Cursor, Cline, Zed)
 
 Examples - HTTP Mode:
-  $ ankimcp                                    # Use defaults
-  $ ankimcp --port 8080                        # Custom port
-  $ ankimcp --host 0.0.0.0 --port 3000         # Listen on all interfaces
-  $ ankimcp --anki-connect http://localhost:8765
+  $ anki-mcp-http                                    # Use defaults
+  $ anki-mcp-http --port 8080                        # Custom port
+  $ anki-mcp-http --host 0.0.0.0 --port 3000         # Listen on all interfaces
+  $ anki-mcp-http --anki-connect http://localhost:8765
+
+Examples - HTTP Mode with Ngrok:
+  $ anki-mcp-http --ngrok                            # Start with ngrok tunnel
+  $ anki-mcp-http --port 8080 --ngrok                # Custom port + ngrok
+  $ anki-mcp-http --host 0.0.0.0 --ngrok             # Public host + ngrok
 
 Examples - STDIO Mode:
-  $ ankimcp --stdio                            # For use with npx in MCP clients
+  $ anki-mcp-http --stdio                            # For use with npx in MCP clients
 
   # MCP client configuration (Cursor, Cline, Zed, etc.):
   {
@@ -58,10 +64,11 @@ Examples - STDIO Mode:
     }
   }
 
-Usage with ngrok (HTTP mode only):
-  1. Start ankimcp in one terminal
-  2. In another terminal: ngrok http 3000
-  3. Share the ngrok URL with your AI assistant
+Ngrok Setup (one-time):
+  1. Install: npm install -g ngrok
+  2. Get auth token from: https://dashboard.ngrok.com/get-started/your-authtoken
+  3. Setup: ngrok config add-authtoken <your-token>
+  4. Run: anki-mcp-http --ngrok
 `);
     program.parse();
     const options = program.opts();
@@ -69,32 +76,39 @@ Usage with ngrok (HTTP mode only):
         port: parseInt(options.port.toString(), 10),
         host: options.host,
         ankiConnect: options.ankiConnect,
+        ngrok: options.ngrok || false,
     };
 }
-function displayStartupBanner(options) {
+function displayStartupBanner(options, ngrokUrl) {
     const version = getVersion();
     const title = `AnkiMCP HTTP Server v${version}`;
     const padding = Math.floor((64 - title.length) / 2);
-    const paddedTitle = ' '.repeat(padding) + title + ' '.repeat(64 - padding - title.length);
+    const paddedTitle = " ".repeat(padding) + title + " ".repeat(64 - padding - title.length);
     console.log(`
 ╔════════════════════════════════════════════════════════════════╗
 ║${paddedTitle}║
 ╚════════════════════════════════════════════════════════════════╝
 
 🚀 Server running on: http://${options.host}:${options.port}
-🔌 AnkiConnect URL:   ${options.ankiConnect}
+🔌 AnkiConnect URL:   ${options.ankiConnect}${ngrokUrl ? `\n🌐 Ngrok tunnel:      ${ngrokUrl}` : ""}
 
 Configuration:
   • Port:               ${options.port} (override: --port 8080)
   • Host:               ${options.host} (override: --host 0.0.0.0)
   • AnkiConnect:        ${options.ankiConnect}
-                        (override: --anki-connect http://localhost:8765)
-
+                        (override: --anki-connect http://localhost:8765)${ngrokUrl ? `\n  • Ngrok tunnel:       ${ngrokUrl}\n  • Ngrok dashboard:    http://localhost:4040` : ""}
+${!ngrokUrl
+        ? `
 Usage with ngrok:
-  1. In another terminal: ngrok http ${options.port}
-  2. Share the ngrok URL with your AI assistant
-
-Run 'ankimcp --help' for more options.
+  1. Install: npm install -g ngrok
+  2. Setup: ngrok config add-authtoken <your-token>
+  3. Run: anki-mcp-http --ngrok
+`
+        : `
+Share this URL with your AI assistant:
+  ${ngrokUrl}
+`}
+Run 'anki-mcp-http --help' for more options.
 `);
 }
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;;;AAyBA,0CAEC;AAED,oCA4DC;AAED,oDA0BC;AArHD,yCAAoC;AACpC,2BAAkC;AAClC,+BAA4B;AAC5B,sEAA6C;AAQ7C,SAAS,cAAc;IACrB,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CACf,IAAA,iBAAY,EAAC,IAAA,WAAI,EAAC,SAAS,EAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC,CAC1D,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;IACrD,CAAC;AACH,CAAC;AAED,SAAS,UAAU;IACjB,OAAO,cAAc,EAAE,CAAC,OAAO,CAAC;AAClC,CAAC;AAED,SAAgB,eAAe;IAC7B,IAAA,yBAAc,EAAC,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;AACrD,CAAC;AAED,SAAgB,YAAY;IAC1B,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,SAAS,CAAC;SACf,WAAW,CAAC,yDAAyD,CAAC;SACtE,OAAO,CAAC,UAAU,EAAE,CAAC;SACrB,MAAM,CACL,SAAS,EACT,6DAA6D,CAC9D;SACA,MAAM,CAAC,qBAAqB,EAAE,+BAA+B,EAAE,MAAM,CAAC;SACtE,MAAM,CAAC,sBAAsB,EAAE,6BAA6B,EAAE,WAAW,CAAC;SAC1E,MAAM,CACL,0BAA0B,EAC1B,iBAAiB,EACjB,uBAAuB,CACxB;SACA,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BL,CACI,CAAC;IAEJ,OAAO,CAAC,KAAK,EAAE,CAAC;IAEhB,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAc,CAAC;IAE3C,OAAO;QACL,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,EAAE,CAAC;QAC3C,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,WAAW,EAAE,OAAO,CAAC,WAAW;KACjC,CAAC;AACJ,CAAC;AAED,SAAgB,oBAAoB,CAAC,OAAmB;IACtD,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,wBAAwB,OAAO,EAAE,CAAC;IAChD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACpD,MAAM,WAAW,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAE1F,OAAO,CAAC,GAAG,CAAC;;GAEX,WAAW;;;+BAGiB,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI;wBACnC,OAAO,CAAC,WAAW;;;0BAGjB,OAAO,CAAC,IAAI;0BACZ,OAAO,CAAC,IAAI;0BACZ,OAAO,CAAC,WAAW;;;;uCAIN,OAAO,CAAC,IAAI;;;;CAIlD,CAAC,CAAC;AACH,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;;;AA0BA,0CAEC;AAED,oCAuEC;AAED,oDAsCC;AA7ID,yCAAoC;AACpC,2BAAkC;AAClC,+BAA4B;AAC5B,sEAA6C;AAS7C,SAAS,cAAc;IACrB,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CACf,IAAA,iBAAY,EAAC,IAAA,WAAI,EAAC,SAAS,EAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC,CAC1D,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;IACrD,CAAC;AACH,CAAC;AAED,SAAS,UAAU;IACjB,OAAO,cAAc,EAAE,CAAC,OAAO,CAAC;AAClC,CAAC;AAED,SAAgB,eAAe;IAC7B,IAAA,yBAAc,EAAC,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;AACrD,CAAC;AAED,SAAgB,YAAY;IAC1B,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,SAAS,CAAC;SACf,WAAW,CAAC,yDAAyD,CAAC;SACtE,OAAO,CAAC,UAAU,EAAE,CAAC;SACrB,MAAM,CACL,SAAS,EACT,6DAA6D,CAC9D;SACA,MAAM,CAAC,qBAAqB,EAAE,+BAA+B,EAAE,MAAM,CAAC;SACtE,MAAM,CAAC,sBAAsB,EAAE,6BAA6B,EAAE,WAAW,CAAC;SAC1E,MAAM,CACL,0BAA0B,EAC1B,iBAAiB,EACjB,uBAAuB,CACxB;SACA,MAAM,CACL,SAAS,EACT,yDAAyD,CAC1D;SACA,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCL,CACI,CAAC;IAEJ,OAAO,CAAC,KAAK,EAAE,CAAC;IAEhB,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAc,CAAC;IAE3C,OAAO;QACL,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,EAAE,CAAC;QAC3C,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,KAAK;KAC9B,CAAC;AACJ,CAAC;AAED,SAAgB,oBAAoB,CAClC,OAAmB,EACnB,QAAiB;IAEjB,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,wBAAwB,OAAO,EAAE,CAAC;IAChD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACpD,MAAM,WAAW,GACf,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAExE,OAAO,CAAC,GAAG,CAAC;;GAEX,WAAW;;;+BAGiB,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI;wBACnC,OAAO,CAAC,WAAW,GAAG,QAAQ,CAAC,CAAC,CAAC,2BAA2B,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE;;;0BAGzE,OAAO,CAAC,IAAI;0BACZ,OAAO,CAAC,IAAI;0BACZ,OAAO,CAAC,WAAW;0EAC6B,QAAQ,CAAC,CAAC,CAAC,6BAA6B,QAAQ,iDAAiD,CAAC,CAAC,CAAC,EAAE;EAE9K,CAAC,QAAQ;QACP,CAAC,CAAC;;;;;CAKL;QACG,CAAC,CAAC;;IAEF,QAAQ;CAEZ;;CAEC,CAAC,CAAC;AACH,CAAC"}

package/dist/http/guards/origin-validation.guard.d.ts

@@ -1,4 +1,4 @@
-import { CanActivate, ExecutionContext } from '@nestjs/common';
+import { CanActivate, ExecutionContext } from "@nestjs/common";
 export declare class OriginValidationGuard implements CanActivate {
     private readonly allowedOrigins;
     constructor();

package/dist/http/guards/origin-validation.guard.js

@@ -14,9 +14,9 @@ const common_1 = require("@nestjs/common");
 let OriginValidationGuard = class OriginValidationGuard {
     allowedOrigins;
     constructor() {
-        const defaultOrigins = 'http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*';
+        const defaultOrigins = "http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*";
         const originsEnv = process.env.ALLOWED_ORIGINS || defaultOrigins;
-        this.allowedOrigins = originsEnv.split(',').map((o) => o.trim());
+        this.allowedOrigins = originsEnv.split(",").map((o) => o.trim());
     }
     canActivate(context) {
         const request = context.switchToHttp().getRequest();
@@ -34,10 +34,10 @@ let OriginValidationGuard = class OriginValidationGuard {
         if (origin === pattern) {
             return true;
         }
-        if (pattern.includes('*')) {
+        if (pattern.includes("*")) {
             const regexPattern = pattern
-                .replace(/\./g, '\\.')
-                .replace(/\*/g, '.*');
+                .replace(/\./g, "\\.")
+                .replace(/\*/g, ".*");
             const regex = new RegExp(`^${regexPattern}$`);
             return regex.test(origin);
         }