kshana-mcp: spør KI-assistenten din, så svarer motoren

kshana-mcp er en MCP-server (Model Context Protocol) for Kshana, den åpne simulatoren for robusthet i PNT (posisjonering, navigasjon og tidssynkronisering). Den lar en KI-assistent (kunstig intelligens) kjøre den virkelige motoren og lese tilbake JSON-svaret (JavaScript Object Notation), i stedet for å gjette på matematikken. Den snakker over stdio (standard inn og ut) med enhver MCP-klient, inkludert Cursor og JetBrains AI Assistant / Junie.

Matematikken som Kshana er validert for, er nettopp der en språkmodell gjetter dårlig: banepropagering med SGP4 (Simplified General Perturbations 4), referansesystemer fra IAU (International Astronomical Union), Allan-deviasjoner, tilgjengelighet for GNSS (Global Navigation Satellite System) og DOP (dilution of precision), beskyttelsesnivåer for ARAIM (advanced receiver autonomous integrity monitoring), fusjon av GNSS og INS (inertial navigation system), og kvantesensormodeller. Still et spørsmål; assistenten kjører et ekte scenario og får kvalitetsmål med opphav og merkelappen VALIDATED eller MODELLED.

Verktøy#

Hvert verktøy er en tynn, tro innpakning rundt en offentlig funksjon i biblioteket kshana — ingen ny simuleringslogikk ligger her, så en agent kjører nøyaktig den validerte motoren.

GNSS IQ-verktøyene: filer inn, kompakt JSON ut#

IQ-opptak går opp i gigabyte, så verktøyene iq_* sender aldri sampler gjennom protokollen. De følger én kontrakt:

• En arbeidsmappe. Serveren leser og skriver IQ-filer bare inne i mappen som er navngitt av KSHANA_MCP_IQ_DIR. Hvert stiargument er relativt til den (en absolutt sti må løses opp innenfor den); inndata løses opp gjennom symlenker før kontrollen, mappen til en utdatafil må allerede finnes inne i den, og en eksisterende utdatafil erstattes bare med overwrite: true. Når den ikke er satt, er IQ-filverktøyene av og sier hvordan de slås på; alle andre verktøy påvirkes ikke.
• Et samplebudsjett. Ett kall genererer eller behandler høyst KSHANA_MCP_IQ_MAX_SAMPLES komplekse sampler (standard 50 000 000). I byte er det 400 MB som cf32_le (8 byte per komplekse sample), 200 MB som ci16_le (4 byte) og 100 MB som ci8 (2 byte); en scene skrives som cf32_le med mindre format sier noe annet. Kontrollen kjører før noe arbeid, og avslaget nevner varigheten eller max_seconds som passer.
• Kompakte svar. Hvert verktøy svarer med ett JSON-sammendrag: akkvisisjonstopper, C/N0, låsetilstand og hver fil som er skrevet, med sti og antall byte. Tabeller per epoke går til filene json_out / csv_out du navngir.
• Ukjente argumenter avvises, ikke ignoreres, så et feilstavet valg er en feil.

Hvert verktøy kjører samme kodesti som kshana iq på kommandolinjen, i prosessen. Laget er bare programvare: det skriver filer for programvaremottakere og styrer ingen radiomaskinvare. IQ-laget legger ikke til noen syntese av interferens eller spoofer, og ingenting sendes noen gang. (Scenariotypen spectrum kan skrive analytiske jammer-IQ-øyeblikksbilder til en fil.)

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

Med Docker-avbildningen monterer du mappen og peker variabelen på den: docker run --rm -i -v "$PWD/iq:/iq" -e KSHANA_MCP_IQ_DIR=/iq ghcr.io/ashfordeou/kshana-mcp.

Alle typer kan nås#

run_scenario sender videre etter scenarioets kind, så alle typer som list_scenario_kinds nevner, kjører gjennom det. Det omfatter de nyere familiene, hver med medfølgende eksempler en agent kan hente:

list_example_scenarios med en kind nevner alle medfølgende eksempler av den typen. Animasjoner, rapporter og interoperabilitetseksporter er ikke typer: de er visninger av en kjøring, og animate_scenario, report_scenario og export_interop returnerer dem for ethvert scenario de gjelder for.

Ikke servert: studiesuiter (kshana --study <suite.toml>), fordi en suite navngir søsterscenariofiler på disken og scenarioverktøyene ikke leser noen fil. Kjør hvert medlem med run_scenario. (IQ-verktøyene leser og skriver filer, men bare innenfor arbeidsmappen sin.)

Installer MCP-serveren#

Veiledende, ikke typegodkjent navigasjonsutstyr: operatøren er fortsatt ansvarlig for navigasjonen. Serveren kjører på din datamaskin; ingenting sendes til Ashforde OÜ.

