### Install and Setup MCP Publisher CLI

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/README.md

Installs the MCP Publisher CLI tool and makes it executable. This is required for manual publishing to the MCP Registry.

```bash
# Install MCP Publisher
curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.1.0/mcp-publisher_1.1.0_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
chmod +x mcp-publisher
sudo mv mcp-publisher /usr/local/bin/
```

--------------------------------

### Run Anki MCP Server with Default Configuration

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/configuration.md

Start the Anki MCP Server using default settings for AnkiConnect URL, timeout, and retries. This is the simplest way to get the server running.

```typescript
import { AnkiMcpServer } from "anki-mcp-server";

// Uses defaults:
// - AnkiConnect at http://localhost:8765
// - Timeout: 5000ms
// - Retries with max backoff of 10000ms
const server = new AnkiMcpServer();
await server.run();
```

--------------------------------

### AnkiClient Configuration Example

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/types.md

Example of how to create an AnkiConfig object and initialize an AnkiClient with custom settings.

```typescript
const config: AnkiConfig = {
  ankiConnectUrl: "http://127.0.0.1:8080",
  apiVersion: 6,
  timeout: 10000,
  retryTimeout: 10000,
  defaultDeck: "Default"
};

const client = new AnkiClient(config);
```

--------------------------------

### Install Dependencies

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/CLAUDE.md

Installs project dependencies using npm.

```bash
npm install
```

--------------------------------

### Build anki-mcp-server Bundle

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/llms-install.md

Installs the MCPB packager globally and builds the installable archive for the anki-mcp-server.

```bash
npm install -g @anthropic-ai/mcpb
mcpb pack
```

--------------------------------

### Install Beta Version

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/RELEASE.md

Users can install the beta version of the package using the '@beta' tag. This allows for testing pre-release features.

```bash
npm install anki-mcp-server@beta
```

--------------------------------

### Batch Create Notes Response Example

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/endpoints.md

Example response for the batch note creation endpoint, showing success and failure statuses for individual notes.

```json
{
  "results": [
    {
      "success": true,
      "noteId": 1234567890,
      "index": 0
    },
    {
      "success": false,
      "error": "Note type not found: Unknown",
      "index": 1
    }
  ],
  "total": 2,
  "successful": 1,
  "failed": 1
}
```

--------------------------------

### ToolSchema Example

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/types.md

An example of a ToolSchema object for a 'create_note' tool.

```typescript
{
  name: "create_note",
  description: "Create a single note...",
  inputSchema: {
    type: "object",
    properties: {
      type: { type: "string" },
      deck: { type: "string" },
      fields: { type: "object" }
    },
    required: ["type", "deck", "fields"]
  }
}
```

--------------------------------

### Initialize and Run AnkiMcpServer

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/anki-mcp-server.md

Instantiate the AnkiMcpServer with a specified port and host, then start the server. The server will run until interrupted by SIGINT.

```typescript
import { AnkiMcpServer } from "anki-mcp-server";

const server = new AnkiMcpServer(8765, "localhost");
await server.run();
```

--------------------------------

### Example Resource Object

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/types.md

An example of a Resource object, representing a collection of all Anki decks.

```typescript
{
  uri: "anki://decks/all",
  name: "All Decks",
  description: "List of all available decks in Anki",
  mimeType: "application/json"
}
```

--------------------------------

### Start AnkiMcpServer

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/anki-mcp-server.md

Starts the MCP server, connecting to the stdio transport and listening for requests. This method blocks until SIGINT is received.

```typescript
const server = new AnkiMcpServer(8765, "localhost");
await server.run(); // Blocks until SIGINT
```

--------------------------------

### Run anki-mcp-server with Auto-Rebuild

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/llms-install.md

Starts the anki-mcp-server in watch mode for development, enabling auto-rebuild on file changes.

```bash
npm run watch
```

--------------------------------

### run() Method

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/anki-mcp-server.md

Starts the MCP server, enabling it to listen for incoming MCP requests. The server remains active until interrupted by a SIGINT signal.

```APIDOC
## run()

### Description
Starts the MCP server by connecting to the stdio transport, sending initial notifications about available tools and resources, and listening for incoming MCP requests. The server will remain running until interrupted by SIGINT (Ctrl+C).

### Method
async

### Endpoint
N/A (Method call)

### Parameters
None

### Request Example
```typescript
const server = new AnkiMcpServer(8765, "localhost");
await server.run(); // Blocks until SIGINT
```

### Response
#### Success Response (void)
Returns a Promise that resolves when the server is stopped.

#### Response Example
N/A (void return type)
```

--------------------------------

### Example NoteInfo Object

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/types.md

An example of a NoteInfo object, representing a note with specific fields and tags.

```typescript
{
  noteId: 1234567890,
  modelName: "Basic",
  tags: ["javascript"],
  fields: {
    Front: {
      value: "What is a closure?",
      order: 0
    },
    Back: {
      value: "A function with outer scope access",
      order: 1
    }
  }
}
```

--------------------------------

### Create Anki Deck

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/README.md

