FAIM Time-Series forecasting

Pronóstico de series temporales con cero ejemplos utilizando modelos fundacionales de series temporales

GitHub
8
Prueba este MCPPatrocinado

Documentación

Servidor MCP de FAIM

npm version License: MIT

Un servidor de Protocolo de Contexto de Modelo (MCP) que integra el SDK de pronóstico de series temporales de FAIM con cualquier asistente de IA compatible con MCP, habilitando capacidades de pronóstico impulsadas por IA.

Paquete npm: @faim-group/mcp

Descripción general

Este servidor MCP actualmente expone dos modelos de series temporales fundamentales de la API de FAIM para pronóstico de cero disparos:

  • Chronos2
  • TiRex

Características clave

✅ Dos herramientas MCP:

  • list_models: Devuelve los modelos de pronóstico disponibles y sus capacidades
  • forecast: Realiza pronósticos de series temporales puntuales y probabilísticos

✅ Formatos de entrada flexibles:

  • Arreglos 1D: Serie temporal univariada única
  • Arreglos 3D: Formato lote/secuencia/característica

✅ Pronóstico probabilístico:

  • Pronósticos puntuales (predicciones de valor único)
  • Pronósticos de cuantiles (intervalos de confianza)
  • Pronósticos de muestras (muestras de distribución)
  • Niveles de cuantiles personalizados para evaluación de riesgos

Instalación

Requisitos previos

  • Node.js 20+
  • npm 10+
  • Clave de API de FAIM: Regístrese en https://faim.it.com/ para obtener su FAIM_API_KEY

Servidor MCP remoto — Útil para herramientas de automatización de flujos de trabajo como n8n

El servidor MCP está desplegado de forma remota.

Para usar el servidor MCP remoto, envíe solicitudes al siguiente endpoint:

https://mcp.faim.it.com

Proporcione su clave de API de FAIM utilizando autenticación Bearer.

Servidor MCP local

Opción 1: Instalar desde npm (Recomendado)

Configure su cliente para usarlo directamente con npx:

{
  "mcpServers": {
    "faim": {
      "command": "npx",
      "args": ["-y", "@faim-group/mcp"],
      "env": {
        "FAIM_API_KEY": "your-api-key-here"
      }
    }
  }
}

No se requiere instalación: npx descargará y ejecutará automáticamente la versión más reciente.

Alternativamente, si prefiere instalar globalmente primero:

npm install -g @faim-group/mcp

Luego en la configuración:

{
  "mcpServers": {
    "faim": {
      "command": "faim-mcp",
      "env": {
        "FAIM_API_KEY": "your-api-key-here"
      }
    }
  }
}

Opción 2: Clonar y compilar localmente

# Clone the repository
git clone <repository-url>
cd faim-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run type checker
npm run lint

Luego use la ruta local:

{
  "mcpServers": {
    "faim": {
      "command": "node",
      "args": ["/path/to/faim-mcp/dist/index.js"],
      "env": {
        "FAIM_API_KEY": "your-api-key-here"
      }
    }
  }
}

Ejemplos

Flujo de trabajo n8n — Pronóstico de demanda

Un flujo de trabajo de ejemplo para n8n de pronóstico de demanda está disponible en examples/n8n/demand_forecasting.json. Este flujo de trabajo demuestra cómo integrar el servidor MCP de FAIM con n8n para tareas automatizadas de pronóstico de demanda.

Para usar este ejemplo:

  1. Abra n8n
  2. Importe el flujo de trabajo desde n8n_examples/demand_forecasting.json
  3. Configure su clave de API de FAIM en la configuración de conexión MCP
  4. Ejecute el flujo de trabajo con sus datos de series temporales

Configuración

Variables de entorno

# Required: Your FAIM API key
export FAIM_API_KEY="your-api-key-here"

# Optional: Set to non-production for verbose logging
export NODE_ENV=development

Compatibilidad con MCP

Este servidor implementa el Protocolo de Contexto de Modelo (MCP), un protocolo abierto para conectar asistentes de IA a herramientas externas y fuentes de datos. Funciona con cualquier LLM y aplicación que implemente un cliente MCP.

Uso con cualquier LLM o sistema

Este servidor implementa el protocolo MCP estándar y funciona con cualquier aplicación que implemente un cliente MCP:

  • Implementación directa de cliente MCP
  • Adaptadores de frameworks de IA que soporten MCP
  • Extensiones de IDE que expongan herramientas MCP a cualquier LLM
  • Middleware personalizado que traduzca entre MCP y el formato de llamada de herramientas de su LLM

