Ranch.Bot MCP

Envie uma nota sobre o gado, revise-a antes de salvar e encontre o histórico daquele animal ou grupo depois. Agende uma demonstração ou obtenha ajuda para trazer registros existentes.

GitHub
1

Documentação

Servidor Ranch.Bot MCP

Trabalhe com registros de gado e ovelhas a partir de um cliente MCP stdio local. Requer Node.js 22 ou mais recente, uma conta Ranch.Bot e acesso a uma fazenda. O Ranch.Bot não opera um endpoint MCP hospedado.

Disponibilidade de versões

Consulte a página de versões e configuração para versões públicas verificadas. Um checkout do código-fonte ou candidato não é evidência de que uma versão está disponível no npm ou no Registry. A CLI pública tem instruções de configuração separadas. Para registros do dia a dia, use configuração via SMS e web.

Comandos de terminal

Com o comando ranchbot-mcp instalado, execute ranchbot-mcp login em um terminal e aprove a URL e o código no seu navegador. Configure seu cliente MCP local para executar ranchbot-mcp sem argumentos. Use um caminho executável absoluto se o cliente não herdar o PATH do seu terminal. ranchbot-mcp --help e ranchbot-mcp --version não exigem autenticação. Execute ranchbot-mcp logout para revogar a sessão antes de remover suas credenciais locais.

Desenvolvimento do código-fonte

Requer Node.js 22 ou mais recente e um ambiente de desenvolvimento Ranch.Bot autorizado.

npm install
npm run build
npm test

Execute a entrada stdio diretamente de um cliente MCP local:

node /absolute/path/to/mcp-server/dist/index.js

Defina estas variáveis de ambiente para o ambiente de desenvolvimento:

VariávelEstado exigidoFinalidade
RANCHBOT_API_URLURL explícita da API de desenvolvimentoAPI Ranch.Bot usada pelo servidor de origem
COGNITO_DEVICE_CLIENT_IDCliente OAuth público explícito de desenvolvimentoRegistro de fluxo de dispositivo para essa API
API_VERSIONOpcional, padrão para v1Versão da API

O padrão é o cliente público estável ranchbot-mcp. Implante sua migração de banco de dados antes de usar autenticação em nuvem. Uma URL de API local por si só não seleciona contas locais à instalação.

Modo de observação de desenvolvimento:

npm run dev

Configuração do cliente local

Um checkout do código-fonte pode apontar um cliente MCP para o arquivo compilado. Exemplo de formato:

{
  "mcpServers": {
    "ranchbot-development": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "RANCHBOT_API_URL": "http://localhost:7001",
        "COGNITO_DEVICE_CLIENT_ID": "development-public-client-id"
      }
    }
  }
}

Use um cliente OAuth público real do ambiente de desenvolvimento. Nunca faça commit de chaves de API, tokens OAuth ou registros de clientes com segredos.

Autenticação

O transporte stdio usa o fluxo de dispositivo OAuth do Ranch.Bot. Execute node dist/index.js login em um terminal antes de conectar seu cliente MCP. Visite a URL exibida e aprove explicitamente o acesso no navegador. Chamadas de ferramentas sem sessão retornam instruções de login no terminal e não iniciam login. node dist/index.js logout revoga a sessão antes de limpar o cache; falha na revogação mantém as credenciais para uma nova tentativa. --help e --version funcionam sem autenticação. Sem argumentos, inicia o stdio.

Logins comuns solicitam read:farms, leitura/escrita de animais, grupos e registros, e read:exports. Use list_my_farms e depois set_default_farm, ou forneça um farm_id explícito, antes de operações na fazenda. Uma sessão substituta para um principal diferente limpa a seleção de fazenda em processo. Os tokens são armazenados em cache localmente em ~/.ranchbot-mcp-tokens.json com permissões de arquivo restritas e são atualizados quando o ambiente configurado suporta isso.

O transporte HTTP auto-hospedado opcional usa autenticação por chave de API bearer para compatibilidade de desenvolvimento. As chaves de API são descontinuadas e não fazem parte da integração de clientes.

Login de importação administrativa

Para importações internas de concierge, adicione --admin ao comando stdio (ou ao array args do cliente local):

node /absolute/path/to/mcp-server/dist/index.js --admin

Isso seleciona o cliente ranchbot-admin-cli nomeado e solicita admin:imports junto com os oito escopos comuns. Isso substitui COGNITO_DEVICE_CLIENT_ID; definir explicitamente essa variável como ranchbot-admin-cli também seleciona o modo administrativo. A API deve ter esse registro de cliente, e uma conta administrativa deve aprovar o código de dispositivo exibido no navegador.

Sessões administrativas usam ~/.ranchbot-mcp-admin-tokens.json e um ~/.ranchbot-mcp-admin-tokens.lock persistente separado. Sessões comuns mantêm seu cache e bloqueio existentes. Execute node dist/index.js login --admin antes de usar o modo administrativo; atualização e login administrativos não substituem a sessão comum.