Example of a natural language command to create a new Anki deck.

```plaintext
Create a new Anki deck called "Programming"
```

--------------------------------

### Anki Search Syntax Examples

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/skills/anki/SKILL.md

Examples of Anki search queries using deck, tag, status, note type, and exact phrase matching.

```text
deck:Python              # Cards in Python deck
tag:重要 is:due          # Due cards tagged "重要"
is:new                   # Unseen cards
note:Basic               # Cards using Basic note type
"exact phrase"           # Exact text match
```

--------------------------------

### Example ResourceTemplate Object

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/types.md

An example of a ResourceTemplate object, representing a schema for note types.

```typescript
{
  uriTemplate: "anki://note-types/{modelName}",
  name: "Note Type Schema",
  description: "Detailed structure information for a specific note type",
  mimeType: "application/json"
}
```

--------------------------------

### Example ResourceContent Object

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/types.md

An example of a ResourceContent object, containing JSON data about Anki decks.

```typescript
{
  uri: "anki://decks/all",
  mimeType: "application/json",
  text: '{"decks":["Default","Programming"],"count":2}'
}
```

--------------------------------

### Create an Anki Card Prompt

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/llms-install.md

Example prompt to create a new Anki card. Ensure Anki and Claude are running, and the anki-mcp-server is configured.

```text
Create an Anki card in the "Default" deck with:
Front: What is the capital of France?
Back: Paris
```

--------------------------------

### Search Notes Response Example

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/endpoints.md

Example response for the search notes endpoint, including query details, total matches, and information for the first 50 notes.

```json
{
  "query": "deck:Programming",
  "total": 152,
  "notes": [
    {
      "noteId": 1234567890,
      "modelName": "Basic",
      "tags": ["javascript"],
      "fields": {
        "Front": {
          "value": "What is a closure?",
          "order": 0
        },
        "Back": {
          "value": "A function with outer scope access",
          "order": 1
        }
      }
    }
  ],
  "limitApplied": true
}
```

--------------------------------

### Set ankiConnectUrl Example Values

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/configuration.md

Illustrates various valid URL formats for configuring the AnkiConnect server address.

```typescript
// Local Anki on default port
"http://localhost:8765"

// Local Anki on custom port
"http://127.0.0.1:8080"

// Remote Anki (not recommended without HTTPS/auth)
"http://192.168.1.100:8765"
```

--------------------------------

### Run AnkiMcpServer CLI with Custom Host and Port

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/configuration.md

Configure the AnkiMcpServer's host and port directly via command-line arguments when starting the server.

```bash
node dist/index.js --host 127.0.0.1 --port 8080
```

--------------------------------

### Example ModelSchema Object

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/types.md

An example of a ModelSchema object, defining the structure and templates for a 'Basic' note type.

```typescript
{
  modelName: "Basic",
  fields: ["Front", "Back"],
  templates: {
    "Card 1": {
      Front: "{{Front}}",
      Back: "{{FrontSide}}<hr>{{Back}}"
    }
  },
  css: "body { font-size: 16px; }"
}
```

--------------------------------

### ToolResult Example

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/types.md

An example of a ToolResult object containing JSON-formatted text content.

```typescript
{
  content: [
    {
      type: "text",
      text: '{"decks":["Default","Programming"],"count":2}'
    }
  ]
}
```

--------------------------------

### Configure Claude Desktop for anki-mcp-server

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/llms-install.md

Manually configures Claude Desktop to use the anki-mcp-server. Ensure Anki is running and AnkiConnect is installed.

```json
{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["--yes", "anki-mcp-server"]
    }
  }
}
```

--------------------------------

### AnkiApiError Usage Example

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/types.md

Example of catching AnkiApiError and logging the error message and code.

```typescript
try {
  await client.addNote({
    deckName: "Default",
    modelName: "Basic",
    fields: { Front: "Q", Back: "A" }
  });
} catch (error) {
  if (error instanceof AnkiApiError) {
    console.log("Anki operation failed:", error.message, error.code);
  }
}
```

--------------------------------

### Install Anki Agent Skill for Claude Code

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/README.md

Installs the Anki skill for Claude Code, providing it with built-in knowledge of Anki tools and workflows. This allows Claude Code to automatically manage Anki tasks.

```bash
npx skills add nailuoGG/anki-mcp-server@anki
```

--------------------------------

### Example Response for create_note

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/endpoints.md

This JSON object shows a successful response from the create_note MCP tool, providing the ID of the created note, the deck it was added to, and the model name used.

```json
{
  "noteId": 1234567890,
  "deck": "Programming",
  "modelName": "Basic"
}
```

--------------------------------

### Pack Anki MCP Server for Desktop Extension

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/README.md

Generates a .mcpb file for installing the Anki MCP Server in Claude Desktop. This file is a distributable bundle validated against manifest.json.

```bash
npm run pack
```

--------------------------------

### Example Note Information Response

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/endpoints.md

A successful response contains the note's ID, model name, tags, and field values.

