kshana-mcp: pergunte ao seu assistente de IA, e o motor responde

kshana-mcp é um servidor de Model Context Protocol (MCP) para o Kshana, o simulador de código aberto para a resiliência de PNT (posicionamento, navegação e temporização). Permite que um assistente de IA (inteligência artificial) execute o motor real e leia o seu JSON (JavaScript Object Notation), em vez de adivinhar a matemática. Comunica por stdio (entrada e saída padrão) com qualquer cliente compatível com MCP, incluindo o Cursor e o JetBrains AI Assistant / Junie.

A matemática para a qual o Kshana é validado é exatamente aquela em que um modelo de linguagem adivinha mal: propagação de órbita SGP4 (Simplified General Perturbations 4), referenciais da IAU (União Astronómica Internacional), desvios de Allan, disponibilidade de GNSS (Global Navigation Satellite System) e DOP (diluição da precisão), níveis de proteção ARAIM (advanced receiver autonomous integrity monitoring), fusão de GNSS e INS (sistema de navegação inercial) e modelos de sensores quânticos. Faça uma pergunta; o assistente executa um cenário real e obtém figuras de mérito com a sua proveniência e a sua etiqueta VALIDATED ou MODELLED.

Ferramentas#

Cada ferramenta é um invólucro fino e fiel de uma função pública da biblioteca kshana — nenhuma lógica de simulação nova reside aqui, pelo que um agente executa exatamente o motor validado.

As ferramentas GNSS IQ: ficheiros à entrada, JSON compacto à saída#

As gravações IQ atingem gigabytes, pelo que as ferramentas iq_* nunca passam amostras pelo protocolo. Seguem um só contrato:

• Um diretório de trabalho. O servidor lê e escreve ficheiros IQ apenas dentro da pasta indicada por KSHANA_MCP_IQ_DIR. Cada argumento de caminho é relativo a ela (um caminho absoluto tem de resolver para dentro dela); as entradas são resolvidas através de ligações simbólicas antes da verificação, a pasta de uma saída tem de já existir dentro dela, e uma saída existente só é substituída com overwrite: true. Se não estiver definida, as ferramentas de ficheiros IQ ficam desligadas e dizem como as ativar; todas as outras ferramentas não são afetadas.
• Um orçamento de amostras. Uma chamada gera ou processa no máximo KSHANA_MCP_IQ_MAX_SAMPLES amostras complexas (predefinição 50 000 000). Em bytes, isso são 400 MB como cf32_le (8 bytes por amostra complexa), 200 MB como ci16_le (4 bytes) e 100 MB como ci8 (2 bytes); uma cena é escrita como cf32_le a menos que format indique outra coisa. A verificação corre antes de qualquer trabalho, e a recusa indica a duração ou o max_seconds que cabe.
• Respostas compactas. Cada ferramenta responde com um resumo JSON: picos de aquisição, C/N0, estado de bloqueio e todos os ficheiros escritos com o seu caminho e contagem de bytes. As tabelas por época vão para os ficheiros json_out / csv_out que indicar.
• Os argumentos desconhecidos são recusados, não ignorados, pelo que uma opção com erro ortográfico é um erro.

Cada ferramenta executa o mesmo caminho de código que kshana iq na linha de comandos, no mesmo processo. A camada é apenas software: escreve ficheiros para recetores de software e não aciona nenhum equipamento de radiofrequência. A camada IQ não acrescenta síntese de interferência nem de spoofer, e nada é alguma vez transmitido. (O tipo de cenário spectrum, separado, pode escrever instantâneos IQ analíticos de jammer num ficheiro.)

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

Com a imagem Docker, monte a pasta e aponte a variável para ela: docker run --rm -i -v "$PWD/iq:/iq" -e KSHANA_MCP_IQ_DIR=/iq ghcr.io/ashfordeou/kshana-mcp.

Todos os tipos de cenário são acessíveis#

run_scenario despacha segundo o kind do cenário, pelo que todos os tipos de cenário que list_scenario_kinds indica são executados através dele. Isso inclui as famílias mais recentes, cada uma com exemplos incluídos que um agente pode obter:

list_example_scenarios com um kind indica todos os exemplos incluídos desse tipo de cenário. As animações, os relatórios e as exportações de interoperabilidade não são tipos de cenário: são vistas de uma execução, e animate_scenario, report_scenario e export_interop devolvem-nas para qualquer cenário a que se apliquem.

Não servidos: os conjuntos de estudo (kshana --study <suite.toml>), porque um conjunto indica ficheiros de cenário irmãos em disco e as ferramentas de cenário não leem ficheiros. Execute cada membro com run_scenario. (As ferramentas IQ leem e escrevem ficheiros, mas apenas dentro do seu diretório de trabalho.)

Instalar o servidor MCP#

