filinglens

filinglens

filinglens は、ホスト型 Finbolt MCP サーバーへの小規模なローカルブリッジです。中心となるのは SEC の提出書類から取得した企業の財務情報で、すべての数値を元の提出書類までたどれます。報告された事実を尋ねると、値とともにアクセッション番号、フォーム、提出日、XBRL タグが返されます。財務諸表を尋ねると、損益計算書、貸借対照表、またはキャッシュフロー計算書が、新しい期間から順に返されます。その中核を取り巻くのは、市場データ（相場、日次／週次／月次の時系列、為替レート、ニュースセンチメント）と、一般的なテクニカル指標です。

このブリッジは独自のデータを保持しません。上流サーバーで取得したツール一覧をローカルで提供し、各ツール呼び出しを上流へ転送して、結果を変更せずに返します。

ラベル付きサブセット — 23 個中 21 個のツール

この再構築版はラベル付きサブセットであり、ライブキャプチャに含まれる 23 個のツールのうち 21 個を提供します。省略した 2 個のツールは find_tool と run_tool です。これは「デフォルト一覧に含まれていないものも含む、113 個すべてのデータツール」を検索して実行するメタディスパッチのペアです。これは、スキーマがどこにも公開されていない、およそ 92 個の列挙されていないツールに動的にアクセスする仕組みです。そのため、同等性を固定できず、意図的にここでは登録していません。テストスイートでは、これらが存在しないことを検証します。

提供する 21 個のツールはすべて読み取り専用です。SEC 提出書類の出典付き財務情報、市場データ、テクニカル指標が含まれます。取引、注文、アカウントのツールはありません。上流の説明ではデータは「個人的な調査のみ」とされています。利用時にはこれを遵守してください。

ツール

時系列、検索、相場：

• fetch_time_series_daily — 日次 OHLCV。必須：symbol。
• fetch_time_series_weekly — 週次 OHLCV。必須：symbol。
• fetch_time_series_monthly — 月次 OHLCV。必須：symbol。
• search_endpoint — シンボル／企業の検索。必須：keywords。
• fetch_quote — 最新価格と取引情報。必須：symbol。
• fetch_news_sentiment — ニュースセンチメント。必須：tickers。
• fetch_company_overview — 概要、各種比率、時価総額。必須：symbol。
• fetch_exchange_rate — 通貨換算。必須：from_currency、to_currency。

財務諸表と業績：

• fetch_income_statement — 必須：symbol。
• fetch_balance_sheet — 必須：symbol。
• fetch_cash_flow — 必須：symbol。
• fetch_earnings — EPS の予想と実績。必須：symbol。

テクニカル指標：

• fetch_sma — 必須：symbol、interval、time_period。
• fetch_ema — 必須：symbol、interval、time_period。
• fetch_macd — 必須：symbol、interval。
• fetch_rsi — 必須：symbol、interval。
• fetch_bbands — 必須：symbol、interval。

SEC 提出書類ツール：

• analyze_stock — 1 回の呼び出しで概要を取得：提出書類に基づくファンダメンタルズ（各提出書類をアクセッション番号で引用）、市場データ、算出された比率。必須：symbol。
• compare_stocks — 2～6 銘柄を並べた比較表。必須：symbols。
• get_fact — 出典付きの報告数値。報告されたことのない数値は推定されず、欠損として返されます。必須：company、concept。
• financials — SEC 提出書類に基づく完全な財務諸表。新しい期間から順に並び、各 null に理由が付されます。必須：company。

設定

• FINBOLT_MCP_URL（任意）— 上流エンドポイントを上書きします。デフォルトは https://api.getfinbolt.com/mcp です。（この上書きフックは、この再構築版独自のラベル付き再現です。）
• FINBOLT_API_KEY（任意）— 設定すると、すべての上流リクエストに Authorization: Bearer <key> ヘッダーが付与されます。設定しない場合、キーのヘッダーは送信されません。（ヘッダー名はレジストリレコードで固定されています。Bearer スキームと環境変数の転送はラベル付き再現です。元のインターフェースはキーなしでキャプチャされました。）

転送の仕組み

最初のツール呼び出し時に、クライアントは上流とのストリーミング可能な HTTP セッションを開きます。まず JSON-RPC の initialize リクエスト（protocolVersion 2025-03-26、clientInfo name filinglens）を送り、続いて notifications/initialized 通知を送り、その後、呼び出し元の引数を変更せずに含めた tools/call リクエストを送ります。上流が initialize に Mcp-Session-Id ヘッダーを付けて応答すると、その値はセッション内の 以降のすべてのリクエストに付与され、プロセスの存続中は同じセッションが 再利用されます。応答は通常の JSON またはサーバー送信イベントとして 届く場合があり、どちらも読み取られます。

上流からの成功した結果は、上流が設定した isError フラグを含め、 そのまま渡されます。JSON-RPC エラー、2xx 以外のステータス、 読み取り不能な応答、または完了できないリクエストといった失敗は、 テキストが filinglens error: で始まる isError 結果として 返されます（この形式は、この再構築版独自のラベル付き表現です）。

CLI

各ツールは、1 つの JSON 引数文字列を受け取るサブコマンドでもあります。

npx @reneturcios/filinglens fetch_quote '{"symbol":"AAPL"}'
npx @reneturcios/filinglens get_fact '{"company":"AAPL","concept":"revenue"}'
npx @reneturcios/filinglens financials '{"company":"AAPL","statement":"income"}'
npx @reneturcios/filinglens --version

終了コード：成功時は 0、isError 結果の場合は 1、使用方法に誤りがある場合は 2 です。

MCP サーバー

npx -y @reneturcios/filinglens mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "filinglens": {
      "command": "npx",
      "args": ["-y", "@reneturcios/filinglens", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/filinglens
docker run --rm ghcr.io/cloudcorprecords/filinglens --version

コンテナーのデフォルトコマンドは mcp です。そのため、最初の形式では標準入出力を使用する MCP サーバーが起動します。それ以外の引数は通常どおり CLI に渡されます。

開発

npm install
npm run build
npm test
npm run dev

テストスイートはすべて、スタブ化された JSON-RPC 上流に対して実行されます。実際のネットワーク呼び出しはありません。

ライセンス

MIT — LICENSE を参照してください。