MCP

Esta página foi traduzida automaticamente e pode conter erros. Encontrou um problema? Use o link "Edit this page" para ajudar a corrigir.

A integração do Model Context Protocol (MCP) permite que assistentes de IA como Claude Code e Cursor inspecionem e interajam com um jogo Turian em execução em tempo real. Em vez de deduzir o estado, um LLM pode consultar a cena real, entidades, componentes e métricas de desempenho.

Como funciona

Claude Code / Cursor
      │  MCP (stdio, JSON-RPC 2.0)
      ▼
turian-cli mcp
      │  Remote Debug Protocol (TCP, port 7777)
      ▼
  Running game (debug server enabled)

O turian-cli mcp faz a ponte entre os dois protocolos. Ele lê as requisições MCP do stdin, encaminha-as ao servidor de depuração do jogo via TCP e retorna resultados estruturados.

Início rápido

1 — Habilite o servidor de depuração no seu jogo

No ponto de entrada do seu jogo, inicie o servidor de depuração antes do loop principal:

const debug = @import("debug");

var srv = debug.Server.init(allocator, .{});
defer srv.deinit(io);
try srv.start(io, .{ .ctx = &world, .getFn = myWorldProvider });

O servidor escuta em 127.0.0.1:7777 por padrão.

2 — Configure seu cliente MCP

Claude Code (~/.claude/mcp.json ou .mcp.json do projeto):

{
  "mcpServers": {
    "turian": {
      "command": "turian-cli",
      "args": ["mcp"]
    }
  }
}

Com token de autenticação (se o servidor de depuração foi iniciado com --token):

{
  "mcpServers": {
    "turian": {
      "command": "turian-cli",
      "args": ["mcp", "--token", "my-secret"]
    }
  }
}

Host/porta customizados:

{
  "mcpServers": {
    "turian": {
      "command": "turian-cli",
      "args": ["mcp", "--host", "192.168.1.10", "--port", "7778"]
    }
  }
}

3 — Inicie seu jogo e faça perguntas

Assim que o jogo estiver em execução e o Claude Code estiver conectado, você poderá perguntar:

"Quais cenas estão carregadas?"
"Inspecione a entidade Player."
"Quais são o FPS e o uso de memória atuais?"
"Liste todas as entidades com um componente Camera."

Ferramentas disponíveis

Ferramentas de leitura

Ferramenta	Descrição
`list_scenes`	Todas as cenas carregadas no momento e seus estados
`inspect_scene`	Cada entidade em uma cena com resumo dos componentes
`find_entities`	Filtra entidades por substring do nome ou tipo de componente
`scene_summary`	Snapshot completo compacto para orientação do LLM
`inspect_entity`	Transform + todos os campos de componentes de uma entidade
`get_component`	Valores dos campos de um componente específico em uma entidade
`get_metrics`	FPS, tempo de frame, memória, draw calls, contagens do ECS
`get_schema`	Esquema de todos os tipos de componentes nativos
`list_assets`	Assets do projeto (guid, caminho, tipo)
`inspect_material`	Inspeciona um asset específico por GUID
`capture_profiler`	Frame mais recente do profiler (contadores + zonas)
`inspect_memory`	Uso de memória do alocador (allocator)
`list_errors`	Avisos/erros recentes do engine

Ferramentas de escrita (servidor em modo de leitura-escrita + confirm: true)

Ferramenta	Descrição
`modify_component`	Define um campo de componente
`set_transform`	Define posição/rotação/escala
`spawn_entity`	Cria uma nova entidade
`destroy_entity`	Remove uma entidade
`reload_asset`	Executa o hot-reload de um asset

As ferramentas de escrita usam um portão de confirmação (confirmation gate): a primeira chamada retorna uma prévia; passe confirm: true para aplicar a alteração de fato.

Referência da CLI

turian-cli mcp [--host <addr>] [--port <n>] [--token <secret>]

Flag	Padrão	Descrição
`--host`	`127.0.0.1`	Nome do host ou IP do servidor de depuração
`--port`	`7777`	Porta do servidor de depuração
`--token`	(vazio)	Token de autenticação (deve corresponder ao `--token` do servidor)

O turian-cli mcp é encerrado quando o stdin fecha — o cliente MCP controla seu tempo de vida.

Detalhes do protocolo

Transporte: JSON-RPC 2.0 via stdio, delimitado por quebra de linha
Versão do MCP: 2024-11-05
Capacidades: tools (listagem + chamada)
Somente leitura por padrão: as ferramentas de mutação retornam um erro a menos que o servidor de depuração seja iniciado no modo de leitura-escrita

Relacionados

Protocolo de Depuração Remota — a camada TCP subjacente
Introspecção em Runtime — a API do engine consumida por ambas as camadas
Referência da CLI — outros comandos do turian-cli

← Toda a documentação Editar esta página