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). Ele permite que um assistente de IA (inteligência artificial) execute o motor real e leia de volta seu JSON (JavaScript Object Notation), em vez de adivinhar a matemática. Fala por stdio (entrada e saída padrão) com qualquer cliente compatível com MCP, inclusive o Cursor e o JetBrains AI Assistant / Junie.

A matemática para a qual o Kshana é validado é exatamente onde 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 (sistema global de navegação por satélite) e DOP (diluição da precisão), níveis de proteção ARAIM (monitoramento avançado de integridade autônomo do receptor), 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 sua proveniência e seu rótulo 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 mora aqui, de modo que um agente executa exatamente o motor validado.

As ferramentas IQ de GNSS: arquivos na entrada, JSON compacto na saída#

As gravações IQ chegam a gigabytes, de modo que as ferramentas iq_* nunca passam amostras pelo protocolo. Elas seguem um único contrato:

• Um diretório de trabalho. O servidor lê e grava arquivos IQ apenas dentro da pasta nomeada por KSHANA_MCP_IQ_DIR. Todo argumento de caminho é relativo a ela (um caminho absoluto deve resolver-se dentro dela); as entradas são resolvidas por links simbólicos antes da verificação, a pasta de uma saída já deve existir dentro dela e uma saída existente só é substituída com overwrite: true. Sem definição, as ferramentas de arquivo IQ ficam desligadas e dizem como ativá-las; 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 (padrão 50.000.000). Em bytes, isso dá 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 é gravada como cf32_le a menos que format diga outra coisa. A verificação roda antes de qualquer trabalho, e a recusa nomeia 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 sincronismo e todo arquivo gravado com seu caminho e sua contagem de bytes. As tabelas por época vão para os arquivos json_out / csv_out que você nomear.
• Argumentos desconhecidos são recusados, não ignorados, de modo que uma opção com erro de grafia é um erro.

Cada ferramenta executa o mesmo caminho de código que kshana iq na linha de comando, no mesmo processo. A camada é só de software: grava arquivos para receptores por software e não aciona hardware de rádio. A camada IQ não acrescenta síntese de interferência nem de falsificador, e nada é jamais transmitido. (O tipo de cenário spectrum, separado, pode gravar em arquivo instantâneos IQ analíticos de interferidores.)

{
  "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.

Todo tipo é alcançável#

run_scenario despacha pelo kind do cenário, de modo que todo tipo que list_scenario_kinds nomeia roda por ele. Isso inclui as famílias mais novas, cada uma com exemplos incluídos que um agente pode obter:

list_example_scenarios com um kind nomeia todo exemplo incluído desse tipo. Animações, relatórios e exportações de interoperabilidade não são tipos: são vistas de uma execução, e animate_scenario, report_scenario e export_interop as devolvem para qualquer cenário ao qual se apliquem.

Não oferecidas: suítes de estudo (kshana --study <suite.toml>), porque uma suíte nomeia arquivos de cenário irmãos em disco e as ferramentas de cenário não leem arquivo. Execute cada membro com run_scenario. (As ferramentas IQ leem e gravam arquivos, apenas dentro de seu diretório de trabalho.)

Instalar o servidor MCP#

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

Uma passagem que nomeia clientes de IA de terceiros fica de fora aqui; ela está em mcp/kshana-mcp/README.md no GitHub.

A partir de uma cópia ou do git (desenvolvimento):

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

Modo HTTP (hospedagem própria)#

kshana-mcp --http 127.0.0.1:8080 serve as mesmas ferramentas por HTTP em fluxo contínuo em /mcp. Faz bind apenas em loopback; um endereço fora de loopback exige --allow-remote e um token de portador (bearer) em KSHANA_MCP_HTTP_TOKEN; as ferramentas de arquivo IQ ficam desligadas; o tamanho, o tempo e a concorrência das requisições são limitados; nenhum cabeçalho CORS é enviado. O Kshana não hospeda um endpoint: você o hospeda por conta própria. Veja docs/deploy/mcp-http.md.

cargo install coloca kshana-mcp no seu PATH (normalmente ~/.cargo/bin/kshana-mcp). O servidor fala JSON-RPC (chamada de procedimento remoto em JSON) por stdio; os logs vão para stderr. Compilar a partir do código-fonte exige uma toolchain Rust ≥ 1,88 (o SDK rmcp 2.x corrigido a exige, e a biblioteca kshana também); a imagem Docker não precisa de nenhuma.

Registre-o em um cliente#

Praticamente todo cliente MCP usa o mesmo bloco de configuração mcpServers — registre 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"]
    }
  }
}

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 depois reinicie completamente a IDE (ambiente de desenvolvimento integrado).
• Assistentes de desktop — a maioria usa um …_config.json com o mesmo formato mcpServers; consulte a documentação do seu cliente para o local do arquivo.
• Agentes de CLI — muitos aceitam o mesmo JSON por um mecanismo mcp add / mcp.json.

Use sempre um caminho absoluto para o binário. Defina RUST_LOG=debug em env para diagnosticar (os diagnósticos vão para stderr; stdout é reservado ao protocolo JSON-RPC).

Experimente#

Depois de registrado, pergunte 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 interrupção de GNSS de 2 horas; qual é o holdover quântico contra o clássico?" → run_scenario
• "Exporte essa constelação GPS (Sistema de Posicionamento Global) como SP3." → export_sp3
• "Dê-me a tabela realtime-frame-eop como CSV." → export_table_csv
• "Ponha essa passagem do Iridium em um globo Cesium." → list_export_formats, export_interop
• "Anime a campanha de jamming." → animate_scenario
• "Dê-me o relatório dessa execução, com seu registro de reprodutibilidade." → report_scenario
• "Faça uma cena GPS L1 de um segundo com os PRNs 3 e 17, depois adquira e rastreie." → iq_signals, iq_scene, iq_acquire, iq_track

Nota de projeto — por que um crate separado#

O servidor é um crate independente, excluído do workspace, com seu próprio Cargo.lock, de modo que o SDK oficial de MCP em Rust (kit de desenvolvimento de software) rmcp e seu runtime assíncrono nunca entram no grafo de dependências do crate kshana publicado: quem usa a biblioteca ou o Python não compila um servidor que não executa. (Ele foi separado primeiro porque rmcp é edition 2024, exigindo rustc ≥ 1,85, enquanto o crate principal então prometia 1,75. A biblioteca e este servidor agora declaram ambos 1,88, o piso do rmcp 2.x corrigido quanto à segurança e dos crates RustCrypto atualizados.) A integração contínua (CI) controla este crate por conta própria — testes e cargo deny contra o seu lockfile. A árvore de licenças do rmcp está limpa (Apache-2.0/MIT/BSD), de modo que, ao contrário do crate de validação cruzada xval/anise-frames, que ele de resto espelha, a separação não tem a 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Ü; veja o LICENSING.md do repositório).