Tradução automática, não revista por um falante nativo. O inglês é a referência.

APIs e integraçõesEditar no GitHubFonte: docs/deploy/mcp-http.md

Execução do kshana-mcp sobre HTTP (alojamento próprio)

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

O Kshana não aloja um ponto de acesso. Não existe nenhum servidor kshana partilhado a que um cliente se possa ligar. Executa-o na sua própria máquina, contentor ou projeto na nuvem, e é o utilizador quem controla o seu acesso e o seu custo. O servidor 0.40.0 é o que consta deste repositório: os seus valores trazem as suas etiquetas VALIDATED ou MODELLED exatamente como em stdio.

As predefinições seguras#

Controlo Comportamento
Endereço de ligação Apenas loopback (127.0.0.1, ::1). Uma porta isolada (--http 8080) significa 127.0.0.1:8080.
Non-loopback Precisa de --allow-remote e de um token de portador na variável de ambiente KSHANA_MCP_HTTP_TOKEN (16 carateres ou mais). Sem ambos, o servidor recusa-se a arrancar. Com ambos, imprime um aviso de que está a escutar para além desta máquina.
Autenticação Authorization: Bearer <token> em cada pedido quando é definido um token (pode ser definido também em loopback). Comparado em tempo constante. Em falta ou errado: 401.
Sistema de ficheiros Nenhum. As ferramentas de ficheiros IQ (iq_*) ficam desligadas no modo HTTP seja o que for que KSHANA_MCP_IQ_DIR indique; todas as outras ferramentas recebem o seu cenário em linha e recusam um que indique um ficheiro. Nenhum argumento de ferramenta lê ou escreve um caminho.
Tamanho do corpo --max-body-bytes, predefinição 5 MiB (o limite do cenário é 4 MiB). Acima dele: 413, quer o comprimento seja declarado quer o corpo seja fragmentado.
Tempo de resposta --request-timeout-secs, predefinição 120. Acima dele: 408. Isto limita quanto tempo um chamador espera, não o trabalho: uma execução já em curso não pode ser interrompida, pelo que continua depois do 408 e termina em segundo plano.
Concorrência --max-concurrent, predefinição 8. Além dele, um pedido recebe 503 com Retry-After de imediato; nenhum fica em fila.
Conjunto de trabalho Cada chamada de ferramenta corre numa thread bloqueante dentro de um conjunto de --max-concurrent posições, nunca nos trabalhadores assíncronos, pelo que uma execução longa não impede o servidor de responder. Uma posição só é libertada quando a própria execução termina, não quando o chamador desiste: as execuções abandonadas não se podem, por isso, acumular para além do tamanho do conjunto, e uma chamada que encontre o conjunto cheio é recusada por ocupação.
Orçamento de trabalho Um cenário que peça muito mais do que os exemplos incluídos é recusado antes de ser executado: mais de 1000 realizações de Monte Carlo (runs), uma grelha de parâmetros com mais de 1000 nós, mais de 5000 execuções-membro (nós da grelha vezes realizações) ou uma grelha de tempo com mais de 2 milhões de épocas. O erro indica o campo a reduzir. O mesmo orçamento aplica-se em stdio; a linha de comandos kshana não tem nenhum.
CORS Nunca é enviado nenhum cabeçalho Access-Control-*. Um pedido que traga um cabeçalho Origin é recusado (403), a menos que seja indicado com --allow-origin <scheme://host[:port]>; * não é aceite.
Cabeçalho Host Verificado face aos nomes de loopback, ou ao endereço de ligação mais cada --allowed-host. Por trás de um proxy ou num URL de plataforma, passe --allowed-host your.domain. Qualquer outra coisa: 403.
Sessões Nenhuma. Cada POST recebe uma resposta JSON; não é mantida nenhuma tabela de sessões nem nenhum fluxo de eventos enviados pelo servidor aberto.

O TLS não é terminado por kshana-mcp. Quando for acessível para além de uma só máquina, coloque HTTPS à sua frente (o TLS da sua plataforma, ou um proxy inverso) e mantenha o token secreto; um token de portador sobre HTTP simples pode ser lido na rede.

Local#

kshana-mcp --http 127.0.0.1:8080

Configuração do cliente (um cliente de URL; acrescente o cabeçalho só quando é definido um token):

{ "mcpServers": { "kshana": { "url": "http://127.0.0.1:8080/mcp",
    "headers": { "Authorization": "Bearer ${KSHANA_MCP_HTTP_TOKEN}" } } } }

Docker#

export KSHANA_MCP_HTTP_TOKEN="$(openssl rand -hex 32)"
docker run --rm -p 127.0.0.1:8080:8080 -e KSHANA_MCP_HTTP_TOKEN \
  ghcr.io/ashfordeou/kshana-mcp:0.40.0 \
  --http 0.0.0.0:8080 --allow-remote --allowed-host localhost:8080 --allowed-host 127.0.0.1:8080

Dentro do contentor, o servidor tem de escutar em 0.0.0.0, pelo que precisa de --allow-remote e do token. Publicar a porta como 127.0.0.1:8080:8080 mantém-na na sua máquina; retire o 127.0.0.1: apenas quando pretender expô-la e, nesse caso, termine o TLS à sua frente. Os modelos de docker compose, Fly.io e Cloud Run constam de mcp-http/.

Modelos (é o utilizador quem os implanta; o Kshana não executa nenhum)#

Cada um executa a imagem publicada, define --allowed-host com o nome de anfitrião da plataforma que substitui no ficheiro e depende da plataforma para o HTTPS.

Defina um limite de CPU e de memória na plataforma#

O tempo limite, o conjunto e o orçamento limitam quanto trabalho é admitido, mas uma chamada admitida pode ainda usar um núcleo durante muito tempo e um resultado grande pode usar centenas de megabytes. Coloque também um limite rígido no contentor: os modelos pedem 2 CPU e 1 GiB (cpus e mem_limit no Compose, [[vm]] no Fly, resources.limits no Cloud Run). Mantenha --max-concurrent igual ou inferior ao número de CPU.

O que não é#

  • Não é um serviço multi-inquilino. Qualquer pessoa com o token executa simulações no seu equipamento; não há quotas por utilizador para além dos limites acima.
  • Consultivo, não um equipamento de navegação homologado: o operador continua a ser responsável pela navegação. As saídas do simulador são valores modelados ou validados para análise, como em todo o lado no Kshana.