Faim Time Series Forecasting

FAIM MCP Server

一个模型上下文协议（MCP）服务，可将 FAIM 时间序列预测 SDK 与任何兼容 MCP 的 AI 助手集成，从而实现 AI 驱动的预测功能。

NPM 包： @faim-group/mcp

概述

此 MCP 服务目前通过 FAIM API 提供两个基础时间序列模型，用于零样本预测：

• Chronos2
• TiRex

主要功能

✅ 两个 MCP 工具：

• list_models：返回可用的预测模型及其功能
• forecast：执行时间序列点预测和概率预测

✅ 灵活的输入格式：

• 1D 数组：单变量时间序列
• 3D 数组：批次/序列/特征格式

✅ 概率预测：

• 点预测（单值预测）
• 分位数预测（置信区间）
• 样本预测（分布样本）
• 用于风险评估的自定义分位数级别

安装

前置条件

• Node.js 20+
• npm 10+
• FAIM API 密钥：在 https://faim.it.com/ 注册以获取 FAIM_API_KEY

远程 MCP 服务 — 适用于 n8n 等工作流自动化工具

MCP 服务已部署在远程。

如需使用远程 MCP 服务，请向以下端点发送请求：

https://mcp.faim.it.com

使用 Bearer 身份验证提供 FAIM API 密钥。

本地 MCP 服务

选项 1：通过 npm 安装（推荐）

将客户端配置为直接通过 npx 使用：

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

无需安装——npx 会自动下载并运行最新版本。

或者，如果你希望先全局安装：

npm install -g @faim-group/mcp

然后在配置中：

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

选项 2：克隆并在本地构建

# 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

然后使用本地路径：

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

示例

n8n 工作流 — 需求预测

examples/n8n/demand_forecasting.json 中提供了一个用于需求预测的 n8n 工作流示例。此工作流演示了如何将 FAIM MCP 服务与 n8n 集成，以自动执行需求预测任务。

使用此示例的步骤：

1. 打开 n8n
2. 从 n8n_examples/demand_forecasting.json 导入工作流
3. 在 MCP 连接设置中配置 FAIM API 密钥
4. 使用你的时间序列数据执行工作流

配置

环境变量

# 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

MCP 兼容性

此服务实现了模型上下文协议（MCP），这是一种用于将 AI 助手连接到外部工具和数据源的开放协议。它适用于任何实现 MCP 客户端的大模型和应用程序。

与任意大模型或系统搭配使用

此服务实现了标准 MCP 协议，适用于任何实现 MCP 客户端的应用程序：

• 直接实现 MCP 客户端
• 支持 MCP 的 AI 框架适配器
• 可向任意大模型开放 MCP 工具的 IDE 扩展
• 可在 MCP 与大模型的工具调用格式之间进行转换的自定义中间件

使用方法

启动服务

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

服务将：

1. 从环境中读取 API 密钥
2. 初始化 FAIM 客户端
3. 通过 stdin 监听 JSON-RPC 请求
4. 将响应发送到 stdout

工具 1：列出模型

返回可用的预测模型及其功能。

请求：

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

响应：

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

工具 2：预测

使用 FAIM 模型执行时间序列预测。

请求（点预测）：

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

请求（带置信区间的分位数预测）：

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

响应：

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

项目结构

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

测试

项目包含全面的测试，涵盖：

• 输入验证：有效/无效输入、边缘情况、边界值
• 错误处理：SDK 错误、JavaScript 错误、错误分类
• 工具功能：响应结构、模型可用性
• 类型安全：TypeScript 编译、类型保护

运行测试：

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

调试

启用详细日志：

NODE_ENV=development node dist/index.js

输出会写入 stderr（不会干扰 stdout 中的 JSON-RPC）。

构建和部署

构建生产版本

npm run build

输出：

• dist/index.js - ESM 模块
• dist/index.cjs - CommonJS 模块
• dist/index.d.ts - 类型声明
• 用于调试的源映射

部署检查清单

• 设置 FAIM_API_KEY 环境变量
• 运行 npm run build
• 运行 npm test 进行验证
• 部署 dist/ 目录
• 以服务进程的形式运行 node dist/index.js

故障排查

“未设置 FAIM_API_KEY”

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

“找不到模块”错误

npm install
npm run build

服务无响应

• 检查 stdout/stderr 是否正确连接
• 验证请求的 JSON-RPC 格式
• 检查日志中的错误消息
• 确保可以访问 FAIM API

许可证

MIT