```json
{
  "noteId": 1234567890,
  "modelName": "Basic",
  "tags": ["javascript"],
  "fields": {
    "Front": {
      "value": "What is a closure?",
      "order": 0
    },
    "Back": {
      "value": "A function with outer scope access",
      "order": 1
    }
  }
}
```

--------------------------------

### Add Basic Anki Card

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/README.md

Example of a natural language command to add a basic Anki card to a specified deck.

```plaintext
Create an Anki card in the "Programming" deck with:
Front: What is a closure in JavaScript?
Back: A closure is the combination of a function and the lexical environment within which that function was declared.
```

--------------------------------

### Example Response for create_deck

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/endpoints.md

This JSON object illustrates a successful response from the create_deck MCP tool, containing the ID and name of the newly created Anki deck.

```json
{
  "deckId": 1234567890,
  "name": "Programming"
}
```

--------------------------------

### AnkiConnectionError Usage Example

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/types.md

Demonstrates how to catch and handle AnkiConnectionError when interacting with the Anki client.

```typescript
try {
  await client.checkConnection();
} catch (error) {
  if (error instanceof AnkiConnectionError) {
    console.log("Anki is not running");
  }
}
```

--------------------------------

### Batch Create Anki Notes

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/skills/anki/SKILL.md

Example of a JSON payload for batch creating Anki notes. Supports 'Basic' and 'Cloze' note types. Ensure 'allowDuplicate' and 'stopOnError' are set as needed.

```json
{
  "notes": [
    {
      "type": "Basic",
      "deck": "Programming::Python",
      "fields": {
        "Front": "What does list comprehension look like in Python?",
        "Back": "[expr for item in iterable if condition]"
      },
      "tags": ["python", "syntax"]
    },
    {
      "type": "Cloze",
      "deck": "Programming::Python",
      "fields": {
        "Text": "In Python, {{c1::def}} defines a function and {{c2::return}} sends back a value."
      },
      "tags": ["python", "basics"]
    }
  ],
  "allowDuplicate": false,
  "stopOnError": false
}
```

--------------------------------

### Request for create_deck

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/endpoints.md

This JSON object is an example request payload for the create_deck MCP tool, specifying the name of the new deck to be created.

```json
{
  "name": "Programming"
}
```

--------------------------------

### Anki Resource Handler Caching Example

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/mcp-resource-handler.md

Demonstrates the caching behavior of the Anki Resource Handler. The first call fetches data from Anki, subsequent calls within 5 minutes use the cache, and calls after 5 minutes fetch fresh data.

```typescript
// First call fetches from Anki
const schema1 = await resourceHandler.readResource("anki://note-types/Basic");

// Second call within 5 minutes uses cache
const schema2 = await resourceHandler.readResource("anki://note-types/Basic");

// After 5 minutes, next call fetches fresh
```

--------------------------------

### Request for create_note

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/endpoints.md

This JSON object is an example request for the create_note MCP tool. It includes the note type, target deck, fields, optional tags, and a flag to allow duplicates.

```json
{
  "type": "Basic",
  "deck": "Programming",
  "fields": {
    "Front": "What is a closure?",
    "Back": "A function with access to its outer scope"
  },
  "tags": ["javascript"],
  "allowDuplicate": false
}
```

--------------------------------

### Claude Desktop Custom Host and Port Configuration

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/configuration.md

Configure Claude Desktop with both a custom host and port for the Anki MCP Server. Ensure the host and port match your AnkiConnect setup.

```json
{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["--yes", "anki-mcp-server", "--host", "127.0.0.1", "--port", "8080"]
    }
  }
}
```

--------------------------------

### Get Note Type Info Request

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/endpoints.md

Request detailed structure for a note type, optionally including CSS. Requires the modelName.

```json
{
  "modelName": "Basic",
  "includeCss": true
}
```

--------------------------------

### Manually Clearing Cache

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/mcp-resource-handler.md

This example shows how to manually clear the cache of the resource handler. This is useful for forcing a refresh after external modifications to note types.

```typescript
// Add a note type externally
// ...

// Clear cache to pick up changes
resourceHandler.clearCache();

// Next call will fetch fresh data
const updated = await resourceHandler.readResource("anki://note-types/all");
```

--------------------------------

### Create and Switch to Beta Branch

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/RELEASE.md

Prepare for a beta release by creating a new branch from 'main'. Ensure you pull the latest changes before branching.

```bash
git checkout main
git pull
git checkout -b beta
```

--------------------------------

### Create Custom Note Type Response

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/endpoints.md

This is an example of a successful response after creating a custom note type. It confirms the model name and the number of templates created.

```json
{
  "success": true,
  "modelName": "Custom Type",
  "fields": ["Field1", "Field2"],
  "templates": 1
}
```

--------------------------------

### Retry Operation After Collection Unavailable

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/errors.md

This example shows how to wait for a dialog to be dismissed and then retry an operation, such as fetching deck names, after a potential collection unavailability.

```typescript
// Wait for dialog dismissal
await sleep(5000);
// Retry operation
await client.getDeckNames();
```

--------------------------------

### Catching Unknown Tool Errors in MCP Tool Handler

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/mcp-tool-handler.md

