CultivarIA - Servidor MCP (Model Context Protocol)

Servidor MCP (Model Context Protocol) oficial para la plataforma CultivarIA (https://cultivaria-9673f.web.app/).

Este servidor expone Herramientas (Tools) y Recursos (Resources) estandarizados a través de transporte HTTP con SSE (Server-Sent Events) para permitir que asistentes de Inteligencia Artificial (como Gemini Spark, Antigravity, Claude, etc.) consulten telemetría en tiempo real, analicen tendencias históricas y ejecuten comandos de control sobre módulos y actuadores de cultivo.

---

1. Requisitos Previos

• Node.js: v18.0.0 o superior.
• npm: v9.0.0 o superior.

---

2. Instalación y Compilación

1. Ingresa a la carpeta del servidor MCP:

   cd mcp-server
   

2. Instala las dependencias:

   npm install
   

3. Compila el código TypeScript a JavaScript en ./dist:

   npm run build
   

4. Inicia el servidor en modo producción:

   npm start
   

5. (Opcional) Inicia en modo desarrollo con auto-recarga:

   npm run dev
   

---

3. Variables de Entorno (.env)

Crea un archivo .env en la raíz de mcp-server/ basado en .env.example:

PORT=3001
CULTIVARIA_MCP_TOKEN=cultivaria_mcp_secret_token_2026
BACKEND_URL=https://cultivaria-9673f-default-rtdb.firebaseio.com

---

4. Configuración del Conector para Clientes MCP (Gemini Spark / Antigravity / Claude)

Conexión HTTP / SSE (Remota o Local)

Agrega la siguiente configuración en la sección de MCP Servers de tu cliente o entorno:

{
  "mcpServers": {
    "cultivaria": {
      "url": "http://localhost:3001/sse",
      "headers": {
        "Authorization": "Bearer cultivaria_mcp_secret_token_2026"
      }
    }
  }
}

---

5. Despliegue 24/7 en la Nube de Google (Google Cloud Run)

Para alojar el servidor MCP encendido las 24 horas del día en la infraestructura global de Google:

1. Ve al panel de Google Cloud: Google Cloud Run Console.
2. Haz clic en el botón "Crear Servicio" (Create Service).
3. Conecta tu repositorio de GitHub o suba la carpeta mcp-server con el Dockerfile optimizado incluido.
4. En la pestaña Variables de entorno y secreto, agrega:
   • CULTIVARIA_MCP_TOKEN = cultivaria_mcp_secret_token_2026
   • BACKEND_URL = https://cultivaria-9673f-default-rtdb.firebaseio.com
5. En Ingreso / Autenticación, marca "Permitir peticiones sin autenticar" (la autenticación de seguridad es manejada internamente por el Bearer Token del MCP).
6. Al hacer clic en Crear, Google te asignará una URL pública HTTPS permanente de 24/7 (ejemplo: https://cultivaria-mcp-server-xyz-uc.a.run.app).

---

6. Alternativa Gratuita 24/7 en Render.com

Si deseas una opción 24/7 de 1 solo clic en una nube gratuita:

1. Ve a render.com y crea un Web Service gratuito conectando este repositorio.
2. Render detectará automáticamente el archivo render.yaml incluido en mcp-server/.
3. Obtendrás una URL pública de 24/7 como https://cultivaria-mcp-server.onrender.com/sse.

---

7. Exposición Remota Temporal para Desarrollo (Túnel con ngrok)

Para permitir que Gemini Spark o cualquier cliente MCP remoto se conecte a tu servidor MCP local mientras desarrollas:

1. Ejecuta el comando de túnel incluido:

   npm run tunnel
   

   (O usa npx ngrok http 3001 directamente).

2. Obtendrás una URL pública segura (ej. https://a1b2-34-56-78-90.ngrok-free.app).

3. Actualiza la URL en tu cliente MCP:

   {
     "mcpServers": {
       "cultivaria": {
         "url": "https://a1b2-34-56-78-90.ngrok-free.app/sse",
         "headers": {
           "Authorization": "Bearer cultivaria_mcp_secret_token_2026"
         }
       }
     }
   }
   

---

6. Ejemplos de Prueba con cURL y Postman

A. Health Check

curl http://localhost:3001/health

Respuesta: {"status":"ONLINE","server":"CultivarIA MCP Server","version":"1.0.0"}

---

B. Iniciar Conexión SSE (Requiere Token Bearer)

curl -i -N \
  -H "Authorization: Bearer cultivaria_mcp_secret_token_2026" \
  http://localhost:3001/sse

Si no envías el token, el servidor responderá 401 Unauthorized.

---

C. Probar Invocación de Herramienta por POST (JSON-RPC)

Envía un mensaje JSON-RPC al endpoint /messages?sessionId=<SESSION_ID> retornado en el evento SSE endpoint:

curl -X POST \
  "http://localhost:3001/messages?sessionId=<SESSION_ID>" \
  -H "Authorization: Bearer cultivaria_mcp_secret_token_2026" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_live_telemetry",
      "arguments": {
        "module_id": "flora-01"
      }
    }
  }'

---

7. Catálogo de Herramientas (MCP Tools)

Herramienta	Descripción	Parámetros Clave
get_live_telemetry	Lecturas de sensores en vivo	module_id
get_historical_telemetry	Serie de tiempo e historial de tendencias	metric, timeframe, module_id
get_phenological_status	Salud vegetal y capturas ESP32	module_id
update_setpoint	Actualiza metas de pH, EC, Temp, VPD	metric, target_value, module_id
trigger_irrigation	Controla electroválvula de riego	action (start/stop), duration_minutes
set_actuator_mode	Ajusta modos de climatización	device, mode, on_minutes, off_minutes
update_strategy	Cambia variedad y semana de cultivo	strain_name, cycle_week

---

8. Recursos MCP (MCP Resources)

• cultivaria://system_status: Resumen del sistema, salud de nodos ESP32 y alertas.
• cultivaria://modules: Módulos de cultivo registrados y resumen de sensores.