kshana-mcp: vraag het aan uw AI-assistent en de engine antwoordt

kshana-mcp is een Model Context Protocol-server (MCP) voor Kshana, de opensource-simulator voor de veerkracht van PNT (positiebepaling, navigatie en tijdsynchronisatie). Hij laat een AI-assistent (kunstmatige intelligentie) de echte engine draaien en de JSON (JavaScript Object Notation) teruglezen, in plaats van de wiskunde te raden. Hij communiceert via stdio (standaard in- en uitvoer) met elke MCP-compatibele client, waaronder Cursor en JetBrains AI Assistant / Junie.

De wiskunde waarvoor Kshana aan een onafhankelijke externe referentie is getoetst, is precies waar een taalmodel slecht raadt: SGP4 (Simplified General Perturbations 4) baanpropagatie, referentiestelsels van de IAU (International Astronomical Union), Allan-deviaties, beschikbaarheid van GNSS (Global Navigation Satellite System) en DOP (dilution of precision), beschermingsniveaus van ARAIM (advanced receiver autonomous integrity monitoring), fusie van GNSS en INS (inertial navigation system) en modellen van kwantumsensoren. Stel een vraag; de assistent draait een echt scenario en krijgt kwaliteitsmaten met hun herkomst en hun label VALIDATED of MODELLED.

Hulpmiddelen#

Elk hulpmiddel is een dunne, getrouwe omhulling van een openbare functie van de bibliotheek kshana — hier zit geen nieuwe simulatielogica, dus een agent draait precies de engine die aan een onafhankelijke externe referentie is getoetst.

De GNSS-IQ-hulpmiddelen: bestanden erin, compacte JSON eruit#

IQ-opnamen lopen op tot gigabytes, dus de iq_*-hulpmiddelen laten nooit samples door het protocol lopen. Ze volgen één contract:

• Een werkmap. De server leest en schrijft IQ-bestanden alleen binnen de map die door KSHANA_MCP_IQ_DIR wordt genoemd. Elk padargument is ten opzichte daarvan (een absoluut pad moet erbinnen uitkomen); invoer wordt vóór de controle via symlinks opgelost, de map van een uitvoer moet er al in bestaan, en een bestaande uitvoer wordt alleen vervangen met overwrite: true. Als de variabele niet is ingesteld, staan de IQ-bestandshulpmiddelen uit en zeggen ze hoe ze aan te zetten; elk ander hulpmiddel blijft ongemoeid.
• Een samplebudget. Eén aanroep genereert of verwerkt hoogstens KSHANA_MCP_IQ_MAX_SAMPLES complexe samples (standaard 50.000.000). In bytes is dat 400 MB als cf32_le (8 bytes per complexe sample), 200 MB als ci16_le (4 bytes) en 100 MB als ci8 (2 bytes); een scène wordt als cf32_le geschreven tenzij format anders bepaalt. De controle vindt plaats vóór enig werk en de weigering noemt de duur of max_seconds die past.
• Compacte antwoorden. Elk hulpmiddel antwoordt met één JSON-samenvatting: acquisitiepieken, C/N0, lock-toestand en elk geschreven bestand met zijn pad en aantal bytes. Tabellen per epoch gaan naar de bestanden json_out / csv_out die u noemt.
• Onbekende argumenten worden geweigerd, niet genegeerd, zodat een verkeerd gespelde optie een fout is.

Elk hulpmiddel draait hetzelfde codepad als kshana iq op de opdrachtregel, in hetzelfde proces. De laag is alleen software: ze schrijft bestanden voor softwareontvangers en stuurt geen radiohardware aan. De IQ-laag voegt geen synthese van interferentie of spoofers toe en er wordt nooit iets uitgezonden. (De aparte scenariosoort spectrum kan analytische IQ-momentopnamen van jammers naar een bestand schrijven.)

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

Koppel bij het Docker-image de map en laat de variabele ernaar wijzen: docker run --rm -i -v "$PWD/iq:/iq" -e KSHANA_MCP_IQ_DIR=/iq ghcr.io/ashfordeou/kshana-mcp.

Elke soort is bereikbaar#

run_scenario verdeelt op de kind van het scenario, dus elke soort die list_scenario_kinds noemt, draait erdoorheen. Dat omvat de nieuwere families, elk met meegeleverde voorbeelden die een agent kan ophalen:

list_example_scenarios met een kind noemt elk meegeleverd voorbeeld van die soort. Animaties, rapporten en interoperabiliteitsexports zijn geen soorten: het zijn weergaven van een run, en animate_scenario, report_scenario en export_interop leveren ze voor elk scenario waarop ze van toepassing zijn.

Niet aangeboden: studiesuites (kshana --study <suite.toml>), omdat een suite naburige scenariobestanden op schijf noemt en de scenariohulpmiddelen geen bestand lezen. Draai elk lid met run_scenario. (De IQ-hulpmiddelen lezen en schrijven wel bestanden, maar alleen binnen hun werkmap.)