Example of how to use a try-catch block to handle potential errors, such as a MethodNotFound error, when executing a tool with the MCP Tool Handler.

```typescript
try {
  const result = await toolHandler.executeTool("unknown_tool", {});
} catch (error) {
  // McpError(ErrorCode.MethodNotFound, "Unknown tool: unknown_tool")
}
```

--------------------------------

### McpError Throw Example

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/types.md

Example of throwing an McpError with a specific ErrorCode and message.

```typescript
import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types";

throw new McpError(
  ErrorCode.InvalidParams,
  "Note type not found: Unknown"
);
```

--------------------------------

### Get All Available Tool Schemas

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/mcp-tool-handler.md

Retrieve the complete MCP tool schema, including names, descriptions, and input schemas for all available tools. This schema is used for client-side validation and prompt generation.

```typescript
const schema = await toolHandler.getToolSchema();
console.log(schema.tools.length); // Total number of tools
schema.tools.forEach(tool => {
  console.log(`${tool.name}: ${tool.description}`);
});
```

--------------------------------

### Build Server

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/CLAUDE.md

Builds the Anki MCP Server project.

```bash
npm run build
```

--------------------------------

### Make Build File Executable

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/llms-install.md

Grants execute permissions to the build index file to resolve 'Permission denied' errors.

```bash
chmod +x build/index.js
```

--------------------------------

### Commit and Push Beta Changes

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/RELEASE.md

Stage, commit, and push your changes to the 'beta' branch. Use a descriptive commit message for tracking.

```bash
git add .
git commit -m "Your commit message"
git push -u origin beta
```

--------------------------------

### Constructor

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/anki-client.md

Creates a new AnkiClient with optional configuration overrides. Falls back to default configuration if none is provided.

```APIDOC
## Constructor

### Description
Creates a new AnkiClient with the given configuration. If not provided, configuration options fall back to `DEFAULT_CONFIG` values.

### Parameters
#### Path Parameters
- **config** (Partial<AnkiConfig>) - Optional - Optional configuration overrides

### Request Example
```typescript
import { AnkiClient } from "anki-mcp-server";

// Use default config (http://localhost:8765)
const client = new AnkiClient();

// Custom host and port
const customClient = new AnkiClient({
  ankiConnectUrl: "http://127.0.0.1:8080",
  timeout: 10000,
});
```
```

--------------------------------

### AnkiTimeoutError Usage Example

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/types.md

Shows how to catch and identify AnkiTimeoutError during Anki operations.

```typescript
try {
  await client.getDeckNames();
} catch (error) {
  if (error instanceof AnkiTimeoutError) {
    console.log("Anki is not responding");
  }
}
```

--------------------------------

### Configure Host and Port via CLI

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/configuration.md

Set both the host and port for the Anki MCP Server using command-line arguments. This allows flexible network configuration.

```bash
# CLI usage
node dist/index.js --port 8080 --host localhost
```

--------------------------------

### Get Deck Names

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/anki-client.md

Retrieves an array of all available deck names in Anki.

```typescript
const decks = await client.getDeckNames();
// ["Default", "Programming", "Spanish"]
```

--------------------------------

### Format Code

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/CLAUDE.md

Formats the project code using Biome.

```bash
npm run format
```

--------------------------------

### AnkiMcpServer Constructor

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/anki-mcp-server.md

Creates a new AnkiMcpServer instance. It initializes the MCP protocol server, sets up the AnkiClient for communication with AnkiConnect, registers handlers for MCP requests, and configures graceful shutdown.

```APIDOC
## constructor AnkiMcpServer

### Description
Creates a new AnkiMcpServer instance that initializes the MCP protocol server, sets up AnkiClient to communicate with AnkiConnect, registers handlers for MCP requests, and sets up graceful shutdown.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method Signature
```typescript
constructor(port?: number, host?: string): AnkiMcpServer
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **port** (number) - Optional - Default: 8765 - AnkiConnect server port to connect to
- **host** (string) - Optional - Default: localhost - AnkiConnect server hostname

### Request Example
```typescript
import { AnkiMcpServer } from "anki-mcp-server";

const server = new AnkiMcpServer(8765, "localhost");
await server.run();
```

### Response
#### Success Response (200)
N/A (Constructor)

