ardupilot-mcp 0.1.0__tar.gz

ardupilot_mcp-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Logs / fixtures (büyük .bin/.tlog/.ulog dosyaları repoya girmesin — fixture'lar ayrı yönetilecek)
+*.tlog
+*.ulg
+# NOT: test fixture .bin dosyaları için tests/fixtures/ altında seçici allow-list kullanılacak (plan aşamasında)
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# Local Claude Code settings (machine-specific)
+.claude/settings.local.json
+
+# Demo output
+examples/*.bin
+
+# Downloaded real logs (third-party data; not ours to redistribute)
+_reallogs/

ardupilot_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-06-14
+
+First release: an offline, read-only MCP server that diagnoses ArduPilot DataFlash
+`.bin` flight logs with a deterministic check engine; the LLM explains the grounded
+findings.
+
+### Added
+- **Parser** (`pymavlink` DFReader) → pure `FlightLog` domain model; defensive against
+  truncated/corrupt logs; flight-relative timestamps robust to corrupt outliers.
+- **16 diagnostic checks** across two families:
+  - Flight dynamics: events/errors, EKF health, vibration, power (BAT/CURR), GPS,
+    compass, attitude tracking, motor balance, RC-link loss, timing.
+  - Configuration & setup: risky parameters, parameter audit (contradictory/disabled/
+    implausible values), calibration, configured-but-silent sensors, firmware pre-arm
+    messages.
+- **Vehicle awareness** (copter/heli/plane/rover) — checks gate to the vehicles they
+  apply to.
+- **Advisory tuning** — harmonic notch (gyro FFT), PID, autotune.
+- **Documentation grounding** — every finding links authoritative ArduPilot docs;
+  reports surface version-specific parameter definitions (`apm.pdef.xml`) for 4.x.
+- **Physical profile** (`vehicle_profile`) — frame, motor count, battery cells, hover
+  throttle → power margin and thrust-to-weight.
+- **9 read-only MCP tools**: `analyze_log`, `log_summary`, `vehicle_profile`,
+  `list_events`, `query_timeseries`, `get_params`, `load_param_file`, `recommend_tuning`,
+  `list_checks`.
+- **Parameter completeness** signals + `.param`/`.params` file ingestion.
+- `examples/analyze.py` CLI and an MCP stdio smoke test.
+- [`docs/SOURCES.md`](docs/SOURCES.md): every threshold/enum/fact audited against
+  authoritative sources.
+
+[Unreleased]: https://github.com/furkanisikay/ardupilot-mcp/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/furkanisikay/ardupilot-mcp/releases/tag/v0.1.0

ardupilot_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Furkan IŞIKAY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ardupilot_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: ardupilot-mcp
+Version: 0.1.0
+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 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](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*. 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`](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

ardupilot_mcp-0.1.0/README.en.md

@@ -0,0 +1,121 @@
+# 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](README.md) · 🇬🇧 **English**
+
+A deterministic-grounded **MCP (Model Context Protocol) server that diagnoses ArduPilot DataFlash (`.bin`) flight logs**. Point it at a `.bin` log and your LLM client (Claude Desktop, etc.) explains what happened in a flight — backed by a deterministic check engine, not vibes.
+
+> This project is built **Turkish-first**, primarily for the Turkish-speaking drone community — but it is fully usable in English. Contributions are very welcome: see [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) (the rules for humans and AI assistants). Every threshold is sourced in [docs/SOURCES.md](docs/SOURCES.md).
+
+## Why log diagnosis?
+
+Reading an ArduPilot `.bin` is an expert bottleneck: you filter `ERR` rows, compare `ATT.DesRoll` vs `ATT.Roll` to spot a mechanical failure, and eyeball vibration / EKF / battery clipping. This server runs those checks deterministically and lets the model narrate the result in plain language.
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+pip install ardupilot-mcp
+```
+
+Or from source (for development):
+
+```bash
+git clone https://github.com/furkanisikay/ardupilot-mcp
+cd ardupilot-mcp
+pip install -e ".[dev]"
+```
+
+## Use with Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ardupilot-mcp": {
+      "command": "ardupilot-mcp"
+    }
+  }
+}
+```
+
+If `ardupilot-mcp` isn't on your PATH, give the full path inside the env you installed into (e.g. `.venv/bin/ardupilot-mcp`, or on Windows `...\Scripts\ardupilot-mcp.exe`). Then ask Claude things like *"analyze the log at C:\\logs\\flight.bin — why did it crash?"*
+
+## Tools (all read-only)
+
+| Tool | What it does |
+|------|--------------|
+| `analyze_log(path)` | Run the full check suite → severity-ranked findings + summary. Each finding carries **official ArduPilot doc links**, and the report includes version-specific parameter docs for 4.x firmware. The headline. |
+| `log_summary(path)` | Vehicle, firmware, duration, message counts, flight modes, max altitude, integrity. |
+| `vehicle_profile(path)` | **Physical/architecture profile**: frame & type, motor count, battery cells/capacity, hover throttle, **power margin** and thrust-to-weight. For physically-grounded reasoning. |
+| `list_events(path, kinds?, start_s?, end_s?)` | Decoded `ERR`/`MODE`/`EV`/`MSG` timeline. |
+| `query_timeseries(path, message_type, fields, start_s?, end_s?, max_points?)` | Decimated numeric series for drilling into a finding. |
+| `get_params(path, name_glob?)` | Parameter values from the log's PARM dump (e.g. `INS_HNTCH_*`), plus the total count, a version-specific metadata link to interpret them, and a note if the snapshot looks incomplete. |
+| `load_param_file(path, name_glob?)` | Read a user-exported `.param`/`.params` file — the authoritative complete config, for when the log's snapshot is truncated or to compare flown-vs-current. |
+| `recommend_tuning(path, area?)` | Advisory tuning (harmonic notch from gyro FFT, PID, autotune). **Recommendation only — never applied.** |
+| `list_checks()` | The registered diagnostic checks (extensible catalogue). |
+
+## How it works
+
+```
+.bin ──▶ parser.py (pymavlink DFReader) ──▶ FlightLog (pure domain model)
+                                               │
+                                               ▼
+                       checks/ registry ──▶ Check plugins (one per concern)
+                                               │
+                                               ▼
+                    orchestrator.diagnose() ──▶ DiagnosisReport (structured)
+                                               │
+                                               ▼
+                       server.py (FastMCP, stdio) ──▶ LLM narrates the findings
+```
+
+- **Core principle:** the deterministic engine is the single source of truth; the LLM only *explains* and cites — it never decides. This directly answers the objection that "LLMs are less reliable than physics-based log analyzers."
+- **`FlightLog`** is a pure, `pymavlink`-free domain model, so checks and their tests run against synthetic logs without a real `.bin`.
+- **Checks** are independent, registry-registered plugins (`@register_check`). Adding one is a single new module. The orchestrator skips a check cleanly when its data wasn't logged, when it doesn't apply to the vehicle kind (e.g. motor-balance on a heli/plane), and isolates any check that raises.
+- The check catalogue has two families. **Flight dynamics:** events/errors, EKF health, vibration, power (BAT/CURR), GPS (fix/sats/HDOP, scoped to the armed window), compass, attitude tracking, motor balance, RC-link loss, timing. **Configuration & setup** (because many crashes are setup mistakes, not flight events): risky parameters (disabled arming checks/failsafes), a **parameter audit** of contradictory/disabled/implausible values, calibration (large/zero compass offsets), configured-but-silent sensors (wiring/connection faults), and the firmware's own pre-arm/startup warnings. Plus advisory tuning.
+- It is **vehicle-aware** (copter / heli / plane / rover): multirotor-specific checks don't run on a heli's swashplate servos or a plane's control surfaces. Validated against 40 real forum logs across Copter 3.2–4.6, Plane, QuadPlane, Heli and Rover.
+- Findings are **documentation-grounded**: each links the authoritative ArduPilot doc page, and reports surface the firmware-version-specific parameter definitions (`apm.pdef.xml`) for 4.x. The server stays offline/deterministic and hands these *pointers* to the LLM, which has its own web access to read and cite them.
+- The **physical profile** (`vehicle_profile`) turns the log into airframe facts — frame, motor count, battery cells, and especially the **power margin** (hover throttle → thrust-to-weight). On a real 12 kg quad that crashed maxing its motors, it reports "underpowered, hovers at 69 %, only 31 % headroom" — the actual cause.
+
+## Safety
+
+This release is **offline and read-only**. No MAVLink connection, no arming, no parameter writes, no actuation. Tuning output is advice only. Live-vehicle features (with a proper safety gateway: SITL-first, human-in-the-loop, kill switch) are explicitly out of scope and deferred.
+
+## Sources & assumptions
+
+Every numeric threshold, enum, default and behavioural claim in the code is audited against authoritative sources (ArduPilot wiki/firmware, MAVLink, the MCP spec) in [`docs/SOURCES.md`](docs/SOURCES.md) — each marked *confirmed* (with a citation), *heuristic* (our conservative choice), or *design choice* (our severity cut-off). That audit found and fixed eight genuine errors (e.g. a wrong heli FRAME_CLASS set, mis-numbered event ids, an EKF field that isn't an innovation test ratio).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check ardupilot_mcp tests
+mypy ardupilot_mcp
+pytest
+```
+
+Checks are tested against synthetic in-memory logs (`tests/helpers.py`) and a synthetic DataFlash writer (`tests/synth_bin.py`) gives the parser a real, hermetic `.bin` to round-trip — no large binary fixtures committed.
+
+## Known limitations
+
+- **Toilet-bowl / compass-heading faults** aren't detected yet — they need circular-position-drift analysis (planned), not just field-magnitude stability.
+- A **genuinely corrupt log** (e.g. a bit-flipped message format) fails to parse with a clear error rather than partial recovery.
+- Large logs (3–4 MB / ~100k records) take ~12–15 s to parse; the MCP server caches a parsed log by path+mtime, so only the first tool call pays that cost.
+
+## Roadmap
+
+1. **This release:** ArduPilot offline `.bin` diagnosis + tuning advice + extensible check framework.
+2. PX4 / ULog support (separate parser + rules; shared diagnosis abstraction).
+3. Live MAVLink connection (SITL-first) with a full safety gateway.
+4. Community check-sharing; confirmation-gated tuning *apply*.
+
+## License
+
+MIT

ardupilot_mcp-0.1.0/README.md

@@ -0,0 +1,121 @@
+# 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 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](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*. 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`](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

ardupilot_mcp-0.1.0/ardupilot_mcp/__init__.py

@@ -0,0 +1,13 @@
+"""Deterministic-grounded MCP server for diagnosing ArduPilot DataFlash logs."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+# Importing the checks package registers every check via decorator side effects.
+from . import checks as checks  # noqa: E402,F401
+from .flight_log import FlightLog, LogMeta
+from .orchestrator import diagnose
+from .parser import parse_bin
+
+__all__ = ["FlightLog", "LogMeta", "diagnose", "parse_bin", "checks", "__version__"]

ardupilot_mcp-0.1.0/ardupilot_mcp/__main__.py

@@ -0,0 +1,17 @@
+"""Entry point: ``python -m ardupilot_mcp`` (or the ``ardupilot-mcp`` script).
+
+Runs the MCP server over stdio — the transport Claude Desktop and other local
+MCP clients use.
+"""
+
+from __future__ import annotations
+
+from .server import mcp
+
+
+def main() -> None:
+    mcp.run()  # stdio transport by default
+
+
+if __name__ == "__main__":
+    main()