Faim Time Series Forecasting

FAIM MCP サーバー

FAIM 時系列予測 SDK を、MCP 対応のあらゆる AI アシスタントと統合する Model Context Protocol（MCP）サーバーです。AI を活用した予測機能を実現します。

NPM パッケージ： @faim-group/mcp

概要

この MCP サーバーは現在、ゼロショット予測用に FAIM API の基盤となる時系列モデルを 2 つ公開しています。

• Chronos2
• TiRex

主な機能

✅ 2 つの MCP ツール：

• list_models：利用可能な予測モデルと機能を返します
• forecast：点予測と確率的時系列予測を実行します

✅ 柔軟な入力形式：

• 1D 配列：単一の単変量時系列
• 3D 配列：バッチ／シーケンス／特徴量形式

✅ 確率的予測：

• 点予測（単一値の予測）
• 分位点予測（信頼区間）
• サンプル予測（分布サンプル）
• リスク評価用のカスタム分位点レベル

インストール

前提条件

• Node.js 20+
• npm 10+
• FAIM API キー：FAIM_API_KEY を取得するには、https://faim.it.com/ で登録してください

リモート 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 ワークフロー — 需要予測

需要予測用の n8n ワークフローの例は、examples/n8n/demand_forecasting.json にあります。このワークフローでは、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 互換性

このサーバーは、AI アシスタントを外部ツールやデータソースに接続するためのオープンプロトコルである Model Context Protocol（MCP） を実装しています。MCP クライアントを実装するあらゆる LLM およびアプリケーションで動作します。

あらゆる LLM またはシステムでの使用

このサーバーは標準の MCP プロトコルを実装しており、MCP クライアントを実装するあらゆるアプリケーションで動作します。

• MCP クライアントの直接実装
• MCP をサポートする AI フレームワークアダプター
• あらゆる LLM に MCP ツールを公開する IDE 拡張機能
• MCP と LLM のツール呼び出し形式を相互変換するカスタムミドルウェア

使用方法

サーバーの起動

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

サーバーは次の処理を行います。

1. 環境変数から API キーを読み取ります
2. FAIM クライアントを初期化します
3. 標準入力で JSON-RPC リクエストを待ち受けます
4. 標準出力にレスポンスを送信します

ツール 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 not set」

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

「Module not found」エラー

npm install
npm run build

サーバーが応答しない

• stdout/stderr が適切に接続されていることを確認します
• リクエストの JSON-RPC 形式を確認します
• エラーメッセージがないかログを確認します
• FAIM API にアクセスできることを確認します

ライセンス

MIT