#### Response Example
N/A (Constructor)
```

--------------------------------

### Get Model Names

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/anki-client.md

Retrieves an array of all available note type (model) names in Anki.

```typescript
const noteTypes = await client.getModelNames();
// ["Basic", "Basic (and reversed card)", "Cloze"]
```

--------------------------------

### Get Note Information Request

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/endpoints.md

Send a JSON object with the noteId to retrieve detailed information about a specific note.

```json
{
  "noteId": 1234567890
}
```

--------------------------------

### Get Model Styling

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/anki-client.md

Retrieves the CSS styling for a specified note type. Returns an object containing the CSS string.

```typescript
const styling = await client.getModelStyling("Basic");
console.log(styling.css); // CSS string
```

--------------------------------

### Initialize AnkiClient with Configuration

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/configuration.md

Configure AnkiClient by passing a Partial<AnkiConfig> object to its constructor. Omitted options default to DEFAULT_CONFIG values.

```typescript
const client = new AnkiClient({
  ankiConnectUrl: "http://127.0.0.1:8080",
  timeout: 10000
});
```

--------------------------------

### Run anki-mcp-server Test Suite

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/llms-install.md

Executes the test suite for the anki-mcp-server to verify its functionality.

```bash
npm test
```

--------------------------------

### Get Note Type Info Response

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/endpoints.md

Response includes the note type's name, fields, templates, and optionally CSS.

```json
{
  "modelName": "Basic",
  "fields": ["Front", "Back"],
  "templates": {
    "Card 1": {
      "Front": "{{Front}}",
      "Back": "{{FrontSide}}<hr id=answer>{{Back}}"
    }
  },
  "css": "body { font-size: 16px; }"
}
```

--------------------------------

### Configure Server Programmatically

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/configuration.md

Instantiate the AnkiMcpServer with a specific port and host when running the server programmatically.

```typescript
const server = new AnkiMcpServer(8080, "localhost");
```

--------------------------------

### Login to MCP Registry

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/README.md

Logs the MCP Publisher CLI into the MCP Registry using GitHub OIDC authentication.

```bash
# Login to MCP Registry
mcp-publisher login github-oidc
```

--------------------------------

### Get Note Information

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/anki-client.md

Retrieves detailed information for specified note IDs. Useful for inspecting note content, model, and tags.

```typescript
async notesInfo(ids: number[]): Promise<{ 
  noteId: number;
  modelName: string;
  tags: string[];
  fields: Record<string, { value: string; order: number }>;
}[]>
```

```typescript
const noteInfo = await client.notesInfo([1234567890]);
// [
//   {
//     noteId: 1234567890,
//     modelName: "Basic",
//     tags: ["javascript"],
//     fields: {
//       Front: { value: "What is a closure?", order: 0 },
//       Back: { value: "A function with outer scope access", order: 1 }
//     }
//   }
// ]
```

--------------------------------

### URL Encoding for Model Names

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/mcp-resource-handler.md

Model names containing special characters must be URL-encoded. This example shows encoding for spaces and parentheses.

```text
anki://note-types/Basic%20%28and%20reversed%20card%29
```

--------------------------------

### Add Cloze Deletion Anki Card

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/README.md

Example of a natural language command to add a cloze deletion card to a specified Anki deck.

```plaintext
Create a cloze card in the "Programming" deck with:
Text: In JavaScript, {{c1::const}} declares a block-scoped variable that cannot be {{c2::reassigned}}.
```

--------------------------------

### Configure AnkiMcpServer Host and Port

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/configuration.md

Initialize AnkiMcpServer with specific port and host parameters to control where the server listens for connections.

```typescript
const server = new AnkiMcpServer(port, host);
```

--------------------------------

### View Published Package Information

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/RELEASE.md

Verify that the package has been successfully published to npm by viewing its details. This command fetches information about the latest version.

```bash
npm view anki-mcp-server
```

--------------------------------

### Get Note Type Schema

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/mcp-resource-handler.md

Retrieves the schema for a specific Anki note type. Special characters in model names must be URL-encoded.

```APIDOC
## GET anki://note-types/{modelName}

### Description
Retrieves the schema for a specific Anki note type, including its fields, templates, and CSS. The `createTool` field indicates the MCP tool used for creating notes of this type. Model names with special characters must be URL-encoded.

### Method
GET

### Endpoint
`anki://note-types/{modelName}`

### Parameters
#### Path Parameters
- **modelName** (string) - Required - The name of the note type to retrieve.

### Response
#### Success Response (200)
- **modelName** (string) - The name of the note type.
- **fields** (string[]) - An array of field names for the note type.
- **templates** (object) - An object mapping template names to their Front and Back HTML.
- **css** (string) - The CSS styling for the note type.
- **createTool** (string) - The MCP tool to use for creating notes of this type.

### Response Example
```json
{
  "modelName": "Basic",
  "fields": ["Front", "Back"],
  "templates": {
    "Card 1": {
      "Front": "{{Front}}",
      "Back": "{{FrontSide}}<hr>{{Back}}"
    }
  },
  "css": "...",
  "createTool": "create_Basic_note"
}
```
```

--------------------------------

### Direct Imports for Other Classes

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/types.md

Demonstrates how to import specific classes like AnkiClient and McpResourceHandler directly from the 'anki-mcp-server' package.

```typescript
import { AnkiClient } from "anki-mcp-server";
import { McpToolHandler } from "anki-mcp-server";
import { McpResourceHandler } from "anki-mcp-server";
```

--------------------------------

### createDeck

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/anki-client.md

Creates a new deck in Anki with the specified name.

```APIDOC
## createDeck(name: string)

### Description
Creates a new deck in Anki with the specified name.

### Parameters
#### Path Parameters
- **name** (string) - Yes - Name of the deck to create

### Returns
`number` — Deck ID (0 if creation failed)

