blackforge

@blackforge-so/mcp

エージェントが BlackForge の市場データを利用できるようにする、Model Context Protocol の stdio サーバーです。暗号資産市場全体をリアルタイムで — 9 つの現物取引所（binance、bitget、bybit、coinbase、gate、kraken、kucoin、mexc、okx）と、計測されるすべての列を、ペアごとに確定した分足単位で提供します（Ultra と PAYG では 1m、すべてのプランで 5m、1h、1d の集計データを提供）。

すべての列は定義に基づく測定値です — 板の深さと形状、板に残る流動性の存続時間、取引量と板から推定される出来高、スプレッド、市場全体の状況などを、エージェントが生の市場マイクロストラクチャーを直接読み取れるよう、コンテキスト内で返します。公開されている BlackForge /v1 API を利用する薄いクライアントであり、データの保存も加工も行いません。

クイックスタート

MCP クライアントにサーバーを追加し、API キーを貼り付けます。Claude Desktop （claude_desktop_config.json）または Claude Code（.mcp.json）の場合：

{
  "mcpServers": {
    "blackforge": {
      "command": "npx",
      "args": ["-y", "@blackforge-so/mcp"],
      "env": { "BLACKFORGE_API_KEY": "bf_live_your_key" }
    }
  }
}

インストール手順はありません — npx -y @blackforge-so/mcp が必要に応じてサーバーを取得し、実行します。

キーの取得先

app.blackforge.so → API でキーを発行します。サーバーはキーを作成しません。環境変数から BLACKFORGE_API_KEY を読み取ります。blackforge_catalog ツールはキーなしで動作するため、キーを貼り付ける前にインストールを確認できます。

ツール

ツール	返される内容
blackforge_catalog	すべての取引所と列の定義 — 9 つの取引所が含まれ、metricCount は現在の列数です。キーは不要です。有効な exchange と metric の識別子を確認するため、最初にこれを呼び出してください。
blackforge_symbols	取引所で扱われている取引ペア。例：["BTCUSDT", …]。
blackforge_latest	1 つの (exchange, symbol) における、プランの間隔での最新の確定バケット（Ultra と PAYG では 1 分、それ以外では 5 分） — 列から数値への対応を示す values オブジェクトと、エポックミリ秒の ts を返します。columns を渡すと対象を絞り込めます。
blackforge_series	指定期間における 1 つの列の時系列：1m（Ultra と PAYG）、5m、1h、1d の昇順 { ts, value } ポイント。上限は 50,000 ポイントで、上限を超える場合は最新のデータが保持され、truncated: true が設定されます。1 分足の行は 1 分足への切り替え以降のデータです（カタログ内の availableFrom を参照）。5m では全履歴を取得できます。
blackforge_usage	キーの最近のリクエスト数と、月間行数クォータの残量。

キーで読み取れる取引所、列、間隔などのプラン利用条件は、API によって適用されます。プランに含まれていない列が除外されると、ツールの結果で columnsOmitted にその列が示されるため、エージェントはキーが表示されない理由を把握できます。取引所または間隔の制限がある場合は、HTTP ステータスとサーバーのメッセージ（アップグレード URL を含め、原文のまま）を含む、明確なツールエラーが返されます。

ライブフォーミュラとライブオーダーブック

保存済みの履歴に加えて、サーバーはBlackForgeのリアルタイムホストに接続します。主要な取引所のオーダーブックと取引データから独自の指標を作成し、毎秒ストリーミングして、指定した値を超えたときに通知を受け取れます。

ツール	内容	プラン
blackforge_formula_validate	フォーミュラを保存せずに検証します。無料です。拒否された場合はデータとして返されます。安定したcode、ソース内の位置を示すpointer、suggestions（例：取引所で実際に使われているペアの表記）が含まれるため、エージェントは修正して再検証できます。	Ultra
blackforge_formula_create	フォーミュラ（name、expr、1～60秒のinterval）を保存します。	Ultra
blackforge_formula_list	保存済みのフォーミュラ、上限、現在の使用量を表示します。	Ultra
blackforge_formula_delete	フォーミュラと、それに設定された通知を削除します。	Ultra
blackforge_formula_watch	保存済みのフォーミュラ（formulaId）または単発のexprを最大60秒間（デフォルトは20秒）ストリーミングし、最初、最後、最小、最大、検出されたフラグ、全時系列を返します。	Ultra
blackforge_alert_create	指定した値（above、below、cross）をフォーミュラが超えたとき、メールと、任意で署名付きのwebhookUrlを通じて通知します。Webhookシークレットは一度だけ表示されます。	Ultra
blackforge_alert_list / blackforge_alert_delete	通知を一覧表示または削除します。	Ultra
blackforge_book	1つのペアのライブオーダーブックを、片側最大200レベルまで返します。	Max, Ultra
blackforge_fill	ライブオーダーブックに対する成行注文の価格を算出します（usdまたはsize）。表示中のオーダーブックですべて約定できない場合、bpsはnullになります。	Max, Ultra
blackforge_spread_map	同じ時点で読み取った、あるベース／クオートのペアを取り扱うすべての取引所の最良買値と最良売値を返します。	Max, Ultra

