kshana-mcp: ask your AI assistant, and the engine answers

kshana-mcp is a Model Context Protocol (MCP) server for Kshana, the open-source simulator for PNT (positioning, navigation and timing) resilience. It lets an AI (artificial intelligence) assistant run the real engine and read back its JSON (JavaScript Object Notation), instead of guessing the maths. It speaks over stdio (standard input and output) to any MCP-compatible client, including Cursor and JetBrains AI Assistant / Junie.

The maths Kshana is validated for is exactly where a language model guesses badly: SGP4 (Simplified General Perturbations 4) orbit propagation, reference frames of the IAU (International Astronomical Union), Allan deviations, GNSS (Global Navigation Satellite System) availability and DOP (dilution of precision), ARAIM (advanced receiver autonomous integrity monitoring) protection levels, GNSS and INS (inertial navigation system) fusion, and quantum-sensor models. Ask a question; the assistant runs a real scenario and gets figures of merit with their provenance and their VALIDATED or MODELLED label.

Tools#

Each tool is a thin, faithful wrapper over a public function of the kshana library — no new simulation logic lives here, so an agent runs exactly the validated engine.

Every kind is reachable#

run_scenario dispatches on the scenario's kind, so every kind list_scenario_kinds names runs through it. That includes the newer families, each with bundled examples an agent can fetch:

list_example_scenarios with a kind names every bundled example of that kind. Animations, reports and interoperability exports are not kinds: they are views of a run, and animate_scenario, report_scenario and export_interop return them for any scenario they apply to.

Not served: study suites (kshana --study <suite.toml>), because a suite names sibling scenario files on disk and this server reads no file. Run each member with run_scenario.

Install#

Pick whichever fits — all run the same server over stdio.

# crates.io (a Rust toolchain builds it from source):
cargo install kshana-mcp

# Docker / OCI (Open Container Initiative) image — no Rust toolchain needed;
# published for linux/amd64 and linux/arm64, so Apple silicon runs it natively:
docker run --rm -i ghcr.io/ashfordeou/kshana-mcp

# From a checkout (development):
cd mcp/kshana-mcp && cargo install --path .

# Bleeding edge, straight from git:
cargo install --git https://github.com/AshfordeOU/kshana kshana-mcp

cargo install puts kshana-mcp on your PATH (typically ~/.cargo/bin/kshana-mcp). The server talks JSON-RPC (JSON remote procedure call) over stdio; logs go to stderr. Building from source needs a Rust toolchain ≥ 1.88 (the patched rmcp 2.x SDK needs it; the kshana library itself needs only 1.85); the Docker image needs none.

Register it with a client#

Virtually every MCP client uses the same mcpServers config block — register the kshana-mcp binary by absolute path:

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

Or, with the Docker image instead of a local binary (no PATH needed):

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

Where that block lives depends on the client:

• Cursor — ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project).
• JetBrains AI Assistant / Junie — Settings → Tools → AI Assistant → Model Context Protocol → Add → As JSON, paste the block, then fully restart the IDE (integrated development environment).
• Desktop assistants — most use a …_config.json with the same mcpServers shape; check your client's docs for the file location.
• CLI agents — many accept the same JSON via an mcp add / mcp.json mechanism.

Always use an absolute path to the binary. Set RUST_LOG=debug in env to troubleshoot (diagnostics go to stderr; stdout is reserved for the JSON-RPC protocol).

Try it#

Once registered, ask your assistant things like:

• "List the Kshana scenario kinds." → list_scenario_kinds
• "Show me a Kshana spectrum example and run it." → list_example_scenarios, get_example_scenario, run_scenario
• "Run the Kshana clock-holdover scenario with a 20 ns threshold and a 2-hour GNSS outage; what's the quantum-vs-classical holdover?" → run_scenario
• "Export that GPS (Global Positioning System) constellation as SP3." → export_sp3
• "Give me the realtime-frame-eop table as CSV." → export_table_csv
• "Put that Iridium pass on a Cesium globe." → list_export_formats, export_interop
• "Animate the jamming campaign." → animate_scenario
• "Give me the report for that run, with its reproducibility record." → report_scenario

Design note — why a separate crate#

The server is a standalone, workspace-excluded crate with its own Cargo.lock, so the official Rust MCP SDK (software development kit) rmcp and its async runtime never enter the published kshana crate's dependency graph: a library or Python user does not compile a server they do not run. (It was first split out because rmcp is edition 2024, needing rustc ≥ 1.85, while the main crate then promised 1.75. The library now declares 1.85; this server declares 1.88, the floor of the security-patched rmcp 2.x.) Continuous integration (CI) gates this crate on its own — tests and cargo deny against its lockfile. rmcp's licence tree is clean (Apache-2.0/MIT/BSD), so, unlike the xval/anise-frames cross-validation crate it otherwise mirrors, the split is not about licensing.

License: AGPL-3.0-only, the GNU Affero General Public License version 3 only (or a commercial licence from Ashforde OÜ; see the repository's LICENSING.md).