Kshana PNT-resilience simulator

kshana-mcp：向 AI 助手提问，由引擎作答

kshana-mcp 是一个 Model Context Protocol（MCP）服务，适用于 Kshana——这款用于 PNT（定位、导航和授时）韧性仿真的开源模拟器。它能让 AI（人工智能）助手运行真实引擎并读取 其 JSON（JavaScript 对象表示法）结果，而不是猜测数学计算。它通过 stdio（标准输入和输出）与任何兼容 MCP 的客户端通信，包括 Cursor 和 JetBrains AI Assistant / Junie。

Kshana 已验证的数学领域，恰恰是语言模型最容易猜错的地方：SGP4 （简化通用摄动 4）轨道传播、IAU（国际天文学联合会）参考系、Allan 偏差、GNSS（全球导航卫星系统） 可用性和 DOP（精度因子）、ARAIM（高级接收机自主完好性监测）保护级别、GNSS 和 INS（惯性导航系统）融合， 以及量子传感器模型。提出问题后，助手会运行真实场景，获取带有来源信息及 VALIDATED 或 MODELLED 标签的 性能指标。

工具

工具	功能
run_scenario	根据 TOML（Tom's Obvious, Minimal Language）定义运行场景；返回摘要和完整结果 JSON（JavaScript Object Notation：性能指标、曲线）。可选的 include_chart 会以 SVG（Scalable Vector Graphics）格式返回图表。
list_scenario_kinds	列出 87 种内置场景类型及其描述和必填／可选字段，方便 Agent 构造有效场景。
validate_scenario	运行前检查：解析 TOML 并检测其类型，不运行场景。
list_example_scenarios	以 JSON 形式列出捆绑的参考场景：每个场景的 name、kind，以及一句说明其展示内容的描述。可选的 kind 筛选器。每个示例都能直接运行，因此这是为某种类型获取有效 TOML 的最快方式。
get_example_scenario	返回一个捆绑参考场景的 TOML 文本，与 scenarios/ 下的文件逐字节一致。
report_scenario	运行场景并返回报告：执行摘要、输入、每项指标及其单位和 VALIDATED 或 MODELLED 标签、事件、已用到的能力以及可复现性记录。format 为 json（默认值）或 html（可打印的单文件页面）。
animate_scenario	运行场景并以动画形式返回其时间序列：svg（默认值）、html（自包含播放器）或 frames（每次回复最多 120 帧）。第一个内容项是所绘制内容的 JSON 摘要；之后为文件。若某种类型没有采样时间轴，则会拒绝处理并说明原因。
list_export_formats	列出适用于某个场景的互操作格式（czml、kml、geojson、stk、sigmf）、不适用时的原因，以及各写入器遵循的规范。不运行场景。
export_interop	将场景导出为 CZML（Cesium Language）、KML（Keyhole Markup Language）、GeoJSON、STK（Systems Tool Kit）星历 .e，或 SigMF（Signal Metadata Format；适用于带有 [iq] 块的 spectrum 场景）。第一个内容项是文件的 JSON 索引（后缀、大小、编码和 SHA-256 摘要，即 256 位 Secure Hash Algorithm）；之后为文件，其中二进制 SigMF 样本文件采用 base64 编码。
import_route	将 GeoJSON LineString 路线写入飞行航点轨迹的场景（terrain-nav、terrain-slam、gravity-map、combined-altpnt），并返回新的 TOML。
export_sp3	将 orbit 场景的星座导出为 SP3-c（Standard Product 3，c 版）精密星历。
export_omm	将 orbit 场景的轨道根数导出为 CCSDS（Consultative Committee for Space Data Systems）502.0-B-2 OMM（Orbit Mean-elements Message）目录。
export_oem	将 orbit 场景的状态序列导出为 CCSDS OEM（Orbit Ephemeris Message）2.0 星历——其中包含 TEME（true equator, mean equinox）位置和速度序列，供飞行动力学工具（GMAT，即 General Mission Analysis Tool；Orekit；STK，即 Systems Tool Kit）读取；它是仅含位置的 export_sp3 的速度补充版本。
export_table_csv	运行场景并以 CSV（逗号分隔值）格式返回其可复现性表，即 CLI（命令行界面）写入的字节稳定表格 <scenario>.table.csv。只有 realtime-frame-eop、lunar-time-budget、lunar-jamming、telecom-timing、leo-navmsg（其对 kepler16 或 kepler-rac 消息模型的 encode-decode 分析），以及设置了 export_site_lat_deg 和 export_site_lon_deg 的 moonlight-service-volume 会生成表格；其他任何类型都会返回错误，并列出这些类型。
sky_geometry	计算方位角相关天际线下的天空几何：根据地点、时间和星座预设、双行根数集（tle，通过 SGP4 推算至 UTC epoch），或方位角／仰角或 ECEF 坐标形式的卫星，返回可见卫星、被天际线遮挡的卫星、由 gnss_lib_py 检查过的 DOP 内核计算的 GDOP/PDOP/HDOP/VDOP/TDOP、东-北-天协因数和协方差（每个系统一个时钟或共用一个时钟），以及水平误差椭圆；若使用 skyline_preset 而非 request，则返回带来源信息和逐度切线角的 REPRESENTATIVE 预设。MODELLED；包含警示信息；不通过 MCP 进行蒙特卡洛计算。参见 docs/SKYLINE.md。
assess_receiver_log	评估真实 GNSS（全球导航卫星系统）接收机日志的可信度。TOML 指定日志的 format（ubx、rinex、android、nmea 或 sbf），并通过 text 或 base64 内联提供日志字节；工具运行可信度监测器（载波噪声密度下降、失锁、AGC（自动增益控制）、干扰指示器、位置跳变，以及在使用 RINEX 和广播导航数据时的 RAIM（接收机自主完整性监测）和时钟辅助监测器），并返回定位结果何时以及为何不再可信。可选的 [[events]] 和 [compare] 部分可根据指定容差，对所述事件和预测的 C/N0 降幅进行评分。[platform] kind = "vessel" 表格会选择海事监测器，并为每个历元添加 0-100 的可信度分数及扣分监测器（警示；MODELLED）。日志通过 text 或 base64 内联提供（最多 4 MiB）。可按需生成图表和逐历元 CSV。参见 docs/RECEIVER-TRUST.md。
assess_vessel_stream	按照 kshana receiver-trust live 的评分方式，对有界 NMEA 0183 摘录（最多 2 MiB 和 20,000 个历元；必须包含校准窗口）进行评分：返回逐历元可信状态和 0-100 分的评分及扣分监测器、摘要和最后一条 $PKSHT。这是实时命令的有界形式：不会打开套接字，也不会向端口写入任何内容；门控、--listen 和遥测导出器（Prometheus、OTLP、syslog）仅限命令行使用。仅供参考；MODELLED。参见 docs/MARITIME-TRUST.md。
assess_vessel_log	将船舶的 NMEA 0183 日志（最多 4 MiB）作为批处理运行，并由会话 TOML 声明船舶限制：返回评分模型和每个历元的 0-100 分评分及扣分情况（回复会按状态统计数量，并列出前 200 个降级或不可信历元）。仅供参考；MODELLED。
jammertest_import	将已发布的 Jammertest 测试目录和发射计划（NPRA/jammertest-plan，MIT）作为预定真值读取（kshana jammertest import）：一个测试区域的时间段会变为接收机可信度事件，且每个标签都包含目录 ID 和年份。使用的是计划时间段，而非记录的实际空中发射时间；不会读取计划中的任何联系人字段。MODELLED。参见 docs/JAMMERTEST.md。
jammertest_score	根据该时间表对接收机日志评分（kshana jammertest score）：逐项测试返回检测延迟、漏报次数和恢复时间，以及所有时间段之外的误报。文本日志使用 log，二进制日志（ubx、sbf）使用 log_base64。签名包需要密钥：仅限命令行使用。仅供参考；MODELLED。
create_evidence_pack	为船舶日志的某个时间窗口创建签名证据包（kshana receiver-trust evidence）：包含该窗口的原始日志字节、配置、逐历元结果和原因、摘要页面，以及带有每个 SHA-256 和哈希链的清单，并使用 Ed25519 签名。不会返回或记录签名种子；若未提供种子，则会使用一次性密钥，因此该证据包证明完整性，而非身份。此为技术记录，不构成法律意见。参见 docs/EVIDENCE-PACKS.md。
attach_evidence_timestamp	在内存中将 RFC 3161 时间戳令牌（.tsr 字节的 base64 编码）绑定到证据包（kshana evidence attach-timestamp）；带有令牌的证据包仍必须通过验证。不会检查时间戳机构的签名：请使用 openssl ts -verify。
verify_evidence_pack	验证证据包（kshana evidence verify）：检查每个哈希、哈希链、签名；若提供签名者公钥和完整日志，还会检查签名者身份以及该片段是否来自该日志。会列出每项失败及其文件。verdict 为 verified（签名者已固定）、intact-signer-not-pinned（所有检查均通过，但未提供公钥，因此无法确认签名者身份）或 failed；若证据包没有时间戳令牌，require_timestamp 会使验证失败。
generate_training_nmea	根据 nmea-scenario TOML（干扰、位置拖偏、时间欺骗、重放延迟）为船员培训生成合成桥楼 NMEA 0183 数据，并附上教员日志（kshana-nmea-training/1）；结果由种子确定。仅生成文本：不会合成 RF 或 IQ 数据，也不会发送任何内容；绝不可用于船舶的实时导航系统。回复包含前 2000 行。
build_interference_map	根据 ADS-B 或 AIS 位置报告的 CSV 文本（最多 4 MiB）生成 GNSS 干扰地图：每个 UTC 日生成一个 kshana-interference-map/v1 GeoJSON，仅提供汇总数据（不含标识符，并隐去少于 5 架不同飞机或艘不同船舶的网格），且内嵌数据集许可证。网格降级并不能证明原因是干扰；这不是预测。MODELLED。参见 docs/INTERFERENCE-MAP.md。
export_test_bench	导出场景中的载具运动和事件，供实验室 GNSS 模拟器使用（kshana bench-export）：运动 CSV 和 JSON、NMEA、航点及事件文本；不会写入磁盘。适用类型：gnss-ins、jamming、gnss-sim。不包含信号：导出的内容都不会生成、模拟或驱动射频或基带信号；信号由模拟器及其操作人员提供。参见 docs/TEST-BENCH.md。
create_round_trip_pack	创建签名实验室往返测试包（kshana evidence round-trip）：包含场景、实验室的 kshana.test-conditions/1 文档、接收机日志及其根据所述事件得出的评分，并通过哈希关联。如果测试条件与评分事件不一致，则拒绝处理。不包含信号；此为技术记录，不构成认证。
iq_sweep	在工作目录中使用多种跟踪环路设计重放一段 IQ 录制（kshana iq sweep）：逐设计和 PRN 返回稳态相位抖动和码抖动、锁定比例以及平均 C/N0。每次调用最多处理 256 个（设计，PRN）通道；片段必须符合样本预算。
iq_monitor	在工作目录中的 IQ 录制上运行干扰和欺骗检测监测器（kshana iq monitor）：宽带功率和频谱监测器，以及根据已学习基线进行逐卫星 C/N0 和信号质量监测。回复包含序列名称和长度，以及最多 200 个事件；可按需将完整报告作为文件返回。事件表示某个测量值偏离了基线，但不说明原因。MODELLED。
iq_labfit	根据 iq-labfit 场景中的实验室运行记录拟合跟踪环路失锁模型（kshana iq labfit）；日志以内联 text 或 base64 形式提供（不接受 path）。不读取或写入任何文件。MODELLED。
iq_test_conditions	验证以文本形式提供的 kshana.test-conditions/1 文件，并返回解析后的测试条件及其哈希。仅接受内联输入。
compliance_report	根据以文本形式提供的结果文档填充公共框架映射（kshana compliance-report）：说明六种韧性框架和标准（美国 DHS Resilient PNT framework v2.0、IMO ships、EASA aviation、NIS2 Article 21、EN 16803、NIST IR 8323r1）中哪些条目有运行结果支持作为证据、哪些没有，以及每个条目的差距。接受 runs，格式为 {label, result, scenario?}（最多 64 项，总计 4 MiB）。某个状态表示这些运行结果支持该条目所列能力的证据；这并不代表符合某个框架，也不是对任何产品的评级或批准。每份报告都会返回 statement；请逐字展示。MODELLED。参见 docs/compliance/。
compliance_mapping	以 Markdown 形式返回静态映射表（或在提供 sources 时，返回其引用的带版本和 URL 的来源文档），并以同一声明开头。无需提供运行结果。
trust_telemetry	使用 kshana trust-telemetry 编码器，将可信数据流（JSON 行）或 receiver-trust 结果转换为 Prometheus 文本、CEF 或 LEEF syslog 行、OTLP JSON 负载，或 Home Assistant MQTT 发现和状态行。回复中为文本：不会发送或提供任何内容，也不会读取时钟。仅供参考。
fit_imu_log	通过 Allan 偏差法，根据静止 IMU 日志（CSV 或 EuRoC）拟合 hybrid 和 fusion 场景的加速度计和陀螺仪参数，并提供可直接粘贴的 [accel_classical] 表和日志的 SHA-256（kshana imu-fit）。输入为文本，输出为 JSON；MODELLED。
list_standards_packs	列出标准包（kshana standards-pack list）：用于 DHS Resilient PNT framework 测试配置文件（级别 1 至 4）、IMO MSC.1/Circ.1575 和 ICAO Doc 9849 Appendix F 的评分场景集。
run_standards_pack	根据运行前声明的标准运行一个标准包（kshana standards-pack run）：每项测试返回 MET、NOT MET 或 NEEDS INPUT，以及测量值和预期值；可将报告交给 compliance_report 查看对应条目。MODELLED；不对任何产品评级。
lunanet_afs_check	根据 LNIS V5 AD1 Volume A（LSIS-AFS V1.0，2025 年 1 月 29 日）检查 LunaNet Augmented Forward Signal：spec（根据文档中印刷的代码表和示例检查实现）、symbols（符号流：同步模式、SB1、FID、TOI 连续性）或 generate（测试流）。不验证子帧 2 至 4 的 LDPC 和 CRC-24Q；不会写入信号。
score_benchmark	根据真值文件对 kshana-bench 提交进行评分；两者均为 JSON 文本（kshana bench score、bench/SPEC.md）：返回结果文件，其中包含规范版本、数据划分、输入哈希和任务指标。MODELLED；仅描述日志或语料库，绝不描述产品。
render_leaderboard	将 kshana-bench 结果文件渲染为静态排行榜页面（HTML 文本）；每个文件都会先经过验证。
trust_telemetry	使用 kshana trust-telemetry 编码器，将可信数据流（JSON 行）或 receiver-trust 结果转换为 Prometheus 文本、CEF 或 LEEF syslog 行，或 OTLP JSON 负载。回复中为文本：不会发送或提供任何内容，也不会读取时钟。仅供参考。
route_exposure	计算一条路线在一个或多个干扰地图的降级、未降级、未评估和未观测网格中所占的长度比例；可选设定日期范围。未观测网格并不证明路线畅通。
iq_signals	显示 GNSS IQ 层的配置：IQ 工具接受的信号名称、IQ 文件工具是否已启用、工作目录以及每次调用的样本预算。请先调用此工具。
iq_info	无需处理即可描述工作目录中的一段 IQ（同相和正交）录制：格式、采样率、中心频率、样本数、持续时间、数据文件及大小（kshana iq info）。
iq_scene	在工作目录中生成多卫星 GNSS IQ 场景（kshana iq scene）：生成指定的多普勒／C/N0 配置文件，或根据 RINEX 导航文件生成真实广播星历几何，并可选用信号级传播信道。回复包含写入的文件及其字节数，以及每颗卫星真值的首个历元。
iq_acquire	对录制中的一个或多个 PRN（伪随机噪声码）进行 FFT（快速傅里叶变换）捕获（kshana iq acquire），可选在前端处理阶段之后执行：逐 PRN 返回是否捕获成功、多普勒、码相位、峰值统计量和阈值；surface_out（单个 PRN）会保留完整的多普勒 × 码相位相关面，并进行精细多普勒优化。
iq_track	先捕获，再使用 DLL/PLL/FLL（延迟锁定环／相位锁定环／频率锁定环）组进行跟踪（kshana iq track）；可使用工作目录中 kshana.loop-design/1 TOML 文件指定的环路（design），或使用内置设计，并可选重新捕获（reacquire）：逐通道返回历元数、最终多普勒、最终和平均 C/N0、相位锁定和码锁定比例、结束时是否锁定、最终锁定状态、错误锁定和重新捕获次数，以及设计名称和哈希。跟踪采用有界内存流式处理；逐历元输出仅写入文件（epochs_out：E/P/L、鉴别器、环路状态、C/N0、锁定状态，格式为 .csv/.jsonl/.bin；events_out）。
iq_frontend	对录制应用接收机前端和干扰缓解 DSP（数字信号处理：带通、陷波、空白处理、剔除、AGC、量化器），并写入新的录制文件（kshana iq frontend）。
iq_campaign	运行实验室重放测试活动（kshana iq campaign）：录制文件（每个文件附有说明实验室已知真值的测试条件文件）× 前端链 × 环路设计。对每个组合项进行评分，包括失锁时间、重新捕获时间、相对于指定 J/S 的 C/N0 降级（附带标记为 MODELLED 的解析参考值）、错误锁定率、PLL/DLL 抖动和可用性。支持增量运行和恢复：每次调用运行符合样本预算（或 max_cells）的待处理组合项。
iq_campaign_status	查看测试活动输出文件夹的进度：已完成和待处理的组合项，以及完成后的摘要。仅读取文件。
每个工具都是对 kshana 库公开函数的轻量、忠实封装——这里没有新增仿真逻辑，因此 Agent 运行的正是经过验证的引擎。

