✨ Lucidity MCP 🔍

Lucidity, Model Context Protocol (MCP) sunucusu olarak, yapay zeka tarafından oluşturulan kodun kalitesini akıllı, prompt tabanlı analiz yoluyla geliştirmek için tasarlanmıştır. AI kodlama asistanlarına yapılandırılmış rehberlik sağlayarak, Lucidity yaygın kalite sorunlarını belirlemek ve çözmek, böylece daha temiz, bakımı kolay ve daha sağlam kod elde etmek yardımcı olur.

Commit etmeden önce, Lucidity'ye değişiklikleri analiz etmesini söyleyin, kendinizi bir kâbus cehennemine "vibe coding" yaparak sürüklemeyin! 😱 💥 🚫

💫 Özellikler

• 🔮 Kapsamlı Sorun Algılaması - Karmaşıklıktan güvenlik açıklarına kadar 10 kritik kalite boyutunu kapsar
• 🔄 Bağlamsal Analiz - Değişiklikleri orijinal kodla karşılaştırarak istenmeyen değişiklikleri tanımlar
• 🌐 Dil Agnostik - AI asistanının anladığı herhangi bir programlama diliyle çalışır
• 🎯 Odaklanmış Analiz - Proje ihtiyaçlarına göre belirli sorun türlerini hedefleme seçeneği
• 📝 Yapılandırılmış Çıktılar - AI'ı net önerilerle eyleme geçirilebilir geri bildirim sağlamaya kılavuzlar
• 🤖 MCP Entegrasyonu - Claude ve diğer MCP uyumlu AI asistanlarıyla sorunsuz entegrasyon
• 🪶 Hafif İmplementasyon - Minimal bağımlılığa sahip basit sunucu tasarımı
• 🧩 Genişletilebilir Framework - Yeni sorun türleri ekleme veya analiz kriterlerini ayarlama kolaylığı
• 🔀 Esnek Transport - Terminal tabanlı etkileşim için stdio ve ağ tabanlı iletişim için SSE destekler
• 🔄 Git Bilgisi - Git diff'ten doğrudan değişiklikleri analiz eder, ön commit incelemeler için ideal

🚀 Kurulum

# Repository'yi clone edin
git clone https://github.com/hyperbliss/lucidity-mcp.git
cd lucidity-mcp

# UV ile sanal ortam kurun
uv venv .venv
source .venv/bin/activate  # Windows'ta: .venv\Scripts\activate

# UV ile bağımlılıkları yükleyin
uv sync

📋 Ön Koşullar

• Python 3.13 veya daha yüksek
• Git (kod değişikliklerini analiz etmek için)
• UV paket yöneticisi (bağımlılık yönetimi için önerilir)

🔮 Hızlı Başlangıç

Lucidity sunucusunu çalıştırın

# Stdio transport ile başlatın (terminal kullanımı için)
lucidity-mcp

# SSE transport ile başlatın (ağ kullanımı için)
lucidity-mcp --transport sse --host 127.0.0.1 --port 6969

# Debug logging ile çalıştırın
lucidity-mcp --debug

# Dosya logging ile çalıştırın
lucidity-mcp --log-file lucidity.log

AI Asistanlarla Kullanım

1. Lucidity'yi SSE modunda başlatın:

   lucidity-mcp --transport sse
   

2. AI asistanınızı MCP protokol URI'sı kullanarak bağlayın:

   sse://localhost:6969/sse
   

3. AI şimdi kod kalitesi geri bildirimi almak için analyze_changes tool'unu çağırabilir!

🧠 Analiz Boyutları

Lucidity, kodu 10 kritik kalite boyutuna göre analiz eder:

1. Gereksiz Karmaşıklık - Aşırı karmaşık algoritmaları, aşırı soyutlamaları ve kafa karıştırıcı mantığı tanımlar
2. Kötü Soyutlamalar - Sızıntılı veya uygunsuz soyutlamaları ve belirsiz endişe ayrımlarını tespit eder
3. İstenmeyen Kod Silme - Kritik işlevselliğin veya doğrulamanın yanlışlıkla kaldırılmasını yakalar
4. Halüsinasyon Bileşenleri - Var olmayan fonksiyonlara, sınıflara veya API'lara yapılan referansları bulur
5. Stil Tutarsızlıkları - Proje kodlama standartlarından ve kurallarından sapmaları fark eder
6. Güvenlik Açıkları - Kod değişikliklerinde potansiyel güvenlik sorunlarını tanımlar
7. Performans Sorunları - Performansı etkileyebilecek verimsiz algoritmaları veya işlemleri tespit eder
8. Kod Tekrarı - Yeniden düzenlenmesi gereken tekrarlanan mantık veya işlevselliği bulur
9. Eksik Hata İşleme - Eksik veya yetersiz exception handling'i fark eder
10. Test Kapsamı Boşlukları - Kritik işlevsellik için eksik testleri tanımlar

📊 Örnek AI Asistanı Sorguları

Lucidity'ye bağlı bir AI asistanı ile bu sorguları deneyin:

• "Son git değişikliklerimin kod kalitesini analiz et"
• "JavaScript değişikliklerinde güvenlik açıklarını kontrol et"
• "Python kodum en iyi uygulamaları takip ettiğinden emin ol"
• "Son kod değişikliklerimde performans sorunlarını belirle"
• "Son refaktoringemde istenmeyen yan etkiler var mı?"
• "Kodumda soyutlamaları geliştirmeme yardımcı ol"
• "Yanlışlıkla önemli doğrulamayı kaldırıp kaldırmadığımı kontrol et"
• "Son commit'imde halüsinasyon API çağrılarını bul"
• "Hata işlemem tam ve sağlam mı?"
• "Yeni özelliğimde test kapsamı boşlukları var mı?"

🛠️ Mevcut MCP Tool'ları

Tools

• analyze_changes - MCP aracılığıyla analiz için git değişikliklerini hazırlar
  • Parametreler:
    • workspace_root: Workspace/git repository'nin kök dizini
    • path: Analiz edilecek isteğe bağlı belirli dosya yolu

💻 Geliştirme

Lucidity, bağımlılık yönetimi ve geliştirme iş akışları için UV kullanır. UV, hızlı ve güvenilir bir Python paket yöneticisi ve resolver'ıdır.

# Bağımlılıkları güncelleyin
uv sync

# Testleri çalıştırın
pytest

# Linting çalıştırın
ruff check .

# Tür kontrolü çalıştırın
mypy .

🔧 Logging Davranışı

Lucidity, transport'a bağlı olarak logging'i farklı şekilde işler:

• SSE transport: Tam konsol logging etkinleştirilir
• Stdio transport with --log-file: Tüm loglar dosyaya gider, konsol devre dışı bırakılır
• Stdio transport without --log-file: Sadece uyarılar ve hatalar stderr'e gider, bilgi logları devre dışı bırakılır

Bu, stdio iletişiminin stdout'ta log görünmesi nedeniyle bozulmamasını sağlar.

🎛️ Komut Satırı Seçenekleri

usage: lucidity-mcp [-h] [--debug] [--host HOST] [--port PORT] [--transport {stdio,sse}]
                [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--verbose]
                [--log-file LOG_FILE]

options:
  -h, --help            show this help message and exit
  --debug               Debug logging'i etkinleştir
  --host HOST           Sunucunun bağlanacağı host (tüm arayüzler için 0.0.0.0 kullanın)
  --port PORT           Ağ bağlantıları için dinlenecek port
  --transport {stdio,sse}
                        Kullanılacak transport türü (terminal için stdio, ağ için sse)
  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Logging seviyesini ayarla
  --verbose             HTTP istekleri için verbose logging'i etkinleştir
  --log-file LOG_FILE   Log dosyasının yolu (stdio transport için gerekli)

🤝 Katkıda Bulunma

Katkılar hoşlanır! Lütfen bir Pull Request göndermekten çekinmeyin.

1. Repository'yi fork edin
2. Özellik dalınızı oluşturun (git checkout -b feature/amazing-feature)
3. Geliştirme ortamınızı UV ile kurun
4. Değişiklikleri yapın
5. Testleri ve linting'i çalıştırın
6. Değişiklikleri commit edin (git commit -m 'Add some amazing feature')
7. Dala push edin (git push origin feature/amazing-feature)
8. Bir Pull Request açın

📝 Lisans

Bu proje Apache License 2.0 altında lisanslanmıştır - detaylar için LICENSE dosyasına bakın.

---