kshana-mcp: fråga din AI-assistent, så svarar motorn

kshana-mcp är en Model Context Protocol-server (MCP) för Kshana, simulatorn med öppen källkod för PNT-resiliens (positionering, navigering och tidssynkronisering). Den låter en AI-assistent (artificiell intelligens) köra den verkliga motorn och läsa tillbaka dess JSON (JavaScript Object Notation) i stället för att gissa matematiken. Den talar över stdio (standard in och ut) med vilken MCP-kompatibel klient som helst, inklusive Cursor och JetBrains AI Assistant / Junie.

Matematiken som Kshana är validerad för är precis där en språkmodell gissar dåligt: SGP4-banpropagering (Simplified General Perturbations 4), IAU:s (International Astronomical Union) referenssystem, Allan-deviationer, tillgänglighet och DOP (dilution of precision) för GNSS (Global Navigation Satellite System), skyddsnivåer för ARAIM (advanced receiver autonomous integrity monitoring), fusion av GNSS och INS (tröghetsnavigeringssystem) samt kvantsensormodeller. Ställ en fråga; assistenten kör ett verkligt scenario och får kvalitetsmått med sitt ursprung och sin etikett VALIDATED eller MODELLED.

Verktyg#

Varje verktyg är ett tunt, troget skal kring en offentlig funktion i biblioteket kshana — ingen ny simuleringslogik finns här, så en agent kör exakt den validerade motorn.

GNSS-IQ-verktygen: filer in, kompakt JSON ut#

IQ-inspelningar kan uppgå till gigabyte, så verktygen iq_* skickar aldrig sampel genom protokollet. De följer ett kontrakt:

• En arbetskatalog. Servern läser och skriver IQ-filer bara i mappen som anges av KSHANA_MCP_IQ_DIR. Varje sökvägsargument är relativt den (en absolut sökväg måste lösas upp inuti den); indata löses upp genom symlänkar före kontrollen, en utdatas mapp måste redan finnas inuti den, och en befintlig utdata ersätts bara med overwrite: true. Om den inte är satt är IQ-filverktygen av och säger hur de aktiveras; alla andra verktyg påverkas inte.
• En samplebudget. Ett anrop genererar eller bearbetar högst KSHANA_MCP_IQ_MAX_SAMPLES komplexa sampel (standard 50 000 000). I byte är det 400 MB som cf32_le (8 byte per komplext sampel), 200 MB som ci16_le (4 byte) och 100 MB som ci8 (2 byte); en scen skrivs som cf32_le om inte format säger annat. Kontrollen körs före allt arbete, och avslaget anger den varaktighet eller max_seconds som ryms.
• Kompakta svar. Varje verktyg svarar med en JSON-sammanfattning: förvärvstoppar, C/N0, låsningstillstånd och varje skriven fil med sin sökväg och sitt bytetal. Tabeller per epok går till de filer json_out / csv_out som du namnger.
• Okända argument avvisas, ignoreras inte, så ett felstavat alternativ är ett fel.

Varje verktyg kör samma kodväg som kshana iq på kommandoraden, i processen. Lagret är enbart programvara: det skriver filer för mjukvarumottagare och driver ingen radiohårdvara. IQ-lagret lägger inte till någon syntes av störning eller spoofer, och ingenting sänds någonsin. (Den separata scenariotypen spectrum kan skriva analytiska ögonblicksbilder av störsändar-IQ till en fil.)

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

Med Docker-avbilden, montera mappen och peka variabeln mot den: docker run --rm -i -v "$PWD/iq:/iq" -e KSHANA_MCP_IQ_DIR=/iq ghcr.io/ashfordeou/kshana-mcp.

Varje typ är nåbar#

run_scenario skickar vidare efter scenariots kind, så varje typ som list_scenario_kinds nämner körs genom den. Det inkluderar de nyare familjerna, var och en med medföljande exempel som en agent kan hämta:

list_example_scenarios med en kind nämner varje medföljande exempel av den typen. Animeringar, rapporter och interoperabilitetsexporter är inga typer: de är vyer av en körning, och animate_scenario, report_scenario och export_interop returnerar dem för varje scenario de gäller.

Serveras inte: studiesviter (kshana --study <suite.toml>), eftersom en svit nämner syskonscenariofiler på disk och scenarioverktygen inte läser någon fil. Kör varje medlem med run_scenario. (IQ-verktygen läser och skriver filer, men bara inuti sin arbetskatalog.)

Installera MCP-servern#