GNSS IQ 工具：输入文件，输出精简 JSON

IQ 录制文件可达数 GB，因此 iq_* 工具不会通过协议传递采样数据。它们遵循以下约定：

• 工作目录。 服务仅读写 KSHANA_MCP_IQ_DIR 指定文件夹内的 IQ 文件。所有路径参数都相对于该目录（绝对路径必须解析到该目录内）；检查前会先通过符号链接解析输入路径；输出文件夹必须已存在于该目录内；只有设置 overwrite: true 时才会替换现有输出。未设置时，IQ 文件工具处于关闭状态，并会说明如何启用；其他工具不受影响。
• 采样预算。 一次调用最多生成或处理 KSHANA_MCP_IQ_MAX_SAMPLES 个复数采样（默认值为 50 000 000）。按字节计算，cf32_le 为 400 MB（每个复数采样 8 字节），ci16_le 为 200 MB（每个复数采样 4 字节），ci8 为 100 MB（每个复数采样 2 字节）；场景默认写为 cf32_le，除非 format 指定其他格式。检查会在任何操作开始前执行，超出限制时会指出符合要求的时长或 max_seconds 值。
• 精简回复。 每个工具都返回一份 JSON 摘要，包含采集峰值、C/N0、锁定状态，以及每个输出文件的路径和字节数。各历元表格会写入你指定的 json_out / csv_out 文件。
• 拒绝未知参数，而不会忽略它们，因此拼错选项会导致错误。