En passasje som nevner tredjeparts AI-klienter er utelatt her; den står i mcp/kshana-mcp/README.md på GitHub.

Fra en utsjekk eller git (utvikling):

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

HTTP-modus (selvdrevet)#

kshana-mcp --http 127.0.0.1:8080 serverer de samme verktøyene over strømmende HTTP på /mcp. Den binder seg bare til loopback; en adresse som ikke er loopback, trenger --allow-remote og et bearer-token i KSHANA_MCP_HTTP_TOKEN; IQ-filverktøyene er av; forespørselsstørrelse, tid og samtidighet er begrenset; ingen CORS-header sendes. Kshana driver ikke noe endepunkt: du drifter det selv. Se docs/deploy/mcp-http.md.

cargo install legger kshana-mcp i din PATH (vanligvis ~/.cargo/bin/kshana-mcp). Serveren snakker JSON-RPC (JSON remote procedure call) over stdio; logger går til stderr. Bygging fra kildekode trenger en Rust-verktøykjede ≥ 1,88 (den patchede rmcp 2.x SDK-en trenger det, og det gjør biblioteket kshana også); Docker-avbildningen trenger ingen.

Registrer den hos en klient#

Så å si alle MCP-klienter bruker den samme konfigurasjonsblokken mcpServers — registrer binærfilen kshana-mcp med absolutt sti:

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

Eller, med Docker-avbildningen i stedet for en lokal binærfil (ingen PATH nødvendig):

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

Hvor den blokken ligger, avhenger av klienten:

• Cursor — ~/.cursor/mcp.json (globalt) eller .cursor/mcp.json (per prosjekt).
• JetBrains AI Assistant / Junie — Settings → Tools → AI Assistant → Model Context Protocol → Add → As JSON, lim inn blokken, og start deretter IDE-en (integrated development environment) helt på nytt.
• Skrivebordsassistenter — de fleste bruker en …_config.json med samme mcpServers-form; sjekk klientens dokumentasjon for filplasseringen.
• CLI-agenter — mange godtar den samme JSON-en gjennom en mcp add / mcp.json-mekanisme.

Bruk alltid en absolutt sti til binærfilen. Sett RUST_LOG=debug i env for å feilsøke (diagnostikk går til stderr; stdout er reservert for JSON-RPC-protokollen).

Prøv det#

Når den er registrert, kan du spørre assistenten din om ting som:

• «List scenariotypene i Kshana.» → list_scenario_kinds
• «Vis meg et spectrum-eksempel i Kshana og kjør det.» → list_example_scenarios, get_example_scenario, run_scenario
• «Kjør scenarioet for klokke-holdover i Kshana med en terskel på 20 ns og et GNSS-utfall på 2 timer; hva er holdover for kvante mot klassisk?» → run_scenario
• «Eksporter den GPS-konstellasjonen (Global Positioning System) som SP3.» → export_sp3
• «Gi meg tabellen realtime-frame-eop som CSV.» → export_table_csv
• «Legg den Iridium-overflyvningen på en Cesium-globus.» → list_export_formats, export_interop
• «Animer jamming-kampanjen.» → animate_scenario
• «Gi meg rapporten for den kjøringen, med reproduserbarhetsposten.» → report_scenario
• «Lag en GPS L1-scene på ett sekund med PRN-ene 3 og 17, og akkvirer og spor den deretter.» → iq_signals, iq_scene, iq_acquire, iq_track

Designnotat — hvorfor en egen crate#

Serveren er en frittstående crate som er utelatt fra workspace, med sin egen Cargo.lock, slik at det offisielle Rust MCP-SDK-et (software development kit) rmcp og den asynkrone kjøretiden aldri kommer inn i avhengighetsgrafen til den publiserte crate-en kshana: en bruker av biblioteket eller Python kompilerer ikke en server vedkommende ikke kjører. (Den ble først skilt ut fordi rmcp er edition 2024 og trenger rustc ≥ 1,85, mens hovedcrate-en den gang lovte 1,75. Biblioteket og denne serveren oppgir nå begge 1,88, gulvet for den sikkerhetspatchede rmcp 2.x og for de oppgraderte RustCrypto-crate-ene.) Kontinuerlig integrasjon (CI) setter port for denne crate-en på egen hånd — tester og cargo deny mot sin egen låsfil. Lisenstreet til rmcp er rent (Apache-2.0/MIT/BSD), så, i motsetning til krysskontrollcrate-en xval/anise-frames den ellers speiler, handler splittingen ikke om lisensiering.

Lisens: AGPL-3.0-only, GNU Affero General Public License versjon 3 alene (eller en kommersiell lisens fra Ashforde OÜ; se LICENSING.md i depotet).