FAIM Time-Series forecasting

Previsão de séries temporais zero-shot com modelos fundamentais de séries temporais

GitHub
8
Experimente este MCPPatrocinado

Documentação

Servidor MCP FAIM

npm version License: MIT

Um servidor Model Context Protocol (MCP) que integra o SDK de previsão de séries temporais FAIM com qualquer assistente de IA compatível com MCP, permitindo capacidades de previsão com IA.

Pacote npm: @faim-group/mcp

Visão Geral

Este servidor MCP atualmente expõe dois modelos de séries temporais de base da API FAIM para previsão zero-shot:

  • Chronos2
  • TiRex

Principais Recursos

✅ Duas Ferramentas MCP:

  • list_models: Retorna os modelos de previsão disponíveis e suas capacidades
  • forecast: Realiza previsões de séries temporais pontuais e probabilísticas

✅ Formatos de Entrada Flexíveis:

  • Arrays 1D: Série temporal univariada única
  • Arrays 3D: formato lote/sequência/recurso

✅ Previsão Probabilística:

  • Previsões pontuais (predições de valor único)
  • Previsões por quantis (intervalos de confiança)
  • Previsões por amostras (amostras de distribuição)
  • Níveis de quantis personalizados para avaliação de risco

Instalação

Pré-requisitos

  • Node.js 20+
  • npm 10+
  • Chave da API FAIM: Registre-se em https://faim.it.com/ para obter sua FAIM_API_KEY

Servidor MCP Remoto — Útil para Ferramentas de Automação de Fluxos de Trabalho como n8n

O servidor MCP é implantado remotamente.

Para usar o servidor MCP remoto, envie solicitações para o seguinte endpoint:

https://mcp.faim.it.com

Forneça sua chave da API FAIM usando autenticação Bearer.

Servidor MCP Local

Opção 1: Instalar a partir do npm (Recomendado)

Configure seu cliente para usá-lo diretamente com npx:

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

Nenhuma instalação necessária — npx baixará e executará automaticamente a versão mais recente.

Alternativamente, se preferir instalar globalmente primeiro:

npm install -g @faim-group/mcp

Depois, na configuração:

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

Opção 2: Clonar e 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

Depois, use o caminho local:

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

Exemplos

Fluxo de Trabalho n8n — Previsão de Demanda

Um exemplo de fluxo de trabalho n8n para previsão de demanda está disponível em examples/n8n/demand_forecasting.json. Este fluxo de trabalho demonstra como integrar o servidor MCP FAIM com n8n para tarefas automatizadas de previsão de demanda.

Para usar este exemplo:

  1. Abra o n8n
  2. Importe o fluxo de trabalho de n8n_examples/demand_forecasting.json
  3. Configure sua chave da API FAIM nas configurações de conexão MCP
  4. Execute o fluxo de trabalho com seus dados de séries temporais

Configuração

Variáveis de Ambiente

# 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

Compatibilidade com MCP

Este servidor implementa o Model Context Protocol (MCP), um protocolo aberto para conectar assistentes de IA a ferramentas externas e fontes de dados. Ele funciona com qualquer LLM e aplicação que implemente um cliente MCP.

Uso com Qualquer LLM ou Sistema

Este servidor implementa o protocolo MCP padrão e funciona com qualquer aplicação que implemente um cliente MCP:

  • Implementação direta de cliente MCP
  • Adaptadores de frameworks de IA que suportam MCP
  • Extensões de IDE que expõem ferramentas MCP a qualquer LLM
  • Middleware personalizado que traduz entre MCP e o formato de chamada de ferramentas do seu LLM

Uso

Iniciando o Servidor

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

O servidor irá:

  1. Ler a chave da API do ambiente
  2. Inicializar o cliente FAIM
  3. Ouvir em stdin para solicitações JSON-RPC
  4. Enviar respostas para stdout

Ferramenta 1: Listar Modelos

Retorna os modelos de previsão disponíveis e suas capacidades.

Solicitação:

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

Resposta:

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

Ferramenta 2: Previsão

Realiza previsões de séries temporais usando modelos FAIM.

Solicitação (Previsão Pontual):

{
  "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"
    }
  }
}

Solicitação (Previsão por Quantis com Intervalos de Confiança):

{
  "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]
    }
  }
}

Resposta:

{
  "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]
      }
    }
  }
}

Estrutura do Projeto

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

Testes

O projeto inclui testes abrangentes para:

  • Validação de Entrada: Entradas válidas/inválidas, casos extremos, valores de limite
  • Tratamento de Erros: Erros do SDK, erros de JavaScript, classificação de erros
  • Funcionalidade das Ferramentas: Estrutura de resposta, disponibilidade de modelos
  • Segurança de Tipos: Compilação TypeScript, guardas de tipo

Execute os testes:

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

Depuração

Ative o registro detalhado:

NODE_ENV=development node dist/index.js

A saída vai para stderr (sem interferir no JSON-RPC do stdout).

Compilação e Implantação

Compilar para Produção

npm run build

Saídas:

  • dist/index.js - Módulo ESM
  • dist/index.cjs - Módulo CommonJS
  • dist/index.d.ts - Declarações de tipos
  • Mapas de origem para depuração

Lista de Verificação de Implantação

  • Defina a variável de ambiente FAIM_API_KEY
  • Execute npm run build
  • Execute npm test para verificar
  • Implante o diretório dist/
  • Execute node dist/index.js como processo do servidor

Solução de Problemas

"FAIM_API_KEY não definida"

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

Erros de "Módulo não encontrado"

npm install
npm run build

Servidor não respondendo

  • Verifique se stdout/stderr estão conectados corretamente
  • Verifique o formato JSON-RPC das solicitações
  • Verifique os logs para mensagens de erro
  • Garanta que a API FAIM esteja acessível

Licença

MIT