Anki MCP

resmi

Bir MCP sunucusu, yapay zeka asistanlarının aralıklı tekrar flashcard uygulaması Anki ile etkileşime girmesini sağlar.

GitHub
481
Bu MCP'yi deneyinSponsorlu

Anki MCP ile neler yapabilirsiniz?

  • Gecikmiş kartları konuşma yoluyla gözden geçir — Asistanınızdan get_due_cards ile gecikmiş kartları getirmesini isteyin, her birini present_card ile sunun ve rate_card ile puanınızı kaydedin.
  • Kart oluştur ve toplu ekle — Asistanın addNotes ile toplu not oluşturmasını sağlayın, isteğe bağlı olarak önce createModel ve updateModelStyling ile özel bir model oluşturun.
  • Mevcut notları ara ve düzenle — Anki sorgu sözdizimiyle findNotes kullanın, notesInfo ile ayrıntıları inceleyin ve updateNoteFields ile alanları güncelleyin.
  • Desteleri ve zamanlamayı yönet — createDeck ile desteler oluşturun, changeDeck ile kartları taşıyın veya setDueDate ve forgetCards kullanarak kartları yeniden zamanlayın.
  • Notlara medya içe aktar — Asistanınızdan storeMediaFile ile yerel bir görsel veya URL yüklemesini isteyin ve bunu bir notun alanına gömün.
  • Anki arayüzünü yönlendir — guiBrowse ve guiEditNote ile tarayıcıyı veya düzenleyiciyi açın veya guiSelectedNotes ile seçili notu alın.

Dokümantasyon

Anki MCP Sunucusu

Tests npm version

Anki + MCP Integration

Anki'yi Model Context Protocol aracılığıyla yapay zeka asistanlarıyla sorunsuz bir şekilde entegre edin

Beta - Bu proje aktif geliştirme aşamasındadır. API'ler ve özellikler değişebilir.

Yapay zeka asistanlarının, aralıklı tekrar flashcard uygulaması olan Anki ile etkileşime girmesini sağlayan bir Model Context Protocol (MCP) sunucusu.

Anki deneyiminizi doğal dil etkileşimiyle dönüştürün - özel bir öğretmeniniz varmış gibi. Yapay zeka asistanı yalnızca soruları ve cevapları sunmakla kalmaz; kavramları açıklayabilir, öğrenme sürecini daha ilgi çekici ve insani hale getirebilir, bağlam sağlayabilir ve öğrenme stilinize uyum sağlayabilir. Anında notlar oluşturabilir ve düzenleyebilir, çalışma oturumlarınızı dinamik sohbetlere dönüştürebilir. Yakında daha fazla özellik gelecek!

Örnekler ve Eğiticiler

Bu MCP sunucusunu Claude Desktop ile kullanmaya yönelik kapsamlı rehberler, gerçek dünya örnekleri ve adım adım eğiticiler için şu adresi ziyaret edin:

ankimcp.ai - Pratik örnekler ve kullanım senaryolarıyla eksiksiz dokümantasyon

Ek dokümantasyon için docs/ bölümüne bakın; gözden geçirici kurulum rehberi ve örnek Anki destesini içerir.

Örnek Kullanım Senaryoları

Bu sunucunun sağladığı araç akışlarını gösteren üç temsili komut:

  1. "İspanyolca destemi gözden geçirmeme yardım et." — Asistan AnkiWeb ile senkronize olur (sync), vadesi gelen kartları getirir (get_due_cards deste filtresiyle), her kartı sunar (present_card) ve puanlamanızı kaydeder (rate_card). Size özel açıklamalarla doğal çalışma sohbeti.

  2. "RTL stilinde 10 Arapça kelime kartı oluştur." — Asistan not türlerini listeler (modelNames), gerekirse özel bir RTL modeli oluşturur (createModel + updateModelStyling sağdan sola CSS için), ardından kartları toplu olarak oluşturur (addNotes).

  3. "İndirilenler klasörümdeki bu görseli seçili notun ön yüzüne aktar." — Asistan yerel dosyayı yükler (storeMediaFile dosya yoluyla), tarayıcıdan seçili notu okur (guiSelectedNotes + notesInfo) ve ön alanı bir <img> etiketiyle günceller (updateNoteFields).

Kullanılabilir Araçlar

Sunucu 50 MCP aracı sunar — günlük Anki işlemleri için 39 temel araç ve not düzenleme/oluşturma iş akışları için Anki masaüstü arayüzünü yönlendiren 11 GUI aracı.

Temel Araçlar

Gözden Geçirme ve Çalışma

  • sync - En son verileri çekmek ve değişiklikleri göndermek için AnkiWeb ile senkronize edin
  • get_due_cards - Gözden geçirme için vadesi gelen kartları alın, isteğe bağlı olarak desteye göre filtrelenir (cevaplar include_answer: true olmadığı sürece atlanır, varsayılan false)
  • get_cards - Duruma (vadesi gelmiş, yeni, öğreniliyor, askıya alınmış, gizlenmiş) ve desteye göre esnek filtrelemeyle kartları alın (cevaplar include_answer: true olmadığı sürece atlanır, varsayılan false)
  • present_card - Soru/ön yüzüyle birlikte gözden geçirme için bir kart gösterin
  • rate_card - Kart performansını puanlayın (Tekrar, Zor, İyi, Kolay) ve bir sonraki gözden geçirmeyi planlayın
  • forgetCards - Kartları yeni durumuna sıfırlayın, planlamalarını bir gözden geçirme kaydetmeden atın
  • setDueDate - Kartları N gün içinde vadesi gelecek şekilde yeniden planlayın ("0", "3-7", "1!"), bir gözden geçirme kaydetmeden

Not: forgetCards ve setDueDate planlamayı gözden geçirme kaydetmeden değiştirir; bu onları rate_card'den ayıran şeydir. Bir kartın planlaması yanlış olduğunda cevap yerine bunlara başvurun: bir kartı daha derine gömmek için Again olarak puanlamak gerçek bir unutma kaydeder ve kolaylık faktörünü düşürür, hem gelecekteki planlamayı hem de istatistiklerinizi kalıcı olarak bozar. forgetCards aralığı siler ve karta yeniden başlar; setDueDate kartın geçmişini korur ve yalnızca bir sonraki gözden geçirmeyi taşır.

