fd-open-data-mcp

オープンデータオントロジーMCP: マルチデータソースの金融/経済データ上に構築されるセマンティック概念レイヤーです。データを概念 + エンティティでリクエストします（例: "Moutai の price.close"、"中国の GDP"）。システムは概念をデータソース間の物理列に解決し、候補ソースを品質 + 到達性でランク付けし、最良のソースから取得（フェイルオーバー付き）し、概念ごとにキャッシュし、概念ごとの頻度で更新します。

English | 中文

オープンデータオントロジーMCP: 複数のデータソースの金融/経済データの上にセマンティック概念レイヤーを構築します。データは概念 + エンティティでリクエストします（例: "茅台の price.close"、"中国の GDP"）。システムは概念を各データソースの物理列に解決し、品質 + 到達性で候補データソースをランク付けし、最適なデータソースから取得（フェイルオーバー付き）し、概念ごとにキャッシュし、各概念の頻度で更新します。

ワンクリックインストール

単一の自己完結型ブロックで、finddata オープンデータスタック全体（ハブ＋すべてのデータソースパッケージ＋オントロジーDB）をブートストラップします。再実行しても安全で、最初のエラーで停止します。

# 1) Install the full stack from PyPI.
#    fd-open-data-protocol is pulled in transitively; fd-polygon and
#    fd-cn-report auto-register via entry-points. Drop "[data]" for a lighter
#    install (MCP server + CLI only, without the akshare/yfinance/playwright SDKs).
pip install "fd-open-data-mcp[data]" fd-polygon fd-cn-report

# 2) Initialize the ontology DB and wire every layer: catalogs -> concepts ->
#    column bindings -> per-source entity ids -> refresh schedules -> manifests.
fd-open-data-mcp migrate \
  && fd-open-data-mcp import-catalog \
  && fd-open-data-mcp consume-concepts \
  && fd-open-data-mcp propose-bindings \
  && fd-open-data-mcp seed-entities \
  && fd-open-data-mcp generate-schedules \
  && fd-open-data-mcp register-discovered

# 3) Start the MCP server (stdio transport, for any MCP client).
fd-open-data-mcp serve

ライブデータの取得には、ソースキーが環境に必要です（コミットしないでください）: POLYGON_API_KEY、EDGAR_IDENTITY、そして fd-cn-report 用の LLM_* / ES_* セットです。各パッケージの設定セクションを参照してください。

Related MCP server: Sugra API MCP

アーキテクチャ

CONSUMED (read-only)                  ADDED by fd-open-data-mcp
 fd-akshare / yfinance / edgar /        concept_bindings      (column -> concept)
 wbgapi / cn-report / cn-gov /           entity_source_identifiers (per-source id)
 datacommons / polygon registries        source_rankings       (quality × access × freshness)
 fd-entities-indicators                 semantic_observations (read-through cache)
   indicator_defs (concepts)             fetch_log / schedules / executions / policies
   countries/cities/symbols/sw_industries   entities / relationships (graph)
        │
   TRANSFORMERS: import_catalog, consume_concepts, propose_bindings,
                 seed_entity_identifiers, generate_refresh_schedules, ingest_entities
        │
   RUNTIME: read() -> cache hit? : dispatch (ranked, failover) -> cache -> log
   SEARCH : semantic_search (concepts) + graph_search (entity relationships) + ai_search

8つの機能領域（openspec/changes/add-fd-open-data-mcp/specs/ を参照）: open-data-catalog、semantic-layer、entity-identity、source-ranking、concept-fetch、scheduled-refresh、entity-graph、vector-search。

インストール

cd fd-open-data-mcp
uv sync                  # base install

# For full data source support (akshare, yfinance, edgar, world bank, etc.)
uv sync --extra data

DBパスはデフォルトで fd_open_data_mcp/metadata/daas.db です。FD_OPEN_DATA_MCP_DATABASE_URL で上書きします。FINDDATA_ROOT（デフォルト: 親の finddata/ ディレクトリ）は fd-* プロバイダーの場所を特定します。

SEC EDGAR は使用前に環境で EDGAR_IDENTITY="your_email@example.com" を必要とします（SEC は匿名アクセスに User-Agent を義務付けています）。

クイックスタート

# 1. create the ontology tables
fd-open-data-mcp migrate

# 2. import the catalogs (akshare, yfinance, cn-gov, cn-report, edgar, ...)
fd-open-data-mcp import-catalog
# or one provider:  fd-open-data-mcp import-catalog akshare