每个工具都会在进程内运行与命令行 kshana iq 相同的代码路径。这一层纯属软件：它为软件接收机写入文件，不驱动任何无线电硬件。IQ 层不会合成干扰或欺骗信号，也绝不会发射任何内容。（单独的 spectrum 场景类型可以将解析干扰源的 IQ 快照写入文件。）

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

使用 Docker 镜像时，挂载文件夹并将变量指向它： docker run --rm -i -v "$PWD/iq:/iq" -e KSHANA_MCP_IQ_DIR=/iq ghcr.io/ashfordeou/kshana-mcp。

每种类型都可运行

run_scenario 根据场景的 kind 分派，因此 list_scenario_kinds 列出的每种类型都可以通过它运行。这包括较新的系列，每个系列都有打包示例可供 Agent 获取：

能力	类型	可供参考的示例
频谱与瀑布图	spectrum	l-band-waterfall-jamming
太阳系	solar-system	solar-system-tour
任意天体周围的星座	constellation-design、body-pnt	lunar-relay-constellation、europa-surface-pnt
任务活动：串联阶段、扫描、蒙特卡洛（带种子的随机集合）、组合	campaign	campaign-sweep-jammer-power
低地球轨道（LEO）导航：信号设计	leo-signal	leo-band-trade
LEO 导航：过境链路预算	leo-pass	leo-pass-iridium
LEO 导航：导航电文	leo-navmsg	leo-navmsg-encode-decode
LEO 导航：融合定位与授时	leo-pvt、leo-ppp、ntn-positioning、leo-pnt-chain	leo-doppler-positioning、leo-pnt-end-to-end