As ferramentas list_pending_imports, get_import_request e update_import_request_status exigem esta sessão administrativa. Sessões de dispositivo comuns e as chaves de API do transporte HTTP não podem usá-las. A API verifica tanto a capacidade de importação quanto o status administrativo atual em cada solicitação.

Superfície de ferramentas

O servidor de origem expõe ferramentas com escopo de fazenda para:

  • fazendas e contexto atual da fazenda;
  • animais e identificadores;
  • grupos;
  • registros de saúde, movimentação, alimentação, genética e outros;
  • eventos de nascimento atômicos, tarefas de acompanhamento vinculadas e versões imutáveis de protocolo da fazenda; e
  • Memória da Fazenda somente leitura.

Escritas MCP externas são executadas por meio do acesso concedido ao cliente MCP. Elas não usam a tela de revisão antes de salvar do aplicativo Ranch.Bot. Ferramentas CRUD comuns chamam os endpoints da fazenda e não criam as linhas de Ação que sustentam o Histórico de Alterações hoje. As garantias que a origem preserva são o escopo da fazenda e a revogação.

preview_birth_event retorna o pacote completo de nascimento, evidências resolvidas e um hash de confirmação sem salvar dados da fazenda. Mostre cada campo ao produtor e obtenha aprovação explícita antes de confirm_birth_event, preservando exatamente o request_id, bundle e confirmation_hash. Correções ou evidências alteradas exigem uma nova pré-visualização e aprovação renovada. A confirmação exige acesso EDITOR e escopos write:records, write:animals e write:groups. list_birth_events e get_birth_event recuperam eventos salvos; list_farm_tasks inclui TODOs sem data, e update_farm_task altera o status ou a data de vencimento opcional. list_protocol_versions e create_protocol_version usam etapas imutáveis fornecidas pelo produtor sem inventar instruções de cuidado.

get_birth_source_evidence lê o status de mídia SMS retido pelo autor da origem e os candidatos de identidade da fazenda atual. Exige read:records, read:animals e acesso à fazenda atual. Correspondências parciais ou ambíguas exigem seleção pelo produtor antes da confirmação de nascimento.

Verificações

npm run build
npm run typecheck
npm run lint
npm run prettier
npm test

A configuração pública retorna somente após passarem as verificações atuais de OAuth/escopos, leitura de volta do npm e do Registry, e instalação em máquina limpa, autenticação, escopo da fazenda, leituras/escritas representativas, revogação e atualizações. A CLI 1.0.0 já é pública e tem orientação de configuração independente; publicação local não implica uma conexão hospedada com ChatGPT/Gemini. Status atual: ranch.bot/connect-your-ai.

Licença

MIT

Bloqueio e atualizações do cache de tokens

Leituras e mutações do cache de tokens usam bloqueios exclusivos gerenciados pelo SO (Node 22, com fs-native-extensions@1.5.0 fixado). Arquivos de bloqueio em ~/.ranchbot-mcp-tokens.lock persistem após logout e saída do processo; sua existência não significa que um cliente detém o bloqueio. O SO libera a propriedade quando um cliente sai ou trava, permitindo que clientes em espera se recuperem automaticamente. Não exclua nem substitua um arquivo de bloqueio enquanto clientes estiverem em execução.

Cada chamada de ferramenta verifica o cache compartilhado para que clientes em execução adotem sessões substitutas. Solicitações que já usam uma sessão revogada podem falhar; solicitações com falha são retornadas ao chamador sem reprodução automática.

Pare todos os processos antigos de CLI/MCP antes de atualizar. Protocolos de bloqueio antigos e novos simultâneos não são suportados. Um arquivo legado que identifica um processo ativo é rejeitado com erro de atualização; um arquivo legado abandonado é reutilizado no lugar. Erros de aquisição falham de forma fechada, e a contenção expira após 30 segundos.

Os caches são vinculados à origem da API e ao ID do cliente OAuth. Uma incompatibilidade é rejeitada sem sobrescrever credenciais. Pare clientes antigos antes de atualizar. Para um cache sem esses metadados, execute logout com seu RANCHBOT_API_URL e COGNITO_DEVICE_CLIENT_ID originais. Credenciais antigas de provedores não podem ser revogadas pelo endpoint de sessão de dispositivo: revogue-as com o provedor original antes de remover o cache. Uma resposta HTTP bem-sucedida por si só não estabelece revogação legada.

Contas locais à instalação mantêm a sessão de instalação gerenciada pela CLI: use ranchbot login --local --api-url <installation> e defina RANCHBOT_DEPLOYMENT_MODE=local mais o mesmo RANCHBOT_API_URL no cliente MCP. Login/logout MCP direciona você para a CLI nesse modo.