Anki AI Server

Este é um repositório completo que fornece um servidor MCP (Model Context Protocol) para integrar o seu Anki Desktop com Inteligências Artificiais modernas. Ele oferece duas formas de uso:

1. Cliente Local (via TypeScript/Stdio): Ideal para editores locais como Cursor, Windsurf, Claude Desktop, etc.
2. Cliente Web (via Python/SSE + ngrok): Ideal para conectar diretamente ao site do ChatGPT (Web) no formato Sandbox (seguro).

Com este servidor, a IA ganha "superpoderes" para ler, criar, buscar, editar e analisar seu banco de estudos diretamente pelo chat, inclusive extraindo textos e mídias de documentos PDF.

---

🔌 1. Pré-requisitos Gerais (Para Ambos os Métodos)

Para que qualquer uma das integrações funcione, o seu computador precisa estar configurado:

A. Instalar o Anki Desktop 💻

O servidor MCP precisa se comunicar com o aplicativo instalado no seu computador.

• Baixe e instale o Anki Desktop.
• (Opcional) Crie uma conta no AnkiWeb para sincronizar seus cartões.

B. Instalar o add-on AnkiConnect 🔌

O Anki precisa de uma extensão para conseguir conversar com o nosso servidor MCP.

1. Abra o seu Anki Desktop.
2. Vá no menu superior em Ferramentas -> Complementos (Add-ons).
3. Clique em Adquirir Complementos... (Get Add-ons).
4. Insira o código do AnkiConnect: 2055492159 e clique em OK.
5. Reinicie o Anki para ativar a extensão.

[!IMPORTANT] O Anki Desktop deve estar sempre aberto e rodando em segundo plano no seu computador para que a Inteligência Artificial consiga se comunicar com os seus cartões!

---

🛠️ Método A: Servidor Local TypeScript (Cursor, Claude Desktop, etc.)

Este método executa o servidor localmente através do terminal (stdio). Ele tem acesso completo de leitura/escrita e suporte ao processamento de PDFs locais.

Requisitos:

• Node.js instalado (versão 18+).
• Dependências do script Python de PDF: pip install pymupdf pillow.

Configuração:

1. Abra a pasta do projeto no terminal e rode:

   npm install
   npx tsc
   

2. Adicione o servidor nas configurações MCP do seu editor/cliente. Exemplo de configuração para o claude_desktop_config.json:

   {
     "mcpServers": {
       "anki-server": {
         "command": "node",
         "args": [
           "C:/caminho/do/projeto/build/index.js"
         ]
       }
     }
   }
   

---

🌐 Método B: Ponte Sandbox Python (ChatGPT Web)

Este método expõe um servidor HTTP/SSE local na porta 8000 e utiliza o ngrok para criar um túnel seguro. Ele foi desenvolvido em modo Sandbox (sem acesso aos seus arquivos locais), permitindo que você conecte o ChatGPT (Web) com segurança.

Requisitos:

• Python 3.10+ instalado.
• Conta e CLI do ngrok configurada.

Como Rodar e Conectar:

1. Inicie o servidor MCP rodando o arquivo run.bat ou executando no terminal:

   pip install -r requirements.txt
   python server.py
   

2. Abra um terminal e inicie o túnel do ngrok:

   ngrok http 8000
   

   (Dica: Registre 1 domínio estático gratuito no site do ngrok e rode ngrok http --url=seu-dominio.ngrok-free.dev 8000 para manter a URL permanente).
3. Acesse o ChatGPT Web, vá em Settings -> Apps, ative o Developer Mode e clique em Add Custom Connector.
4. Configure a URL gerada pelo ngrok com /sse no final:
   • URL: https://seu-dominio.ngrok-free.dev/sse

---

🧰 Lista de Superpoderes Disponíveis (MCP Tools)

• list_decks / anki_get_deck_names: Lista todos os seus baralhos locais.
• create_deck / anki_create_deck: Cria um novo baralho no Anki.
• list_models: Lista os modelos de nota disponíveis no Anki (ex: Básico, Basic).
• list_model_fields: Lista os campos específicos de um modelo de nota (ex: ['Frente', 'Verso']).
• add_card / anki_add_note: Cria e adiciona um card (Frente e Verso) no baralho escolhido. Mapeia automaticamente as perguntas/respostas para os campos do modelo (ex: Frente/Verso ou Front/Back).
• add_multiple_cards: Adiciona múltiplos cards ao mesmo tempo de forma otimizada.
• search_cards / anki_find_notes: Busca e lista cards existentes com base em termos de busca (ex: "deck:Biologia DNA").
• edit_card / anki_update_note_fields: Atualiza a pergunta ou resposta de um card existente usando seu ID.
• delete_card / anki_delete_decks: Remove cards ou baralhos.
• sync_anki: Força a sincronização dos seus cartões locais com o AnkiWeb.
• store_media_file / anki_store_media_file: Salva imagens ou mídias diretamente no Anki (útil para cards com imagens criadas pelo ChatGPT).
• add_card_with_media: Cria o card e faz o upload da imagem de forma atômica em um único comando. Resolve automaticamente o mapeamento de campos (Frente/Verso ou Front/Back).
• get_capabilities: Retorna a lista completa de ferramentas e instruções recomendadas para o assistente de IA.
• anki_parse_pdf: (Apenas no Método A) Lê PDFs locais, extrai textos/mídias e anexa automaticamente as imagens extraídas na pasta de mídia do seu Anki.

---

💡 Exemplos de Prompts

• "Crie 5 cards de inglês no meu baralho de Vocabulário sobre palavras corporativas avançadas."
• "Procure no meu Anki por cards que mencionam 'Mitocôndria' e me traga os textos deles."
• "Altere a resposta do card de ID 1685890000000 para '42'."
• "Sincronize o meu Anki."

---

📄 Licença

Licença ISC. Desenvolvido para uso pessoal e integrações seguras.