使用带 kind 参数的 list_example_scenarios，可列出该类型的所有打包示例。 动画、报告和互操作性导出不是场景类型，而是某次运行的视图；animate_scenario、report_scenario 和 export_interop 会为其适用的任何场景返回这些内容。

不支持：研究套件（kshana --study <suite.toml>），因为套件会在磁盘上指定同级场景文件，而场景工具不会读取文件。请使用 run_scenario 逐一运行其中的场景。（IQ 工具确实会读取和写入文件，但仅限其工作目录内。）

安装 MCP 服务

这不是经过类型认证的导航设备，仅供参考；操作员仍需对导航负责。 服务运行在你的计算机上；不会向 Ashforde OÜ 发送任何内容。

选择任意一种渠道；它们运行的都是同一服务。各客户端的配置片段（Claude Desktop、Claude Code、Cursor、 VS Code、Windsurf、Zed、Goose、Codex CLI、Gemini CLI、Continue）请参阅 docs/MCP-INSTALL.md。

渠道	命令或按钮	要求	固定版本形式
Claude Desktop 扩展	双击适用于你系统的 .mcpb：macOS（Apple 芯片） · macOS（Intel） · Windows	无	v0.39.0 的 kshana-mcp-<target>.mcpb
Cursor（一键安装）	npx（Node） · Docker	Node 或 Docker	[email protected] / ghcr.io/ashfordeou/kshana-mcp:0.39.0
VS Code（一键安装）	npx（Node） · Docker · Insiders（npx）	Node 或 Docker	[email protected] / ghcr.io/ashfordeou/kshana-mcp:0.39.0
Claude Code	claude mcp add kshana -- npx -y [email protected] · 插件：/plugin marketplace add ashfordeOU/kshana 然后执行 /plugin install kshana@ashforde	Node（或 Docker）	[email protected]
npx	npx -y [email protected]	Node 18+	[email protected]
uvx / pipx	uvx kshana-mcp==0.39.0 · pipx run kshana-mcp==0.39.0	Python 3.9+，以及 uv 或 pipx	kshana-mcp==0.39.0
Docker	docker run -i --rm ghcr.io/ashfordeou/kshana-mcp:0.39.0	Docker	ghcr.io/ashfordeou/kshana-mcp:0.39.0
Homebrew	brew install ashfordeOU/tap/kshana-mcp	brew	v0.39.0 对应的 formula
Scoop	scoop bucket add ashforde https://github.com/ashfordeOU/scoop-bucket 然后执行 scoop install kshana-mcp	Scoop（Windows）	v0.39.0 对应的清单
winget	winget install AshfordeOU.KshanaMcp	winget（Windows）	--version 0.39.0
cargo	cargo install kshana-mcp --version 0.39.0	Rust 1.88+	kshana-mcp 0.39.0
预编译二进制文件	发布页面：kshana-mcp（Linux x86-64）、kshana-mcp-<target>[.exe]，由 SHA256SUMS 和 gh attestation verify 验证	无	v0.39.0
MCP 注册表	io.github.ashfordeOU/kshana-mcp（可由支持注册表的客户端查找）	支持注册表的客户端	0.39.0
远程（可流式传输的 HTTP）	kshana-mcp --http 127.0.0.1:8080；可自托管，参见 https://github.com/ashfordeOU/kshana/blob/main/docs/deploy/mcp-http.md	你自己的主机	v0.39.0