# 3. consume indicator_defs as concepts + propose column->concept bindings
fd-open-data-mcp consume-concepts
fd-open-data-mcp propose-bindings

# 4. seed per-source entity identifiers (akshare/yfinance for stocks, worldbank for countries)
fd-open-data-mcp seed-entities

# 5. generate per-concept refresh schedules from indicator_defs.frequency
fd-open-data-mcp generate-schedules

# 6. read data by concept + entity (read-through cache + ranked dispatch + failover)
fd-open-data-mcp read --concept-id 234 --entity-type stock --entity-id 1 --date 2024-07-26

MCPサーバー

fd-open-data-mcp serve          # FastMCP, stdio transport

MCPツール面は8つの機能領域に編成されています（信頼できるセットはMCPクライアントのツールリストを参照してください）:

ai_search はエンドツーエンドのエントリポイントです: セマンティック検索 → グラフ探索 → 値のクエリを1回の呼び出しで行います。

データソース

ソースは fd_open_data_mcp/fetch/runner.py::run_upstream() で配線されています。これはハードコードされたソース→ランナーチェーンです。以下の表は、各アダプターの実際の状態を反映しており、理想的な状態ではありません。

本番（ネットワーク接続）

外部データソースパッケージ（polygon、datacommons）はフェッチ時に遅延インポートされるため、fd-open-data-mcp は実際にフェッチを行うまでそれらのSDKに依存しません。

スタブ / プレースホルダー

これらのアダプターは存在し、ディスパッチ可能ですが、プレースホルダーデータを返します。将来のスクレイピング作業のための足場であり、実用的なデータソースではありません:

amac-fund、shfe-metal-futures、agriculture（DCE）、cme-agricultural-futures、chemicals、electronics、nonferrous、flowers-kifc、fin_platforms、sac-securities。

注: fd-open-data-mcp list-sources CLI はすべてのアダプターを「✅ 完全サポート」とマークします。このラベルは統合の保証ではありません。アダプターファイルが存在するかどうかをチェックしているだけです。上記のスタブリストを正として扱ってください。

読み取り専用レジストリ

クロールコントロールセンター（パネル + レコンサイラー）

ポリシーは 何をクロールするか を記述します: コンセプト × エンティティスコープ × 日付範囲 × 頻度 × モード。CrawlPolicy はパネルから作成され、レコンサイラーによって CrawlPlan にコンパイルされ、scraw-fd-open-data-mcp によって実行されて semantic_observations に取り込まれます。

# Serve the control panel (default http://0.0.0.0:8000)
FD_OPEN_DATA_MCP_DATABASE_URL=<db url> fd-open-data-mcp panel

# Run the reconciler once (due policies -> launch; closes stale runs)
python -m fd_open_data_mcp.refresh.reconciler

環境変数:

• PANEL_TOKEN — 設定されている場合、/panel/* はそれを要求します（ヘッダー X-Panel-Token、?token=、またはクッキー）。

• POLICY_MAX_FETCHES（デフォルト 50000）— プランサイズのガードレール。フェッチ見積もりがこれを超える期日到来ポリシーは、ポリシーに force が設定されていない限り拒否されます（失敗したランとして記録されます）。

• RECONCILER_LAUNCHER — scrapyd（デフォルト）または k8s（K8sJobLauncher）。

• SCRAPYD_URL / SCRAW_PLAN_DIR（scrapydランチャー）、SCRAW_K8S_NAMESPACE / SCRAW_K8S_IMAGE / SCRAW_K8S_DATABASE_URL / SCRAW_K8S_REDIS_URL（k8sランチャー）。

• FD_PROXY_FORWARDER — ローカル開発では未設定（インジェクションシムがダイレクトセンチネルを返す → ダイレクト出力。スタンドアロンの fd-proxy-service フォワーダーがクラスクロールのプロキシ選択を担当）。従来の FD_PROXY_POOL/FD_EGRESS_MODE 変数は読み取られなくなりました。

ポリシー例（パネル経由、またはMCP policy_create）:

name:        fund-nav-daily
entity_type: fund
concepts:    nav.unit, nav.accumulated
mode:        per_date          # or "series" (one bulk fetch per entity)
date_policy: since_last        # start = observation watermarks
frequency:   daily
source:      akshare
cron:        45 6 * * * UTC

2つの頻度に関する注意: series モードはエンティティごとに1回の一括フェッチで履歴をバックフィルします（明示的な範囲）。一方、since_last の per_date は定常状態の増分モードです（各コンセプトのウォーターマーク以降の新しい日付のみ。ウォーターマークのないエンティティはバックフィルされません — 最初に明示的な範囲のバックフィルを実行してください）。検証済みパイロット（本番DB上の76k NAV観測値）については、openspec/changes/add-fund-crawl-control-center/docs/phase7-validation.md を参照してください。

CLI

fd-open-data-mcp migrate                 # create ontology tables
fd-open-data-mcp import-catalog [src]    # import fd-* catalogs
fd-open-data-mcp consume-concepts        # indicator_defs -> concepts
fd-open-data-mcp propose-bindings        # column -> concept bindings
fd-open-data-mcp seed-entities           # per-source entity identifiers
fd-open-data-mcp generate-schedules     # per-concept refresh schedules
fd-open-data-mcp plan-crawl ...         # compile a CrawlPlan
fd-open-data-mcp read --concept-id N --entity-type stock --entity-id 1 --date YYYY-MM-DD
fd-open-data-mcp rank-sources --concept-id N
fd-open-data-mcp register-datasource <path>
fd-open-data-mcp register-discovered    # auto-discover entry-point manifests
fd-open-data-mcp list-sources           # adapter inventory (see caveat above)
fd-open-data-mcp serve                  # MCP server (stdio)
fd-open-data-mcp panel                  # crawl control panel

プロキシプール操作（クラスタ）: seed-proxy-health、probe-cycle、proxy-health。

テスト

uv run --with pytest pytest -q

LLM設定（PDFレポート抽出用）

fd-cn-report はLLMを使用して年次報告書PDFから財務指標を抽出します。これは fd-open-data-mcp と同じ環境で実行され、.env / .env.local の LLM_* 環境変数で設定されます。

LLM_BASE_URL=https://api.plan/v1          # Ark endpoint
LLM_API_KEY=<your-ark-key>                # Ark API key
LLM_MODEL=deepseek-v4-flash              # default model

デフォルトのプロバイダーは DeepSeek on Ark です。OpenAI互換の LLM_BASE_URL（OpenAI、Azure OpenAI、OpenRouter、ローカルOllama）でも動作します — LLM_BASE_URL / LLM_API_KEY / LLM_MODEL をそのURLに向けてください。LLM_API_KEY は OPENAI_API_KEY より優先されます（両方が設定されている場合）。

設計上の注意 / 制限事項

• 提案と確認: 列→コンセプトのバインディングは confidence と provenance を持ちます。しきい値未満のバインディングはディスパッチから保留されます（レビューキュー）。実際のフェッチにより、バインディングは sample-confirmed に昇格します。

• ランキングは (source × concept) ごとに行われ、fetch_log から自己調整されます（1回の失敗でソースが削除されないように制限されています）。

• 競合ポリシー: (concept, entity, date) ごとに1つのキャッシュ値が保存され、source_used が付与されます。値がソース間でマージされることはありません。

• ベクトル検索はJSONB + numpyを使用します（対象のPostgresではpgvectorが利用不可）。コンセプトとエンティティの埋め込みが semantic_search* と ai_search を支えます。

• 実ソースのフェイルオーバー: 関数は real_sources を宣言します（例: stock_zh_a_hist → [eastmoney, tencent, sina]）。eastmoney が禁止されると、ディスパッチャーは tencent/sina にフェイルオーバーします。サーキットブレーカーキーはライブラリ単位ではなく実ソース単位です。

• フェッチランナーの _build_params / _extract_value はベストエフォートです。本番ランナーは関数ごとの日付形式やペイロード形状の癖を改善します。

完全な仕様は openspec/changes/add-fd-open-data-mcp/ を、プロキシ/サーキットブレーカーの設計は openspec/changes/add-source-proxy-health/ を参照してください。

コントリビューション

新しいデータソースを追加するには:

1. fd-open-data-protocol に従ってマニフェストを作成します（YAML/JSONまたは CATALOG ディクショナリ）。

2. パッケージの pyproject.toml の fd_open_data_mcp.datasources エントリポイントを介して公開するか、fd-open-data-mcp register-datasource <path> を使用します。

3. フェッチロジックを組み込みランナーとして表現できない場合は、アダプター（または外部パッケージ）に run_<source>(command, params) を同梱し、run_upstream() で分岐させます。

4. その後、fd-open-data-mcp register-discovered がそれを取り込み、propose-bindings がその列をコンセプトにバインドします。

ライセンス

MIT