Anki MCP

Anki MCP Sunucusu

Beta - Bu proje aktif olarak geliştirilmektedir. API'ler ve özellikler değişebilir.

Yapay zeka asistanlarının, aralıklı tekrar bilgi kartı uygulaması Anki ile etkileşime girmesini sağlayan bir Model Bağlam Protokolü (MCP) sunucusu.

Doğal dil etkileşimi ile Anki deneyiminizi dönüştürün - tıpkı özel bir öğretmene sahip olmak gibi. Yapay zeka asistanı sadece soru ve cevapları sunmakla kalmaz; kavramları açıklayabilir, öğrenme sürecini daha ilgi çekici ve insana benzer hale getirebilir, bağlam sağlayabilir ve öğrenme stilinize uyum sağlayabilir. Anında notlar oluşturup düzenleyerek çalışma seanslarınızı dinamik sohbetlere dönüştürebilir. Daha fazla özellik çok yakında!

Örnekler ve Eğitimler

Bu MCP sunucusunu Claude Desktop ile kullanmaya yönelik kapsamlı kılavuzlar, gerçek dünya örnekleri ve adım adım eğitimler için ziyaret edin:

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

docs/ sayfasında, inceleme arayüzü kurulum kılavuzu ve örnek Anki destesi dahil olmak üzere tamamlayıcı dokümantasyona bakın.

Örnek Kullanım Senaryoları

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

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

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

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

Mevcut Araçlar

Sunucu 42 MCP aracı sunar — günlük Anki işlemleri için 31 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 almak ve değişiklikleri göndermek için AnkiWeb ile senkronize olun
• get_due_cards - İsteğe bağlı olarak desteye göre filtrelenmiş, gözden geçirilmesi gereken kartları alın
• get_cards - Duruma (zamanı gelmiş, yeni, öğreniliyor, askıya alınmış, gömülü) ve desteye göre esnek filtreleme ile kartları alın
• present_card - Bir kartı, sorusu/ön yüzü ile birlikte inceleme için gösterin
• rate_card - Kart performansını derecelendirin (Yine, Zor, İyi, Kolay) ve bir sonraki gözden geçirmeyi planlayın

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

Deste Yönetimi

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

Not Yönetimi

• addNote - Belirtilen alanlar ve etiketlerle tek bir not oluşturun
• addNotes - Bir desteyi ve modeli paylaşan en fazla 100 notu toplu olarak 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 stili)
• updateNoteFields - Mevcut not alanlarını güncelleyin (CSS duyarlı, HTML içeriğini destekler)
• deleteNotes - Notları ve ilişkili tüm kartları silin (yıkıcı, onay gerektirir)

Etiket Yönetimi

• getTags - Koleksiyondaki tüm etiketleri alın (tekrardan kaçınmak için önce kullanın)
• addTags - Belirtilen notlara boşlukla ayrılmış etiketler ekleyin
• removeTags - Belirtilen notlardan boşlukla ayrılmış etiketleri kaldırın
• replaceTags - Belirtilen notlar genelinde bir etiketi yeniden adlandırın
• clearUnusedTags - Hiçbir not tarafından kullanılmayan yetim etiketleri kaldırın (yıkıcı)

Medya Yönetimi

• getMediaFilesNames - collection.media içindeki medya dosyalarını, isteğe bağlı olarak desene göre filtrelenmiş şekilde listeleyin
• retrieveMediaFile - Bir medya dosyasını base64 içeriği olarak indirin
• storeMediaFile - Base64 verisinden, mutlak bir dosya yolundan veya bir URL'den medya yükleyin
• deleteMediaFile - collection.media içinden bir medya dosyasını kaldırın (yıkı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 yeterlidir; o, en verimli yöntemi kullanarak yüklemeyi otomatik olarak gerçekleştirecektir.

Model/Şablon Yönetimi

• modelNames - Mevcut tüm not türlerini/modellerini listeleyin
• modelFieldNames - Belirli bir not türü için alan adlarını alın
• modelStyling - Bir not türü için CSS stil 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ü için CSS stilini güncelleyin (tüm kartlarına uygulanır)
• updateModelTemplates - Mevcut bir not türü için 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 yerleştirilir)
• 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ündeki bir alanı yeniden adlandırın (eski ada başvuran kart şablonları ayrıca güncellenmelidir)
• repositionModelField - Mevcut bir not türü içindeki bir alanın konumunu değiştirin