フォーミュラの例：mid(binance:BTCUSDT) - mid(okx:BTC-USDT)、または buyVol(binance:SOLUSDT, 60s) / max(sellVol(binance:SOLUSDT, 60s), 1)です。ペアは blackforge_symbolsに記載されている表記と完全に一致させてください。関数の全一覧は blackforge_formula_validateツールの説明に記載されています。ストリーミングと通知では、評価ごとに参照されたペア1つにつき1行分が課金されます。ライブオーダーブックの読み取りは、返された、または参照されたレベル数に応じて課金され、他のすべての利用と同じ月間クォータが適用されます。ストリーミングされる各値にはflagsが付与されます（例：ウィンドウを使う項のウィンドウがまだ満たされていない間はWARMING）。nullは数値が存在しなかったことを意味し、ゼロを意味することはありません。

ストリームではNode組み込みのWebSocketを使用するため、blackforge_formula_watchにはNode 22以降が必要です。それ以外のツールはすべてNode 20で動作します。キーはx-api-keyヘッダーで送信され、URLに含まれることはありません。

チャート

blackforge_seriesにはインタラクティブなチャートも含まれています。 MCP Apps拡張機能 （io.modelcontextprotocol/ui）を実装しているホストでは、結果が折れ線グラフとして表示されます。フラグ付きバケットはBlackForgeコンソールと同じ表記で描画されます。それ以外のホストでは、従来どおりのJSONがそのまま表示されます。

ツールの仕様に変更はありません。チャートのペイロードは結果の_metaに含まれます。これはプロトコルメタデータであり、モデルには届きません。そのため、ホストがウィジェットを描画するかどうかにかかわらず、content[0].textはバイト単位で同一であり、時系列データのトークンコストも変わりません。これは意図的な設計です。structuredContentは一見すると適切な格納先ですが、コアMCPではこのフィールドをサーバー生成の結果データとして扱います。そのため、Appsに対応していないホストがこれをモデルに渡し、大きな時系列データのコストが2倍になる可能性があります。

チャートは、uPlotとすべてのCSSをインライン化した自己完結型のHTMLファイルです。MCP Appsはデフォルトですべてを拒否するCSPの下で描画されるため、外部の<script>は読み込まれません。チャートは読み取り専用で、サーバーにコールバックすることはありません。渡されたポイントを描画するだけなので、ユーザーに知らせずに行クォータを消費することはありません。2,000ポイントを超える時系列データはチャート表示に限り間引かれます。ツールは引き続きすべてのポイントを返し、ペイロードには線をひそかに間引いたのではなく、間引きを行ったことが明記されます。

データ品質

API が行の測定品質を報告すると、blackforge_latest はそれを quality オブジェクト（ウィンドウ内で発生した問題を示す flags と、フラグが付いた数値を列挙する contaminates）および平易な英語の qualityNote として引き継ぎます。blackforge_series は各ポイントに繰り返し付与するのではなく、1 つの qualitySummary（{ flaggedBuckets, of, flags }）に集約します。何もフラグが付いていない場合、どちらのキーも完全に省略されます。また、quality.raw が 32768 の場合、その行は品質レールが導入される前のもので、評価されていないことを意味します。つまり、品質不良ではなく不明です。フラグのデコードテーブルは blackforge_catalog の qualityFlags メトリックに bits 配列として格納されています。このサーバーはそこから読み取り、独自のコピーは保持しません。

設定

環境変数	デフォルト	用途
BLACKFORGE_API_KEY	(なし)	キーです。blackforge_catalog を除くすべてのツールで必須です。
BLACKFORGE_BASE_URL	https://api.blackforge.so	API のベース URL です。パスは /v1/... として追加されます。セルフホスト環境またはローカル開発用の API（例：http://localhost:3001/api）を使う場合は上書きしてください。
BLACKFORGE_REALTIME_URL	https://realtime.blackforge.so	ライブ数式ストリームとライブ注文板の読み取りに使用するリアルタイムホストです。

ローカル開発

npm install
npm run build     # → dist/index.js (ESM, executable) + dist/widget/chart.html
npm test          # client unit tests + a stdio integration test

build は最初に tsup を実行し、次にウィジェットの vite ビルドを実行します。この順序は重要です。tsup の clean は dist/ 全体を削除するため、順序を逆にするとウィジェットが削除され、サーバーは存在しないリソースを提供することになります。

統合テストでは、ビルド済みサーバーを stdio 経由で起動し、MCP クライアントで操作します。データのアサーションには http://localhost:3001/api で動作するローカルの BlackForge API が必要です。API がない場合、該当するアサーションはスキップされますが、ツール一覧のチェックは引き続き実行されます。

ライセンス

MIT