ardupilot-mcp 0.1.0

ArduPilot uçuş loglarını teşhis eden deterministik MCP sunucusu · Deterministic MCP server that diagnoses ArduPilot DataFlash flight logs

ardupilot-mcp

🇹🇷 Türkçe · 🇬🇧 English

ArduPilot DataFlash (.bin) uçuş loglarını teşhis eden, deterministik-temelli bir MCP (Model Context Protocol) sunucusu. Bir .bin logunu gösterirsin; Claude Desktop gibi bir yapay zekâ istemcisi uçuşta ne olduğunu düz Türkçe anlatır — tahminle değil, deterministik bir kontrol motoruyla.

Bu araç çoğunlukla Türk ve Türkçe konuşan drone topluluğu için, Türkçe-öncelikli olarak geliştiriliyor. Katkı vermek isteyenlere bayılıyoruz — CONTRIBUTING.md ve AGENTS.md (insanlar ve yapay zekâ asistanları için kurallar). Her eşik değeri docs/SOURCES.md'de kaynağıyla belgeli.

Neden log teşhisi?

Bir ArduPilot .bin logunu okumak uzmanlık ister: ERR satırlarını filtreler, mekanik arıza için ATT.DesRoll ile ATT.Roll'u karşılaştırır, titreşim / EKF / batarya clipping'ine göz gezdirirsin. Drone'un düştüğünde "neden?" sorusunun cevabı bu logun içindedir ama okumak doktorun röntgen okuması gibidir. Bu sunucu o kontrolleri deterministik olarak çalıştırır ve yapay zekânın sonucu sade dille anlatmasını sağlar.

Kurulum

Python 3.11+ gerekir.

pip install ardupilot-mcp

Kaynaktan (geliştirme için):

git clone https://github.com/furkanisikay/ardupilot-mcp
cd ardupilot-mcp
pip install -e ".[dev]"

Claude Desktop ile kullanım

claude_desktop_config.json dosyana ekle:

{
  "mcpServers": {
    "ardupilot-mcp": {
      "command": "ardupilot-mcp"
    }
  }
}

ardupilot-mcp komutu PATH'te bulunamazsa, kurduğun ortamdaki tam yolu ver (ör. .venv/bin/ardupilot-mcp veya Windows'ta ...\Scripts\ardupilot-mcp.exe). Sonra Claude'a şöyle sor: "C:\loglar\ucus.bin logunu analiz et — neden düştü?"

Araçlar (hepsi salt-okunur)