Not: Kart front/back içeriği, her kart için kendi şablonundan (Anki'nin gösterdiği gibi) işlenir, böylece ters ve boşluk doldurma kartları doğru yönü gösterir. Kart şablonlarınız tarafından eklenen statik metin de çıktıda görünür.

Deste Yönetimi

  • listDecks - Tüm desteleri listeleyin, isteğe bağlı olarak deste başına çalışma kuyruğu istatistikleriyle
  • deckStats - Tek bir deste için kapsamlı istatistikler alın (çalışma kuyruğu, gerçek kart durumu sayıları, kolaylık/aralık dağılımları)
  • createDeck - Yeni bir boş deste oluşturun (Parent::Child destekler, en fazla 2 seviye)
  • changeDeck - Kartları farklı bir desteye taşıyın (yoksa oluşturulur)

Not: Deste istatistikleri iki türde gelir. counts bloğu (ve listDecks'nin raporladığı her şey) Anki'nin deste tarayıcısını yansıtır: bugün vadesi gelen kartlar, her destenin günlük yeni/tekrar limitleriyle sınırlandırılmış, askıya alınmış ve gizlenmiş kartlar hariç — bu nedenle review "olgun kartlar" değildir ve other kovası yalnızca aritmetik kalandır (çoğunlukla bugün vadesi gelmeyen tekrar kartları artı günlük limitin üzerindeki yeni kartlar). Durum başına gerçek toplamlar için deckStats / collection_stats üzerindeki states bloğunu kullanın; bu blok Anki aramalarıyla new, learning, review, suspended ve buried sayar, vade tarihlerini ve günlük limitleri yok sayar.

Not Yönetimi

  • addNote - Belirtilen alanlar ve etiketlerle tek bir not oluşturun
  • addNotes - Aynı deste ve modeli paylaşan en fazla 100 notu toplu oluşturun (kısmi başarı desteklenir)
  • findNotes - Anki sorgu sözdizimini kullanarak notları arayın (deck:, tag:, is:due, vb.)
  • notesInfo - Notlar hakkında ayrıntılı bilgi alın (alanlar, etiketler, CSS stillendirme)
  • updateNoteFields - Mevcut not alanlarını güncelleyin (CSS duyarlı, HTML içeriği destekler)
  • deleteNotes - Notları ve ilişkili tüm kartları silin (kalıcı, onay gerektirir)

Etiket Yönetimi

  • getTags - Koleksiyondaki tüm etiketleri alın (çoğaltmayı önlemek için ilkini kullanın)
  • addTags - Belirtilen notlara boşlukla ayrılmış etiketler ekleyin
  • removeTags - Belirtilen notlardan boşlukla ayrılmış etiketleri kaldırın
  • replaceTags - Belirtilen notlarda bir etiketi yeniden adlandırın
  • clearUnusedTags - Hiçbir not tarafından kullanılmayan sahipsiz etiketleri kaldırın (kalıcı)

Medya Yönetimi

  • getMediaFilesNames - collection.media içindeki medya dosyalarını listeleyin, isteğe bağlı olarak desene göre filtrelenir
  • retrieveMediaFile - Bir medya dosyasını base64 içerik olarak indirin
  • storeMediaFile - Base64 verilerinden, mutlak bir dosya yolundan veya bir URL'den medya yükleyin
  • deleteMediaFile - collection.media içinden bir medya dosyasını kaldırın (kalıcı)

💡 Görseller için En İyi Uygulama:

  • ✅ Dosya yollarını kullanın (örn. /Users/you/image.png) - Hızlı ve verimli
  • ✅ URL'leri kullanın (örn. https://example.com/image.jpg) - Doğrudan indirme
  • ❌ Base64'ten kaçının - Son derece yavaş ve token açısından verimsiz

Claude'a görselin nerede olduğunu söylemeniz yeterli; en verimli yöntemi kullanarak yüklemeyi otomatik olarak halleder.

Model/Şablon Yönetimi

  • modelNames - Tüm kullanılabilir not türlerini/modelleri listeleyin
  • modelFieldNames - Belirli bir not türü için alan adlarını alın
  • modelStyling - Bir not türü için CSS stillendirme bilgilerini alın
  • modelTemplates - Bir not türü için kart şablonlarını (Ön ve Arka HTML) alın
  • createModel - Özel alanlar, kart şablonları ve CSS ile yeni bir not türü oluşturun (örn. RTL modelleri)
  • updateModelStyling - Mevcut bir not türünün CSS stillendirmesini güncelleyin (tüm kartlarına uygulanır)
  • updateModelTemplates - Mevcut bir not türünün kart şablonlarını (Ön ve Arka HTML) güncelleyin (tüm kartlarına uygulanır)
  • addModelField - Mevcut bir not türüne yeni bir alan ekleyin (sona eklenir veya belirli bir konuma eklenir)
  • removeModelField - Mevcut bir not türünden bir alanı kaldırın (içeriğini tüm notlardan siler; açık onay gerektirir)
  • renameModelField - Mevcut bir not türünde bir alanı yeniden adlandırın (eski adı referans alan kart şablonları ayrıca güncellenmelidir)
  • repositionModelField - Mevcut bir not türünde bir alanın konumunu değiştirin

İstatistikler

  • collection_stats - Deste başına döküm ve koleksiyon genelinde kart durumu sayılarıyla tüm destelerde toplanmış istatistikler
  • review_stats - Gözden geçirme geçmişi analizi (zamansal desenler, kalıcılık metrikleri, çalışma serileri)

GUI Araçları

Anki masaüstü arayüzünü yönlendiren araçlar. Not düzenleme/oluşturma ve deste yönetimi iş akışları için tasarlanmıştır, gözden geçirme oturumları için değil.

  • guiBrowse - Kart Tarayıcısını açın ve kartları arayın
  • guiSelectCard - Kart Tarayıcısında belirli bir kartı seçin
  • guiSelectedNotes - Kart Tarayıcısında seçili notların kimliklerini alın
  • guiAddCards - Önceden ayarlanmış not ayrıntılarıyla Kart Ekle iletişim kutusunu açın
  • guiEditNote - Belirli bir not için not düzenleyiciyi açın
  • guiDeckOverview - Belirli bir deste için Deste Genel Bakış iletişim kutusunu açın
  • guiDeckBrowser - Deste Tarayıcısı iletişim kutusunu açın
  • guiCurrentCard - Gözden geçirme modunda geçerli kart hakkında bilgi alın
  • guiShowQuestion - Geçerli kartın soru tarafını gösterin
  • guiShowAnswer - Geçerli kartın cevap tarafını gösterin
  • guiUndo - Anki'deki son eylemi geri alın

Ön Koşullar

Kurulum

Sunucuyu makinenize getirmenin birkaç yolu vardır. Kurulduktan sonra, yerel veya uzaktan yapay zeka asistanınıza bağlamak için Bir Yapay Zeka İstemcisini Bağlama bölümüne gidin.

npm (global veya npx)

Sunucuyu kurmanın genel amaçlı yolu, doğrudan başlatan herhangi bir MCP istemcisi için uygundur.

ankimcp komutunu çalıştıran istemciler için global olarak kurun:

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

Veya kurulum gerektirmeden isteğe bağlı olarak çalıştırın:

npx @ankimcp/anki-mcp-server

MCPB Paketi (Claude Desktop için Önerilir)

Bu MCP sunucusunu Claude Desktop için kurmanın en kolay yolu:

  1. Sürümler sayfasından en son .mcpb paketini indirin
  2. Claude Desktop'ta uzantıyı kurun:
    • Yöntem 1: Ayarlar → Uzantılar'a gidin, ardından .mcpb dosyasını sürükleyip bırakın
    • Yöntem 2: Ayarlar → Geliştirici → Uzantılar → Uzantı Kur'a gidin, ardından .mcpb dosyasını seçin
  3. Gerekirse AnkiConnect URL'sini yapılandırın (varsayılan http://localhost:8765)
  4. Claude Desktop'u yeniden başlatın

Bu kadar! Paket, sunucuyu yerel olarak çalıştırmak için gereken her şeyi içerir.

Anthropic MCP Dizin inceleyicileri için: önceden doldurulmuş örnek bir desteyle sıfırdan entegrasyona kadar bir yol haritası docs/reviewer-setup.md içinde yer alır.

Kaynaktan Kurulum (geliştirme için)

Geliştirme veya ileri düzey kullanım için (test paketini çalıştırmak Node.js 24.9+ gerektirir — npm test komut dosyaları, yalnızca ESM destekli NestJS 12 paketlerini require(esm) aracılığıyla yükler; Jest bunu yalnızca orada destekler; sunucuyu kullanmak için çalışma zamanı gereksinimi 22.12.0+ olarak kalır):

npm install
npm run build

Bir Yapay Zeka İstemcisini Bağlama

Bir yapay zeka asistanının bu sunucuya ulaşmasının iki yolu vardır; asistanın nerede çalıştığına bağlı olarak:

  • Yerel — sunucu, yapay zeka istemcisiyle (Claude Desktop, Cursor, Cline, Zed veya yerel bir tarayıcı oturumu) aynı makinede çalışır. Masaüstü MCP istemcileri için STDIO, yerel web tabanlı araçlar için HTTP kullanın.
  • Uzaktan — barındırılan/uzak bir yapay zeka (örn. bulutta ChatGPT veya Claude.ai), yerel makinenizde çalışan Anki'ye ulaşmalıdır. Yönetilen Tünel'i (✅ önerilir — kimlik doğrulamalı) veya daha hafif, kimlik doğrulamasız bir alternatif olarak ngrok'u kullanın.

Yerel

Sunucu, yapay zeka istemcinizle aynı bilgisayarda çalışır ve localhost üzerindeki AnkiConnect ile konuşur.

STDIO (birincil yerel entegrasyon)

STDIO, yerel masaüstü MCP istemcileri için standart taşıma katmanıdır — Claude Desktop, Cursor IDE, Cline, Zed Editor ve diğerleri. İstemci, sunucuyu bir alt süreç olarak başlatır ve standart giriş/çıkış üzerinden iletişim kurar. Desteklenen İstemciler:

  • Claude Desktop
  • Cursor IDE - Yapay zeka destekli kod editörü
  • Cline - Yapay zeka yardımı için VS Code uzantısı
  • Zed Editor - Hızlı, modern kod editörü
  • STDIO taşımasını destekleyen diğer MCP istemcileri

Claude Desktop için MCPB paketi en kolay yoldur. Diğer istemciler için npm paketini --stdio bayrağıyla yapılandırın.

Yapılandırma - Bir yöntem seçin:

Yöntem 1: npx kullanma (önerilir - kurulum gerekmez)

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

Yöntem 2: Global kurulum kullanma

Önce global olarak kurun:

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

Ardından yapılandırın:

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

Yapılandırma dosyası konumları:

  • Cursor IDE: ~/.cursor/mcp.json (macOS/Linux) veya %USERPROFILE%\.cursor\mcp.json (Windows)
  • Cline: VS Code içindeki ayarlar arayüzü üzerinden erişilebilir
  • Zed Editor: Uzantı mağazası üzerinden MCP uzantısı olarak kurun

İstemciye özel özellikler ve sorun giderme için MCP istemcinizin belgelerine bakın. Doğrudan derlenmiş bir dist/main-stdio.js sürümüne işaret eden bir yapılandırma için ayrıca Claude Desktop'a Bağlanma bölümüne bakın.

HTTP (yerel web tabanlı yapay zeka)

HTTP modu, sunucuyu MCP Streamable HTTP protokolünü konuşan yerel bir web sunucusu olarak çalıştırır. Web tabanlı bir yapay zeka aracının makinenize işaret edildiğinde konuştuğu taşıma biçimidir ve aynı zamanda Remote seçeneklerinin dış dünyaya açtığı şeydir. Tek başına HTTP modu yalnızca localhost adresine bağlanır.

Localhost dışına bağlanmak mı? --host 0.0.0.0 (veya ters proxy/genel alan adı arkasında) kullanıyorsanız, sunucu varsayılan olarak DNS-rebinding koruması için yalnızca loopback Host başlıklarını kabul eder — istemcilerin kullandığı ana bilgisayar adlarını ALLOWED_HOSTS olarak ayarlayın. HTTP Modu Yapılandırması bölümüne bakın.

Kurulum - Bir yöntem seçin:

Yöntem 1: npx kullanma (önerilir - kurulum gerekmez)

# 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

Yöntem 2: Global kurulum kullanma

# 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

Yöntem 3: Kaynaktan kurulum (geliştirme için)

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

Yerel bir HTTP sunucusunu bulut tabanlı bir yapay zekaya erişilebilir kılmak için aşağıdaki Remote seçeneklerinden birini kullanın.

Remote

Barındırılan/uzak bir yapay zeka (bulutta çalışan ChatGPT veya Claude.ai gibi) localhost adresine doğrudan erişemez. Bu seçenekler yerel Anki'nizi internete açarak uzak bir asistanın onunla konuşmasını sağlar.

Tunnel (✅ Önerilen)

Önerilen uzak yol — kimliği doğrulanmış ve güvenli. Ham bir genel bağlantı noktasının aksine, tünel modu oturum açmanızı gerektirir (OAuth 2.0 cihaz akışı), böylece uç nokta URL'yi tahmin eden herkese açık değildir.

Tünel modu, web tabanlı yapay zeka asistanlarının kendi tünelinizi çalıştırmadan yerel Anki'nize erişmesini sağlar. Sunucu, yönetilen AnkiMCP tünel hizmetine (wss://tunnel.ankimcp.ai) bir WebSocket üzerinden bağlanır ve kendisine genel bir URL atanır. Kimlik doğrulama yerleşiktir — ngrok hesabı veya ayrı bir tünel işlemi gerekmez ve bir kez oturum açarsınız.

Oturum açma (OAuth cihaz akışı):

Tünel modu, OAuth 2.0 Cihaz Yetkilendirme Hibe akışını kullanır. Oturum açma, kodun URL'ye zaten gömülü olduğu bir onay sayfasına tarayıcınızı otomatik olarak açar — yazacak bir şey yok, sadece onaylayın. (Tarayıcı açılamazsa, terminal yedek olarak manuel olarak girilecek bir doğrulama URL'si ve kod yazdırır.) Başarılı olursa, kimlik bilgileri ~/.ankimcp/credentials.json dosyasına kaydedilir (dosya izinleri 0600).

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

# Clear saved credentials
ankimcp --logout

Tüneli başlatın:

# 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

Kimlik bilgileri yoksa, --tunnel otomatik olarak önce oturum açma akışını başlatır, ardından tünele devam eder. Bu otomatik oturum açma etkileşimli bir terminal gerektirir — stdout bir TTY olmadığında (systemd, başsız Docker, CI), sunucu hızla başarısız olur ve sizden önce ankimcp --login çalıştırmanızı ister. Bağlandıktan sonra genel tünel URL'si yazdırılır; bağlantıyı kesmek için Ctrl+C'ye basın. Bu URL'yi yapay zeka asistanınızla paylaşın.

Tünel modu ortam değişkenleri:

DeğişkenAçıklamaVarsayılan
TUNNEL_SERVER_URLTünel sunucusu WebSocket URL'si (--tunnel/--login bayrak değeri bunu geçersiz kılar)wss://tunnel.ankimcp.ai
TUNNEL_AUTH_CLIENT_IDCihaz akışı için OAuth istemci kimliği. Gelişmiş — yalnızca kendi kendine barındırılan bir tünel/auth hizmetini işaret ederken gerekir.(yerleşik)

Cihaz akışı kimlik doğrulama uç noktaları (/auth/device, /auth/token) TUNNEL_SERVER_URL adresinden türetilir; bu nedenle --tunnel (veya TUNNEL_SERVER_URL) adresini farklı bir ana bilgisayara işaret etmek, kimlik doğrulamayı da o ana bilgisayara taşır.

Nasıl çalışır: Tünel modu, MCP sunucusunu bellek içi bir taşıma (TunnelTransport) arkasında süreç içinde çalıştırır. Bu taşıma MCP sunucusuna sahiptir ve her aktarılan istek gövdesini bir yanıta dönüştürür ve TunnelClient onu uzak tünel hizmetine bir WebSocket üzerinden köprüleyerek MCP isteklerini içeri ve yanıtları dışarı aktarır. AnkiConnect'e yalnızca yerel makinenizde erişilir.

Protokol revizyonları: Tünel, MCP sunucusunu süreç içinde bağladığından, tünel modu yalnızca MCP protokolünün 2025 revizyonuna hizmet ederken, STDIO ve HTTP modları hem 2025 hem de daha yeni 2026-07-28 revizyonuna hizmet eder. Her araç her iki şekilde de aynı şekilde davranır — ancak yalnızca 2026-07-28 konuşan bir istemci, tünel üzerinden bir protokol sürümü hatasıyla geri çevrilir; bu istemci için STDIO veya HTTP modunu çalıştırın.

ngrok (kimliği doğrulanmamış alternatif)

Yönetilen tünelde hesap olmadan yerel HTTP modunu herkese açık hale getirmeyi tercih ederseniz, yerleşik --ngrok bayrağı bir ngrok alt sürecini (src/services/ngrok.service.ts) başlatır ve genel URL'yi başlangıç başlığında yazdırır:

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

Bu yol kimliği doğrulanmamıştır — URL'ye sahip olan herkes Anki'nize erişebilir, bu nedenle Tunnel bölümünden daha az güvenlidir. Kendi ngrok uç noktanızı yönetmek için belirli bir nedeniniz yoksa Tunnel'ı tercih edin. (Global bir ngrok kurulumu ve authtoken gerektirir.)

--ngrok bayrağı ngrok'u --host-header=rewrite ile başlatır; böylece ngrok, iletmeden önce yukarı akış Host adresini localhost olarak yeniden yazar. Bu, genel *.ngrok alan adını ALLOWED_HOSTS adresine eklemenize gerek kalmadan istekleri loopback Host beyaz listesinde tutar (bkz. DNS-rebinding koruması). ngrok'u manuel olarak çalıştırırsanız aynı bayrağı kullanın — ngrok http --host-header=rewrite 3000 — aksi takdirde ngrok genel ngrok ana bilgisayar adını Host olarak iletir ve sunucu bunu 403 ile reddeder.

CLI Seçenekleri (tüm modlar)

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 all write operations)
  --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