### Request Example
```typescript
const deckId = await client.createDeck("Programming");
console.log("Created deck with ID:", deckId);
```
```

--------------------------------

### Main Module Export

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/types.md

Exports the main AnkiMcpServer class from the package's entry point.

```typescript
export { AnkiMcpServer } from "./ankiMcpServer.js";
```

--------------------------------

### Get Model Templates

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/anki-client.md

Retrieves the card templates for a given note type. Returns an object mapping template names to their front and back HTML.

```typescript
const templates = await client.getModelTemplates("Basic");
// {
//   "Card 1": {
//     "Front": "{{Front}}",
//     "Back": "{{FrontSide}}<hr id=answer>{{Back}}"
//   }
// }
```

--------------------------------

### Get Model Field Names

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/anki-client.md

Retrieves an array of field names for a specified note type. Handles different models like 'Basic' or 'Cloze'.

```typescript
const fields = await client.getModelFieldNames("Basic");
// ["Front", "Back"]

const clozeFields = await client.getModelFieldNames("Cloze");
// ["Text", "Extra"]
```

--------------------------------

### Run MCP Inspector

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/CLAUDE.md

Launches the MCP Inspector for debugging purposes.

```bash
npm run inspector
```

--------------------------------

### Initialize McpToolHandler

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/mcp-tool-handler.md

Instantiate McpToolHandler with an optional AnkiClient. A default client is created if none is provided.

```typescript
import { McpToolHandler, AnkiClient } from "anki-mcp-server";

const client = new AnkiClient({ ankiConnectUrl: "http://localhost:8765" });
const toolHandler = new McpToolHandler(client);
```

--------------------------------

### List Available Resources

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/mcp-resource-handler.md

Retrieves a list of static resources available directly by URI. Currently, this includes the 'anki://decks/all' URI.

```typescript
const resources = await resourceHandler.listResources();
// Returns:
// {
//   resources: [
//     {
//       uri: "anki://decks/all",
//       name: "All Decks",
//       description: "List of all available decks in Anki",
//       mimeType: "application/json"
//     }
//   ]
// }
```

--------------------------------

### Instantiate AnkiClient

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/anki-client.md

Creates a new AnkiClient. Use default configuration or provide custom overrides for AnkiConnect URL and timeout.

```typescript
import { AnkiClient } from "anki-mcp-server";

// Use default config (http://localhost:8765)
const client = new AnkiClient();

// Custom host and port
const customClient = new AnkiClient({
  ankiConnectUrl: "http://127.0.0.1:8080",
  timeout: 10000,
});
```

--------------------------------

### create_deck

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/endpoints.md

Creates a new Anki deck. This tool requires an active Anki connection and a deck name.

```APIDOC
## create_deck

### Description
Create a new Anki deck.

### Method
POST

### Endpoint
/mcp/callTool

### Parameters
#### Request Body
- **name** (string) - Required - Name of the deck to create

### Request Example
```json
{
  "tool": "create_deck",
  "args": {
    "name": "Programming"
  }
}
```

### Response
#### Success Response (200)
- **deckId** (number) - ID of the newly created deck
- **name** (string) - Name of the deck

#### Response Example
```json
{
  "deckId": 1234567890,
  "name": "Programming"
}
```
```

--------------------------------

### Anki Note Type Schema Example

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/mcp-resource-handler.md

This JSON object represents the schema for an Anki note type, including its fields, card templates, CSS, and the tool used for creation. The 'createTool' field specifies the MCP tool for creating notes of this type.

```json
{
  "modelName": "Basic",
  "fields": ["Front", "Back"],
  "templates": {
    "Card 1": {
      "Front": "{{Front}}",
      "Back": "{{FrontSide}}<hr>{{Back}}"
    }
  },
  "css": "...",
  "createTool": "create_Basic_note"
}
```

--------------------------------

### McpToolHandler Constructor

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/mcp-tool-handler.md

Initializes a new instance of the McpToolHandler. An AnkiClient instance can be provided, otherwise a default one will be created.

```APIDOC
## McpToolHandler Constructor

### Description
Initializes a new instance of the McpToolHandler. An AnkiClient instance can be provided, otherwise a default one will be created.

### Parameters
#### Path Parameters
- **ankiClient** (AnkiClient) - Optional - AnkiClient instance; creates default if not provided

### Request Example
```typescript
import { McpToolHandler, AnkiClient } from "anki-mcp-server";

const client = new AnkiClient({ ankiConnectUrl: "http://localhost:8765" });
const toolHandler = new McpToolHandler(client);
```
```

--------------------------------

### Configure ankiConnectUrl for AnkiClient

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/configuration.md

Set the full URL for the AnkiConnect server when initializing AnkiClient. Ensure the URL includes the protocol, host, and port.

```typescript
const client = new AnkiClient({
  ankiConnectUrl: "http://127.0.0.1:8080"
});
```

--------------------------------

### Search Notes by Query

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/endpoints.md

Search for notes using Anki's query syntax. This endpoint returns detailed information for the first 50 matching notes.

```json
{
  "query": "deck:Programming tag:javascript"
}
```

--------------------------------

### create_note

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/endpoints.md

Creates a single note in Anki. For multiple notes, use `batch_create_notes`. Requires an Anki connection and note details.

```APIDOC
## create_note

