anki_mcp_server CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP server enabling AI assistants to interact with Anki via AnkiConnect. Built with NestJS and @rekog/mcp-nest.

• Package: @ankimcp/anki-mcp-server (npm)
• License: MIT
• Status: Beta (0.x.x) - breaking changes allowed
• User-facing docs: README.md covers installation, client setup (Claude Desktop/MCPB, HTTP, tunnel), and the full tool catalog — consult it for anything user-facing rather than reconstructing it here.

Quick Reference

# Build & Run
npm run build                    # Build → dist/ (all three entry points)
npm run start:dev:stdio          # STDIO mode with watch
npm run start:dev:http           # HTTP mode with watch

npm run start:dev:tunnel         # Tunnel mode with watch + debug

# Testing
npm test                         # All tests
npm test -- path/to/file.spec.ts # Single test file
npm run test:tools               # Tool unit tests only
npm run test:workflows           # Multi-tool workflow scenarios (mocked)
npm run test:cov                 # With coverage (70% threshold)
npm run e2e:full:local           # One-shot E2E: up → test → down

# Quality
npm run lint && npm run type-check   # Pre-push checks (also runs via Husky)

# Debugging
npm run inspector:stdio          # MCP Inspector UI for testing tools
npm run inspector:stdio:debug    # With debugger on port 9229
npm run inspector:http           # Inspector against HTTP transport

Architecture

Entry Points

Three entry points compiled in a single build:

Mode	Entry	Use Case	Logging
STDIO	dist/main-stdio.js	Claude Desktop, MCP clients	stderr
HTTP	dist/main-http.js	Web-based AI (ChatGPT, claude.ai)	stdout
Tunnel	dist/main-tunnel.js	Remote access via WebSocket tunnel	stderr

Core Files

src/
├── main-stdio.ts            # STDIO bootstrap: NestFactory.createApplicationContext()
├── main-http.ts             # HTTP bootstrap: NestFactory.create() + guards
├── main-tunnel.ts           # Tunnel bootstrap: auth commands + WebSocket tunnel
├── app.module.ts            # Root module with forStdio()/forHttp()/forTunnel() factories
├── bootstrap.ts             # Shared logger setup (pino → NestJS LoggerService)
├── version.ts               # Package version constant (read from package.json at build)
├── cli/                     # CLI layer (Commander parsing + user-facing output)
│   ├── args.ts              # Commander entrypoint: option parsing, subcommand dispatch
│   ├── cli-output.ts        # User-facing print helpers (cli.success/error/info/box) — separate from args.ts so non-CLI code can use it without pulling in Commander
│   ├── spinner.ts           # Terminal spinner for long-running CLI operations
│   └── index.ts             # Barrel re-export for the cli module
├── app-config.service.ts    # IAnkiConfig implementation (reads from validated AppConfig)
├── config/                  # Zod-validated config system (schema, factory, APP_CONFIG token)
├── services/ngrok.service.ts # Optional ngrok subprocess for HTTP-mode public tunneling
├── http/guards/             # HTTP-only guards (Origin allowlist)
├── tunnel/                  # Tunnel mode: WebSocket client, OAuth device flow, credentials
│   ├── tunnel.client.ts     # WebSocket client for tunnel server
│   ├── tunnel-mcp.service.ts # Bridges MCP ↔ tunnel via InMemoryTransport
│   ├── in-memory.transport.ts # MCP transport that connects to TunnelClient in-process
│   ├── tunnel.protocol.ts   # WS message type definitions (request/response/ping/error)
│   ├── device-flow.service.ts # OAuth device flow authentication
│   ├── credentials.service.ts # Persistent credential storage
│   └── commands/            # CLI command handlers (login, logout, tunnel)
└── mcp/
    ├── clients/anki-connect.client.ts  # HTTP client using ky (retries, error handling, read-only guard)
    ├── config/anki-config.interface.ts # ANKI_CONFIG injection token + IAnkiConfig interface
    ├── types/anki.types.ts             # Shared Anki types (cards, notes, ratings)
    ├── utils/                          # Shared utilities (anki.utils, markdown.utils, stats.utils)
    ├── primitives/essential/           # Core tools, prompts, resources
    └── primitives/gui/                 # GUI-specific tools (require user approval)