Salt Okunur Mod (tüm modlar)

--read-only bayrağı, Anki koleksiyonunuzda herhangi bir değişiklik yapılmasını engeller. Etkinleştirildiğinde:

  • Tüm okuma işlemleri normal çalışır (desteleri görüntüleme, kartları görüntüleme, notları arama)
  • İnceleme işlemlerine izin verilir (senkronizasyon, answerCards, askıya alma/askıdan çıkarma)
  • İçerik değişiklikleri engellenir (addNote, deleteNotes, createDeck, updateNoteFields, vb.)
  • Anki verilerini yanlışlıkla değiştirme riski olmadan güvenle keşfetmek için kullanışlıdır
# 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

Salt okunur modu ortam değişkeniyle de etkinleştirebilirsiniz:

READ_ONLY=true ankimcp

Veya MCP istemci yapılandırmasında:

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

Claude Desktop'a Bağlanma (Yerel Mod)

Sunucuyu Claude Desktop'ta şu şekilde yapılandırabilirsiniz:

  • Ayarlar → Geliştirici → Yapılandırmayı Düzenle bölümüne giderek
  • Veya yapılandırma dosyasını manuel olarak düzenleyerek

Yapılandırma

Claude Desktop yapılandırmanıza aşağıdakileri ekleyin:

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

