Treinar a IA do OSH pelo Claude

Dá ao Claude Code (ou Codex) acesso ao treinamento da IA de um cliente: base de conhecimento, personalidade, regras, agentes e tipos de quarto — sem passar por 8 telas.

Uma chave = um cliente. A chave que você recebe vale para um único hotel. Não é possível apontar para outro sem trocar a chave, nem por engano.

Uso interno da Onscreen Hotels. Requer uma chave emitida na plataforma OSH — sem ela o pacote não faz nada. Decisão de arquitetura: ADR-128 (repositório interno).

Antes de tudo: conseguir a chave

A chave não é auto-gerada:

1. Em Configurações › Tokens MCP na Automação (/mcp-tokens), aba Solicitar: escolha o cliente, o que a chave poderá fazer, o ambiente e a validade.
2. Um administrador diferente de você aprova (aba Aprovações).
3. Na aprovação a chave aparece uma única vez. Quem aprovou copia e entrega.

Você só consegue pedir poderes que você mesmo já tem no cliente. Se a chave for usada depois que você perder o acesso àquele cliente, ela morre junto.

Instalação (uma vez, ~2 minutos)

Você precisa de: Node.js 18 ou mais novo, e a chave.

Cole no terminal, trocando o nome do hotel e a chave.

Windows (use npx.cmd, não npx):

claude mcp add pousada-velho-chico ^
  --env OSH_MCP_TOKEN=oshmcp_prod_COLE_SUA_CHAVE_AQUI ^
  -- npx.cmd -y @osociohoteleiro/mcp-treinamento-ia

Mac / Linux:

claude mcp add pousada-velho-chico \
  --env OSH_MCP_TOKEN=oshmcp_prod_COLE_SUA_CHAVE_AQUI \
  -- npx -y @osociohoteleiro/mcp-treinamento-ia

⚠️ No Windows é npx.cmd. Com npx puro o comando resolve para npx.ps1, que o Claude Code não consegue iniciar — e o servidor nunca conecta. Confirmado em 2026-08-02.

⚠️ Cole a chave direto no terminal, nunca numa conversa com a IA. O claude mcp add grava a chave em texto puro no .claude.json da sua máquina; se ela também passar pelo chat, fica no histórico da conversa. Chave exposta = revogar e emitir outra.

Use o nome do hotel como identificador (pousada-velho-chico). Quem atende vários clientes repete o comando para cada um, com a chave e o nome de cada um — e passa a ver todos listados, sem confundir.

Pronto. Não é preciso baixar pasta nem clonar repositório: o npx busca o pacote na hora e mantém atualizado sozinho.

Segundo passo: instalar a skill (recomendado)

O comando acima entrega as ferramentas. A skill entrega o procedimento — a ordem dos passos, o que verificar depois de cada mudança e quando parar e perguntar. Sem ela cada pessoa inventa o próprio caminho, e a base de conhecimento piora sem ninguém perceber.

npx -y -p @osociohoteleiro/mcp-treinamento-ia osh-mcp-install-skill

Vale para Windows, Mac e Linux, e pode rodar de novo a qualquer momento para atualizar. Ele grava em ~/.claude/skills/osh-treinar-ia/. Reinicie o Claude Code depois.

Instalada, ela entra em ação sozinha quando você pedir algo como "a IA não sabe o horário do café, corrija" — não é preciso invocá-la pelo nome.

Homologação

Para testar sem tocar em cliente real, aponte para homologação e use uma chave de homologação (uma chave nunca vale em outro ambiente):

claude mcp add teste-homologacao ^
  --env OSH_MCP_TOKEN=oshmcp_stg_SUA_CHAVE ^
  --env OSH_API_URL=https://staging-api.osociohoteleiro.com.br/api ^
  -- npx.cmd -y @osociohoteleiro/mcp-treinamento-ia

(No Mac/Linux, troque ^ por \ e npx.cmd por npx.)

Claude Desktop

Mesma ideia, no arquivo de configuração (Configurações › Desenvolvedor › Editar config):

{
  "mcpServers": {
    "pousada-velho-chico": {
      "command": "npx.cmd",
      "args": ["-y", "@osociohoteleiro/mcp-treinamento-ia"],
      "env": { "OSH_MCP_TOKEN": "oshmcp_prod_SUA_CHAVE" }
    }
  }
}

A tela Conectores do Claude não serve para este servidor: ela espera um endereço na internet, e este roda como programa local na sua máquina.

Conferindo que é o cliente certo

