Zettelkasten MCP Server

Zettelkasten bilgi yönetimi metodolojisini uygulayan bir Model Context Protocol (MCP) sunucusu. Claude ve diğer MCP uyumlu istemciler aracılığıyla atomik notlar oluşturmanızı, bağlantı kurmanızı, keşfetmenizi ve sentezlemenizi sağlar.

Zettelkasten Nedir?

Zettelkasten yöntemi, Alman sosyolog Niklas Luhmann tarafından geliştirilen bir bilgi yönetimi sistemidir. Luhmann bu sistemi kullanarak 70'ten fazla kitap ve yüzlerce makale üretmiştir. Üç temel prensipten oluşur:

Atomiklik: Her not tam olarak bir fikir içerir ve bilginin ayrı bir birimi olarak işlev görür
Bağlantılılık: Notlar birbirine bağlanarak bir bilgi ağı oluşturur ve fikirler arasında anlamlı ilişkiler kurulur
Ortaya Çıkış: Ağ büyüdükçe, bireysel notlar oluşturulurken belirgin olmayan yeni desenler ve içgörüler ortaya çıkar

Zettelkasten yaklaşımını güçlü kılan şey, birden fazla şekilde keşif yapma imkanı sunmasıdır:

Dikey keşif: Bir konu alanı içindeki bağlantıları takip ederek belirli konulara daha derin inin.
Yatay keşif: Etki alanları aşan bağlantıları takip ederek farklı alanlar arasında beklenmedik ilişkiler keşfedin.

Bu yapı, nottan nota düşünce izlerini takip ederken serendipitous keşifler için zemin hazırlar ve aynı zamanda her bilgi parçasını benzersiz kimliği aracılığıyla kolayca erişilebilir tutar. Luhmann sistemini "ikinci beyin" veya "iletişim ortağı" olarak adlandırmıştır - bu dijital uygulama modern teknoloji aracılığıyla benzer faydalar sağlamayı amaçlar.

Özellikler

Benzersiz zaman damgası tabanlı ID'lerle atomik notlar oluşturma
Bir bilgi grafiği oluşturmak için notları çift yönlü olarak bağlama
Kategorik organizasyon için notları etiketleme
İçerik, etiketler veya bağlantılara göre not arama
İnsan tarafından okunabilirlik ve düzenleme için markdown formatı kullanma
MCP aracılığıyla Claude ile entegrasyon için yapay zeka destekli bilgi yönetimi
Çift depolama mimarisi (aşağıya bakınız)
Basitleştirilmiş mimari için senkron işletim modeli

Örnekler

Bilgi oluşturma: Zettelkasten yöntemi hakkında küçük bir Zettelkasten bilgi ağı

Not Türleri

Zettelkasten MCP sunucusu farklı not türlerini destekler:

Tür	İşleyici	Açıklama
Geçici notlar	`fleeting`	Fikirleri yakalamak için hızlı, geçici notlar
Literatür notları	`literature`	Okuma materyalinden alınan notlar
Kalıcı notlar	`permanent`	İyi formüle edilmiş, uzun ömürlü notlar
Yapı notları	`structure`	Diğer notları organize eden indeks veya ana hat notları
Hub notları	`hub`	Zettelkasten'e ana konularda giriş noktaları

Bağlantı Türleri

Zettelkasten MCP sunucusu, notlar arasında anlamlı bağlantılar oluşturan kapsamlı bir semantik bağlama sistemi kullanır. Her bağlantı türü belirli bir ilişkiyi temsil eder ve zengin, çok boyutlu bir bilgi grafiği oluşturmaya olanak tanır.

Birincil Bağlantı Türü	Ters Bağlantı Türü	İlişki Açıklaması
`reference`	`reference`	Basit referans (simetrik ilişki)
`extends`	`extended_by`	Bir not diğerinden kavramlar üzerine inşa eder veya geliştirir
`refines`	`refined_by`	Bir not diğerini açıklığa kavuşturur veya iyileştirir
`contradicts`	`contradicted_by`	Bir not diğerine karşıt görüşler sunar
`questions`	`questioned_by`	Bir not diğeri hakkında sorular sorar
`supports`	`supported_by`	Bir not diğerine kanıt sağlar
`related`	`related`	Genel ilişki (simetrik ilişki)