/path/to/anki-mcp-server yerine gerçek proje yolunuzu yazın.

Yapılandırma Dosyası Konumları

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

Daha fazla ayrıntı için resmi MCP belgelerine bakın.

Ortam Değişkenleri (İsteğe Bağlı)

DeğişkenAçıklamaVarsayılan
ANKI_CONNECT_URLAnkiConnect URL'sihttp://localhost:8765
ANKI_CONNECT_API_VERSIONAPI sürümü6
ANKI_CONNECT_API_KEYAnkiConnect'te yapılandırılmışsa API anahtarı-
ANKI_CONNECT_TIMEOUTms cinsinden istek zaman aşımı5000
READ_ONLYSalt okunur modu etkinleştir (true veya 1)false
PORTHTTP modu: dinlenecek bağlantı noktası (--port bayrağı önceliklidir)3000
HOSTHTTP modu: bağlanılacak adres (--host bayrağı önceliklidir)127.0.0.1
ALLOWED_HOSTSHTTP modu: loopback dışında kabul edilecek ek Host başlık değerleri (virgülle ayrılmış ana bilgisayar adları). LAN/genel adrese bağlanırken veya ters proxy arkasında çalışırken gereklidir. HTTP Modu Yapılandırması bölümüne bakın.yalnızca loopback
ALLOWED_ORIGINSHTTP modu: virgülle ayrılmış tarayıcı Origin/Referer desenleri beyaz listesi (joker karakterler desteklenir, örn. https://*.ngrok.io).http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*
TUNNEL_SERVER_URLTünel sunucusu WebSocket URL'si (yalnızca tünel modu)wss://tunnel.ankimcp.ai
MEDIA_ALLOWED_TYPESDosya yolu içe aktarımları için izin verilecek ek MIME türleri (virgülle ayrılmış, örn. application/pdf)-
MEDIA_IMPORT_DIRDosya yolu içe aktarımlarını bu dizine kısıtla-
MEDIA_ALLOWED_HOSTSURL içe aktarımları için belirli özel ağ ana bilgisayarlarına izin ver (virgülle ayrılmış, örn. 192.168.1.50,my-nas)-

Kullanım Örnekleri

Notları Arama ve Güncelleme

# 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)

Anki Sorgu Sözdizimi Örnekleri

findNotes aracı, Anki'nin güçlü sorgu sözdizimini destekler:

  • "deck:DeckName" - Belirli bir destedeki tüm notlar
  • "tag:important" - "önemli" etiketine sahip notlar
  • "is:due" - İnceleme zamanı gelen kartlar
  • "is:new" - Henüz çalışılmamış yeni kartlar
  • "added:7" - Son 7 gün içinde eklenen notlar
  • "front:hello" - Ön alanında "merhaba" yazan notlar
  • "flag:1" - Kırmızı bayraklı notlar
  • "prop:due<=2" - 2 gün içinde vadesi gelen kartlar
  • "deck:Spanish tag:verb" - Fiil etiketli İspanyolca deste notları (VE)
  • "deck:Spanish OR deck:French" - Her iki desteden notlar

Önemli Notlar

CSS ve HTML İşleme

  • notesInfo aracı, doğru işleme farkındalığı için CSS stil bilgilerini döndürür
  • updateNoteFields aracı, alanlarda HTML içeriğini destekler ve CSS stillerini korur
  • Her not modelinin kendi CSS stili vardır - modele özel CSS almak için modelStyling kullanın

Güncelleme Uyarısı

⚠️ ÖNEMLİ: updateNoteFields kullanırken, güncelleme sırasında notu Anki'nin tarayıcısında GÖRÜNTÜLEMEYİN, aksi takdirde alanlar düzgün güncellenmez. Güncellemeden önce tarayıcıyı kapatın veya farklı bir nota geçin. Daha fazla ayrıntı için Bilinen Sorunlar bölümüne bakın.

Silme Güvenliği

deleteNotes aracı, yanlışlıkla silinmeyi önlemek için açık onay (confirmDeletion: true) gerektirir. Bir notu silmek, ilişkili TÜM kartları kalıcı olarak kaldırır.

Güvenlik

Medya Dosyası Yolu ve URL Doğrulama

Medya araçları (storeMediaFile, retrieveMediaFile, deleteMediaFile) ve updateNoteFields ses/resim alanları, komut enjeksiyonu yoluyla kötüye kullanımı önlemek için güvenlik doğrulaması içerir:

  • Dosya yolu içe aktarımları yalnızca medya dosya türleriyle (resimler, ses, video) sınırlıdır. Medya olmayan dosyalar (örn. SSH anahtarları, kimlik bilgileri, kabuk yapılandırmaları) MIME türüne göre reddedilir. Ek dosya türlerine izin vermek için MEDIA_ALLOWED_TYPES yapılandırın veya içe aktarımları belirli bir dizine kısıtlamak için MEDIA_IMPORT_DIR kullanın.
  • URL içe aktarımları SSRF saldırılarına karşı doğrulanır. Özel ağlara (10.x, 172.16.x, 192.168.x), loopback (127.x), bağlantı-yerel (169.254.x) ve HTTP(S) olmayan şemalara yapılan istekler engellenir. Belirli özel ağ ana bilgisayarlarına izin vermek için MEDIA_ALLOWED_HOSTS yapılandırın.
  • Dosya adları, yol geçişini önlemek için temizlenir (örn. ../../ dizileri kaldırılır).

Bu korumalar storeMediaFile, retrieveMediaFile, deleteMediaFile ve updateNoteFields ses/resim alanları için geçerlidir.

Yol geçiş güvenlik açığı Hideaki Takahashi tarafından bildirildi.

DNS-Rebinding Koruması (HTTP taşıması)

HTTP modunda çalışırken, sunucu her istekte Host başlığını doğrular. Varsayılan olarak yalnızca geri döngü (loopback) ana bilgisayarları (localhost, 127.0.0.1, ::1) kabul edilir, bağlantı noktasından bağımsız olarak. Host tarayıcı tarafından yasaklanmış bir başlıktır, bu nedenle kötü niyetli bir web sayfası bunu taklit edemez — bu, yeniden bağlanan bir sayfanın sahte bir Host ile ve Origin olmadan yerel sunucuya ulaştığı ve MCP araçlarına eriştiği DNS-rebinding yolunu kapatır. İzin verilmeyen bir Host, 403 ile reddedilir.

0.0.0.0 adresine bağlanırsanız, bir ters proxy arkasında çalışırsanız veya genel bir tünel alan adı açarsanız, bu ana bilgisayarlara izin vermek için ALLOWED_HOSTS (virgülle ayrılmış ana bilgisayar adları) ayarlayın. ngrok ile tünel açarken sunucu --host-header=rewrite kullanır, bu nedenle yukarı akış hala bir geri döngü Host görür. Seçeneklerin tam listesi için HTTP Modu Yapılandırması bölümüne bakın.

avishaigo-commits ve yotampe-pluto tarafından bildirilen DNS-rebinding güvenlik açığı.

Gizlilik Politikası

Bu MCP sunucusu makinenizde yerel olarak çalışır ve hiçbir telemetri, analiz veya kullanım verisi toplamaz.

Tam politika: https://ankimcp.ai/privacy/

  • Veri toplama: Sunucu hiçbir şey toplamaz. Yapay zeka asistanınız ile yerel AnkiConnect eklentiniz arasında istekleri proxy olarak iletir.
  • Kullanım / depolama: Sunucu tarafında depolama yoktur. Tüm flashcard verileri, kendi cihazınızdaki Anki kurulumunuzda kalır.
  • Üçüncü taraf paylaşımı: Yok. Sunucu yalnızca yapılandırdığınız AnkiConnect URL'siyle (varsayılan: localhost) konuşur. Anki'nin yerleşik AnkiWeb senkronizasyonunu etkinleştirirseniz, bu doğrudan Anki kurulumunuz ile AnkiWeb arasında gerçekleşir — bu sunucunun kapsamı dışındadır.
  • Saklama: Geçerli değil — sunucu tarafında hiçbir veri saklanmaz.
  • İletişim: support@ankimcp.ai

Bilinen Sorunlar

Bilinen sorunların ve sınırlamaların kapsamlı bir listesi için lütfen dokümantasyonumuzu ziyaret edin:

Bilinen Sorunlar Dokümantasyonu

Kritik Sınırlamalar

Tarayıcıda Görüntülenirken Not Güncellemeleri Başarısız Olur

⚠️ ÖNEMLİ: updateNoteFields kullanarak notları güncellerken, not Anki'nin tarayıcı penceresinde görüntüleniyorsa güncelleme sessizce başarısız olur. Bu, yukarı akış AnkiConnect sınırlamasıdır.

Geçici çözüm: Güncellemeden önce tarayıcıyı her zaman kapatın veya farklı bir nota gidin.

Daha fazla ayrıntı ve diğer bilinen sorunlar için tam dokümantasyona bakın.

Sorun Giderme

ERR_REQUIRE_ESM Hatası

Aşağıdaki gibi bir hata görürseniz:

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

Bu, Node.js sürümünüzün desteklenmediği anlamına gelir. Sunucu Node.js 22.12.0+ gerektirir.

Not: Desteklenen minimum çalışma zamanı Node.js 22.12.0'dır. Node.js 20 (Iron) 2026-04-30 tarihinde kullanım ömrünün sonuna ulaşmıştır ve artık desteklenmemektedir.

Sürümünüzü kontrol edin:

node --version

Çözüm: Node.js'i 22.12.0+ sürümüne güncelleyin. nodejs.org adresinden indirebilir veya nvm gibi bir sürüm yöneticisi kullanabilirsiniz.

Geliştirme

Aktarım Modları

Bu sunucu, ayrı giriş noktaları aracılığıyla üç MCP aktarım modunu destekler:

STDIO Modu (Varsayılan)

  • Claude Desktop gibi yerel MCP istemcileri için
  • İletişim için standart giriş/çıkış kullanır
  • Giriş noktası: dist/main-stdio.js
  • Çalıştırma: npm run start:prod:stdio veya node dist/main-stdio.js
  • MCPB paketi: STDIO modunu kullanır

HTTP Modu (Akışkan HTTP)

  • Uzak MCP istemcileri ve web tabanlı entegrasyonlar için
  • MCP Streamable HTTP protokolünü kullanır
  • Giriş noktası: dist/main-http.js
  • Çalıştırma: npm run start:prod:http veya node dist/main-http.js
  • Varsayılan bağlantı noktası: 3000 (PORT env değişkeniyle yapılandırılabilir)
  • Varsayılan ana bilgisayar: 127.0.0.1 (HOST env değişkeniyle yapılandırılabilir)
  • MCP uç noktası: http://127.0.0.1:3000/ (kök yol)

Tünel Modu (Yönetilen WebSocket Tüneli)

  • Yerleşik kimlik doğrulamalı, yönetilen AnkiMCP tünel hizmeti aracılığıyla web tabanlı yapay zeka asistanları için
  • MCP sunucusu, bellek içi bir aktarımın arkasında süreç içinde çalışır; TunnelTransport MCP sunucusuna sahiptir ve TunnelClient onu bir WebSocket üzerinden tünel hizmetine köprüler
  • Protokol: yalnızca 2025 MCP revizyonunu sunar (STDIO ve HTTP ayrıca 2026-07-28 sunar)
  • Giriş noktası: dist/main-tunnel.js
  • Çalıştırma: node dist/main-tunnel.js --tunnel (veya ankimcp --tunnel)
  • Kimlik doğrulama: ankimcp --login / ankimcp --logout; kimlik bilgileri ~/.ankimcp/credentials.json adresinde saklanır (0600)
  • Geliştirme: npm run start:dev:tunnel (izleme modu, --tunnel --debug çalıştırır)

Derleme

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

main-stdio.js, main-http.js ve main-tunnel.js aynı dist/ dizinine derlenir. İhtiyaçlarınıza göre hangisini çalıştıracağınızı seçin.

HTTP Modu Yapılandırması

Ortam Değişkenleri:

  • PORT - HTTP sunucu bağlantı noktası (varsayılan: 3000)
  • HOST - Bağlama adresi (varsayılan: yalnızca localhost için 127.0.0.1)
  • ALLOWED_HOSTS - Yerleşik geri döngü kümesinin (localhost, 127.0.0.1, ::1) ötesinde kabul edilecek virgülle ayrılmış ek Host başlık değerleri. Yalnızca ana bilgisayar adı ve bağlantı noktasından bağımsız. Varsayılan: yalnızca geri döngü.
  • ALLOWED_ORIGINS - Tarayıcı Origin/Referer desenlerinin virgülle ayrılmış beyaz listesi; joker karakterler desteklenir (örn. https://*.ngrok.io). Varsayılan: http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*.
  • LOG_LEVEL - Günlük düzeyi (varsayılan: info)

Güvenlik:

  • Ana bilgisayar başlığı doğrulaması (DNS-rebinding koruması) — her HTTP isteği, beyaz listeyle eşleşen bir Host başlığı taşımalıdır. Varsayılan olarak yalnızca geri döngü ana bilgisayarları (localhost, 127.0.0.1, ::1) kabul edilir, bağlantı noktasından bağımsız olarak. Host tarayıcı tarafından yasaklanmış bir başlıktır, bu nedenle kötü niyetli bir web sayfası bunu taklit edemez — bu, yeniden bağlanan bir sayfanın sahte bir Host ile ve Origin olmadan sunucuya ulaştığı DNS-rebinding yolunu kapatır. İzin verilmeyen bir Host, 403 ile reddedilir.
  • Origin başlığı doğrulaması — mevcut ancak izin verilmeyen bir Origin/Referer içeren tarayıcı istekleri reddedilir. Hiçbir Origin içermeyen isteklere (curl, Postman, MCP-over-HTTP istemcileri) izin verilir; Ana bilgisayar doğrulaması, yeniden bağlanmaya karşı savunmadır.
  • Varsayılan olarak localhost'a (127.0.0.1) bağlanır.
  • Geçerli sürümde kimlik doğrulama yoktur (OAuth desteği planlanmaktadır).

HTTP modunu localhost dışına açma — bir LAN/genel adrese bağlanırsanız veya sunucuyu bir ters proxy veya genel alan adının arkasına koyarsanız, istemcilerin kullanacağı ana bilgisayar ad(lar)ına ALLOWED_HOSTS ayarlamanız gerekir, aksi takdirde geri döngü olmayan her istek 403 ile reddedilir:

# 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

0.0.0.0/:: adresine ALLOWED_HOSTS olmadan bağlandığınızda, sunucu yalnızca geri döngü Host başlıklarının kabul edileceğine dair bir başlangıç uyarısı günlüğe kaydeder.

Docker / ters proxy / genel alan adı: aynı kural geçerlidir. Docker'da istekler genellikle kapsayıcının yayınlanan ana bilgisayar adı veya proxy'nin Host ile gelir, bu nedenle ALLOWED_HOSTS buna göre ayarlayın. Bir ters proxy (nginx, Caddy, Traefik) orijinal Host iletmeli ve bu ana bilgisayar adını ALLOWED_HOSTS içinde listelemiş olmalı veya yukarı akış Host değerini localhost olarak yeniden yazmalıdır. Yerleşik --ngrok entegrasyonu bunu otomatik olarak halleder (aşağıya bakın).

Örnek: Çalıştırma Modları

# 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

MCPB Paketi Oluşturma

Dağıtılabilir bir MCPB paketi oluşturmak için:

npm run mcpb:bundle

Bu komut şunları yapar:

  1. Sürümü package.json konumundan manifest.json konumuna senkronize eder
  2. Eski .mcpb dosyalarını kaldırır
  3. TypeScript projesini derler
  4. dist/ ve node_modules/ dosyalarını bir .mcpb dosyasına paketler
  5. devDependencies'i kaldırmak için mcpb clean çalıştırır (paketi ~47MB'den ~10MB'ye optimize eder)

Çıktı dosyası anki-mcp-server-X.X.X.mcpb olarak adlandırılır ve tek tıklamayla kurulum için dağıtılabilir.

Pakete Neler Dahil Edilir

MCPB paketi şunları içerir:

  • Derlenmiş JavaScript (dist/ dizini - üç giriş noktasının tümünü içerir)
  • Yalnızca üretim bağımlılıkları (node_modules/ - devDependencies mcpb clean tarafından kaldırılır)
  • Paket meta verileri (package.json)
  • Manifest yapılandırması (manifest.json - main-stdio.js kullanacak şekilde yapılandırılmıştır)
  • Simge (icon.png)

Kaynak dosyalar, testler ve geliştirme yapılandırmaları .mcpbignore aracılığıyla otomatik olarak hariç tutulur.

Claude Desktop'ta Günlük Kaydı

Claude Desktop'ta bir MCPB uzantısı olarak çalışırken, günlükler şuraya yazılır:

Günlük Konumu: ~/Library/Logs/Claude/ (macOS)

Günlükler birden çok dosyaya bölünmüştür:

  • main.log - Genel Claude Desktop uygulama günlükleri
  • mcp-server-Anki MCP Server.log - Bu uzantı için MCP protokol mesajları
  • mcp.log - Tüm sunuculardan birleştirilmiş MCP günlükleri

Not: pino günlükçü çıktısı (sunucu kodundan INFO, ERROR, WARN mesajları) stderr'e gider ve MCP'ye özgü günlük dosyalarında görünür. Claude Desktop hangi günlük dosyasının hangi mesajları alacağını belirler, ancak genel olarak:

  • Uygulama başlatma ve MCP protokol iletişimi → MCP'ye özgü günlük
  • Sunucu iç günlüğü (pino) → Hem MCP'ye özgü günlük hem de bazen main.log

Günlükleri gerçek zamanlı görüntülemek için:

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

MCP Sunucusunda Hata Ayıklama

MCP sunucusunda MCP Inspector kullanarak ve IDE'nizden (WebStorm, VS Code vb.) bir hata ayıklayıcı ekleyerek hata ayıklayabilirsiniz.

HTTP Modu Notu: HTTP modunu (Streamable HTTP) MCP Inspector ile test ederken CORS hatalarını önlemek için "Connection Type: Via Proxy" kullanın.

Adım 1: MCP Inspector'da Hata Ayıklama Sunucusunu Yapılandırma

mcp-inspector-config.json zaten bir hata ayıklama sunucusu yapılandırması içerir:

{
  "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"
    }
  }
}