Uso

Iniciar el servidor

# Build and start the server
npm run build
node dist/index.js

El servidor:

  1. Leerá la clave de API del entorno
  2. Inicializará el cliente de FAIM
  3. Escuchará en stdin las solicitudes JSON-RPC
  4. Enviará respuestas a stdout

Herramienta 1: Listar modelos

Devuelve los modelos de pronóstico disponibles y sus capacidades.

Solicitud:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Respuesta:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "list_models",
        "description": "...",
        "inputSchema": { ... }
      },
      {
        "name": "forecast",
        "description": "...",
        "inputSchema": { ... }
      }
    ]
  }
}

Herramienta 2: Pronóstico

Realiza pronósticos de series temporales utilizando los modelos de FAIM.

Solicitud (Pronóstico puntual):

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "forecast",
    "arguments": {
      "model": "chronos2",
      "x": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
      "horizon": 10,
      "output_type": "point"
    }
  }
}

Solicitud (Pronóstico de cuantiles con intervalos de confianza):

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "forecast",
    "arguments": {
      "model": "chronos2",
      "x": [[[100, 50], [102, 51], [105, 52]]],
      "horizon": 5,
      "output_type": "quantiles",
      "quantiles": [0.1, 0.5, 0.9]
    }
  }
}

Respuesta:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "success": true,
    "data": {
      "model_name": "chronos2",
      "model_version": "1.0",
      "output_type": "point",
      "forecast": {
        "point": [[[11], [12], [13], ...]]
      },
      "metadata": {
        "token_count": 150,
        "duration_ms": 245
      },
      "shape_info": {
        "input_shape": [1, 10, 1],
        "output_shape": [1, 10, 1]
      }
    }
  }
}

Estructura del proyecto

faim-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── types.ts              # TypeScript interfaces
│   ├── tools/
│   │   ├── list-models.ts    # List models tool
│   │   └── forecast.ts       # Forecasting tool
│   └── utils/
│       ├── client.ts         # FAIM client singleton
│       ├── validation.ts     # Input validation
│       └── errors.ts         # Error transformation
├── tests/
│   ├── tools/
│   │   ├── list-models.test.ts
│   │   └── forecast.test.ts
│   └── utils/
│       ├── validation.test.ts
│       └── errors.test.ts
├── dist/                     # Built output
│   ├── index.js             # ESM bundle
│   ├── index.cjs            # CommonJS bundle
│   ├── index.d.ts           # Type declarations
│   └── *.map                # Source maps
└── package.json, tsconfig.json, tsup.config.ts, vitest.config.ts

Pruebas

El proyecto incluye pruebas integrales para:

  • Validación de entrada: Entradas válidas/inválidas, casos límite, valores frontera
  • Manejo de errores: Errores del SDK, errores de JavaScript, clasificación de errores
  • Funcionalidad de herramientas: Estructura de respuesta, disponibilidad de modelos
  • Seguridad de tipos: Compilación de TypeScript, guardas de tipos

Ejecutar pruebas:

npm test                 # Run all tests
npm run test:coverage   # Run with coverage report
npm run test:ui         # Run with UI dashboard

Depuración

Habilite el registro detallado:

NODE_ENV=development node dist/index.js

La salida va a stderr (sin interferir con el JSON-RPC de stdout).

Compilación y despliegue

Compilar para producción

npm run build

Salidas:

  • dist/index.js - Módulo ESM
  • dist/index.cjs - Módulo CommonJS
  • dist/index.d.ts - Declaraciones de tipos
  • Mapas de origen para depuración

Lista de verificación de despliegue

  • Establezca la variable de entorno FAIM_API_KEY
  • Ejecute npm run build
  • Ejecute npm test para verificar
  • Despliegue el directorio dist/
  • Ejecute node dist/index.js como proceso del servidor

Solución de problemas

"FAIM_API_KEY no establecida"

export FAIM_API_KEY="your-key-here"
node dist/index.js

Errores de "Módulo no encontrado"

npm install
npm run build

El servidor no responde

  • Verifique que stdout/stderr estén correctamente conectados
  • Verifique el formato JSON-RPC de las solicitudes
  • Revise los registros para ver mensajes de error
  • Asegúrese de que la API de FAIM sea accesible

Licencia

MIT