Anki MCP

oficial

Um servidor MCP que permite que assistentes de IA interajam com o Anki, o aplicativo de flashcards de repetição espaçada.

GitHub

542

O que você pode fazer com Anki MCP?

Review due cards — Peça ao seu assistente para buscar os cartões vencidos de um baralho específico e testar você com eles usando get_due_cards e present_card.
Rate card performance — Peça ao assistente para registrar a qualidade da sua resposta (Again, Hard, Good, Easy) para reprogramar as revisões via rate_card.
Create custom flashcards — Instrua o assistente a criar novos tipos de nota com campos personalizados e estilo RTL usando createModel e updateModelStyling, e depois adicionar notas em lote com addNotes.
Manage note content — Pesquise notas com a sintaxe de consulta do Anki (deck:, tag:, is:due) via findNotes e depois atualize os campos delas com updateNoteFields.
Import media into cards — Peça ao assistente para enviar uma imagem de um caminho local ou URL com storeMediaFile e inseri-la no campo de uma nota selecionada usando guiSelectedNotes e updateNoteFields.
Organize decks and cards — Crie baralhos aninhados (Parent::Child) com createDeck, mova cartões entre baralhos com changeDeck ou suspenda cartões com suspend para pulá-los durante a revisão.

Documentação

Servidor Anki MCP

Integre perfeitamente o Anki com assistentes de IA através do Model Context Protocol

[!IMPORTANT] Prefira o addon AnkiMCP para a maioria das configurações.

O addon (GitHub) executa o servidor MCP diretamente dentro do Anki. Não é necessário instalar Node.js, configurar AnkiConnect ou manter um processo separado em execução: instale-o com o código 124672614, reinicie o Anki, e o servidor estará ativo toda vez que o Anki abrir. Ele cobre acesso HTTP local e acesso remoto através de um túnel integrado.

Este repositório é a escolha certa quando você precisar especificamente de:

Transporte STDIO — Claude Desktop, Claude Code, Cursor ou qualquer cliente que inicie o servidor como subprocesso

Pacote MCPB — a instalação com um clique do .mcpb para Claude Desktop

Para HTTP, túnel ou clientes baseados na web (claude.ai, ChatGPT), o addon é o caminho mais simples e com melhor suporte.

Este repositório não está sendo descontinuado. Ele permanece mantido e lançado junto com o addon como parte do mesmo projeto ankimcp.ai.

Um servidor Model Context Protocol (MCP) que permite que assistentes de IA interajam com o Anki, o aplicativo de flashcards de repetição espaçada.

Transforme sua experiência com o Anki através de interação em linguagem natural — como ter um tutor particular. O assistente de IA não apenas apresenta perguntas e respostas; ele pode explicar conceitos, tornar o processo de aprendizado mais envolvente e humano, fornecer contexto e se adaptar ao seu estilo de aprendizado. Ele pode criar e editar notas em tempo real, transformando suas sessões de estudo em conversas dinâmicas. Mais recursos em breve!

Exemplos e Tutoriais

Para guias abrangentes, exemplos do mundo real e tutoriais passo a passo sobre como usar este servidor MCP com o Claude Desktop, visite:

ankimcp.ai - Documentação completa com exemplos práticos e casos de uso

Consulte docs/ para documentação complementar, incluindo o guia de configuração do revisor e o baralho Anki de exemplo.

Exemplos de Casos de Uso

Três prompts representativos mostrando os fluxos de ferramentas que este servidor permite:

"Ajude-me a revisar meu baralho de espanhol." — O assistente se oferece para sincronizar com o AnkiWeb (sync), busca cartões pendentes (get_due_cards com filtro de baralho), apresenta cada cartão (present_card) e registra sua avaliação (rate_card). Conversa de estudo natural com explicações adaptadas a você.
"Crie 10 cartões de vocabulário em árabe com estilo RTL." — O assistente lista os tipos de nota (modelNames), cria um modelo RTL personalizado se necessário (createModel + updateModelStyling para CSS da direita para a esquerda) e depois cria os cartões em lote (addNotes).
"Importe esta imagem da minha pasta Downloads para a frente da nota selecionada." — O assistente envia o arquivo local (storeMediaFile com um caminho de arquivo), lê a nota atualmente selecionada no navegador (guiSelectedNotes + notesInfo) e atualiza o campo da frente com uma tag <img> (updateNoteFields).

Ferramentas Disponíveis

O servidor expõe 53 ferramentas MCP — 42 ferramentas essenciais para operações diárias do Anki e 11 ferramentas GUI que controlam a interface desktop do Anki para fluxos de edição/criação de notas.

Ferramentas Essenciais

Revisão e Estudo

sync - Sincronize com o AnkiWeb para puxar os dados mais recentes e enviar alterações
get_due_cards - Obtenha cartões pendentes de revisão, opcionalmente filtrados por baralho (respostas omitidas a menos que include_answer: true, padrão false)
get_cards - Obtenha cartões com filtragem flexível por estado (pendente, novo, aprendendo, suspenso, enterrado) e baralho (respostas omitidas a menos que include_answer: true, padrão false)
present_card - Mostre um cartão para revisão com sua pergunta/lado da frente
rate_card - Avalie o desempenho do cartão (Again, Hard, Good, Easy) e agende a próxima revisão
forgetCards - Redefina cartões para novo, descartando seu agendamento sem registrar uma revisão
setDueDate - Reagende cartões para ficarem pendentes em N dias ("0", "3-7", "1!"), sem registrar uma revisão
areSuspended - Verifique o estado de suspensão de um ou mais cartões sem alterar nada
suspend - Suspenda cartões para que sejam pulados durante a revisão até serem dessuspensos
unsuspend - Dessuspenda cartões para que voltem à revisão normal

Nota: forgetCards e setDueDate alteram o agendamento sem registrar uma revisão, que é o que os diferencia de rate_card. Use-os quando o agendamento de um cartão estiver errado em vez da resposta: avaliar um cartão como Again para enterrá-lo mais profundamente registra uma falha real e reduz seu fator de facilidade, distorcendo permanentemente tanto o agendamento futuro quanto suas estatísticas. forgetCards zera o intervalo e recomeça o cartão; setDueDate mantém o histórico do cartão e apenas move a próxima revisão.

Nota: O conteúdo de front/back do cartão é renderizado por cartão a partir de seu próprio modelo (como o Anki o exibe), então cartões reversos e de cloze exibem a direção correta. Texto estático adicionado pelos seus modelos de cartão também aparece na saída.

Gerenciamento de Baralhos