Adım 2: Hata Ayıklama Sunucusunu Başlatma

MCP Inspector'ı hata ayıklama sunucusuyla çalıştırın:

npm run inspector:debug

Bu, sunucuyu 9229 bağlantı noktasında Node.js hata ayıklama etkin ve ilk satırda yürütmeyi duraklatarak başlatır.

Adım 3: IDE'nizden Hata Ayıklayıcı Ekleme

WebStorm
  1. Run → Edit Configurations bölümüne gidin
  2. Yeni bir Attach to Node.js/Chrome yapılandırması ekleyin
  3. Bağlantı noktasını 9229 olarak ayarlayın
  4. Eklemek için Debug düğmesine tıklayın
VS Code
  1. Hata Ayıklama panelini açın (Ctrl+Shift+D / Cmd+Shift+D)
  2. Debug MCP Server (Attach) yapılandırmasını seçin
  3. Eklemek için F5'e basın

Adım 4: Kesme Noktaları Ayarlama ve Hata Ayıklama

Eklendikten sonra şunları yapabilirsiniz:

  • TypeScript kaynak dosyalarınızda kesme noktaları ayarlayın
  • Kod yürütme boyunca adım adım ilerleyin
  • Değişkenleri ve çağrı yığınını inceleyin
  • İfadeleri değerlendirmek için hata ayıklama konsolunu kullanın