İstatistikler

• collection_stats - Deste bazında dağılım ile tüm desteler genelinde toplu istatistikler
• review_stats - Gözden geçirme geçmişi analizi (zamansal desenler, hatırlama 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 seansları için değildir.

• guiBrowse - Kart Tarayıcıyı açın ve kartları arayın
• guiSelectCard - Kart Tarayıcıda belirli bir kartı seçin
• guiSelectedNotes - Kart Tarayıcıda o anda seçili olan notların kimliklerini alın
• guiAddCards - Önceden ayarlanmış not detayları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ı iletişim kutusunu açın
• guiCurrentCard - Gözden geçirme modundaki mevcut kart hakkında bilgi alın
• guiShowQuestion - Mevcut kartın soru tarafını gösterin
• guiShowAnswer - Mevcut kartın cevap tarafını gösterin
• guiUndo - Anki'deki son eylemi geri alın

Ön Koşullar

• AnkiConnect eklentisi yüklü Anki
• Node.js 22.12.0+

Kurulum

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

npm (global veya npx)

Sunucuyu doğrudan başlatan herhangi bir MCP istemcisi için uygun, genel amaçlı kurulum yöntemi.

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ı yükleyin:
   • 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ı Yükle'ye 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'ı yeniden başlatın

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

Anthropic MCP Dizini inceleyicileri için: önceden doldurulmuş örnek bir deste ile sıfırdan entegrasyona kadar bir kılavuz docs/reviewer-setup.md içinde bulunmaktadır.

Kaynaktan Kurulum (geliştirme için)

Geliştirme veya ileri düzey kullanım için:

npm install
npm run build

Bir Yapay Zeka İstemcisi Bağlama

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

• 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.
• Uzak — barındırılan/uzak bir yapay zeka (örn. buluttaki ChatGPT veya Claude.ai), yerel makinenizde çalışan Anki'ye ulaşmalıdır. Yönetilen Tünel (✅ önerilir — kimlik doğrulamalı) veya daha hafif, kimlik doğrulamasız bir alternatif olarak ngrok kullanın.

Yerel

Sunucu, yapay zeka istemcinizle aynı bilgisayarda çalışır ve localhost üzerinde AnkiConnect ile iletişim kurar.

STDIO (birincil yerel entegrasyon)

STDIO, yerel masaüstü MCP istemcileri için standart aktarımdır — Claude Desktop, Cursor IDE, Cline, Zed Editor ve diğerleri. İstemci, sunucuyu bir alt süreç olarak başlatır ve standart girdi/çıktı ü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 aktarımı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 gerektirmez)