从检出副本或 git 安装（开发版）：

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

HTTP 模式（可自托管）

kshana-mcp --http 127.0.0.1:8080 会在 /mcp 通过可流式传输的 HTTP 提供相同的工具。它仅绑定到环回地址；非环回地址需要使用 --allow-remote，并在 KSHANA_MCP_HTTP_TOKEN 中设置 bearer 令牌；IQ 文件工具处于关闭状态；请求大小、耗时和并发数均有限制；不会发送 CORS 标头。Kshana 不托管端点：你需要自行托管。请参阅 docs/deploy/mcp-http.md。

cargo install 会将 kshana-mcp 安装到你的 PATH 中（通常是 ~/.cargo/bin/kshana-mcp）。 服务通过 stdio 使用 JSON-RPC（JSON 远程过程调用）；日志会写入 stderr。从源代码构建需要 Rust 工具链 ≥ 1.88（修补后的 rmcp 2.x SDK 需要此版本；kshana 库本身只需要 1.85）；Docker 镜像则不需要。

将其注册到客户端

几乎所有 MCP 客户端都使用相同的 mcpServers 配置块——通过绝对路径注册 kshana-mcp 二进制文件：

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

或者，使用 Docker 镜像而非本地二进制文件（无需 PATH）：

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

该配置块的位置取决于客户端：