İstemi (Prompting)

Maksimum etkinlik için, LLM'ye bilgi işleme, Zettelkasten notlarınızı keşfetme veya sentezleme görevleri verirken bir sistem istemi ("proje talimatları"), proje bilgisi ve uygun bir sohbet istemi kullanmanızı öneriz. Bu havuzun docs dizini başlamanız için gerekli dosyaları içerir:

Sistem istemi

Birini seçin:

Proje bilgisi

Son kullanıcılar için:

zettelkasten-methodology-technical.md
link-types-in-zettelkasten-mcp-server.md
(projenizle ilgili daha fazla bilgi)

Sohbet İstemleri

Proje bilgisi (geliştirici)

Geliştirici ve katkıda bulunanlar için:

NB: İsteğe bağlı olarak repomix gibi bir araçla kaynak kodu ekleyin.

Depolama Mimarisi

Bu sistem çift depolama yaklaşımı kullanır:

Markdown Dosyaları: Tüm notlar, meta veriler için YAML ön materyali ile birlikte insan tarafından okunabilir Markdown dosyaları olarak depolanır. Bu dosyalar doğru kaynaktır ve şunlar yapılabilir:
- Herhangi bir metin düzenleyicide doğrudan düzenlenme
- Versiyon kontrolü altına alınma (Git, vb.)
- Standart dosya yedekleme prosedürleri kullanılarak yedekleme
- Diğer metin dosyaları gibi paylaşılma veya aktarılma
SQLite Veritabanı: Şunları sağlayan bir indeksleme katmanı olarak işlev görür:
- Verimli sorgulama ve arama işlemlerine olanak tanır
- Claude'un bilgi grafiğini hızlı bir şekilde geçmesine olanak tanır
- Bağlantı geçişini hızlandırmak için ilişki bilgilerini korur
- Gerektiğinde Markdown dosyalarından otomatik olarak yeniden oluşturulur

Markdown dosyalarını sistem dışında doğrudan düzenlerseniz, veritabanını güncellemek için zk_rebuild_index aracını çalıştırmanız gerekir. Veritabanının kendisi istediğiniz zaman silinebilir - Markdown dosyalarınızdan yeniden oluşturulacaktır.

Kurulum

# Depoyu klonla
git clone https://github.com/entanglr/zettelkasten-mcp.git
cd zettelkasten-mcp

# uv ile sanal ortam oluştur
uv venv
source .venv/bin/activate  # Windows'ta: .venv\Scripts\activate

# Bağımlılıkları yükle
uv add "mcp[cli]"

# Geliştirici bağımlılıklarını yükle
uv sync --all-extras

Yapılandırma

Örneği kopyalayarak proje köküne bir .env dosyası oluşturun:

cp .env.example .env

Daha sonra dosyayı düzenleyerek bağlantı parametrelerinizi yapılandırın.

Kullanım

Sunucuyu Başlatma

python -m zettelkasten_mcp.main

Veya açık yapılandırma ile:

python -m zettelkasten_mcp.main --notes-dir ./data/notes --database-path ./data/db/zettelkasten.db

Claude Desktop'a Bağlanma

Claude Desktop'ınıza aşağıdaki yapılandırmayı ekleyin:

{
  "mcpServers": {
    "zettelkasten": {
      "command": "/absolute/path/to/zettelkasten-mcp/.venv/bin/python",
      "args": [
        "-m",
        "zettelkasten_mcp.main"
      ],
      "env": {
        "ZETTELKASTEN_NOTES_DIR": "/absolute/path/to/zettelkasten-mcp/data/notes",
        "ZETTELKASTEN_DATABASE_PATH": "/absolute/path/to/zettelkasten-mcp/data/db/zettelkasten.db",
        "ZETTELKASTEN_LOG_LEVEL": "INFO"
      }
    }
  }
}

Mevcut MCP Araçları

Tüm araçlara daha iyi organizasyon için zk_ öneki eklenmiştir:

Araç	Açıklama
`zk_create_note`	Başlık, içerik ve isteğe bağlı etiketlerle yeni bir not oluştur
`zk_get_note`	Belirli bir notu ID veya başlığa göre al
`zk_update_note`	Varolan bir notun içeriğini veya meta verilerini güncelle
`zk_delete_note`	Bir notu sil
`zk_create_link`	Notlar arasında bağlantı oluştur
`zk_remove_link`	Notlar arasında bağlantı kaldır
`zk_search_notes`	İçerik, etiketler veya bağlantılara göre notları ara
`zk_get_linked_notes`	Belirli bir nota bağlı notları bul
`zk_get_all_tags`	Sistemdeki tüm etiketleri listele
`zk_find_similar_notes`	Verilen nota benzer notları bul
`zk_find_central_notes`	En fazla bağlantıya sahip notları bul
`zk_find_orphaned_notes`	Hiçbir bağlantısı olmayan notları bul
`zk_list_notes_by_date`	Notları oluşturulma/güncelleme tarihine göre listele
`zk_rebuild_index`	Veritabanı indeksini Markdown dosyalarından yeniden oluştur

Proje Yapısı

zettelkasten-mcp/
├── src/
│   └── zettelkasten_mcp/
│       ├── models/       # Veri modelleri
│       ├── storage/      # Depolama katmanı
│       ├── services/     # İş mantığı
│       └── server/       # MCP sunucu uygulaması
├── data/
│   ├── notes/            # Not depolaması (Markdown dosyaları)
│   └── db/               # İndeksleme için veritabanı
├── tests/                # Test paketi
├── .env.example          # Ortam değişkeni şablonu
└── README.md

Testler

Zettelkasten MCP'nin modelden MCP sunucu uygulamasına kadar uygulamanın tüm katmanlarını kapsayan kapsamlı test paketi.

Testleri Nasıl Çalıştıracağınız

Proje kök dizininden şunu çalıştırın:

pytest'i doğrudan kullanma

python -m pytest -v tests/

UV kullanma

uv run pytest -v tests/

Kapsam raporu ile

uv run pytest --cov=zettelkasten_mcp --cov-report=term-missing tests/

Belirli bir test dosyasını çalıştırma

uv run pytest -v tests/test_models.py

Belirli bir test sınıfını çalıştırma

uv run pytest -v tests/test_models.py::TestNoteModel

Belirli bir test fonksiyonunu çalıştırma

uv run pytest -v tests/test_models.py::TestNoteModel::test_note_validation

Tests Dizin Yapısı

tests/
├── conftest.py - Tüm testler için ortak fixture'lar
├── test_integration.py - Tüm sistemin entegrasyon testleri
├── test_mcp_server.py - MCP sunucu araçlarının testleri
├── test_models.py - Veri modellerinin testleri
├── test_note_repository.py - Not repository'sinin testleri
├── test_search_service.py - Arama hizmetinin testleri
├── test_semantic_links.py - Semantik bağlammanın testleri
└── test_zettel_service.py - Zettel hizmetinin testleri

Önemli Uyarı

⚠️ KENDİ RİSKİNİZDE KULLANIN: Bu yazılım deneyseldir ve hiçbir garantisi olmaksızın olduğu gibi sağlanmaktadır. Veri bütünlüğünü sağlamak için çaba gösterilmiş olsa da, veri kaybı veya bozulmasına yol açabilecek hatalar içerebilir. Notlarınızı düzenli olarak yedekleyin ve önemli bilgilerle test ederken dikkatli olun.

Kredi Verilmesi Gereken Yerlere

Bu MCP sunucusu, Claude'un yardımıyla oluşturulmuştur. Claude, bu projenin atomik düşüncelerini tutarlı bir bilgi grafiğinde organize etmesine yardımcı oldu. İyi bir Zettelkasten sistemi gibi, Claude aksi takdirde izole kalabilecek fikirler arasındaki noktaları birleştirdi. Ancak Luhmann'ın kağıt tabanlı sisteminden farklı olarak, Claude etkili olmak için 90.000 index karta ihtiyaç duymadı.

Lisans

MIT Lisansı

entanglr/zettelkasten-mcp

Bu MCP sunucusu hakkında