@spacholski1225/anki-connect-mcp 1.0.5 → 2.0.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Szymon Pacholski
-
-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.
+MIT License
+
+Copyright (c) 2025 Szymon Pacholski
+
+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.

package/README.md

@@ -1,245 +1,260 @@
-# Anki Connect MCP Server
-
-A Model Context Protocol (MCP) server that provides seamless integration with Anki through the AnkiConnect add-on. This server enables AI assistants and other MCP clients to interact with your Anki flashcard collection programmatically.
-
-## What is Anki Connect?
-
-[AnkiConnect](https://ankiweb.net/shared/info/2055492159) is a powerful Anki add-on that exposes Anki's functionality through a REST API. It allows external applications to:
-
-- Create, modify, and delete flashcards
-- Manage decks and their configurations
-- Control Anki's GUI programmatically
-- Search and retrieve card information
-- Manage tags and note types
-- Perform bulk operations on cards and notes
-
-## What is MCP (Model Context Protocol)?
-
-The Model Context Protocol is a standardized way for AI assistants to connect to external data sources and tools. This MCP server acts as a bridge between MCP clients (like Claude Desktop) and AnkiConnect, allowing AI assistants to help you manage your Anki flashcards naturally through conversation.
-
-## Features
-
-This MCP server provides comprehensive access to AnkiConnect functionality through the following tools:
-
-### Flashcard Management
-- [`create_flashcard()`](src/index.ts:67) - Create new flashcards with front and back content
-- [`add_note()`](src/tools/notes.ts:22) - Add notes with custom fields and tags
-- [`add_notes()`](src/tools/notes.ts) - Bulk add multiple notes
-- [`update_note_fields()`](src/tools/notes.ts) - Update existing note fields
-- [`find_notes()`](src/tools/notes.ts) - Search for notes using Anki's query syntax
-
-### Deck Management
-- [`deck_names()`](src/tools/decks.ts:19) - Get all deck names
-- [`deck_names_and_ids()`](src/tools/decks.ts:30) - Get deck names with their IDs
-- [`change_deck()`](src/tools/decks.ts) - Move cards between decks
-- [`delete_decks()`](src/tools/decks.ts) - Delete decks and optionally their cards
-- [`get_deck_config()`](src/tools/decks.ts) - Retrieve deck configuration settings
-
-### Card Operations
-- [`find_cards()`](src/tools/cards.ts) - Search for cards
-- [`cards_info()`](src/tools/cards.ts) - Get detailed card information
-- [`suspend()`](src/tools/cards.ts:18) / [`unsuspend()`](src/tools/cards.ts) - Suspend/unsuspend cards
-- [`are_suspended()`](src/tools/cards.ts) / [`are_due()`](src/tools/cards.ts) - Check card status
-
-### GUI Control
-- [`gui_deck_browser()`](src/index.ts:177) - Open deck browser
-- [`gui_deck_review()`](src/index.ts:185) - Start deck review
-- [`gui_browse()`](src/index.ts:196) - Open card browser with search
-- [`gui_add_cards()`](src/index.ts:207) - Open add cards dialog
-
-### Utility Tools
-- [`version()`](src/index.ts:98) - Get AnkiConnect version
-- [`get_tags()`](src/index.ts:114) - Retrieve all tags
-- [`multi()`](src/index.ts:223) - Execute multiple AnkiConnect requests in batch
-
-## Prerequisites
-
-### 1. Install AnkiConnect Add-on
-
-1. Open Anki
-2. Go to **Tools** → **Add-ons**
-3. Click **Get Add-ons...**
-4. Enter the code: `2055492159`
-5. Click **OK** and restart Anki
-
-### 2. Configure AnkiConnect (Optional)
-
-AnkiConnect works out of the box, but you can customize its settings:
-
-1. Go to **Tools** → **Add-ons**
-2. Select **AnkiConnect** and click **Config**
-3. Modify settings if needed (default port is 8765)
-4. Restart Anki after making changes
-
-## Installation
-
-1. Clone this repository:
-```bash
-git clone https://github.com/spacholski1225/mcp-server.git
-cd mcp-server
-```
-
-2. Install dependencies:
-```bash
-npm install
-```
-
-3. Build the project:
-```bash
-npm run build
-```
-
-## MCP Client Configuration
-
-### Claude Desktop
-
-To use this MCP server with Claude Desktop, add the following configuration to your MCP settings file:
-
-**Location of MCP configuration file:**
-- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Linux**: `~/.config/Claude/claude_desktop_config.json`
-
-**Configuration Options:**
-
-#### Option 1: Using Node.js (Local Installation)
-```json
-{
-  "mcpServers": {
-    "anki-connect-mcp": {
-      "command": "node",
-      "args": [
-        "dist/index.js"
-      ],
-      "env": {},
-      "disabled": false,
-      "alwaysAllow": [
-        "deck_names",
-        "cards_info",
-        "deck_names_and_ids",
-        "gui_deck_browser"
-      ]
-    }
-  }
-}
-```
-
-#### Option 2: Using npx (NPM Package)
-
-**Then configure your MCP client:**
-```json
-{
-  "mcpServers": {
-    "anki-connect": {
-      "command": "npx",
-      "args": [
-        "@spacholski1225/anki-connect-mcp"
-      ],
-      "env": {},
-      "disabled": false,
-      "alwaysAllow": [
-        "deck_names",
-        "cards_info",
-        "deck_names_and_ids",
-        "gui_deck_browser"
-      ]
-    }
-  }
-}
-```
-
-#### Option 3: Using Docker
-```json
-{
-  "mcpServers": {
-    "anki-connect": {
-      "command": "docker",
-      "args": [
-        "run",
-        "--rm",
-        "-i",
-        "--network=host",
-        "-e", "ANKI_CONNECT_URL=http://host.docker.internal:8765",
-        "spacholski/anki-connect-mcp:latest"
-      ],
-      "env": {},
-      "disabled": false,
-      "alwaysAllow": [
-        "deck_names",
-        "cards_info",
-        "deck_names_and_ids",
-        "gui_deck_browser"
-      ]
-    }
-  }
-}
-```
-
-**Docker-Specific AnkiConnect Configuration:**
-
-When using the Docker option, you **must** configure AnkiConnect with specific settings to allow Docker container access:
-
-1. Go to **Tools** → **Add-ons** in Anki
-2. Select **AnkiConnect** and click **Config**
-3. Update the configuration with the following settings:
-
-```json
-{
-    "apiKey": null,
-    "apiLogPath": null,
-    "ignoreOriginList": [],
-    "webBindAddress": "0.0.0.0",
-    "webBindPort": 8765,
-    "webCorsOriginList": [
-        "http://localhost",
-        "http://host.docker.internal",
-        "http://host.docker.internal:3000"
-    ]
-}
-```
-
-**Key Docker Configuration Points:**
-- **`webBindAddress: "0.0.0.0"`** - Allows AnkiConnect to accept connections from any IP address (required for Docker containers)
-- **`webCorsOriginList`** - Must include `"http://host.docker.internal"` and related origins to allow cross-origin requests from Docker containers
-- Restart Anki after making these configuration changes
-
-**Important Notes:**
-- **For Node.js option**: Replace the path in `args` with the actual path to your built `index.js` file
-- **For npx option**: Uses the published NPM package `@spacholski1225/anki-connect-mcp` - no local installation required
-- **For Docker option**: Uses the pre-built Docker image `spacholski/anki-connect-mcp:latest`
-- The `alwaysAllow` array contains tools that won't require confirmation each time
-- Make sure Anki is running with AnkiConnect enabled before using the MCP server
-- For Docker option, the `--network=host` flag allows the container to access AnkiConnect on the host machine
-
-## Usage Examples
-
-Once configured with an MCP client like Claude Desktop, you can interact with your Anki collection naturally:
-
-- *"Create a flashcard about the capital of France"*
-- *"Show me all my deck names"*
-- *"Find all cards tagged with 'vocabulary'"*
-- *"Suspend all cards in the 'Difficult Words' deck"*
-- *"Open the deck browser in Anki"*
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Connection refused**: Make sure Anki is running and AnkiConnect is installed
-2. **Port conflicts**: Check if port 8765 is available or configure AnkiConnect to use a different port
-3. **Permission errors**: Ensure the MCP server has proper file system permissions
-4. **Tool not found**: Verify the MCP client configuration and restart the client
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
-
-## License
-
-ISC License
-
-## References
-
-- [AnkiConnect Documentation](https://foosoft.net/projects/anki-connect/)
-- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
-- [MCP SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk)
+# Anki Connect MCP Server
+
+A Model Context Protocol (MCP) server that provides seamless integration with Anki through the AnkiConnect add-on. This server enables AI assistants and other MCP clients to interact with your Anki flashcard collection programmatically.
+
+![Project](assets/anki-connect-mcp.gif)
+
+## What is Anki Connect?
+
+[AnkiConnect](https://ankiweb.net/shared/info/2055492159) is a powerful Anki add-on that exposes Anki's functionality through a REST API. It allows external applications to:
+
+- Create, modify, and delete flashcards
+- Manage decks and their configurations
+- Control Anki's GUI programmatically
+- Search and retrieve card information
+- Manage tags and note types
+- Perform bulk operations on cards and notes
+
+## What is MCP (Model Context Protocol)?
+
+The Model Context Protocol is a standardized way for AI assistants to connect to external data sources and tools. This MCP server acts as a bridge between MCP clients (like Claude Desktop) and AnkiConnect, allowing AI assistants to help you manage your Anki flashcards naturally through conversation.
+
+## Features
+
+Every tool comes with a description, a title and MCP annotations (`readOnlyHint` / `destructiveHint`), so clients can auto-approve read-only tools and ask before destructive ones. On connect the server also sends instructions for the agent: Anki search syntax, note IDs vs card IDs, and the recommended flow for adding cards.
+
+Errors are reported as tool errors (`isError: true`): `AnkiConnect error: ...` when Anki rejects a request, and `Could not reach AnkiConnect at <url>...` when Anki is not running.
+
+### Default tools
+
+- **Notes:** `add_note`, `add_notes`, `can_add_notes`, `update_note_fields`, `add_tags`, `remove_tags`, `find_notes`, `notes_info`
+- **Cards:** `find_cards`, `cards_info`, `cards_to_notes`, `suspend`, `unsuspend`, `are_suspended`, `are_due`, `get_intervals`
+- **Decks:** `deck_names`, `deck_names_and_ids`, `get_decks`, `change_deck`, `delete_decks`, `get_deck_config`
+- **Models:** `model_names`, `model_names_and_ids`, `model_field_names`, `model_fields_on_templates`
+- **Misc:** `version`, `get_tags`
+
+`find_notes` and `find_cards` return `{ ids, total, truncated }` and accept an optional `limit` (default 100). `cards_info` strips the card CSS from the question and answer.
+
+### Optional tool groups
+
+| Group | Enabled by | Tools |
+|-------|-----------|-------|
+| GUI | `ANKI_MCP_ENABLE_GUI=1` | `gui_browse`, `gui_add_cards`, `gui_current_card`, `gui_start_card_timer`, `gui_show_question`, `gui_show_answer`, `gui_answer_card`, `gui_deck_overview`, `gui_deck_browser`, `gui_deck_review`, `gui_exit_anki` |
+| Advanced | `ANKI_MCP_ENABLE_ADVANCED=1` | `multi`, `upgrade`, `save_deck_config`, `set_deck_config_id`, `clone_deck_config_id`, `remove_deck_config_id` |
+
+## Configuration
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `ANKI_CONNECT_URL` | `http://localhost:8765` | AnkiConnect address |
+| `ANKI_CONNECT_API_KEY` | – | Sent as `key` with every request; set it when AnkiConnect has `apiKey` configured |
+| `ANKI_MCP_ENABLE_GUI` | off | `1` or `true` enables the GUI tools |
+| `ANKI_MCP_ENABLE_ADVANCED` | off | `1` or `true` enables the advanced tools |
+
+### Upgrading from 1.x
+
+- `create_flashcard` was removed; use `add_note` with `deckName`, `modelName` and `fields`.
+- GUI tools, `multi`, `upgrade` and deck-config editing tools are hidden unless their group is enabled.
+- Tool results contain only AnkiConnect's `result` (no `{result, error}` envelope); errors come back as tool errors.
+- `find_notes` / `find_cards` return `{ ids, total, truncated }` instead of a plain array.
+- Node.js 20 or newer is required.
+
+## Prerequisites
+
+### 1. Install AnkiConnect Add-on
+
+1. Open Anki
+2. Go to **Tools** → **Add-ons**
+3. Click **Get Add-ons...**
+4. Enter the code: `2055492159`
+5. Click **OK** and restart Anki
+
+### 2. Configure AnkiConnect (Optional)
+
+AnkiConnect works out of the box, but you can customize its settings:
+
+1. Go to **Tools** → **Add-ons**
+2. Select **AnkiConnect** and click **Config**
+3. Modify settings if needed (default port is 8765)
+4. Restart Anki after making changes
+
+## Installation
+
+1. Clone this repository:
+```bash
+git clone https://github.com/spacholski1225/anki-connect-mcp.git
+cd anki-connect-mcp
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Build the project:
+```bash
+npm run build
+```
+
+## MCP Client Configuration
+
+### Claude Desktop
+
+To use this MCP server with Claude Desktop, add the following configuration to your MCP settings file:
+
+**Location of MCP configuration file:**
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+**Configuration Options:**
+
+#### Option 1: Using Node.js (Local Installation)
+```json
+{
+  "mcpServers": {
+    "anki-connect-mcp": {
+      "command": "node",
+      "args": [
+        "dist/index.js"
+      ],
+      "env": {},
+      "disabled": false,
+      "alwaysAllow": [
+        "deck_names",
+        "cards_info",
+        "deck_names_and_ids",
+        "find_notes"
+      ]
+    }
+  }
+}
+```
+
+#### Option 2: Using npx (NPM Package)
+
+**Then configure your MCP client:**
+```json
+{
+  "mcpServers": {
+    "anki-connect": {
+      "command": "npx",
+      "args": [
+        "@spacholski1225/anki-connect-mcp"
+      ],
+      "env": {},
+      "disabled": false,
+      "alwaysAllow": [
+        "deck_names",
+        "cards_info",
+        "deck_names_and_ids",
+        "find_notes"
+      ]
+    }
+  }
+}
+```
+
+#### Option 3: Using Docker
+```json
+{
+  "mcpServers": {
+    "anki-connect": {
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "-i",
+        "--network=host",
+        "-e", "ANKI_CONNECT_URL=http://host.docker.internal:8765",
+        "spacholski/anki-connect-mcp:latest"
+      ],
+      "env": {},
+      "disabled": false,
+      "alwaysAllow": [
+        "deck_names",
+        "cards_info",
+        "deck_names_and_ids",
+        "find_notes"
+      ]
+    }
+  }
+}
+```
+
+**Docker-Specific AnkiConnect Configuration:**
+
+When using the Docker option, you **must** configure AnkiConnect with specific settings to allow Docker container access:
+
+1. Go to **Tools** → **Add-ons** in Anki
+2. Select **AnkiConnect** and click **Config**
+3. Update the configuration with the following settings:
+
+```json
+{
+    "apiKey": null,
+    "apiLogPath": null,
+    "ignoreOriginList": [],
+    "webBindAddress": "0.0.0.0",
+    "webBindPort": 8765,
+    "webCorsOriginList": [
+        "http://localhost",
+        "http://host.docker.internal",
+        "http://host.docker.internal:3000"
+    ]
+}
+```
+
+**Key Docker Configuration Points:**
+- **`webBindAddress: "0.0.0.0"`** - Allows AnkiConnect to accept connections from any IP address (required for Docker containers)
+- **`webCorsOriginList`** - Must include `"http://host.docker.internal"` and related origins to allow cross-origin requests from Docker containers
+- Restart Anki after making these configuration changes
+
+**Important Notes:**
+- **For Node.js option**: Replace the path in `args` with the actual path to your built `index.js` file
+- **For npx option**: Uses the published NPM package `@spacholski1225/anki-connect-mcp` - no local installation required
+- **For Docker option**: Uses the pre-built Docker image `spacholski/anki-connect-mcp:latest`
+- The `alwaysAllow` array contains tools that won't require confirmation each time
+- Make sure Anki is running with AnkiConnect enabled before using the MCP server
+- For Docker option, the `--network=host` flag allows the container to access AnkiConnect on the host machine
+
+## Usage Examples
+
+Once configured with an MCP client like Claude Desktop, you can interact with your Anki collection naturally:
+
+- *"Create a flashcard about the capital of France in my Geography deck"*
+- *"Show me all my deck names"*
+- *"Find all cards tagged with 'vocabulary'"*
+- *"Suspend all cards in the 'Difficult Words' deck"*
+- *"Open the deck browser in Anki"* (needs `ANKI_MCP_ENABLE_GUI=1`)
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Connection refused**: Make sure Anki is running and AnkiConnect is installed
+2. **Port conflicts**: Check if port 8765 is available or configure AnkiConnect to use a different port
+3. **Permission errors**: Ensure the MCP server has proper file system permissions
+4. **Tool not found**: Verify the MCP client configuration and restart the client
+
+## Development
+
+```bash
+npm run typecheck   # type-check sources and tests
+npm test            # protocol-level tests against a fake AnkiConnect
+npm run build
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
+
+## License
+
+MIT License
+
+## References
+
+- [AnkiConnect Documentation](https://foosoft.net/projects/anki-connect/)
+- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
+- [MCP SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk)