kshana-mcp: zeptejte se svého asistenta s umělou inteligencí a odpoví engine

kshana-mcp je server Model Context Protocol (MCP) pro Kshana, open-source simulátor odolnosti PNT (určování polohy, navigace a času). Umožňuje asistentovi s umělou inteligencí (AI) spustit skutečný engine a přečíst si jeho výstup ve formátu JSON (JavaScript Object Notation), místo aby matematiku odhadoval. Komunikuje přes stdio (standardní vstup a výstup) s libovolným klientem kompatibilním s MCP, včetně Cursoru a JetBrains AI Assistant / Junie.

Matematika, pro kterou je Kshana ověřena, je přesně tam, kde jazykový model odhaduje špatně: šíření oběžné dráhy podle SGP4 (Simplified General Perturbations 4), referenční soustavy IAU (Mezinárodní astronomická unie), Allanovy odchylky, dostupnost GNSS (globální družicový navigační systém) a faktor DOP (zhoršení přesnosti), ochranné úrovně ARAIM (advanced receiver autonomous integrity monitoring), fúze GNSS a INS (inerciální navigační systém) a modely kvantových senzorů. Položíte otázku; asistent spustí skutečný scénář a získá ukazatele kvality s jejich původem a s označením VALIDATED nebo MODELLED.

Nástroje#

Každý nástroj je tenký, věrný obal veřejné funkce knihovny kshana — žádná nová simulační logika zde není, takže agent spouští přesně ten ověřený engine.

Nástroje GNSS IQ: soubory na vstupu, kompaktní JSON na výstupu#

Záznamy IQ dosahují gigabajtů, proto nástroje iq_* nikdy nepředávají vzorky přes protokol. Řídí se jednou smlouvou:

• Pracovní adresář. Server čte a zapisuje soubory IQ pouze uvnitř složky pojmenované v KSHANA_MCP_IQ_DIR. Každý argument s cestou je vůči ní relativní (absolutní cesta se musí vyhodnotit uvnitř ní); vstupy se před kontrolou převádějí přes symbolické odkazy, složka výstupu už musí uvnitř existovat a existující výstup se nahradí pouze s overwrite: true. Pokud není nastaven, nástroje pro soubory IQ jsou vypnuté a uvedou, jak je zapnout; všechny ostatní nástroje to neovlivní.
• Rozpočet vzorků. Jedno volání vygeneruje nebo zpracuje nejvýše KSHANA_MCP_IQ_MAX_SAMPLES komplexních vzorků (výchozí 50 000 000). V bajtech to je 400 MB jako cf32_le (8 bajtů na komplexní vzorek), 200 MB jako ci16_le (4 bajty) a 100 MB jako ci8 (2 bajty); scéna se zapisuje jako cf32_le, pokud format neurčí jinak. Kontrola proběhne před jakoukoli prací a odmítnutí uvede délku nebo max_seconds, která se vejde.
• Stručné odpovědi. Každý nástroj odpovídá jedním shrnutím ve formátu JSON: píky akvizice, C/N0, stav zachycení a každý zapsaný soubor s cestou a velikostí v bajtech. Tabulky po epochách jdou do souborů json_out / csv_out, které pojmenujete.
• Neznámé argumenty se odmítají, nikoli ignorují, takže překlep v názvu volby je chyba.

Každý nástroj běží stejnou cestou kódu jako kshana iq v příkazové řádce, uvnitř procesu. Vrstva je čistě softwarová: zapisuje soubory pro softwarové přijímače a neřídí žádný rádiový hardware. Vrstva IQ nepřidává syntézu interference ani spoofera a nic se nikdy nevysílá. (Samostatný druh scénáře spectrum umí zapsat do souboru analytické snímky IQ rušičky.)

{
  "mcpServers": {
    "kshana": {
      "command": "/Users/you/.cargo/bin/kshana-mcp",
      "env": { "KSHANA_MCP_IQ_DIR": "/Users/you/iq" }
    }
  }
}

U obrazu Dockeru připojte složku a nasměrujte na ni proměnnou: docker run --rm -i -v "$PWD/iq:/iq" -e KSHANA_MCP_IQ_DIR=/iq ghcr.io/ashfordeou/kshana-mcp.

Dostupný je každý druh#

run_scenario rozhoduje podle kind scénáře, takže jím běží každý druh, který jmenuje list_scenario_kinds. To zahrnuje i novější rodiny, každou s přibalenými příklady, které si agent může vyžádat:

list_example_scenarios s kind jmenuje každý přibalený příklad daného druhu. Animace, zprávy a interoperabilní exporty nejsou druhy: jsou to pohledy na běh a animate_scenario, report_scenario a export_interop je vrátí pro libovolný scénář, na který se vztahují.

Neposkytuje se: sady studií (kshana --study <suite.toml>), protože sada jmenuje sourozenecké soubory scénářů na disku a nástroje scénářů žádný soubor nečtou. Spusťte každého člena pomocí run_scenario. (Nástroje IQ soubory čtou i zapisují, ale pouze uvnitř svého pracovního adresáře.)

Instalace serveru MCP#

Pouze poradní charakter, nikoli typově schválené navigační zařízení: za navigaci zůstává odpovědný provozovatel. Server běží na vašem počítači; Ashforde OÜ se nic neodesílá.