### Description
Create a single note in Anki. For multiple notes, use `batch_create_notes` instead (10-20 notes per batch recommended). Always call `get_note_type_info` first to understand required fields.

### Method
POST

### Endpoint
/mcp/callTool

### Parameters
#### Request Body
- **type** (string) - Required - Note type name (e.g., "Basic", "Cloze")
- **deck** (string) - Required - Target deck name
- **fields** (object) - Required - Note fields (keys must match model fields)
- **allowDuplicate** (boolean) - Optional - Whether to allow duplicate notes (defaults to false)
- **tags** (string[]) - Optional - Optional tags for organization (defaults to [])

### Request Example
```json
{
  "tool": "create_note",
  "args": {
    "type": "Basic",
    "deck": "Programming",
    "fields": {
      "Front": "What is a closure?",
      "Back": "A function with access to its outer scope"
    },
    "tags": ["javascript"],
    "allowDuplicate": false
  }
}
```

### Response
#### Success Response (200)
- **noteId** (number) - ID of created note
- **deck** (string) - Target deck name
- **modelName** (string) - Note type used

#### Response Example
```json
{
  "noteId": 1234567890,
  "deck": "Programming",
  "modelName": "Basic"
}
```
```

--------------------------------

### Anki MCP Server Module Structure

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/README.md

Overview of the Anki MCP Server's directory structure, including source files and compiled output.

```tree
anki-mcp-server
├── src/
│   ├── index.ts              # Entry point (CLI parser)
│   ├── ankiMcpServer.ts      # AnkiMcpServer class
│   ├── ankiClient.ts         # AnkiClient class (anti-corruption layer)
│   ├── mcpTools.ts           # McpToolHandler class
│   ├── mcpResource.ts        # McpResourceHandler class
│   ├── utils.ts              # Error classes and helpers
│   └── _version.ts           # Version (generated at build)
└── dist/                      # Compiled output
    └── index.js              # Built server entrypoint
```

--------------------------------

### Configure MCP Server for Anki

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/skills/anki/SKILL.md

Configure the MCP server to use the anki-mcp-server integration. Ensure you do not use the .mcpb packaged version.

```json
{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["-y", "anki-mcp-server"]
    }
  }
}
```

--------------------------------

### Configure Anki MCP Server for Claude Desktop with Custom Port

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/README.md

Specifies a custom port for AnkiConnect when configuring the Anki MCP Server in claude_desktop_config.json. Use this if AnkiConnect is not running on the default port.

```json
{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["--yes", "anki-mcp-server", "--port", "8080"]
    }
  }
}
```

--------------------------------

### list_decks

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/endpoints.md

Lists all available Anki decks. This tool requires an active Anki connection.

```APIDOC
## list_decks

### Description
List all available Anki decks.

### Method
POST

### Endpoint
/mcp/callTool

### Parameters
None

### Request Body
```json
{
  "tool": "list_decks",
  "args": {}
}
```

### Response
#### Success Response (200)
- **decks** (string[]) - Array of deck names
- **count** (number) - Total number of decks

#### Response Example
```json
{
  "decks": ["Default", "Programming", "Spanish"],
  "count": 3
}
```
```

--------------------------------

### Initialize McpResourceHandler

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/mcp-resource-handler.md

Initializes the resource handler with an optional AnkiClient instance. Internal caching for model schemas is set up with a 5-minute expiry.

```typescript
import { McpResourceHandler, AnkiClient } from "anki-mcp-server";

const client = new AnkiClient();
const resourceHandler = new McpResourceHandler(client);
```

--------------------------------

### batch_create_notes

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/endpoints.md

Create multiple notes at once. It's recommended to limit batch size to 10-20 notes for optimal performance and split larger sets into multiple batches. Always call `get_note_type_info` first to understand the required fields.

```APIDOC
## batch_create_notes

### Description
Create multiple notes at once. IMPORTANT: For optimal performance, limit batch size to 10-20 notes at a time. For larger sets, split into multiple batches. Always call `get_note_type_info` first to understand the required fields.

### Parameters
#### Request Body
- **notes** (array) - Required - Array of note objects (max 50)
  - **notes[].type** (string) - Required - Note type name
  - **notes[].deck** (string) - Required - Target deck name
  - **notes[].fields** (object) - Required - Note fields
  - **notes[].tags** (string[]) - Optional - Optional tags
- **allowDuplicate** (boolean) - Optional - Allow duplicate notes
- **stopOnError** (boolean) - Optional - Stop on first error or continue

### Request Example
```json
{
  "notes": [
    {
      "type": "Basic",
      "deck": "Programming",
      "fields": {
        "Front": "What is a closure?",
        "Back": "A function with outer scope access"
      },
      "tags": ["javascript"]
    },
    {
      "type": "Cloze",
      "deck": "Programming",
      "fields": {
        "Text": "In JavaScript, {{c1::const}} is {{c2::block-scoped}}"
      },
      "tags": ["javascript"]
    }
  ],
  "stopOnError": false
}
```

