Metadata-Version: 2.4
Name: ardupilot-mcp
Version: 0.1.1
Summary: ArduPilot uçuş loglarını teşhis eden deterministik MCP sunucusu · Deterministic MCP server that diagnoses ArduPilot DataFlash flight logs
Project-URL: Homepage, https://github.com/furkanisikay/ardupilot-mcp
Project-URL: Repository, https://github.com/furkanisikay/ardupilot-mcp
Project-URL: Issues, https://github.com/furkanisikay/ardupilot-mcp/issues
Project-URL: Changelog, https://github.com/furkanisikay/ardupilot-mcp/blob/main/CHANGELOG.md
Author: Furkan IŞIKAY
License: MIT
License-File: LICENSE
Keywords: ardupilot,dataflash,diagnostics,drone,flight-log,mavlink,mcp,model-context-protocol,uav
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: mcp>=1.27
Requires-Dist: numpy>=2.0
Requires-Dist: pymavlink>=2.4.49
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy==2.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff==0.15.17; extra == 'dev'
Description-Content-Type: text/markdown

# ardupilot-mcp

[![CI](https://github.com/furkanisikay/ardupilot-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/furkanisikay/ardupilot-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/ardupilot-mcp.svg)](https://pypi.org/project/ardupilot-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/ardupilot-mcp.svg)](https://pypi.org/project/ardupilot-mcp/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

🇹🇷 Türkçe · [🇬🇧 English](README.en.md)

**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 dille anlatır — tahminle değil, deterministik bir kontrol motoruyla.

Katkılar için: [CONTRIBUTING.md](CONTRIBUTING.md) ve [AGENTS.md](AGENTS.md) (insanlar ve yapay zekâ asistanları için kurallar). Her eşik değeri [docs/SOURCES.md](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.

```bash
pip install ardupilot-mcp
```

Kaynaktan (geliştirme için):

```bash
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:

```json
{
  "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*.
- **`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`](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

```bash
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