Pasáž, která jmenuje klienty umělé inteligence třetích stran, je zde vynechána; najdete ji v mcp/kshana-mcp/README.md na GitHubu.

Z checkoutu nebo gitu (vývoj):

cd mcp/kshana-mcp && cargo install --path .
cargo install --git https://github.com/AshfordeOU/kshana kshana-mcp

Režim HTTP (vlastní hosting)#

kshana-mcp --http 127.0.0.1:8080 poskytuje stejné nástroje přes streamable HTTP na /mcp. Naslouchá pouze na loopbacku; adresa mimo loopback vyžaduje --allow-remote a bearer token v KSHANA_MCP_HTTP_TOKEN; nástroje pro soubory IQ jsou vypnuté; velikost požadavku, čas i souběžnost jsou omezeny; neodesílá se žádná hlavička CORS. Kshana žádný koncový bod neprovozuje: hostujete si jej sami. Viz docs/deploy/mcp-http.md.

cargo install umístí kshana-mcp do vaší PATH (typicky ~/.cargo/bin/kshana-mcp). Server komunikuje JSON-RPC (JSON remote procedure call) přes stdio; logy jdou na stderr. Sestavení ze zdrojů vyžaduje toolchain Rustu ≥ 1,88 (vyžaduje jej opravené SDK rmcp 2.x, stejně jako knihovna kshana); obraz Dockeru nepotřebuje nic.

Registrace u klienta#

Prakticky každý klient MCP používá stejný konfigurační blok mcpServers — zaregistrujte binární soubor kshana-mcp absolutní cestou:

{
  "mcpServers": {
    "kshana": {
      "command": "/Users/you/.cargo/bin/kshana-mcp",
      "args": [],
      "env": {}
    }
  }
}

Nebo s obrazem Dockeru místo místního binárního souboru (PATH není potřeba):

{
  "mcpServers": {
    "kshana": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/ashfordeou/kshana-mcp"]
    }
  }
}

Kde tento blok žije, závisí na klientovi:

• Cursor — ~/.cursor/mcp.json (globálně) nebo .cursor/mcp.json (pro projekt).
• JetBrains AI Assistant / Junie — Settings → Tools → AI Assistant → Model Context Protocol → Add → As JSON, vložte blok a poté plně restartujte IDE (integrované vývojové prostředí).
• Desktopoví asistenti — většina používá soubor …_config.json se stejným tvarem mcpServers; umístění souboru zjistíte v dokumentaci svého klienta.
• Agenti v příkazové řádce — mnozí přijímají stejný JSON přes mechanismus mcp add / mcp.json.

K binárnímu souboru vždy použijte absolutní cestu. Při řešení potíží nastavte RUST_LOG=debug v env (diagnostika jde na stderr; stdout je vyhrazen pro protokol JSON-RPC).

Vyzkoušejte#

Po registraci se svého asistenta zeptejte například:

• „Vypiš druhy scénářů Kshana.“ → list_scenario_kinds
• „Ukaž mi příklad spektra v Kshana a spusť ho.“ → list_example_scenarios, get_example_scenario, run_scenario
• „Spusť scénář holdoveru hodin v Kshana s prahem 20 ns a 2hodinovým výpadkem GNSS; jaký je holdover kvantový oproti klasickému?“ → run_scenario
• „Exportuj tuto konstelaci GPS (Global Positioning System) jako SP3.“ → export_sp3
• „Dej mi tabulku realtime-frame-eop jako CSV.“ → export_table_csv
• „Zobraz ten přelet Iridia na globu Cesium.“ → list_export_formats, export_interop
• „Animuj kampaň rušení.“ → animate_scenario
• „Dej mi zprávu o tom běhu i se záznamem reprodukovatelnosti.“ → report_scenario
• „Vytvoř jednosekundovou scénu GPS L1 s PRN 3 a 17, pak ji zachyť a sleduj.“ → iq_signals, iq_scene, iq_acquire, iq_track

Poznámka k návrhu — proč samostatný crate#

Server je samostatný crate vyňatý z workspace s vlastním Cargo.lock, takže oficiální Rust MCP SDK (sada pro vývoj softwaru) rmcp a jeho asynchronní runtime nikdy nevstoupí do grafu závislostí publikovaného crate kshana: uživatel knihovny nebo Pythonu nekompiluje server, který nespouští. (Původně byl oddělen proto, že rmcp je edice 2024 a vyžaduje rustc ≥ 1,85, zatímco hlavní crate tehdy slibovaly 1,75. Knihovna i tento server nyní deklarují 1,88, minimum bezpečnostně opraveného rmcp 2.x a aktualizovaných crate z RustCrypto.) Kontinuální integrace (CI) tento crate hlídá samostatně — testy a cargo deny proti jeho lockfile. Licenční strom rmcp je čistý (Apache-2.0/MIT/BSD), takže na rozdíl od křížově validačního crate xval/anise-frames, který jinak kopíruje, oddělení nesouvisí s licencováním.

Licence: pouze AGPL-3.0, GNU Affero General Public License verze 3 (nebo komerční licence od Ashforde OÜ; viz LICENSING.md v repozitáři).