Hata ayıklayıcı, derlenmiş JavaScript yerine orijinal TypeScript kodunda hata ayıklamanıza olanak tanıyan kaynak haritalarıyla çalışır.

Claude Desktop ile Hata Ayıklama

Node.js hata ayıklayıcısını etkinleştirerek ve IDE'nizi ekleyerek Claude Desktop içinde çalışan MCP sunucusunda da hata ayıklayabilirsiniz.

Adım 1: Hata Ayıklama için Claude Desktop'ı Yapılandırma

Hata ayıklamayı etkinleştirmek için Claude Desktop yapılandırmanızı güncelleyin:

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"
      }
    }
  }
}

Önemli değişiklik: dist/main-stdio.js yolundan önce --inspect=9229 ekleyin

Hata ayıklama seçenekleri:

  • --inspect=9229 - Hata ayıklayıcıyı hemen başlatır, engellemez (önerilir)
  • --inspect-brk=9229 - Hata ayıklayıcı eklenene kadar yürütmeyi duraklatır (başlatma sorunlarında hata ayıklamak için)

Adım 2: Claude Desktop'ı Yeniden Başlatma

Yapılandırmayı kaydettikten sonra Claude Desktop'ı yeniden başlatın. MCP sunucusu artık 9229 bağlantı noktasında hata ayıklama etkin olarak çalışacaktır.