listDecks - Liste todos os baralhos, opcionalmente com estatísticas de fila de estudo por baralho
deckStats - Obtenha estatísticas abrangentes para um único baralho (fila de estudo, contagens reais de estado de cartão, distribuições de facilidade/intervalo)
createDeck - Crie um novo baralho vazio (suporta Parent::Child, máximo de 2 níveis)
changeDeck - Mova cartões para um baralho diferente (criado se não existir)

Nota: As estatísticas de baralho vêm em duas versões. O bloco counts (e tudo que listDecks relata) espelha o navegador de baralhos do Anki: cartões pendentes hoje, limitados pelos limites diários de novos/revisão de cada baralho, com cartões suspensos e enterrados excluídos — então review não é "cartões maduros" e o grupo other é apenas o restante aritmético (principalmente cartões de revisão não pendentes hoje mais novos cartões acima do limite diário). Para totais reais por estado, use o bloco states em deckStats / collection_stats, que conta new, learning, review, suspended e buried via buscas do Anki, ignorando datas de vencimento e limites diários.

Gerenciamento de Notas

addNote - Crie uma única nota com campos e tags especificados
addNotes - Crie em lote até 100 notas compartilhando baralho e modelo (sucesso parcial suportado)
findNotes - Busque notas usando a sintaxe de consulta do Anki (deck:, tag:, is:due, etc.)
notesInfo - Obtenha informações detalhadas sobre notas (campos, tags, tipo de nota, IDs de cartão; CSS vem de modelStyling)
updateNoteFields - Atualize campos de notas existentes (ciente de CSS, suporta conteúdo HTML)
deleteNotes - Exclua notas e todos os cartões associados (destrutivo, requer confirmação)

Gerenciamento de Tags

getTags - Obtenha todas as tags na coleção (use primeiro para evitar duplicação)
addTags - Adicione tags separadas por espaço às notas especificadas
removeTags - Remova tags separadas por espaço das notas especificadas
replaceTags - Renomeie uma tag nas notas especificadas
clearUnusedTags - Remova tags órfãs não usadas por nenhuma nota (destrutivo)

Gerenciamento de Mídia

getMediaFilesNames - Liste arquivos de mídia em collection.media, opcionalmente filtrados por padrão
retrieveMediaFile - Baixe um arquivo de mídia como conteúdo base64
storeMediaFile - Envie mídia a partir de dados base64, um caminho de arquivo absoluto ou uma URL
deleteMediaFile - Remova um arquivo de mídia de collection.media (destrutivo)

💡 Melhor Prática para Imagens:

✅ Use caminhos de arquivo (ex.: /Users/you/image.png) - Rápido e eficiente
✅ Use URLs (ex.: https://example.com/image.jpg) - Download direto
❌ Evite base64 - Extremamente lento e ineficiente em tokens

Basta dizer ao Claude onde a imagem está, e ele lidará com o envio automaticamente usando o método mais eficiente.

Gerenciamento de Modelos/Modelos de Cartão

modelNames - Liste todos os tipos de nota/modelos disponíveis
modelFieldNames - Obtenha nomes de campos para um tipo de nota específico
modelStyling - Obtenha informações de estilo CSS para um tipo de nota
modelTemplates - Obtenha os modelos de cartão (HTML da Frente e do Verso) para um tipo de nota
createModel - Crie um novo tipo de nota com campos personalizados, modelos de cartão e CSS (ex.: modelos RTL)
updateModelStyling - Atualize o estilo CSS de um tipo de nota existente (aplica-se a todos os seus cartões)
updateModelTemplates - Atualize os modelos de cartão (HTML da Frente e do Verso) para um tipo de nota existente (aplica-se a todos os seus cartões)
addModelField - Adicione um novo campo a um tipo de nota existente (anexado no final ou inserido em uma posição específica)
removeModelField - Remova um campo de um tipo de nota existente (exclui seu conteúdo de todas as notas; requer confirmação explícita)
renameModelField - Renomeie um campo em um tipo de nota existente (o Anki reescreve referências ao nome antigo nos modelos de cartão)
repositionModelField - Altere a posição de um campo dentro de um tipo de nota existente

Estatísticas

collection_stats - Estatísticas agregadas em todos os baralhos com detalhamento por baralho e contagens de estado de cartão em toda a coleção
review_stats - Análise do histórico de revisões (padrões temporais, métricas de retenção, sequências de estudo)

Ferramentas GUI

Ferramentas que controlam a interface desktop do Anki. Destinadas a fluxos de edição/criação de notas e gerenciamento de baralhos, não para sessões de revisão.

guiBrowse - Abra o Navegador de Cartões e busque cartões
guiSelectCard - Selecione um cartão específico no Navegador de Cartões
guiSelectedNotes - Obtenha IDs de notas atualmente selecionadas no Navegador de Cartões
guiAddCards - Abra a caixa de diálogo Adicionar Cartões com detalhes de nota predefinidos
guiEditNote - Abra o editor de notas para uma nota específica
guiDeckOverview - Abra a caixa de diálogo Visão Geral do Baralho para um baralho específico
guiDeckBrowser - Abra a caixa de diálogo Navegador de Baralhos
guiCurrentCard - Obtenha informações sobre o cartão atual no modo de revisão (inclui a resposta; erros fora do modo de revisão)
guiShowQuestion - Mostre o lado da pergunta do cartão atual
guiShowAnswer - Mostre o lado da resposta do cartão atual
guiUndo - Desfaça a última ação no Anki

Pré-requisitos

Anki com o plugin AnkiConnect instalado
Node.js 22.12.0+

Instalação

Existem algumas maneiras de colocar o servidor na sua máquina. Depois de instalado, vá para Conectando um Cliente de IA para conectá-lo ao seu assistente de IA — local ou remotamente.

npm (global ou npx)

A maneira de propósito geral de instalar o servidor, adequada para qualquer cliente MCP que o inicie diretamente.

Instale-o globalmente para clientes que executam o comando ankimcp:

npm install -g @ankimcp/anki-mcp-server

Ou execute-o sob demanda sem necessidade de instalação:

npx @ankimcp/anki-mcp-server

Pacote MCPB (Recomendado para Claude Desktop)

A maneira mais fácil de instalar este servidor MCP para Claude Desktop:

Baixe o pacote .mcpb mais recente da página de Releases
No Claude Desktop, instale a extensão:
- Método 1: Vá para Configurações → Extensões e arraste e solte o arquivo .mcpb
- Método 2: Vá para Configurações → Desenvolvedor → Extensões → Instalar Extensão e selecione o arquivo .mcpb
Configure a URL do AnkiConnect se necessário (padrão é http://localhost:8765)
Reinicie o Claude Desktop

Pronto! O pacote inclui tudo o que é necessário para executar o servidor localmente.

Para revisores do Diretório MCP da Anthropic: um passo a passo do zero à integração com um baralho de exemplo pré-populado está em docs/reviewer-setup.md.

Instalar a partir do Código-Fonte (para desenvolvimento)

Para desenvolvimento ou uso avançado (executar a suíte de testes requer Node.js 24.9+ — os scripts de teste do npm carregam os pacotes NestJS 12 somente-ESM via require(esm), que o Jest só suporta nessa versão; o requisito de runtime para usar o servidor continua sendo 22.12.0+):

npm install
npm run build

Conectando um Cliente de IA

Existem duas maneiras de um assistente de IA alcançar este servidor, dependendo de onde o assistente é executado:

Local — o servidor roda na mesma máquina que o cliente de IA (Claude Desktop, Cursor, Cline, Zed ou uma sessão de navegador local). Use STDIO para clientes MCP de desktop e HTTP para ferramentas web locais.
Remoto — uma IA hospedada/remota (por exemplo, ChatGPT ou Claude.ai na nuvem) precisa alcançar o Anki rodando na sua máquina local. Use o Túnel gerenciado (✅ recomendado — autenticado) ou, como alternativa não autenticada mais leve, ngrok.

Local

O servidor roda no mesmo computador que seu cliente de IA e conversa com o AnkiConnect em localhost.

STDIO (integração local principal)

STDIO é o transporte padrão para clientes MCP locais de desktop — Claude Desktop, Cursor IDE, Cline, Zed Editor, opencode e outros. O cliente inicia o servidor como um subprocesso e se comunica via entrada/saída padrão.

Clientes suportados:

Claude Desktop
Cursor IDE — editor de código com IA
Cline — extensão do VS Code para assistência de IA
Zed Editor — editor de código rápido e moderno
opencode — agente de codificação de IA para terminal
Outros clientes MCP que suportam transporte STDIO

Para Claude Desktop, o pacote MCPB é o caminho mais fácil. Para outros clientes, configure o pacote npm com a flag --stdio.

Configuração — Escolha um método:

Método 1: Usando npx (recomendado — sem necessidade de instalação)

{
  "mcpServers": {
    "anki-mcp": {
      "command": "npx",
      "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Método 2: Usando instalação global

Primeiro, instale globalmente:

npm install -g @ankimcp/anki-mcp-server

Depois configure:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "ankimcp",
      "args": ["--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

opencode usa seu próprio formato — servidores ficam em mcp, o comando é um único array e variáveis de ambiente ficam em environment:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "anki-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@ankimcp/anki-mcp-server", "--stdio"],
      "enabled": true,
      "environment": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Locais dos arquivos de configuração:

Cursor IDE: ~/.cursor/mcp.json (macOS/Linux) ou %USERPROFILE%\.cursor\mcp.json (Windows)
Cline: acessível pela interface de configurações no VS Code
Zed Editor: instale como extensão MCP pelo marketplace de extensões
opencode: opencode.json na raiz do seu projeto, ou ~/.config/opencode/opencode.json globalmente

Para recursos específicos de clientes e solução de problemas, consulte a documentação do seu cliente MCP. Veja também Conectar ao Claude Desktop para uma configuração que aponta diretamente para um dist/main-stdio.js compilado.

HTTP (IA web local)

O modo HTTP executa o servidor como um servidor web local que fala o protocolo MCP Streamable HTTP. É o transporte que uma ferramenta de IA baseada em web usa quando apontada para sua máquina, e também é o que as opções Remoto expõem para o mundo externo. Por si só, o modo HTTP vincula-se apenas a localhost.

Vinculando além de localhost? Se você passar --host 0.0.0.0 (ou rodar atrás de um proxy reverso/domínio público), o servidor só aceita cabeçalhos Host de loopback por padrão para proteção contra rebinding de DNS — defina ALLOWED_HOSTS para o(s) hostname(s) que os clientes usam. Veja Configuração do Modo HTTP.

Configuração — Escolha um método:

Método 1: Usando npx (recomendado — sem necessidade de instalação)

# Quick start
npx @ankimcp/anki-mcp-server

# 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

Método 2: Usando instalação global

# Install once
npm install -g @ankimcp/anki-mcp-server

# Run the server
ankimcp

# With custom options
ankimcp --port 8080 --host 0.0.0.0
ankimcp --anki-connect http://localhost:8765

Método 3: Instalar a partir do código-fonte (para desenvolvimento)

npm install
npm run build
npm run start:prod:http

Para tornar um servidor HTTP local acessível por uma IA hospedada na nuvem, use uma das opções Remoto abaixo.

Remoto

Uma IA hospedada/remota (como ChatGPT ou Claude.ai rodando na nuvem) não consegue alcançar localhost diretamente. Essas opções expõem seu Anki local à internet para que um assistente remoto possa conversar com ele.

Túnel (✅ Recomendado)

Caminho remoto recomendado — autenticado e seguro. Diferente de uma porta pública bruta, o modo túnel exige que você faça login (fluxo de dispositivo OAuth 2.0), então o endpoint não fica aberto para qualquer um que adivinhe a URL.

O modo túnel permite que assistentes de IA baseados em web alcancem seu Anki local sem executar seu próprio túnel. O servidor conecta-se ao serviço de túnel gerenciado AnkiMCP (wss://tunnel.ankimcp.ai) via WebSocket e recebe uma URL pública. A autenticação é integrada — sem necessidade de conta ngrok ou processo de túnel separado, e você faz login apenas uma vez.

Login (fluxo de dispositivo OAuth):

O modo túnel usa o OAuth 2.0 Device Authorization Grant. O login abre seu navegador automaticamente em uma página de aprovação com o código já embutido na URL — nada para digitar, apenas aprovar. (Se o navegador não abrir, o terminal imprime uma URL de verificação e o código para inserir manualmente como alternativa.) Em caso de sucesso, as credenciais são salvas em ~/.ankimcp/credentials.json (permissões de arquivo 0600).

# Pre-authenticate (optional — --tunnel will trigger this automatically if needed)
ankimcp --login
npx @ankimcp/anki-mcp-server --login

# Clear saved credentials
ankimcp --logout

Iniciar o túnel:

# Connect to the managed tunnel service (wss://tunnel.ankimcp.ai)
ankimcp --tunnel
npx @ankimcp/anki-mcp-server --tunnel

# Override the tunnel server URL (must be ws:// or wss://) — e.g. for self-hosting
ankimcp --tunnel wss://my-tunnel.example.com

Se não houver credenciais, --tunnel inicia automaticamente o fluxo de login primeiro e depois continua para o túnel. Este login automático requer um terminal interativo — quando stdout não é um TTY (systemd, Docker headless, CI), o servidor falha rapidamente e pede que você execute ankimcp --login primeiro. Uma vez conectado, a URL pública do túnel é impressa; pressione Ctrl+C para desconectar. Compartilhe essa URL com seu assistente de IA.

Variáveis de ambiente do modo túnel:

Variável	Descrição	Padrão
`TUNNEL_SERVER_URL`	URL do WebSocket do servidor de túnel (o valor da flag `--tunnel`/`--login` substitui isso)	`wss://tunnel.ankimcp.ai`
`TUNNEL_AUTH_CLIENT_ID`	ID do cliente OAuth para o fluxo de dispositivo. Avançado — necessário apenas ao apontar para um serviço de túnel/auth auto-hospedado.	(integrado)

Os endpoints de autenticação do fluxo de dispositivo (/auth/device, /auth/token) são derivados de TUNNEL_SERVER_URL, então apontar --tunnel (ou TUNNEL_SERVER_URL) para um host diferente também move a autenticação para esse host.

Como funciona: O modo túnel executa o servidor MCP em processo atrás de um transporte em memória (TunnelTransport). Esse transporte é dono do servidor MCP e transforma cada corpo de requisição retransmitido em uma resposta, e TunnelClient faz a ponte para o serviço de túnel remoto via WebSocket — retransmitindo requisições MCP de entrada e respostas de saída. O AnkiConnect ainda é alcançado apenas na sua máquina local.

Revisões de protocolo: Como o túnel conecta o servidor MCP em processo, o modo túnel atende apenas à revisão de 2025 do protocolo MCP, enquanto os modos STDIO e HTTP atendem tanto a 2025 quanto à revisão mais nova de 2026-07-28. Cada ferramenta se comporta da mesma forma de qualquer maneira — mas um cliente que fala apenas 2026-07-28 é recusado pelo túnel com um erro de versão de protocolo; execute o modo STDIO ou HTTP para esse cliente.

ngrok (alternativa não autenticada)

Se você preferir expor o modo HTTP local publicamente sem uma conta no túnel gerenciado, a flag integrada --ngrok inicia um subprocesso ngrok (src/services/ngrok.service.ts) e imprime a URL pública no banner de inicialização:

# One-time ngrok setup, then:
ankimcp --ngrok

Esta rota é não autenticada — qualquer pessoa com a URL pode alcançar seu Anki, então é menos segura que o Túnel. Prefira o Túnel, a menos que você tenha um motivo específico para gerenciar seu próprio endpoint ngrok. (Requer instalação global do ngrok e authtoken.)

A flag --ngrok inicia o ngrok com --host-header=rewrite, então o ngrok reescreve o Host upstream para localhost antes de encaminhar. Isso mantém as requisições dentro da lista de permissões de Host de loopback (veja proteção contra rebinding de DNS) sem que você precise adicionar o domínio público *.ngrok a ALLOWED_HOSTS. Se você executar o ngrok manualmente, use a mesma flag — ngrok http --host-header=rewrite 3000 — caso contrário, o ngrok encaminha o hostname público do ngrok como Host e o servidor o rejeita com 403.

Opções de CLI (todos os modos)

ankimcp [options]

Options:
  --stdio                        Run in STDIO mode (for MCP clients)
  --tunnel [url]                 Connect via the managed tunnel (authenticated)
  --login                        Authenticate for tunnel mode (OAuth device flow)
  --logout                       Clear saved tunnel credentials
  -p, --port <number>            Port to listen on (HTTP mode; default: 3000, or PORT env var)
  -h, --host <address>           Host to bind to (HTTP mode; default: 127.0.0.1, or HOST env var)
  -a, --anki-connect <url>       AnkiConnect URL (default: http://localhost:8765, or ANKI_CONNECT_URL env var)
  --ngrok                        Start ngrok tunnel (requires global ngrok installation)
  --read-only                    Run in read-only mode (blocks content changes and rescheduling; rating, suspend and sync still work)
  --help                         Show help message

Usage with npx (no installation needed):
  npx @ankimcp/anki-mcp-server                        # HTTP mode
  npx @ankimcp/anki-mcp-server --port 8080            # Custom port
  npx @ankimcp/anki-mcp-server --stdio                # STDIO mode
  npx @ankimcp/anki-mcp-server --tunnel               # Managed tunnel mode
  npx @ankimcp/anki-mcp-server --ngrok                # HTTP mode with ngrok tunnel
  npx @ankimcp/anki-mcp-server --read-only            # Read-only mode

Usage with global installation:
  npm install -g @ankimcp/anki-mcp-server             # Install once
  ankimcp                                             # HTTP mode
  ankimcp --port 8080                                 # Custom port
  ankimcp --stdio                                     # STDIO mode
  ankimcp --tunnel                                    # Managed tunnel mode
  ankimcp --ngrok                                     # HTTP mode with ngrok tunnel
  ankimcp --read-only                                 # Read-only mode

Modo Somente Leitura (todos os modos)

A flag --read-only (ou READ_ONLY=true) bloqueia alterações no conteúdo de notas, baralhos, tags, mídia e tipos de nota, e reagendamento manual de cartões. Quando habilitado:

Todas as operações de leitura funcionam normalmente (navegar por baralhos, visualizar cartões, pesquisar notas)
Estas alterações ainda são permitidas: avaliar um cartão durante a revisão (rate_card), suspender/reativar cartões (suspend, unsuspend), sincronizar com o AnkiWeb (sync) e as ferramentas de GUI que navegam pelas janelas do Anki (guiBrowse, guiDeckOverview, …)
Modificações de conteúdo são bloqueadas (addNote, deleteNotes, createDeck, updateNoteFields, etc.); createDeck para um baralho que já existe ainda é bem-sucedido, pois nada é gravado
Reagendamento manual é bloqueado: forgetCards (redefinir para novo) e setDueDate
guiUndo é bloqueado, pois um desfazer pode reverter uma alteração na coleção
guiAddCards e guiEditNote são bloqueados, pois uma nota adicionada ou salva no diálogo que eles abrem é gravada na coleção
Útil para explorar dados do Anki sem alterações acidentais em seu conteúdo

# HTTP mode with read-only
ankimcp --read-only

# STDIO mode with read-only
ankimcp --stdio --read-only

# Can combine with other flags
ankimcp --ngrok --read-only

Você também pode habilitar o modo somente leitura via variável de ambiente:

READ_ONLY=true ankimcp

Ou na configuração do cliente MCP:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "npx",
      "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio", "--read-only"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Conectar ao Claude Desktop (Modo Local)

Você pode configurar o servidor no Claude Desktop de duas formas:

Indo em: Configurações → Desenvolvedor → Editar Config
Ou editando manualmente o arquivo de configuração

Configuração

Adicione o seguinte à configuração do seu Claude Desktop:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "node",
      "args": ["/path/to/anki-mcp-server/dist/main-stdio.js"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Substitua /path/to/anki-mcp-server pelo caminho real do seu projeto.

Locais dos Arquivos de Configuração

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Para mais detalhes, veja a documentação oficial do MCP.

Variáveis de Ambiente (Opcional)

Variável	Descrição	Padrão
`ANKI_CONNECT_URL`	URL do AnkiConnect	`http://localhost:8765`
`ANKI_CONNECT_API_VERSION`	Versão da API	`6`
`ANKI_CONNECT_API_KEY`	Chave de API se configurada no AnkiConnect	-
`ANKI_CONNECT_TIMEOUT`	Timeout de requisição em ms	`5000`
`READ_ONLY`	Habilitar modo somente leitura (`true` ou `1`)	`false`
`PORT`	Modo HTTP: porta para escutar (a flag `--port` tem precedência)	`3000`
`HOST`	Modo HTTP: endereço para vincular (a flag `--host` tem precedência)	`127.0.0.1`
`ALLOWED_HOSTS`	Modo HTTP: valores extras de cabeçalho `Host` para aceitar além de loopback (hostnames separados por vírgula). Necessário ao vincular a um endereço LAN/público ou rodar atrás de um proxy reverso. Veja Configuração do Modo HTTP.	apenas loopback
`ALLOWED_ORIGINS`	Modo HTTP: lista de permissões separada por vírgulas de padrões de `Origin`/`Referer` do navegador (curingas suportados, ex.: `https://*.ngrok.io`).	`http://localhost:,http://127.0.0.1:,https://localhost:,https://127.0.0.1:`
`TUNNEL_SERVER_URL`	URL do WebSocket do servidor de túnel (apenas modo túnel)	`wss://tunnel.ankimcp.ai`
`MEDIA_ALLOWED_TYPES`	Tipos MIME extras para permitir em importações de caminho de arquivo (separados por vírgulas, ex.: `application/pdf`)	-
`MEDIA_IMPORT_DIR`	Restringir importações de caminho de arquivo a este diretório	-
`MEDIA_ALLOWED_HOSTS`	Permitir hosts específicos de rede privada para importações de URL (separados por vírgulas, ex.: `192.168.1.50,my-nas`)	-

Exemplos de Uso

Pesquisando e Atualizando Notas

# Search for notes in a specific deck
findNotes(query: "deck:Spanish")

# Get detailed information about notes
notesInfo(notes: [1234567890, 1234567891])

# Update a note's fields (HTML content supported)
updateNoteFields(note: {
  id: 1234567890,
  fields: {
    "Front": "<b>¿Cómo estás?</b>",
    "Back": "How are you?"
  }
})

# Delete notes (requires confirmation)
deleteNotes(notes: [1234567890], confirmDeletion: true)

Exemplos de Sintaxe de Consulta do Anki

A ferramenta findNotes suporta a poderosa sintaxe de consulta do Anki:

"deck:DeckName" - Todas as notas em um baralho específico
"tag:important" - Notas com a tag "importante"
"is:due" - Cartões que estão prontos para revisão
"is:new" - Cartões novos que ainda não foram estudados
"added:7" - Notas adicionadas nos últimos 7 dias
"front:hello" - Notas com "olá" no campo da frente
"flag:1" - Notas com bandeira vermelha
"prop:due<=2" - Cartões com vencimento em até 2 dias
"deck:Spanish tag:verb" - Notas do baralho de espanhol com tag de verbo (E)
"deck:Spanish OR deck:French" - Notas de qualquer um dos baralhos

Notas Importantes

Manipulação de CSS e HTML

A ferramenta notesInfo retorna o nome do tipo de nota de cada nota; o CSS em si vem de modelStyling
A ferramenta updateNoteFields suporta conteúdo HTML nos campos e preserva a estilização CSS
Cada modelo de nota tem sua própria estilização CSS - use modelStyling para obter o CSS específico do modelo

Aviso de Atualização

⚠️ IMPORTANTE: Ao usar updateNoteFields, NÃO visualize a nota no navegador do Anki durante a atualização, ou os campos não serão atualizados corretamente. Feche o navegador ou mude para uma nota diferente antes de atualizar. Consulte Problemas Conhecidos para mais detalhes.

Segurança na Exclusão

A ferramenta deleteNotes exige confirmação explícita (confirmDeletion: true) para evitar exclusões acidentais. Excluir uma nota remove TODOS os cartões associados permanentemente.

Segurança

Validação de Caminho de Arquivo de Mídia e URL

As ferramentas de mídia (storeMediaFile, retrieveMediaFile, deleteMediaFile) e os campos de áudio/imagem do updateNoteFields incluem validação de segurança para prevenir uso indevido via injeção de prompt:

Importações de caminho de arquivo são restritas apenas a tipos de arquivos de mídia (imagens, áudio, vídeo). Arquivos que não são de mídia (por exemplo, chaves SSH, credenciais, configurações de shell) são rejeitados com base no tipo MIME. Configure MEDIA_ALLOWED_TYPES para permitir tipos de arquivo adicionais, ou MEDIA_IMPORT_DIR para restringir importações a um diretório específico.
Importações de URL são validadas contra ataques SSRF. Requisições para redes privadas (10.x, 172.16.x, 192.168.x), loopback (127.x), link-local (169.254.x) e esquemas não-HTTP(S) são bloqueadas. Configure MEDIA_ALLOWED_HOSTS para permitir hosts específicos de redes privadas.
Nomes de arquivo são sanitizados para prevenir path traversal (por exemplo, sequências ../../ são removidas).

Essas proteções se aplicam a storeMediaFile, retrieveMediaFile, deleteMediaFile e aos campos de áudio/imagem do updateNoteFields.

Vulnerabilidade de path traversal reportada por Hideaki Takahashi.

Proteção contra DNS-Rebinding (transporte HTTP)

Ao executar em modo HTTP, o servidor valida o cabeçalho Host em cada requisição. Por padrão, apenas hosts de loopback (localhost, 127.0.0.1, ::1) são aceitos, independentemente da porta. Host é um cabeçalho proibido em navegadores, então uma página da web maliciosa não pode forjá-lo — isso fecha o caminho de DNS-rebinding onde uma página redirecionada alcança o servidor local com um Host falsificado e sem Origin, e alcança as ferramentas MCP. Um Host não permitido é rejeitado com 403.

Se você vincular a 0.0.0.0, executar atrás de um proxy reverso, ou expor um domínio de túnel público, defina ALLOWED_HOSTS (nomes de host separados por vírgula) para permitir esses hosts. Ao usar túnel com ngrok, o servidor usa --host-header=rewrite, então o upstream ainda vê um Host de loopback. Consulte Configuração do Modo HTTP para a lista completa de opções.

Vulnerabilidade de DNS-rebinding reportada por avishaigo-commits e yotampe-pluto.

Política de Privacidade

Este servidor MCP roda localmente na sua máquina e não coleta telemetria, análises ou dados de uso.

Política completa: https://ankimcp.ai/privacy/

Coleta de dados: O servidor não coleta nada. Ele faz proxy de requisições entre seu assistente de IA e seu plugin AnkiConnect local.
Uso / armazenamento: Sem armazenamento no servidor. Todos os dados de flashcards permanecem na sua instalação do Anki no seu próprio dispositivo.
Compartilhamento com terceiros: Nenhum. O servidor apenas fala com a URL do AnkiConnect que você configurar (padrão: localhost). Se você habilitar a sincronização AnkiWeb integrada do Anki, isso acontece entre sua instalação do Anki e o AnkiWeb diretamente — fora do escopo deste servidor.
Retenção: Não aplicável — nenhum dado é retido no servidor.
Contato: support@ankimcp.ai

Problemas Conhecidos

Para uma lista abrangente de problemas conhecidos e limitações, visite nossa documentação:

Documentação de Problemas Conhecidos

Limitações Críticas

Atualizações de Notas Falham Quando Visualizadas no Navegador

⚠️ IMPORTANTE: Ao atualizar notas usando updateNoteFields, a atualização falhará silenciosamente se a nota estiver sendo visualizada na janela do navegador do Anki. Esta é uma limitação do AnkiConnect upstream.

Solução alternativa: Sempre feche o navegador ou navegue para uma nota diferente antes de atualizar.

Para mais detalhes e outros problemas conhecidos, consulte a documentação completa.

Solução de Problemas

Erro ERR_REQUIRE_ESM

Se você vir um erro como:

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported

Isso significa que sua versão do Node.js não é suportada. O servidor requer Node.js 22.12.0+.

Nota: O runtime mínimo suportado é Node.js 22.12.0. Node.js 20 (Iron) atingiu o fim da vida útil em 2026-04-30 e não é mais suportado.

Verifique sua versão:

node --version

Solução: Atualize o Node.js para a versão 22.12.0+. Você pode baixá-lo em nodejs.org ou usar um gerenciador de versões como nvm.

Desenvolvimento

Modos de Transporte

Este servidor suporta três modos de transporte MCP via pontos de entrada separados:

Modo STDIO (Padrão)

Para clientes MCP locais como Claude Desktop
Usa entrada/saída padrão para comunicação
Ponto de entrada: dist/main-stdio.js
Executar: npm run start:prod:stdio ou node dist/main-stdio.js
Pacote MCPB: Usa modo STDIO

Modo HTTP (HTTP Streamable)

Para clientes MCP remotos e integrações baseadas na web
Usa o protocolo MCP Streamable HTTP
Ponto de entrada: dist/main-http.js
Executar: npm run start:prod:http ou node dist/main-http.js
Porta padrão: 3000 (configurável via variável de ambiente PORT)
Host padrão: 127.0.0.1 (configurável via variável de ambiente HOST)
Endpoint MCP: http://127.0.0.1:3000/ (caminho raiz)

Modo Túnel (Túnel WebSocket Gerenciado)

Para assistentes de IA baseados na web via serviço de túnel AnkiMCP gerenciado, com autenticação integrada
O servidor MCP roda em processo atrás de um transporte em memória; TunnelTransport possui o servidor MCP e TunnelClient o conecta ao serviço de túnel via WebSocket
Protocolo: serve apenas a revisão MCP de 2025 (STDIO e HTTP também servem 2026-07-28)
Ponto de entrada: dist/main-tunnel.js
Executar: node dist/main-tunnel.js --tunnel (ou ankimcp --tunnel)
Autenticação: ankimcp --login / ankimcp --logout; credenciais armazenadas em ~/.ankimcp/credentials.json (0600)
Dev: npm run start:dev:tunnel (modo de observação, executa --tunnel --debug)

Compilação

npm run build  # Builds once, creates dist/ with all three entry points

main-stdio.js, main-http.js e main-tunnel.js são todos compilados no mesmo diretório dist/. Escolha qual executar com base nas suas necessidades.

Configuração do Modo HTTP

Variáveis de Ambiente:

PORT - Porta do servidor HTTP (padrão: 3000)
HOST - Endereço de vinculação (padrão: 127.0.0.1 para somente localhost)
ALLOWED_HOSTS - Valores extras do cabeçalho Host separados por vírgula para aceitar além do conjunto de loopback integrado (localhost, 127.0.0.1, ::1). Somente nome de host e independente de porta. Padrão: somente loopback.
ALLOWED_ORIGINS - Lista de permissões separada por vírgulas de padrões de Origin/Referer do navegador; curingas suportados (por exemplo, https://*.ngrok.io). Padrão: http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*.
LOG_LEVEL - Nível de registro (padrão: info)

Segurança:

Validação do cabeçalho Host (proteção contra DNS-rebinding) — cada requisição HTTP deve conter um cabeçalho Host que corresponda à lista de permissões. Por padrão, apenas hosts de loopback (localhost, 127.0.0.1, ::1) são aceitos, independentemente da porta. Host é um cabeçalho proibido em navegadores, então uma página da web maliciosa não pode forjá-lo — isso fecha o caminho de DNS-rebinding onde uma página redirecionada alcança o servidor com um Host falsificado e sem Origin. Um Host não permitido é rejeitado com 403.
Validação do cabeçalho Origin — requisições de navegador com um Origin/Referer presente, mas não permitido, são rejeitadas. Requisições sem Origin (curl, Postman, clientes MCP-over-HTTP) são permitidas; a validação de Host é a defesa contra rebinding.
Vincula a localhost (127.0.0.1) por padrão.
Sem autenticação na versão atual (suporte a OAuth planejado).

Expondo o modo HTTP além de localhost — se você vincular a um endereço LAN/público ou colocar o servidor atrás de um proxy reverso ou domínio público, você deve definir ALLOWED_HOSTS para o(s) nome(s) de host que os clientes usarão, caso contrário, toda requisição não-loopback é rejeitada com 403:

# Bind to all interfaces and accept the machine's LAN name + a public domain
ALLOWED_HOSTS=my-nas.local,anki.example.com PORT=8080 HOST=0.0.0.0 node dist/main-http.js

Quando você vincula a 0.0.0.0/:: sem ALLOWED_HOSTS, o servidor registra um aviso de inicialização de que apenas cabeçalhos Host de loopback serão aceitos.

Docker / proxy reverso / domínio público: a mesma regra se aplica. No Docker, as requisições geralmente chegam com o nome de host publicado do contêiner ou o Host do proxy, então defina ALLOWED_HOSTS de acordo. Um proxy reverso (nginx, Caddy, Traefik) deve encaminhar o Host original e ter esse nome de host listado em ALLOWED_HOSTS, ou reescrever o Host upstream para localhost. A integração integrada --ngrok lida com isso automaticamente (veja abaixo).

Exemplo: Modos de Execução

# Development - STDIO mode (watch mode with auto-rebuild)
npm run start:dev:stdio

# Development - HTTP mode (watch mode with auto-rebuild)
npm run start:dev:http

# Production - STDIO mode
npm run start:prod:stdio
# or
node dist/main-stdio.js

# Production - HTTP mode
npm run start:prod:http
# or
PORT=8080 HOST=0.0.0.0 node dist/main-http.js

Compilando um Pacote MCPB

Para criar um pacote MCPB distribuível:

npm run mcpb:bundle

Este comando irá:

Sincronizar a versão de package.json para manifest.json
Remover arquivos .mcpb antigos
Compilar o projeto TypeScript
Empacotar dist/ e node_modules/ em um arquivo .mcpb
Executar mcpb clean para remover devDependencies (otimiza o pacote de ~47MB para ~10MB)

O arquivo de saída será nomeado anki-mcp-server-X.X.X.mcpb e pode ser distribuído para instalação com um clique.

O Que é Empacotado

O pacote MCPB inclui:

JavaScript compilado (diretório dist/ - inclui todos os três pontos de entrada)
Apenas dependências de produção (node_modules/ - devDependencies removidas por mcpb clean)
Metadados do pacote (package.json)
Configuração do manifesto (manifest.json - configurado para usar main-stdio.js)
Ícone (icon.png)

Arquivos de origem, testes e configurações de desenvolvimento são automaticamente excluídos via .mcpbignore.

Registro no Claude Desktop

Ao executar como uma extensão MCPB no Claude Desktop, os registros são gravados em:

Localização do Registro: ~/Library/Logs/Claude/ (macOS)

Os registros são divididos em vários arquivos:

main.log - Registros gerais do aplicativo Claude Desktop
mcp-server-Anki MCP Server.log - Mensagens de protocolo MCP para esta extensão
mcp.log - Registros MCP combinados de todos os servidores

Nota: A saída do logger pino (mensagens INFO, ERROR, WARN do código do servidor) vai para stderr e aparece nos arquivos de registro específicos do MCP. O Claude Desktop determina qual arquivo de registro recebe quais mensagens, mas geralmente:

Inicialização do aplicativo e comunicação do protocolo MCP → registro específico do MCP
Registro interno do servidor (pino) → Ambos o registro específico do MCP e às vezes main.log

Para visualizar os registros em tempo real:

tail -f ~/Library/Logs/Claude/mcp-server-Anki\ MCP\ Server.log

Depurando o Servidor MCP

Você pode depurar o servidor MCP usando o MCP Inspector e anexando um depurador do seu IDE (WebStorm, VS Code, etc.).

Nota para o Modo HTTP: Ao testar o modo HTTP (Streamable HTTP) com o MCP Inspector, use "Connection Type: Via Proxy" para evitar erros de CORS.

Passo 1: Configurar o Servidor de Depuração no MCP Inspector

O mcp-inspector-config.json já inclui uma configuração de servidor de depuração:

{
  "mcpServers": {
    "stdio-server-debug": {
      "type": "stdio",
      "command": "node",
      "args": ["--inspect-brk=9229", "dist/main-stdio.js"],
      "env": {
        "MCP_SERVER_NAME": "anki-mcp-stdio-debug",
        "MCP_SERVER_VERSION": "1.0.0",
        "LOG_LEVEL": "debug"
      },
      "note": "Anki MCP server with debugging enabled on port 9229"
    }
  }
}

Etapa 2: Iniciar o Servidor de Depuração

Execute o MCP Inspector com o servidor de depuração:

npm run inspector:debug

Isso iniciará o servidor com a depuração Node.js habilitada na porta 9229 e pausará a execução na primeira linha.

Etapa 3: Anexar o Depurador da Sua IDE

WebStorm

Vá em Run → Edit Configurations
Adicione uma nova configuração Attach to Node.js/Chrome
Defina a porta para 9229
Clique em Debug para anexar

VS Code

Abra o painel de Depuração (Ctrl+Shift+D / Cmd+Shift+D)
Selecione a configuração Debug MCP Server (Attach)
Pressione F5 para anexar

Etapa 4: Definir Pontos de Interrupção e Depurar

Uma vez anexado, você pode:

Definir pontos de interrupção nos seus arquivos de código-fonte TypeScript
Percorrer a execução do código passo a passo
Inspecionar variáveis e a pilha de chamadas
Usar o console de depuração para avaliar expressões

O depurador funcionará com source maps, permitindo que você depure o código TypeScript original em vez do JavaScript compilado.

Depuração com Claude Desktop

Você também pode depurar o servidor MCP enquanto ele é executado dentro do Claude Desktop, habilitando o depurador Node.js e anexando sua IDE.

Etapa 1: Configurar o Claude Desktop para Depuração

Atualize a configuração do Claude Desktop para habilitar a depuração:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "anki-mcp": {
      "command": "node",
      "args": [
        "--inspect=9229",
        "<path_to_project>/anki-mcp-server/dist/main-stdio.js"
      ],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Mudança principal: Adicione --inspect=9229 antes do caminho para dist/main-stdio.js

Opções de depuração:

--inspect=9229 - Inicia o depurador imediatamente, sem bloquear (recomendado)
--inspect-brk=9229 - Pausa a execução até o depurador anexar (para depurar problemas de inicialização)

Etapa 2: Reiniciar o Claude Desktop

Após salvar a configuração, reinicie o Claude Desktop. O servidor MCP agora será executado com a depuração habilitada na porta 9229.

Etapa 3: Anexar o Depurador da Sua IDE

WebStorm

Vá em Run → Edit Configurations
Clique no botão + e selecione Attach to Node.js/Chrome
Configure:
- Name: Attach to Anki MCP (Claude Desktop)
- Host: localhost
- Port: 9229
- Attach to: Node.js < 8 ou Chrome or Node.js > 6.3 (dependendo da versão do WebStorm)
Clique em OK
Clique em Debug (Shift+F9) para anexar

VS Code

Adicione a .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Anki MCP (Claude Desktop)",
      "port": 9229,
      "skipFiles": ["<node_internals>/**"],
      "sourceMaps": true,
      "outFiles": ["${workspaceFolder}/dist/**/*.js"]
    }
  ]
}

Abra o painel de Depuração (Ctrl+Shift+D / Cmd+Shift+D)
Selecione Attach to Anki MCP (Claude Desktop)
Pressione F5 para anexar

Etapa 4: Depurar em Tempo Real

Uma vez anexado, você pode:

Definir pontos de interrupção nos seus arquivos de código-fonte TypeScript (por exemplo, src/mcp/primitives/essential/tools/create-model.tool.ts)
Usar o Claude Desktop normalmente - os pontos de interrupção serão acionados quando as ferramentas forem invocadas
Percorrer a execução do código passo a passo
Inspecionar variáveis e a pilha de chamadas
Usar o console de depuração

Exemplo: Defina um ponto de interrupção em create-model.tool.ts na linha 119 e peça ao Claude para criar um novo modelo. O depurador pausará no seu ponto de interrupção!

Nota: O depurador permanece anexado enquanto o Claude Desktop estiver em execução. Você pode desanexar/reanexar a qualquer momento sem reiniciar o Claude Desktop.

Comandos de Build

npm run build              # Build the project (compile TypeScript to JavaScript)
npm run start:dev:stdio    # STDIO mode with watch (auto-rebuild)
npm run start:dev:http     # HTTP mode with watch (auto-rebuild)
npm run type-check         # Run TypeScript type checking
npm run lint               # Run ESLint
npm run mcpb:bundle        # Sync version, clean, build, and create MCPB bundle

Teste do Pacote NPM (Local)

Teste o pacote npm localmente antes de publicar:

# 1. Create local package
npm run pack:local         # Builds and creates @ankimcp/anki-mcp-server-*.tgz

# 2. Install globally from local package
npm run install:local      # Installs from ./@ankimcp/anki-mcp-server-*.tgz

# 3. Test the command
ankimcp                    # Runs HTTP server on port 3000

# 4. Uninstall when done testing
npm run uninstall:local    # Removes global installation

Como funciona:

npm pack cria um arquivo .tgz idêntico ao que o npm publish criaria
Instalar a partir de .tgz simula o que os usuários obtêm de npm install -g ankimcp
Isso permite testar a experiência completa do usuário antes de publicar no npm

Comandos de Teste

npm test              # Run all tests
npm run test:unit     # Run unit tests only
npm run test:tools    # Run tool-specific tests
npm run test:workflows # Run workflow integration tests
npm run test:e2e      # Run end-to-end tests
npm run test:cov      # Run tests with coverage report
npm run test:watch    # Run tests in watch mode
npm run test:debug    # Run tests with debugger
npm run test:ci       # Run tests for CI (silent, with coverage)

Cobertura de Testes

O projeto mantém limites mínimos de cobertura de 70% para:

Branches
Funções
Linhas
Declarações

Os relatórios de cobertura são gerados no diretório coverage/.

Versionamento

Este projeto segue Versionamento Semântico com uma abordagem de desenvolvimento pré-1.0:

0.x.x - Versões Beta/Desenvolvimento (fase atual)
- 0.1.x - Correções de bugs e patches
- 0.2.0+ - Novos recursos ou melhorias menores
- Mudanças que quebram compatibilidade são aceitáveis nas versões 0.x
1.0.0 - Primeira versão estável
- Será lançada quando a API estiver estável e testada
- Mudanças que quebram compatibilidade exigirão aumentos de versão principal (2.0.0, etc.)

Status Atual: 0.27.0 - Desenvolvimento beta ativo. Recursos recentes incluem análise de revisão em todo o acervo (review_stats agora agrega todos os baralhos quando deck é omitido), gerenciamento de campos de modelo (addModelField, removeModelField, renameModelField, repositionModelField), criação de notas em lote (addNotes), tunelamento ngrok integrado (flag --ngrok), gerenciamento de arquivos de mídia, gerenciamento de modelos/modelos e estatísticas abrangentes de baralhos. As APIs podem mudar com base em feedback e testes.

Evolução da especificação MCPB

Este projeto tem como alvo a especificação de pacote MCPB da Anthropic, que ainda está em evolução. Acompanhamos a especificação em https://github.com/modelcontextprotocol/mcpb e podemos introduzir mudanças que quebram compatibilidade para permanecer em conformidade. Mudanças que quebram compatibilidade são permitidas sob o esquema de versionamento 0.x.x.

Projetos Semelhantes

Se você está explorando integrações Anki MCP, aqui estão outros projetos neste espaço:

scorzeth/anki-mcp-server

Status: Parece estar abandonado (sem atualizações recentes)
Implementação inicial da integração Anki MCP

nailuoGG/anki-mcp-server

Abordagem: Implementação leve e de arquivo único
Arquitetura: Estrutura de código procedural com todas as ferramentas em um arquivo
Bom para: Casos de uso simples, dependências mínimas

Por que este projeto é diferente:

Arquitetura de nível empresarial: Construído em NestJS com injeção de dependência
Design modular: Cada ferramenta é uma classe separada com clara separação de responsabilidades
Facilidade de manutenção: Fácil de estender com novos recursos sem tocar no código existente
Testes: Suíte de testes abrangente com requisito de cobertura de 70%
Segurança de tipos: TypeScript estrito com validação Zod
Tratamento de erros: Tratamento robusto de erros com feedback útil ao usuário
Pronto para produção: Registro adequado, relatórios de progresso e suporte a pacotes MCPB
Escalabilidade: Pode facilmente crescer de ferramentas básicas para fluxos de trabalho complexos

Caso de uso: Se você precisa de uma base sólida para construir integrações avançadas do Anki ou planeja estender a funcionalidade significativamente, a abordagem arquitetônica deste projeto facilita a manutenção e a escala ao longo do tempo.

Links Úteis

Licença e Atribuições

Este projeto é licenciado sob a Licença MIT — veja LICENSE para o texto completo.

Atribuições de Terceiros

Anki® é uma marca registrada da Ankitects Pty Ltd. Este projeto é uma ferramenta não oficial de terceiros e não é afiliado, endossado ou patrocinado pela Ankitects Pty Ltd. O logotipo do Anki é usado sob a licença alternativa para referenciar o Anki com um link para https://apps.ankiweb.net. Para o aplicativo oficial do Anki, visite https://apps.ankiweb.net.
Model Context Protocol (MCP) é um padrão aberto da Anthropic. O logotipo do MCP é do repositório oficial de documentação do MCP e é usado sob a Licença MIT. Para mais informações sobre o MCP, visite https://modelcontextprotocol.io.
Este é um projeto independente que conecta as tecnologias Anki e MCP. Todas as marcas registradas, marcas de serviço, nomes comerciais, nomes de produtos e logotipos são propriedade de seus respectivos proprietários.