Ao conectar, o servidor pergunta à API de quem é a chave e anuncia o nome do cliente ao Claude. A partir daí:

• Pergunte "de qual cliente é este acesso?" a qualquer momento (get_client_info).
• Toda tentativa de gravar sem confirmar mostra o nome do cliente antes de você responder "sim" — confirmação cega é confirmação ruim.
• Se o servidor não conseguir confirmar de quem é a chave, ele não sobe. Melhor falhar na largada do que deixar alguém editar às cegas.

Usando

Converse normalmente. Alguns pedidos que funcionam bem:

Liste o conhecimento da IA e me diga o que está faltando.

Leia este PDF de implantação e cadastre o que ainda não existe na base.

Um cliente perguntou "posso levar meu cachorro?" — teste o que a IA responderia
e corrija se estiver ruim.

Revise as palavras-chave dos itens sobre café da manhã.

Regras que o Claude segue sozinho:

| Regra | Por quê | |---|---| | Toda gravação pede confirmação, nomeando o cliente | O erro caro aqui é treinar o hotel errado | | dry_run mostra o antes/depois sem gravar | Revisar é mais barato que desfazer | | Palavras-chave são escolhidas à mão, nunca automáticas | Palavra-chave ruim sequestra a busca e a IA responde outra coisa | | Testar depois de criar | Criar sem testar não prova nada |

Quando algo não funciona

| Mensagem | O que fazer | |---|---| | não foi possível confirmar a que cliente este token pertence | Chave errada, expirada ou revogada — peça uma nova | | Esta operação não está liberada | A chave só alcança o treinamento da IA. Faturamento, conversas e usuários estão fora, de propósito | | O token não tem escopo para esta operação | A chave foi emitida sem esse poder. Poder não aumenta depois — peça outra chave | | O token não vale neste ambiente | Chave de homologação apontando para produção (ou o contrário) | | CONFLITO: o OSH_WORKSPACE_UUID configurado não é o do token | Configuração antiga. Remova o OSH_WORKSPACE_UUID — ele vem da chave | | Limite de requisições excedido | Aguarde um minuto | | No Windows, o servidor aparece mas não conecta | Você usou npx em vez de npx.cmd. Remova (claude mcp remove nome) e refaça | | No Linux/WSL: /usr/bin/env: 'node\r': No such file or directory | Versão até a 1.3.0, publicada com quebra de linha do Windows. Atualize: npx -y @osociohoteleiro/mcp-treinamento-ia@latest (limpe o cache antes com npx clear-npx-cache se persistir) |

Configuração

| Variável | Obrigatória | Padrão | |---|---|---| | OSH_MCP_TOKEN | sim | — | | OSH_API_URL | não | produção | | OSH_WORKSPACE_UUID | não | vem da chave | | OSH_TIMEOUT_MS | não | 30000 | | OSH_MCP_DEBUG | não | 0 — em 1, o log mostra endereço da API, workspace e escopos |

OSH_WORKSPACE_UUID existe só para casos especiais. Se você preencher com algo diferente do que a chave diz, o servidor recusa subir em vez de escolher um dos dois.

As ferramentas

Conhecimento: list_knowledge · get_knowledge · list_knowledge_categories · knowledge_stats · create_knowledge · update_knowledge · delete_knowledge · reembed_knowledge

Testar: test_knowledge_query · debug_knowledge_query · test_ai_message

Configuração: get_ai_config · update_ai_config · update_ai_extra_rules · list_ai_channels · get_ai_channel_config · update_ai_channel_config

Agentes: list_agents · get_agent · update_agent_prompt

Tipos de quarto: list_room_types · create_room_type · update_room_type

Contexto: get_client_info

Nenhuma delas aceita "cliente" como parâmetro — vem sempre da chave. Há teste garantindo isso, justamente para que ninguém consiga apontar para o cliente errado.

Para quem administra

O pacote é publicado no npm para que ninguém precise de acesso ao repositório. Ele é um cliente HTTP fino: sem lógica de negócio, sem segredo embutido, sem acesso ao banco. Toda a segurança vive na API — um funcionário mexendo nos arquivos locais não contorna regra nenhuma.

cd mcp-server
npm version patch     # ou minor / major
npm publish           # publishConfig.access = public
npm test              # 17 casos, sem precisar da API no ar

⚠️ Antes de publicar pela primeira vez, decida com o dono: o código-fonte deste pacote fica visível publicamente. Ele não expõe segredo nenhum, mas revela os nomes das rotas de treinamento da IA. A alternativa é um registro privado — funciona igual, mas exige que cada funcionário se autentique nele.