### Response
#### Success Response (200)
- **results** (array) - Array of per-note results
  - **results[].success** (boolean) - Whether this note succeeded
  - **results[].noteId** (number | null) - Note ID if successful
  - **results[].error** (string) - Error message if failed
  - **results[].index** (number) - Index in original notes array
- **total** (number) - Total notes requested
- **successful** (number) - Number of successful notes
- **failed** (number) - Number of failed notes

#### Response Example
```json
{
  "results": [
    {
      "success": true,
      "noteId": 1234567890,
      "index": 0
    },
    {
      "success": false,
      "error": "Note type not found: Unknown",
      "index": 1
    }
  ],
  "total": 2,
  "successful": 1,
  "failed": 1
}
```

### Error Cases
- Notes array is required: InvalidParams error
- Empty notes array: InvalidParams error
- Individual note validation errors: Reported per-note in results

### Behavior
- Processes notes sequentially
- Each note's deck is auto-created if it doesn't exist
- Field names are normalized case-insensitively
- If stopOnError is true, stops at first failure
- If stopOnError is false, continues and reports all failures
- Max 50 notes per request (recommended: 10-20 for performance)

### Requires Anki Connection
Yes
```

--------------------------------

### Run Test Coverage

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/CLAUDE.md

Generates a code coverage report for the project tests.

```bash
npm run test:coverage
```

--------------------------------

### listResources

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/mcp-resource-handler.md

Retrieves a list of static resources available directly by URI. These are not templates and are intended for direct access.

```APIDOC
## listResources()

### Description
Returns static resources available directly by URI (not templates). Currently lists `anki://decks/all`.

### Method
async

### Endpoint
listResources()

### Returns
Object containing array of static resources:
- `resources[].uri` — Absolute resource URI
- `resources[].name` — Human-readable name
- `resources[].description` — Optional description
- `resources[].mimeType` — Content type (application/json)

### Response Example
```json
{
  "resources": [
    {
      "uri": "anki://decks/all",
      "name": "All Decks",
      "description": "List of all available decks in Anki",
      "mimeType": "application/json"
    }
  ]
}
```
```

--------------------------------

### listResourceTemplates

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/mcp-resource-handler.md

Retrieves a list of resource URI templates that accept parameters, allowing for dynamic resource access.

```APIDOC
## listResourceTemplates()

### Description
Returns template URIs that accept parameters. Available templates include those for note-types and decks.

### Method
async

### Endpoint
listResourceTemplates()

### Returns
Object containing array of resource URI templates:
- `resourceTemplates[].uriTemplate` — URI template with variables in `{braces}`
- `resourceTemplates[].name` — Human-readable name
- `resourceTemplates[].description` — Optional description
- `resourceTemplates[].mimeType` — Content type

### Response Example
```json
{
  "resourceTemplates": [
    {
      "uriTemplate": "anki://note-types/{modelName}",
      "name": "Note Type Details",
      "description": "Details for a specific note type"
    },
    {
      "uriTemplate": "anki://note-types/all",
      "name": "All Note Type Names",
      "description": "List of all note type names"
    },
    {
      "uriTemplate": "anki://note-types/all-with-schemas",
      "name": "All Note Types with Schemas",
      "description": "All note types with full schemas"
    },
    {
      "uriTemplate": "anki://decks/all",
      "name": "All Decks",
      "description": "Complete list of decks"
    }
  ]
}
```
```

--------------------------------

### Create a New Anki Model

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/anki-client.md

Use this method to define a new note type with custom fields, styling, and card templates. Ensure all required parameters are provided.

```typescript
async createModel(params: {
  modelName: string;
  inOrderFields: string[];
  css: string;
  cardTemplates: {
    name: string;
    front: string;
    back: string;
  }[];
}): Promise<void>
```

```typescript
await client.createModel({
  modelName: "Custom Note Type",
  inOrderFields: ["Field1", "Field2"],
  css: "body { font-size: 16px; }",
  cardTemplates: [
    {
      name: "Card 1",
      front: "{{Field1}}",
      back: "{{Field2}}"
    }
  ]
});
```

--------------------------------

### Response Schema: anki://decks/all

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/api-reference/mcp-resource-handler.md

JSON response structure for the 'anki://decks/all' resource, listing available decks and their count.

```json
{
  "decks": ["Default", "Programming", "Spanish"],
  "count": 3
}
```

--------------------------------

### Trigger Anki Sync

Source: https://github.com/nailuogg/anki-mcp-server/blob/master/_autodocs/endpoints.md

Initiate a synchronization with AnkiWeb. This is a fire-and-forget operation; success indicates the request was accepted, not that the sync is complete. Anki may queue the sync if a dialog is open.

```json
{
  "success": true,
  "message": "Sync requested. AnkiConnect does not confirm completion; if changes don't appear on AnkiWeb, check Anki for a pending dialog."
}
```