Consultivo, não um equipamento de navegação homologado: o operador continua a ser responsável pela navegação. O servidor é executado no seu computador; nada é enviado à Ashforde OÜ.

Uma passagem que menciona clientes de IA de terceiros é omitida aqui; consta de mcp/kshana-mcp/README.md no GitHub.

A partir de um checkout ou de git (desenvolvimento):

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

Modo HTTP (alojamento próprio)#

kshana-mcp --http 127.0.0.1:8080 serve as mesmas ferramentas sobre HTTP em fluxo contínuo em /mcp. Liga-se apenas ao loopback; um endereço que não seja de loopback precisa de --allow-remote e de um token de portador em KSHANA_MCP_HTTP_TOKEN; as ferramentas de ficheiros IQ ficam desligadas; o tamanho, o tempo e a concorrência dos pedidos são limitados; não é enviado nenhum cabeçalho CORS. O Kshana não aloja um ponto de acesso: é o utilizador quem o aloja. Ver docs/deploy/mcp-http.md.

cargo install coloca kshana-mcp no seu PATH (tipicamente ~/.cargo/bin/kshana-mcp). O servidor fala JSON-RPC (JSON remote procedure call) sobre stdio; os registos vão para o stderr. Compilar a partir do código-fonte exige uma cadeia de ferramentas Rust ≥ 1,88 (o SDK rmcp 2.x corrigido exige-o, tal como a biblioteca kshana); a imagem Docker não exige nenhuma.

Registá-lo num cliente#

Praticamente todos os clientes MCP usam o mesmo bloco de configuração mcpServers — registe o binário kshana-mcp por caminho absoluto:

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

Ou, com a imagem Docker em vez de um binário local (sem necessidade de PATH):

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

O local onde esse bloco fica depende do cliente:

• Cursor — ~/.cursor/mcp.json (global) ou .cursor/mcp.json (por projeto).
• JetBrains AI Assistant / Junie — Settings → Tools → AI Assistant → Model Context Protocol → Add → As JSON, cole o bloco e reinicie por completo o IDE (ambiente de desenvolvimento integrado).
• Assistentes de ambiente de trabalho — a maioria usa um …_config.json com a mesma estrutura mcpServers; consulte a documentação do seu cliente para saber a localização do ficheiro.
• Agentes de CLI — muitos aceitam o mesmo JSON através de um mecanismo mcp add / mcp.json.

Use sempre um caminho absoluto para o binário. Defina RUST_LOG=debug em env para diagnosticar problemas (o diagnóstico vai para o stderr; o stdout está reservado ao protocolo JSON-RPC).

Experimente#

Depois de registado, peça ao seu assistente coisas como:

• "Liste os tipos de cenário do Kshana." → list_scenario_kinds
• "Mostre-me um exemplo de spectrum do Kshana e execute-o." → list_example_scenarios, get_example_scenario, run_scenario
• "Execute o cenário de holdover de relógio do Kshana com um limiar de 20 ns e uma falha de GNSS de 2 horas; qual é o holdover quântico face ao clássico?" → run_scenario
• "Exporte essa constelação GPS (Global Positioning System) como SP3." → export_sp3
• "Dê-me a tabela realtime-frame-eop como CSV." → export_table_csv
• "Coloque essa passagem de Iridium num globo Cesium." → list_export_formats, export_interop
• "Anime a campanha de jamming." → animate_scenario
• "Dê-me o relatório dessa execução, com o seu registo de reprodutibilidade." → report_scenario
• "Crie uma cena GPS L1 de um segundo com os PRN 3 e 17, depois adquira-a e siga-a." → iq_signals, iq_scene, iq_acquire, iq_track

Nota de conceção — porque um crate separado#

O servidor é um crate autónomo, excluído do workspace, com o seu próprio Cargo.lock, pelo que o SDK (software development kit) oficial de MCP para Rust, rmcp, e o seu runtime assíncrono nunca entram no grafo de dependências do crate kshana publicado: quem usa a biblioteca ou Python não compila um servidor que não executa. (Foi separado primeiro porque rmcp é edition 2024, o que exige rustc ≥ 1,85, enquanto o crate principal prometia então 1,75. A biblioteca e este servidor declaram agora ambos 1,88, o mínimo do rmcp 2.x corrigido em segurança e dos crates RustCrypto atualizados.) A integração contínua (CI) condiciona este crate por si só — testes e cargo deny face ao seu ficheiro de bloqueio. A árvore de licenças do rmcp está limpa (Apache-2.0/MIT/BSD), pelo que, ao contrário do crate de validação cruzada xval/anise-frames, que de resto espelha, a separação não tem que ver com licenciamento.

Licença: AGPL-3.0-only, a GNU Affero General Public License versão 3 apenas (ou uma licença comercial da Ashforde OÜ; ver o LICENSING.md do repositório).