Adım 3: IDE'nizden Hata Ayıklayıcı Ekleme

WebStorm
  1. Run → Edit Configurations bölümüne gidin
  2. + düğmesine tıklayın ve Attach to Node.js/Chrome seçin
  3. Yapılandırın:
    • Name: Attach to Anki MCP (Claude Desktop)
    • Host: localhost
    • Port: 9229
    • Attach to: Node.js < 8 veya Chrome or Node.js > 6.3 (WebStorm sürümüne bağlı olarak)
  4. OK düğmesine tıklayın
  5. Eklemek için Debug (Shift+F9) düğmesine tıklayın
VS Code
  1. .vscode/launch.json dosyasına ekleyin:
{
  "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"]
    }
  ]
}
  1. Hata Ayıklama panelini açın (Ctrl+Shift+D / Cmd+Shift+D)
  2. Attach to Anki MCP (Claude Desktop) seçin
  3. Eklemek için F5'e basın

Adım 4: Gerçek Zamanlı Hata Ayıklama

Ekledikten sonra şunları yapabilirsiniz:

  • TypeScript kaynak dosyalarınızda kesme noktaları belirleyin (ör. src/mcp/primitives/essential/tools/create-model.tool.ts)
  • Claude Desktop'ı normal şekilde kullanın - araçlar çağrıldığında kesme noktaları tetiklenecektir
  • Kod yürütme adımlarında ilerleyin
  • Değişkenleri ve çağrı yığınını inceleyin
  • Hata ayıklama konsolunu kullanın