Araç	Ne yapar
analyze_log(path)	Tüm kontrol paketini çalıştırır → önem-sıralı bulgular + özet. Her bulgu resmi ArduPilot doküman linkleri taşır; rapor 4.x firmware için sürüm-özel parametre dokümanlarını da içerir. Manşet araç.
log_summary(path)	Araç, firmware, süre, mesaj sayıları, uçuş modları, max irtifa, bütünlük.
vehicle_profile(path)	Fiziksel / mimari profil: frame & tip, motor sayısı, batarya hücresi/kapasitesi, hover gazı, güç marjı ve itki/ağırlık. Fiziğe-dayalı muhakeme için.
list_events(path, kinds?, start_s?, end_s?)	Çözümlenmiş ERR/MODE/EV/MSG zaman çizelgesi.
query_timeseries(path, message_type, fields, start_s?, end_s?, max_points?)	Bir bulguya derinlemesine bakmak için seyreltilmiş sayısal seri.
get_params(path, name_glob?)	Logun PARM dökümünden parametre değerleri (ör. INS_HNTCH_*), toplam sayı, yorumlamak için sürüm-özel metadata linki, ve döküm eksikse bir uyarı.
load_param_file(path, name_glob?)	Kullanıcının dışa aktardığı .param/.params dosyasını okur — log dökümü kesikse veya "uçtuğu config vs şimdiki"yi karşılaştırmak için tam, otoriter config.
recommend_tuning(path, area?)	Tavsiye niteliğinde tuning (gyro FFT'sinden harmonik notch, PID, autotune). Sadece öneri — asla uygulanmaz.
list_checks()	Kayıtlı teşhis kontrolleri (genişletilebilir katalog).

Nasıl çalışır

.bin ──▶ parser.py (pymavlink DFReader) ──▶ FlightLog (saf domain modeli)
                                               │
                                               ▼
                       checks/ registry ──▶ Check eklentileri (her biri bir konu)
                                               │
                                               ▼
                    orchestrator.diagnose() ──▶ DiagnosisReport (yapısal)
                                               │
                                               ▼
                       server.py (FastMCP, stdio) ──▶ Yapay zekâ bulguları anlatır

• Anahtar ilke: deterministik motor tek doğruluk kaynağı; yapay zekâ sadece açıklar ve kaynak gösterir, karar vermez. Bu, "yapay zekâ fizik-temelli analizörlerden güvenilmez" eleştirisine doğrudan cevaptır.
• FlightLog saf, pymavlink-bağımsız bir domain modelidir; bu yüzden kontroller ve testler gerçek .bin olmadan sentetik loglarla çalışır.
• Kontroller bağımsız, registry'e kayıtlı eklentilerdir (@register_check). Yeni bir tane eklemek = tek bir yeni modül. Orchestrator, verisi loglanmamış kontrolü zarifçe atlar, araç tipine uymayanı (ör. heli/uçakta motor-dengesi) çalıştırmaz ve hata fırlatan kontrolü izole eder.
• Katalog iki aile: Uçuş dinamiği — olaylar/hatalar, EKF sağlığı, titreşim, güç (BAT/CURR), GPS (fix/uydu/HDOP, armed pencerede), pusula, attitude takibi, motor dengesi, RC sinyal kaybı, zamanlama. Konfigürasyon & kurulum (çünkü çoğu kaza uçuş anında değil kurulum hatasıdır): riskli parametreler (kapalı arming/failsafe), çelişkili/kapalı/mantıksız değerlerin parametre denetimi, kalibrasyon (büyük/sıfır pusula offset'i), yapılandırılmış-ama-sessiz sensörler (kablo/bağlantı arızası), ve firmware'in kendi pre-arm/açılış uyarıları. Artı tavsiye niteliğinde tuning.
• Araç-farkında (copter / heli / uçak / rover): çoklu-rotora özel kontroller bir helinin swashplate servolarında ya da bir uçağın kontrol yüzeylerinde çalışmaz. Copter 3.2–4.6, Plane, QuadPlane, Heli ve Rover'ı kapsayan 40 gerçek forum loguyla doğrulandı.
• Bulgular doküman-temelli: her biri ilgili resmi ArduPilot sayfasına link verir; raporlar 4.x için sürüm-özel parametre tanımlarını (apm.pdef.xml) yüzeye çıkarır. Sunucu offline/deterministik kalır; bu işaretçileri web erişimi olan yapay zekâya verir, o okur ve alıntılar.
• Fiziksel profil (vehicle_profile) logu airframe gerçeklerine dönüştürür — frame, motor sayısı, batarya hücresi ve özellikle güç marjı (hover gazı → itki/ağırlık). Motorlarını sonuna kadar açıp düşen gerçek bir 12 kg'lık quad'da "underpowered, %69 gazda asılı, sadece %31 pay" diyor — kazanın asıl sebebi.

Güvenlik

Bu sürüm offline ve salt-okunur. MAVLink bağlantısı yok, arming yok, parametre yazma yok, aktüasyon yok. Tuning çıktısı sadece tavsiyedir. Canlı-araç özellikleri (düzgün bir güvenlik gateway'i ile: SITL-önce, insan-onayı, kill switch) bilinçli olarak kapsam dışı ve ertelenmiş.

Kaynaklar & varsayımlar

Koddaki her sayısal eşik, enum, varsayılan ve davranışsal iddia otoriter kaynaklara karşı (ArduPilot wiki/firmware, MAVLink, MCP spec) docs/SOURCES.md'de denetlenmiştir — her biri onaylandı (atıflı), heuristik (bizim ihtiyatlı seçimimiz, en yakın rehber atıflı) veya tasarım kararı (bizim severity sınırımız) olarak işaretli. Bu denetim 8 gerçek hatayı bulup düzeltti (ör. yanlış bir heli FRAME_CLASS kümesi, yanlış-numaralı event id'leri, innovation test-ratio'su olmayan bir EKF alanı).

Geliştirme

pip install -e ".[dev]"
ruff check ardupilot_mcp tests        # lint
mypy ardupilot_mcp                    # tip kontrolü
pytest                                # testler

Kontroller sentetik in-memory loglarla (tests/helpers.py) test edilir; sentetik bir DataFlash yazıcısı (tests/synth_bin.py) parser'a round-trip için gerçek, hermetik bir .bin verir — repoya büyük ikili fixture girmez.

Bilinen sınırlamalar

• Toilet-bowl / pusula-heading arızaları henüz tespit edilmiyor — sadece alan-büyüklüğü stabilitesi değil, dairesel-pozisyon-drift analizi gerektiriyor (planlı).
• Gerçekten bozuk bir log (ör. bit-flip'li mesaj formatı) kısmi-kurtarma yerine net bir hatayla başarısız olur.
• Büyük loglar (3–4 MB / ~100k kayıt) ~12–15 sn'de parse olur; MCP sunucusu parse'ı path+mtime ile cache'ler, yani bu maliyeti sadece ilk araç çağrısı öder.

Yol haritası

1. Bu sürüm: ArduPilot offline .bin teşhisi + tuning tavsiyesi + genişletilebilir kontrol çerçevesi.
2. PX4 / ULog desteği (ayrı parser + kurallar; ortak teşhis soyutlaması).
3. Canlı MAVLink bağlantısı (SITL-önce) + tam güvenlik gateway'i.
4. Topluluk kontrol-paylaşımı; onay-kapılı tuning uygulaması.

Lisans

MIT