• Cursor — ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（按项目）。
• JetBrains AI Assistant / Junie — Settings → Tools → AI Assistant → Model Context Protocol → Add → As JSON，粘贴配置块，然后彻底重启 IDE（集成开发环境）。
• 桌面助手 — 大多数使用形如 …_config.json 的文件，且结构相同，均为 mcpServers； 请查阅客户端文档了解文件位置。
• CLI Agent — 许多支持通过 mcp add / mcp.json 机制传入相同的 JSON。

请始终使用二进制文件的绝对路径。可在 env 中设置 RUST_LOG=debug 以排查问题 （诊断信息会写入 stderr；stdout 专用于 JSON-RPC 协议）。

试用

注册后，可以向助手提出如下问题：

• “列出 Kshana 的场景类型。” → list_scenario_kinds
• “给我看一个 Kshana 频谱示例并运行它。” → list_example_scenarios、 get_example_scenario、run_scenario
• “运行 Kshana 时钟保持场景，阈值设为 20 ns，GNSS 中断 2 小时；量子与经典的保持性能有何不同？” → run_scenario
• “将该 GPS（全球定位系统）星座导出为 SP3。” → export_sp3
• “将 realtime-frame-eop 表以 CSV 格式提供给我。” → export_table_csv
• “将该 Iridium 过境显示在 Cesium 地球仪上。” → list_export_formats、export_interop
• “为干扰行动制作动画。” → animate_scenario
• “给我该次运行的报告及其可复现性记录。” → report_scenario
• “创建一个持续一秒、包含 PRN 3 和 17 的 GPS L1 场景，然后获取并跟踪信号。” → iq_signals、iq_scene、iq_acquire、iq_track

设计说明 — 为何使用独立 crate

该服务是一个独立的、排除在工作区之外的 crate，拥有自己的 Cargo.lock，因此官方 Rust MCP SDK（软件开发工具包）rmcp 及其异步运行时不会进入已发布的 kshana crate 依赖关系图：库或 Python 用户不会编译自己并不运行的服务。（最初将其拆分出来，是因为 rmcp 使用edition 2024，需要 rustc ≥ 1.85， 而当时主 crate 承诺支持 1.75。现在库声明的最低版本为 1.85；此服务声明为 1.88，这是经过安全修补的 rmcp 2.x 的最低版本。）持续集成（CI） 会单独检查此 crate——运行测试，并针对其锁定文件执行 cargo deny。rmcp 的许可证依赖树符合要求 （Apache-2.0/MIT/BSD），因此，与它所对应的 xval/anise-frames 交叉验证 crate 不同，此次拆分并非出于许可证方面的考虑。

许可证：AGPL-3.0-only，即 GNU Affero 通用公共许可证第 3 版（仅限此版本），或 Ashforde OÜ 提供的 商业许可证；请参阅代码仓库中的 LICENSING.md。