De MCP-server installeren#

Adviserend, geen typegoedgekeurde navigatieapparatuur: de exploitant blijft verantwoordelijk voor de navigatie. De server draait op uw computer; er wordt niets naar Ashforde OÜ verzonden.

Een passage waarin AI-clients van derden worden genoemd, is hier weggelaten; ze staat in mcp/kshana-mcp/README.md op GitHub.

Vanuit een checkout of git (ontwikkeling):

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

HTTP-modus (zelf gehost)#

kshana-mcp --http 127.0.0.1:8080 biedt dezelfde hulpmiddelen via streamable HTTP op /mcp. Hij bindt alleen aan loopback; een niet-loopbackadres vereist --allow-remote en een bearer-token in KSHANA_MCP_HTTP_TOKEN; de IQ-bestandshulpmiddelen staan uit; omvang, tijd en gelijktijdigheid van verzoeken zijn begrensd; er wordt geen CORS-header verzonden. Kshana host geen endpoint: u host het zelf. Zie docs/deploy/mcp-http.md.

cargo install zet kshana-mcp op uw PATH (meestal ~/.cargo/bin/kshana-mcp). De server praat JSON-RPC (JSON remote procedure call) via stdio; logs gaan naar stderr. Bouwen uit de broncode vereist een Rust-toolchain ≥ 1,88 (de gepatchte rmcp 2.x-SDK heeft die nodig, net als de bibliotheek kshana); het Docker-image heeft er geen nodig.

Registreer hem bij een client#

Vrijwel elke MCP-client gebruikt hetzelfde configuratieblok mcpServers — registreer het binaire bestand kshana-mcp met zijn absolute pad:

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

Of, met het Docker-image in plaats van een lokaal binair bestand (geen PATH nodig):

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

Waar dat blok staat, hangt van de client af:

• Cursor — ~/.cursor/mcp.json (globaal) of .cursor/mcp.json (per project).
• JetBrains AI Assistant / Junie — Settings → Tools → AI Assistant → Model Context Protocol → Add → As JSON, plak het blok en start de IDE (integrated development environment) daarna volledig opnieuw.
• Desktopassistenten — de meeste gebruiken een …_config.json met dezelfde mcpServers-vorm; raadpleeg de documentatie van uw client voor de bestandslocatie.
• CLI-agents — veel accepteren dezelfde JSON via een mechanisme mcp add / mcp.json.

Gebruik altijd een absoluut pad naar het binaire bestand. Stel RUST_LOG=debug in env in om problemen op te sporen (diagnostiek gaat naar stderr; stdout is gereserveerd voor het JSON-RPC-protocol).

Probeer het#

Eenmaal geregistreerd, kunt u uw assistent zulke dingen vragen als:

• "Geef de Kshana-scenariosoorten weer." → list_scenario_kinds
• "Toon me een Kshana-spectrumvoorbeeld en draai het." → list_example_scenarios, get_example_scenario, run_scenario
• "Draai het Kshana-scenario voor klok-holdover met een drempel van 20 ns en een GNSS-uitval van 2 uur; wat is de holdover kwantum versus klassiek?" → run_scenario
• "Exporteer die GPS-constellatie (Global Positioning System) als SP3." → export_sp3
• "Geef me de tabel realtime-frame-eop als CSV." → export_table_csv
• "Zet die Iridium-overpassing op een Cesium-globe." → list_export_formats, export_interop
• "Animeer de jamming-campagne." → animate_scenario
• "Geef me het rapport voor die run, met zijn reproduceerbaarheidsrecord." → report_scenario
• "Maak een GPS L1-scène van een seconde met PRN's 3 en 17, en verwerf en volg die daarna." → iq_signals, iq_scene, iq_acquire, iq_track

Ontwerpnotitie — waarom een aparte crate#

De server is een zelfstandige crate buiten de workspace met een eigen Cargo.lock, zodat de officiële Rust MCP-SDK (software development kit) rmcp en zijn asynchrone runtime nooit in de afhankelijkheidsgraaf van de gepubliceerde crate kshana terechtkomen: een gebruiker van de bibliotheek of van Python compileert geen server die hij niet draait. (Hij werd eerst afgesplitst omdat rmcp edition 2024 is en rustc ≥ 1,85 vereist, terwijl de hoofdcrate toen 1,75 beloofde. De bibliotheek en deze server verklaren nu allebei 1,88, de ondergrens van de beveiligingsgepatchte rmcp 2.x en van de geüpgradede RustCrypto-crates.) Continue integratie (CI) toetst deze crate afzonderlijk — tests en cargo deny tegen zijn lockfile. De licentieboom van rmcp is schoon (Apache-2.0/MIT/BSD), dus anders dan de kruisvalidatiecrate xval/anise-frames, die hij verder nabootst, gaat de afsplitsing niet om licenties.

Licentie: alleen AGPL-3.0, de GNU Affero General Public License versie 3 (of een commerciële licentie van Ashforde OÜ; zie LICENSING.md van de repository).