Örnek: create-model.tool.ts içinde 119. satıra bir kesme noktası belirleyin, ardından Claude'dan yeni bir model oluşturmasını isteyin. Hata ayıklayıcı kesme noktanızda duraklayacaktır!

Not: Claude Desktop çalıştığı sürece hata ayıklayıcı bağlı kalır. Claude Desktop'ı yeniden başlatmadan istediğiniz zaman bağlantıyı kesebilir/yeniden bağlayabilirsiniz.

Derleme Komutları

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

NPM Paket Testi (Yerel)

Yayınlamadan önce npm paketini yerel olarak test edin:

# 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

Nasıl çalışır:

  • npm pack, npm publish'in oluşturacağı dosyayla aynı olan bir .tgz dosyası oluşturur
  • .tgz üzerinden kurulum, kullanıcıların npm install -g ankimcp üzerinden aldıklarını simüle eder
  • Bu, npm'e yayınlamadan önce tam kullanıcı deneyimini test etmenizi sağlar

Test Komutları

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)

Test Kapsamı

Proje aşağıdakiler için minimum %70 kapsam eşiklerini korur:

  • Dallar
  • Fonksiyonlar
  • Satırlar
  • İfadeler

Kapsam raporları coverage/ dizininde oluşturulur.

Sürümleme

Bu proje, 1.0 öncesi geliştirme yaklaşımıyla Semantik Sürümleme izler:

  • 0.x.x - Beta/Geliştirme sürümleri (mevcut aşama)

    • 0.1.x - Hata düzeltmeleri ve yamalar
    • 0.2.0+ - Yeni özellikler veya küçük iyileştirmeler
    • 0.x sürümlerinde geriye dönük uyumluluğu bozan değişiklikler kabul edilebilir

  • 1.0.0 - İlk kararlı sürüm

    • API kararlı ve test edildiğinde yayınlanacaktır
    • Geriye dönük uyumluluğu bozan değişiklikler ana sürüm artışları gerektirecektir (2.0.0, vb.)

Mevcut Durum: 0.22.0 - Aktif beta geliştirme. Son özellikler arasında koleksiyon genelinde inceleme analizi (review_stats artık deck atlandığında tüm destelerde toplar), model alan yönetimi (addModelField, removeModelField, renameModelField, repositionModelField), toplu not oluşturma (addNotes), entegre ngrok tünelleme (--ngrok bayrağı), medya dosyası yönetimi, model/şablon yönetimi ve kapsamlı deste istatistikleri yer alır. API'ler geri bildirim ve testlere göre değişebilir.

MCPB spesifikasyonunun gelişimi

Bu proje, hâlâ gelişmekte olan Anthropic'in MCPB paket spesifikasyonunu hedefler. Spesifikasyonu https://github.com/modelcontextprotocol/mcpb adresinde takip ediyoruz ve uyumlu kalmak için geriye dönük uyumluluğu bozan değişiklikler yapabiliriz. 0.x.x sürümleme şeması kapsamında geriye dönük uyumluluğu bozan değişikliklere izin verilir.

Benzer Projeler

Anki MCP entegrasyonlarını keşfediyorsanız, bu alandaki diğer projeler şunlardır:

scorzeth/anki-mcp-server

  • Durum: Görünüşe göre terk edilmiş (son güncelleme yok)
  • Anki MCP entegrasyonunun erken uygulaması

nailuoGG/anki-mcp-server

  • Yaklaşım: Hafif, tek dosyalık uygulama
  • Mimari: Tüm araçların tek dosyada olduğu prosedürel kod yapısı
  • Uygun olduğu durumlar: Basit kullanım senaryoları, minimum bağımlılıklar

Bu projenin farkı:

  • Kurumsal düzeyde mimari: Bağımlılık enjeksiyonu ile NestJS üzerine inşa edilmiştir
  • Modüler tasarım: Her araç, net sorumluluk ayrımına sahip ayrı bir sınıftır
  • Bakım kolaylığı: Mevcut koda dokunmadan yeni özelliklerle genişletmek kolaydır
  • Test: %70 kapsam gereksinimi olan kapsamlı test paketi
  • Tip güvenliği: Zod doğrulamalı sıkı TypeScript
  • Hata yönetimi: Yararlı kullanıcı geri bildirimi ile sağlam hata yönetimi
  • Üretime hazır: Uygun günlükleme, ilerleme raporlama ve MCPB paket desteği
  • Ölçeklenebilirlik: Temel araçlardan karmaşık iş akışlarına kolayca büyüyebilir

Kullanım senaryosu: Gelişmiş Anki entegrasyonları oluşturmak için sağlam bir temele ihtiyacınız varsa veya işlevselliği önemli ölçüde genişletmeyi planlıyorsanız, bu projenin mimari yaklaşımı zaman içinde bakımı ve ölçeklendirmeyi kolaylaştırır.

Faydalı Bağlantılar

Lisans ve Atıf

Bu proje MIT Lisansı altında lisanslanmıştır — tam metin için LISANS bölümüne bakın.

Telif Hakkı © 2026 Anatoly Tarnavsky.

Üçüncü Taraf Atıfları

  • Anki®, Ankitects Pty Ltd'nin tescilli ticari markasıdır. Bu proje resmi olmayan bir üçüncü taraf aracıdır ve Ankitects Pty Ltd ile bağlantılı değildir, onaylanmamıştır veya desteklenmemektedir. Anki logosu, https://apps.ankiweb.net bağlantısıyla Anki'ye atıfta bulunmak için alternatif lisans altında kullanılmaktadır. Resmi Anki uygulaması için https://apps.ankiweb.net adresini ziyaret edin.

  • Model Context Protocol (MCP), Anthropic'in açık standardıdır. MCP logosu, resmi MCP dokümantasyon deposundan alınmıştır ve MIT Lisansı altında kullanılmaktadır. MCP hakkında daha fazla bilgi için https://modelcontextprotocol.io adresini ziyaret edin.

  • Bu, Anki ve MCP teknolojilerini birbirine bağlayan bağımsız bir projedir. Tüm ticari markalar, hizmet markaları, ticari unvanlar, ürün adları ve logolar ilgili sahiplerinin mülkiyetindedir.