Rådgivande, inte typgodkänd navigationsutrustning: operatören är fortsatt ansvarig för navigeringen. Servern körs på din dator; ingenting skickas till Ashforde OÜ.

Ett stycke som nämner AI-klienter från tredje part är utelämnat här; det finns i mcp/kshana-mcp/README.md på GitHub.

Från en utcheckning eller git (utveckling):

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

HTTP-läge (egen drift)#

kshana-mcp --http 127.0.0.1:8080 serverar samma verktyg över streamable HTTP på /mcp. Den binder bara loopback; en adress som inte är loopback kräver --allow-remote och en bearer-token i KSHANA_MCP_HTTP_TOKEN; IQ-filverktygen är av; förfrågans storlek, tid och samtidighet är begränsade; inget CORS-huvud skickas. Kshana tillhandahåller ingen slutpunkt: du driver den själv. Se docs/deploy/mcp-http.md.

cargo install lägger kshana-mcp på din PATH (vanligen ~/.cargo/bin/kshana-mcp). Servern talar JSON-RPC (JSON remote procedure call) över stdio; loggar går till stderr. Att bygga från källkod kräver en Rust-verktygskedja ≥ 1,88 (den lagade SDK:n rmcp 2.x kräver det, och det gör även biblioteket kshana); Docker-avbilden behöver ingen.

Registrera den hos en klient#

Praktiskt taget varje MCP-klient använder samma konfigurationsblock mcpServers — registrera binärfilen kshana-mcp med absolut sökväg:

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

Eller, med Docker-avbilden i stället för en lokal binärfil (ingen PATH behövs):

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

Var det blocket finns beror på klienten:

• Cursor — ~/.cursor/mcp.json (globalt) eller .cursor/mcp.json (per projekt).
• JetBrains AI Assistant / Junie — Settings → Tools → AI Assistant → Model Context Protocol → Add → As JSON, klistra in blocket och starta sedan om IDE:n (integrated development environment) helt.
• Skrivbordsassistenter — de flesta använder en …_config.json med samma form mcpServers; kontrollera din klients dokumentation för filens plats.
• CLI-agenter — många accepterar samma JSON via en mekanism mcp add / mcp.json.

Använd alltid en absolut sökväg till binärfilen. Sätt RUST_LOG=debug i env för att felsöka (diagnostik går till stderr; stdout är reserverad för JSON-RPC-protokollet).

Prova#

När den är registrerad, fråga din assistent saker som:

• "Lista scenariotyperna i Kshana." → list_scenario_kinds
• "Visa mig ett spektrumexempel i Kshana och kör det." → list_example_scenarios, get_example_scenario, run_scenario
• "Kör scenariot clock-holdover i Kshana med en tröskel på 20 ns och ett GNSS-avbrott på 2 timmar; vad är holdover för kvant jämfört med klassisk?" → run_scenario
• "Exportera den GPS-konstellationen (Global Positioning System) som SP3." → export_sp3
• "Ge mig tabellen realtime-frame-eop som CSV." → export_table_csv
• "Lägg den Iridium-passagen på en Cesium-glob." → list_export_formats, export_interop
• "Animera jamming-kampanjen." → animate_scenario
• "Ge mig rapporten för den körningen, med dess reproducerbarhetspost." → report_scenario
• "Skapa en GPS L1-scen på en sekund med PRN 3 och 17, förvärva och spåra den sedan." → iq_signals, iq_scene, iq_acquire, iq_track

Designanteckning — varför en separat crate#

Servern är en fristående crate utanför arbetsytan med egen Cargo.lock, så att den officiella Rust-MCP-SDK:n (software development kit) rmcp och dess asynkrona körmiljö aldrig hamnar i beroendegrafen för den publicerade crate:n kshana: en biblioteks- eller Python-användare kompilerar inte en server de inte kör. (Den delades först ut eftersom rmcp är edition 2024 och kräver rustc ≥ 1,85, medan huvudcrate:n då lovade 1,75. Biblioteket och den här servern deklarerar nu båda 1,88, golvet för den säkerhetslagade rmcp 2.x och för de uppgraderade RustCrypto-crate:ena.) Kontinuerlig integration (CI) styr den här crate:n för sig — tester och cargo deny mot dess låsfil. rmcp:s licensträd är rent (Apache-2.0/MIT/BSD), så, till skillnad från korsvalideringscrate:n xval/anise-frames som den i övrigt speglar, handlar uppdelningen inte om licensiering.

Licens: endast AGPL-3.0, GNU Affero General Public License version 3 endast (eller en kommersiell licens från Ashforde OÜ; se förrådets LICENSING.md).