{
  "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'daki ayarlar kullanıcı arayüzü üzerinden erişilebilir
• Zed Editor: Uzantı pazar yeri üzerinden MCP uzantısı olarak yükleyin

İstemciye özgü özellikler ve sorun giderme için MCP istemcinizin dokümantasyonuna başvurun. Ayrıca, doğrudan derlenmiş bir dist/main-stdio.js'i işaret eden bir yapılandırma için Claude Desktop'a Bağlanma bölümüne bakın.

HTTP (yerel web tabanlı yapay zeka)

HTTP modu, sunucuyu MCP Akışlı HTTP protokolünü konuşan yerel bir web sunucusu olarak çalıştırır. Web tabanlı bir yapay zeka aracının makinenize yönlendirildiğinde iletişim kurduğu aktarımdır ve aynı zamanda Uzak seçeneklerinin dış dünyaya sunduğu şeydir. Kendi başına, HTTP modu yalnızca localhost adresine bağlanır.

Localhost ötesine bağlanma? Eğer --host 0.0.0.0 iletirseniz (veya bir ters proxy/ortak alan adının arkasında çalıştırırsanız), sunucu DNS yeniden bağlama koruması için varsayılan olarak yalnızca geri döngü Host başlıklarını kabul eder — ALLOWED_HOSTS değerini istemcilerin kullandığı ana bilgisayar ad(lar)ına ayarlayın. Bkz. HTTP Modu Yapılandırması.

Kurulum - Bir yöntem seçin:

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

# 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 bulutta barındırılan bir yapay zekanın erişebileceği hale getirmek için aşağıdaki Uzak seçeneklerinden birini kullanın.

Uzak

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, uzak bir asistanın onunla konuşabilmesi için yerel Anki'nizi internete açar.

Tünel (✅ Önerilen)

Önerilen uzak yol — kimlik doğrulamalı ve güvenli. Ham bir genel portun 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 bir genel URL atanır. Kimlik doğrulama yerleşiktir — ngrok hesabı veya ayrı bir tünel süreci gerekmez ve bir kez oturum açarsınız.

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

Tünel modu, OAuth 2.0 Cihaz Yetkilendirme İzni'ni kullanır. Oturum açmak, kodun zaten URL'ye 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 giriş için bir doğrulama URL'si ve kodu yazdırır.) Başarılı olunduğunda, 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 bilgisi yoksa, --tunnel önce oturum açma akışını otomatik olarak 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ızlıca başarısız olur ve önce ankimcp --login komutunu ç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 tuşlarına basın. Bu URL'yi yapay zeka asistanınızla paylaşın.

Tünel modu ortam değişkenleri:

Değişken	Açıklama	Varsayılan
TUNNEL_SERVER_URL	Tünel sunucusu WebSocket URL'si (--tunnel/--login bayrak değeri bunu geçersiz kılar)	wss://tunnel.ankimcp.ai
TUNNEL_AUTH_CLIENT_ID	Cihaz akışı için OAuth istemci kimliği. Gelişmiş — yalnızca kendi barındırdığınız bir tünel/kimlik doğrulama hizmetine işaret ederken gereklidir.	(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 yönlendirmek, kimlik doğrulamayı da o ana bilgisayara taşır.

Nasıl çalışır: Tünel modu, MCP sunucusunu bellek içi bir aktarımın arkasında süreç içinde çalıştırır (McpModule yerleşik aktarım olmadan başlatılır). TunnelMcpService bu bellek içi aktarımı MCP sunucusuna bağlar ve TunnelClient bunu bir WebSocket üzerinden uzak tünel hizmetine köprüler — MCP isteklerini içeri ve yanıtları dışarı iletir. AnkiConnect'e hala yalnızca yerel makinenizden erişilir.

ngrok (kimlik doğrulamasız alternatif)

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

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

Bu yol kimlik doğrulamasızdır — URL'ye sahip herkes Anki'nize erişebilir, bu nedenle Tünel modundan daha az güvenlidir. Kendi ngrok uç noktanızı yönetmek için belirli bir nedeniniz yoksa Tünel'i 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 başlığını localhost olarak yeniden yazar. Bu, genel *.ngrok alan adını ALLOWED_HOSTS adresine eklemek zorunda kalmadan istekleri geri döngü Ana Bilgisayar izin listesi içinde tutar (bkz. DNS yeniden bağlama koruması). Bunun yerine 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 <port>              Port to listen on (HTTP mode, default: 3000)
  -h, --host <host>              Host to bind to (HTTP mode, default: 127.0.0.1)
  -a, --anki-connect <url>       AnkiConnect URL (default: http://localhost:8765)
  --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 şekilde çalışır (destelere göz atma, kartları görüntüleme, notları arama)
• Gözden geçirme işlemlerine izin verilir (eşitleme, answerCards, askıya alma/askıdan çıkarma)
• İçerik değişiklikleri engellenir (addNote, deleteNotes, createDeck, updateNoteFields, vb.)
• Yanlışlıkla değişiklik yapma riski olmadan Anki verilerini 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şkeni aracılığıyla da 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 yollarla yapılandırabilirsiniz:

• Ayarlar → Geliştirici → Yapılandırmayı Düzenle'ye giderek
• Veya yapılandırma dosyasını manuel olarak düzenleyerek

Yapılandırma

Claude Desktop yapılandırmanıza aşağıdakini 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 kısmını gerçek proje yolunuzla değiştirin.

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şken	Açıklama	Varsayılan
ANKI_CONNECT_URL	AnkiConnect URL'si	http://localhost:8765
ANKI_CONNECT_API_VERSION	API sürümü	6
ANKI_CONNECT_API_KEY	AnkiConnect'te yapılandırılmışsa API anahtarı	-
ANKI_CONNECT_TIMEOUT	Milisaniye cinsinden istek zaman aşımı	5000
READ_ONLY	Salt okunur modu etkinleştir (true veya 1)	false
ALLOWED_HOSTS	HTTP modu: geri döngü dışında kabul edilecek ek Host başlık değerleri (virgülle ayrılmış ana bilgisayar adları). Bir LAN/genel adrese bağlanırken veya bir ters proxy arkasında çalışırken gereklidir. Bkz. HTTP Modu Yapılandırması.	yalnızca geri döngü
ALLOWED_ORIGINS	HTTP modu: tarayıcı Origin/Referer kalıplarının virgülle ayrılmış izin listesi (joker karakterler desteklenir, örn. https://*.ngrok.io).	http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*
TUNNEL_SERVER_URL	Tünel sunucusu WebSocket URL'si (yalnızca tünel modu)	wss://tunnel.ankimcp.ai
MEDIA_ALLOWED_TYPES	Dosya yolu içe aktarımları için izin verilecek ek MIME türleri (virgülle ayrılmış, örn., application/pdf)	-
MEDIA_IMPORT_DIR	Dosya yolu içe aktarımlarını bu dizinle sınırla	-
MEDIA_ALLOWED_HOSTS	URL 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" - "important" etiketine sahip notlar
• "is:due" - Gözden geçirilmesi gereken kartlar
• "is:new" - Henüz çalışılmamış yeni kartlar
• "added:7" - Son 7 günde eklenen notlar
• "front:hello" - Ön alanında "hello" geçen notlar
• "flag:1" - Kırmızı bayraklı notlar
• "prop:due<=2" - 2 gün içinde tekrarı gelen kartlar
• "deck:Spanish tag:verb" - Fiil etiketine sahip İ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ı, alanlardaki HTML içeriğini destekler ve CSS stilini korur
• Her not modelinin kendi CSS stili vardır - modele özgü 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ülemeyin, 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 silmeleri ö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 Dosya Yolu ve URL Doğrulaması

Medya araçları (storeMediaFile, retrieveMediaFile, deleteMediaFile) ve updateNoteFields ses/resim alanları, istem 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 dizinle sınırlamak 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), geri döngüye (127.x), bağlantı-yerel'e (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ı, dizin geçişini önlemek için temizlenir (örn., ../../ dizileri çıkarılır).

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

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

DNS Yeniden Bağlama Koruması (HTTP aktarımı)

HTTP modunda çalışırken, sunucu her istekte Host başlığını doğrular. Varsayılan olarak, porttan bağımsız olarak yalnızca geri döngü ana bilgisayarları (localhost, 127.0.0.1, ::1) kabul edilir. Host tarayıcı tarafından yasaklanmış bir başlıktır, bu nedenle kötü amaçlı bir web sayfası bunu taklit edemez — bu, yeniden bağlanan bir sayfanın sahte bir Host ve Origin olmadan yerel sunucuya ulaştığı ve MCP araçlarına eriştiği DNS yeniden bağlama 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ıştırırsanız veya bir genel tünel alan adı yayınlarsanı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, böylece 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.

DNS yeniden bağlama güvenlik açığı avishaigo-commits ve yotampe-pluto tarafından bildirildi.

Gizlilik Politikası

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

Politikanın tamamı: https://ankimcp.ai/privacy/

• Veri toplama: Sunucu hiçbir şey toplamaz. Yapay zeka asistanınız ile yerel AnkiConnect eklentiniz arasındaki istekleri iletir.
• Kullanım / depolama: Sunucu tarafında depolama yoktur. Tüm flash kart verileri kendi cihazınızdaki Anki kurulumunuzda kalır.
• Üçüncü taraflarla paylaşım: Yok. Sunucu yalnızca yapılandırdığınız AnkiConnect URL'si ile konuşur (varsayılan: localhost). Anki'nin yerleşik AnkiWeb eşitlemesini etkinleştirirseniz, bu Anki kurulumunuz ile AnkiWeb arasında doğrudan 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 belgelerimizi ziyaret edin:

Bilinen Sorunlar Belgeleri

Kritik Sınırlamalar

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

⚠️ ÖNEMLİ: updateNoteFields kullanarak notları güncellerken, not şu anda 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 her zaman tarayıcıyı kapatın veya farklı bir nota gidin.

Daha fazla ayrıntı ve diğer bilinen sorunlar için tüm belgelere 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'da kullanım ömrünün sonuna ulaştı ve artık desteklenmiyor.

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

node --version

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

Geliştirme

Taşıma Modları

Bu sunucu, ayrı giriş noktaları aracılığıyla üç MCP taşıma 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 Akışkan 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 port: 3000 (PORT ortam değişkeni ile yapılandırılabilir)
• Varsayılan ana bilgisayar: 127.0.0.1 (HOST ortam değişkeni ile 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ğrulama ile yönetilen AnkiMCP tünel hizmeti aracılığıyla web tabanlı AI asistanları için
• MCP sunucusu, bellek içi bir taşımanın arkasında süreç içinde çalışır; TunnelMcpService bunu MCP sunucusuna bağlar ve TunnelClient bunu bir WebSocket üzerinden tünel hizmetine köprüler
• 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 (0600) konumunda saklanır
• 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 hepsi 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 portu (varsayılan: 3000)
• HOST - Bağlanma 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 porttan bağımsız. Varsayılan: yalnızca geri döngü.
• ALLOWED_ORIGINS - Tarayıcı Origin/Referer desenlerinin virgülle ayrılmış izin 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 kaydı seviyesi (varsayılan: info)

Güvenlik:

• Host başlığı doğrulaması (DNS-yeniden bağlama koruması) — her HTTP isteği, izin listesiyle eşleşen bir Host başlığı taşımalıdır. Varsayılan olarak, porttan bağımsız olarak yalnızca geri döngü ana bilgisayarları (localhost, 127.0.0.1, ::1) kabul edilir. Host tarayıcı tarafından yasaklanmış bir başlıktır, bu nedenle kötü amaçlı bir web sayfası bunu taklit edemez — bu, yeniden bağlanan bir sayfanın sahte bir Host ve Origin olmadan sunucuya ulaştığı DNS-yeniden bağlama yolunu kapatır. İzin verilmeyen bir Host, 403 ile reddedilir.
• Origin başlığı doğrulaması — mevcut ancak izin verilmeyen Origin/Referer içeren tarayıcı istekleri reddedilir. Origin olmayan isteklere (curl, Postman, HTTP üzerinden MCP istemcileri) izin verilir; Yeniden bağlamaya karşı savunma Host doğrulamasıdır.
• Varsayılan olarak localhost'a (127.0.0.1) bağlanır.
• Mevcut sürümde kimlik doğrulama yok (OAuth desteği planlanıyor).

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, ALLOWED_HOSTS değerini istemcilerin kullanacağı ana bilgisayar ad(lar)ına 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

ALLOWED_HOSTS olmadan 0.0.0.0/:: adresine 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ı kaydeder.

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

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

# 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ı yapacaktır:

1. Sürümü package.json ile manifest.json arasında 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'ı kaldırmak için mcpb clean çalıştırır (paketi ~47MB'tan ~10MB'a optimize eder)

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

Neler Paketlenir

MCPB paketi şunları içerir:

• Derlenmiş JavaScript (dist/ dizini - üç giriş noktasını da 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 logger çıktısı (sunucu kodundan gelen INFO, ERROR, WARN mesajları) stderr'e gider ve MCP'ye özgü günlük dosyalarında görünür. Hangi günlük dosyasının hangi mesajları alacağını Claude Desktop belirler, ancak genellikle:

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

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

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

MCP Sunucusunda Hata Ayıklama

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

HTTP Modu için Not: MCP Inspector ile HTTP modunu (Akışkan HTTP) test ederken, CORS hatalarını önlemek için "Connection Type: Via Proxy" seçeneğini kullanın.

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

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şlatın

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

npm run inspector:debug

Bu, sunucuyu 9229 portunda Node.js hata ayıklama etkinken başlatacak ve ilk satırda yürütmeyi duraklatacaktır.

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

WebStorm

1. Run → Edit Configurations menüsüne gidin
2. Yeni bir Attach to Node.js/Chrome yapılandırması ekleyin
3. Portu 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 tuşuna basın

Adım 4: Kesme Noktaları Ayarlayın ve Hata Ayıklayın

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ı, kaynak haritalarla çalışarak derlenmiş JavaScript yerine orijinal TypeScript kodunda hata ayıklamanıza olanak tanır.

Claude Desktop ile Hata Ayıklama

Node.js hata ayıklayıcısını etkinleştirip IDE'nizi ekleyerek MCP sunucusu Claude Desktop içinde çalışırken de hata ayıklayabilirsiniz.

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

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şlangıç sorunlarında hata ayıklamak için)

Adım 2: Claude Desktop'ı Yeniden Başlatın

Yapılandırmayı kaydettikten sonra Claude Desktop'ı yeniden başlatın. MCP sunucusu artık 9229 portunda hata ayıklama etkinken çalışacaktır.

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

WebStorm

1. Run → Edit Configurations menüsüne gidin
2. + düğmesine tıklayın ve Attach to Node.js/Chrome seçeneğini belirleyin
3. Yapılandırın:
   • Ad: Attach to Anki MCP (Claude Desktop)
   • Ana Bilgisayar: localhost
   • Port: 9229
   • Ekle: 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"]
    }
  ]
}

2. Hata Ayıklama panelini açın (Ctrl+Shift+D / Cmd+Shift+D)
3. Attach to Anki MCP (Claude Desktop) seçeneğini belirleyin
4. Eklemek için F5 tuşuna basın

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

Eklendikten sonra şunları yapabilirsiniz:

• TypeScript kaynak dosyalarınızda kesme noktaları ayarlayın (örn., 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 boyunca adım adım ilerleyin
• Değişkenleri ve çağrı yığınını inceleyin
• Hata ayıklama konsolunu kullanın

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

Not: Hata ayıklayıcı, Claude Desktop çalıştığı sürece bağlı kalır. Claude Desktop'ı yeniden başlatmadan istediğiniz zaman ayırabilir/tekrar ekleyebilirsiniz.

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ğıyla aynı bir .tgz dosyası oluşturur
• .tgz adresinden kurulum yapmak, kullanıcıların npm install -g ankimcp adresinden ne alacağını simüle eder
• Bu, npm'de 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üm Oluşturma

Bu proje, 1.0 öncesi bir geliştirme yaklaşımıyla Semantik Sürüm Oluşturma kurallarını takip eder:

• 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
  • Kırıcı değişiklikler 0.x sürümlerinde kabul edilebilir

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

  • API kararlı ve test edildiğinde yayınlanacaktır
  • Kırıcı 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 bulunmaktadır. API'ler geri bildirim ve testlere bağlı olarak değişebilir.

MCPB belirtim evrimi

Bu proje, halen gelişmekte olan Anthropic'in MCPB paket belirtimini hedefler. Belirtimi https://github.com/modelcontextprotocol/mcpb adresinden takip ediyoruz ve uyumlu kalmak için kırıcı değişiklikler yapabiliriz. 0.x.x sürüm oluşturma şeması altında kırıcı 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: Terk edilmiş gibi görünüyor (yakın zamanda güncelleme yok)
• Anki MCP entegrasyonunun erken bir uygulaması

nailuoGG/anki-mcp-server

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

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 bir sorumluluk ayrımına sahip ayrı bir sınıftır
• Sürdürülebilirlik: Mevcut koda dokunmadan yeni özellikler eklemek kolaydır
• Test: %70 kapsama gereksinimi olan kapsamlı test paketi
• Tip güvenliği: Zod doğrulaması ile katı TypeScript
• Hata yönetimi: Yararlı kullanıcı geri bildirimi ile sağlam hata yönetimi
• Üretime hazır: Düzgün günlükleme, ilerleme raporlaması ve MCPB paket desteği
• Ölçeklenebilirlik: Temel araçlardan karmaşık iş akışlarına kolayca büyüyebilir

Kullanım durumu: 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.

Yararlı Bağlantılar

• Model Bağlam Protokolü Dokümantasyonu
• AnkiConnect API Dokümantasyonu
• Claude Desktop İndirme
• Masaüstü Uzantıları Oluşturma (Anthropic Blog)
• MCP Sunucuları Deposu
• NestJS Dokümantasyonu
• Anki Resmi Web Sitesi

Lisans ve Atıf

Bu proje MIT Lisansı altında lisanslanmıştır — tam metin için LICENSE dosyasına 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ı, onaylanmış veya sponsorlu değildir. Anki logosu, https://apps.ankiweb.net bağlantısıyla Anki'ye atıfta bulunmak için alternatif lisans kapsamında kullanılmıştır. Resmi Anki uygulaması için https://apps.ankiweb.net adresini ziyaret edin.

• Model Bağlam Protokolü (MCP), Anthropic tarafından geliştirilen açık bir standarttır. MCP logosu, resmi MCP dokümantasyon deposundan alınmıştır ve MIT Lisansı kapsamında kullanılmıştı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 adlar, ürün adları ve logolar ilgili sahiplerinin mülkiyetindedir.