Ranch.Bot MCP

Servidor MCP de Ranch.Bot

Trabaje con registros de ganado vacuno y ovino desde un cliente MCP local stdio. Requiere Node.js 22 o superior, una cuenta de Ranch.Bot y acceso a una granja. Ranch.Bot no opera un endpoint MCP alojado.

Disponibilidad de versiones

Consulte la página de versiones y configuración para ver versiones públicas verificadas. Una copia del código fuente o un candidato no es evidencia de que una versión esté disponible en npm o en el Registro. El CLI público tiene instrucciones de configuración separadas. Para registros cotidianos, use la configuración por SMS y web.

Comandos de terminal

Con el comando ranchbot-mcp instalado, ejecute ranchbot-mcp login en una terminal y apruebe la URL y el código en su navegador. Configure su cliente MCP local para ejecutar ranchbot-mcp sin argumentos. Use una ruta ejecutable absoluta si el cliente no hereda el PATH de su terminal. ranchbot-mcp --help y ranchbot-mcp --version no requieren autenticación. Ejecute ranchbot-mcp logout para revocar la sesión antes de eliminar sus credenciales locales.

Desarrollo del código fuente

Requiere Node.js 22 o superior y un entorno de desarrollo autorizado de Ranch.Bot.

npm install
npm run build
npm test

Ejecute la entrada stdio directamente desde un cliente MCP local:

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

Establezca estas variables de entorno para el entorno de desarrollo:

Variable	Estado requerido	Propósito
RANCHBOT_API_URL	URL de API de desarrollo explícita	API de Ranch.Bot utilizada por el servidor fuente
COGNITO_DEVICE_CLIENT_ID	Cliente OAuth de desarrollo público explícito	Registro de flujo de dispositivo para esa API
API_VERSION	Opcional, por defecto v1	Versión de API

El valor predeterminado es el cliente público estable ranchbot-mcp. Implemente su migración de base de datos antes de usar autenticación en la nube. Una URL de API local por sí sola no selecciona cuentas locales de instalación.

Modo de observación de desarrollo:

npm run dev

Configuración del cliente local

Una copia del código fuente puede apuntar un cliente MCP al archivo compilado. Ejemplo de forma:

{
  "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 un cliente OAuth público real del entorno de desarrollo. Nunca confirme claves de API, tokens OAuth o registros de clientes con secretos.

Autenticación

El transporte stdio utiliza el flujo de dispositivo OAuth de Ranch.Bot. Ejecute node dist/index.js login en una terminal antes de conectar su cliente MCP. Visite la URL mostrada y apruebe explícitamente el acceso del navegador. Las llamadas a herramientas sin sesión devuelven instrucciones de inicio de sesión en terminal y no inician sesión. node dist/index.js logout revoca la sesión antes de limpiar la caché; la revocación fallida conserva las credenciales para un reintento. --help y --version funcionan sin autenticación. Sin argumentos inicia stdio.

Las solicitudes de inicio de sesión ordinarias requieren read:farms, lectura/escritura de animales, grupos y registros, y read:exports. Use list_my_farms y luego set_default_farm, o proporcione un farm_id explícito, antes de operaciones de granja. Una sesión de reemplazo para un principal diferente limpia la selección de granja en proceso. Los tokens se almacenan en caché localmente en ~/.ranchbot-mcp-tokens.json con permisos de archivo restringidos y se actualizan cuando el entorno configurado lo admite.

El transporte HTTP autohospedado opcional utiliza autenticación de clave de API tipo bearer para compatibilidad de desarrollo. Las claves de API están obsoletas y no forman parte de la incorporación de clientes.

Inicio de sesión de importación de administrador

Para importaciones internas de conserjería, agregue --admin al comando stdio (o al array args del cliente local):

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

Esto selecciona el cliente ranchbot-admin-cli nombrado y solicita admin:imports junto con los ocho ámbitos ordinarios. Anula COGNITO_DEVICE_CLIENT_ID; establecer explícitamente esa variable en ranchbot-admin-cli también selecciona el modo administrador. La API debe tener ese registro de cliente, y una cuenta de administrador debe aprobar el código de dispositivo mostrado en el navegador.

Las sesiones de administrador usan ~/.ranchbot-mcp-admin-tokens.json y una ~/.ranchbot-mcp-admin-tokens.lock persistente separada. Las sesiones ordinarias conservan su caché y bloqueo existentes. Ejecute node dist/index.js login --admin antes de usar el modo administrador; la actualización y el inicio de sesión de administrador no reemplazan la sesión ordinaria.

Las herramientas list_pending_imports, get_import_request y update_import_request_status requieren esta sesión de administrador. Las sesiones de dispositivo ordinarias y las claves de API del transporte HTTP no pueden usarlas. La API verifica tanto la capacidad de importación como el estado de administrador actual en cada solicitud.

Superficie de herramientas

El servidor fuente expone herramientas con ámbito de granja para:

• granjas y contexto de granja actual;
• animales e identificadores;
• grupos;
• salud, movimiento, alimentación, genética y otros registros;
• eventos de nacimiento atómicos, tareas de seguimiento vinculadas y versiones de protocolo de granja inmutables; y
• Memoria de Granja de solo lectura.

Las escrituras MCP externas se ejecutan a través del acceso otorgado al cliente MCP. No utilizan la pantalla de revisión antes de guardar de la aplicación Ranch.Bot. Las herramientas CRUD ordinarias llaman a los endpoints de granja y no crean las filas de Acción que respaldan el Historial de Cambios actualmente. Las garantías que el código fuente preserva son el ámbito de granja y la revocación.

preview_birth_event devuelve el paquete de nacimiento completo, la evidencia resuelta y un hash de confirmación sin guardar datos de granja. Muestre cada campo al productor y obtenga aprobación explícita antes de confirm_birth_event, preservando el request_id, bundle y confirmation_hash exactos. Las correcciones o cambios de evidencia requieren una vista previa nueva y aprobación renovada. La confirmación requiere acceso EDITOR y ámbitos write:records, write:animals y write:groups. list_birth_events y get_birth_event recuperan eventos guardados; list_farm_tasks incluye TAREAS pendientes sin fecha, y update_farm_task cambia el estado o la fecha de vencimiento opcional. list_protocol_versions y create_protocol_version usan pasos inmutables proporcionados por el productor sin inventar instrucciones de cuidado.

get_birth_source_evidence lee el estado de medios SMS retenido por el autor de la fuente y los candidatos de identidad de granja actual. Requiere read:records, read:animals y acceso a la granja actual. Las coincidencias parciales o ambiguas requieren selección del productor antes de la confirmación de nacimiento.

Verificaciones

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

La configuración pública regresa solo después de que pasen los OAuth/ámbitos actuales, la lectura de npm y Registro, y la instalación en máquina limpia, autenticación, ámbito de granja, lecturas/escrituras representativas, revocación y actualizaciones. CLI 1.0.0 ya es público y tiene guía de configuración independiente; la publicación local no implica una conexión alojada de ChatGPT/Gemini. Estado actual: ranch.bot/connect-your-ai.

Licencia

MIT

Bloqueo de caché de tokens y actualizaciones

Las lecturas y mutaciones de caché de tokens usan bloqueos exclusivos administrados por el sistema operativo (Node 22, fijado fs-native-extensions@1.5.0). Los archivos de bloqueo en ~/.ranchbot-mcp-tokens.lock persisten después del cierre de sesión y la salida del proceso; su existencia no significa que un cliente tenga el bloqueo. El sistema operativo libera la propiedad cuando un cliente sale o falla, permitiendo que los clientes en espera se recuperen automáticamente. No elimine ni reemplace un archivo de bloqueo mientras los clientes estén en ejecución.

Cada llamada de herramienta verifica la caché compartida para que los clientes en ejecución adopten sesiones de reemplazo. Las solicitudes que ya usan una sesión revocada pueden fallar; las solicitudes fallidas se devuelven al llamante sin reproducción automática.

Detenga todos los procesos CLI/MCP antiguos antes de actualizar. Los protocolos de bloqueo concurrentes antiguos/nuevos no son compatibles. Un archivo heredado que identifica un proceso vivo se rechaza con un error de actualización; un archivo heredado abandonado se reutiliza en su lugar. Los errores de adquisición fallan de forma cerrada, y la contención expira después de 30 segundos.

Las cachés están vinculadas al origen de la API y al ID de cliente OAuth. Una discrepancia se rechaza sin sobrescribir credenciales. Detenga los clientes antiguos antes de actualizar. Para una caché sin estos metadatos, ejecute logout con su RANCHBOT_API_URL y COGNITO_DEVICE_CLIENT_ID originales. Las credenciales de proveedor antiguas no pueden ser revocadas por el endpoint de sesión de dispositivo: revóquelas con el proveedor original antes de eliminar la caché. Una respuesta HTTP exitosa por sí sola no establece revocación heredada.

Las cuentas locales de instalación conservan la sesión de instalación administrada por CLI: use ranchbot login --local --api-url <installation> y establezca RANCHBOT_DEPLOYMENT_MODE=local más el mismo RANCHBOT_API_URL en el cliente MCP. El inicio/cierre de sesión de MCP lo dirige al CLI en ese modo.