fd-open-data-mcp

Ein Open-Data-Ontologie-MCP: eine semantische Konzeptschicht über Finanz-/Wirtschaftsdaten aus mehreren Datenquellen. Sie fragen Daten in Konzepten + Entitäten ab (z. B. „price.close für Moutai", „GDP für China"); das System löst das Konzept in physische Spalten über Datenquellen hinweg auf, stuft Kandidatenquellen nach Qualität + Zugänglichkeit ein, ruft von der besten ab (mit Failover), cacht nach Konzept und aktualisiert mit einer Frequenz pro Konzept.

Es konsumiert die fd-*-Datenquellen-Registries von finddata und fd-entities-indicators schreibgeschützt und fügt die vereinheitlichenden Schichten darüber hinzu: Konzeptbindungen, quellenspezifische Entitätskennungen, Quellen-Rankings, einen Read-through-Wertcache und (obendrein) eine Entitätsgraph- + Vektor-Suchschicht für relationale und semantische Abfragen.

Englisch | 中文

Ein Open-Data-Ontologie-MCP: eine semantische Konzeptschicht über Finanz-/Wirtschaftsdaten aus mehreren Datenquellen. Sie fragen Daten in Konzepten + Entitäten ab (z. B. „price.close für Moutai", „GDP für China"); das System löst das Konzept in physische Spalten über Datenquellen hinweg auf, stuft Kandidatenquellen nach Qualität + Zugänglichkeit ein, ruft von der besten ab (mit Failover), cacht nach Konzept und aktualisiert mit einer Frequenz pro Konzept.

Installation mit einem Klick

Ein einziger in sich geschlossener Block, der den gesamten finddata-Open-Data-Stack bootstrapt (Hub + jedes Datenquellen-Paket + Ontologie-DB). Kann bedenkenlos erneut ausgeführt werden; stoppt beim ersten Fehler.

# 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

Live-Datenabrufe benötigen Quellenschlüssel in der Umgebung (niemals eingecheckt): POLYGON_API_KEY, EDGAR_IDENTITY sowie die LLM_*- / ES_*-Reihe für fd-cn-report. Siehe den Konfigurationsabschnitt jedes Pakets.

Related MCP server: Sugra API MCP

Architektur

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

Acht Fähigkeitsbereiche (siehe 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.

Installation

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

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

Der DB-Pfad lautet standardmäßig fd_open_data_mcp/metadata/daas.db; überschreiben Sie ihn mit FD_OPEN_DATA_MCP_DATABASE_URL. FINDDATA_ROOT (Standard: das übergeordnete finddata/-Verzeichnis) lokalisiert die fd-*-Anbieter.

SEC EDGAR erfordert EDGAR_IDENTITY="your_email@example.com" in der Umgebung vor Verwendung (die SEC schreibt einen User-Agent für den anonymen Zugriff vor).

Schnellstart

# 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-Server

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

Die MCP-Tooloberfläche ist in acht Fähigkeitsbereiche gegliedert (die maßgebliche Liste finden Sie in Ihrem MCP-Client):

ai_search ist der End-to-End-Einstiegspunkt: semantische Suche → Graph-Traversierung → Wertabfrage, in einem einzigen Aufruf.

Datenquellen

Quellen sind in fd_open_data_mcp/fetch/runner.py::run_upstream() verdrahtet, einer hartcodierten Quelle→Runner-Kette. Die folgende Tabelle spiegelt den tatsächlichen Zustand jedes Adapters wider, keinen Wunschstatus.

Produktion (netzwerkbasiert)

Externe Datenquellen-Pakete (polygon, datacommons) werden beim Abruf lazy-importiert, sodass fd-open-data-mcp nicht von deren SDKs abhängt, sofern nicht tatsächlich ein Abruf erfolgt.

Stub / Platzhalter

Diese Adapter existieren und sind aufrufbar, geben aber Platzhalterdaten zurück — sie sind Gerüste für zukünftige Scraping-Arbeiten, keine nutzbaren Datenquellen:

amac-fund, shfe-metal-futures, agriculture (DCE), cme-agricultural-futures, chemicals, electronics, nonferrous, flowers-kifc, fin_platforms, sac-securities.

Hinweis: Die fd-open-data-mcp list-sources-CLI markiert jeden Adapter mit „✅ Full support". Dieses Label ist keine Integrationsgarantie — es prüft nur, ob eine Adapterdatei existiert. Behandeln Sie die obige Stub-Liste als maßgeblich.

Nur-Lese-Registries

Crawl-Kontrollzentrum (Panel + Reconciler)

Richtlinien beschreiben, was gecrawlt werden soll: Konzepte × Entitätsumfang × Datumsbereich × Häufigkeit × Modus. Eine CrawlPolicy wird über das Panel erstellt, vom Reconciler in einen CrawlPlan kompiliert und von scraw-fd-open-data-mcp in semantic_observations ausgeführt.

# 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

Umgebungsvariablen:

• PANEL_TOKEN — wenn gesetzt, erfordert /panel/* ihn (Header X-Panel-Token, ?token= oder Cookie).

• POLICY_MAX_FETCHES (Standard 50000) — Schutzschranke für die Plangröße; eine fällige Richtlinie, deren Abrufschätzung diesen Wert überschreitet, wird abgelehnt (als fehlgeschlagener Lauf protokolliert), es sei denn, die Richtlinie hat force gesetzt.

• RECONCILER_LAUNCHER — scrapyd (Standard) oder k8s (K8sJobLauncher).

• SCRAPYD_URL / SCRAW_PLAN_DIR (scrapyd-Launcher), SCRAW_K8S_NAMESPACE / SCRAW_K8S_IMAGE / SCRAW_K8S_DATABASE_URL / SCRAW_K8S_REDIS_URL (k8s-Launcher).

• FD_PROXY_FORWARDER — für die lokale Entwicklung nicht gesetzt (der Injektions-Shim gibt einen direkten Sentinel zurück → direkter Egress; der eigenständige fd-proxy-service-Forwarder übernimmt die Proxy-Auswahl bei Cluster-Crawls). Die Legacy-Variablen FD_PROXY_POOL/FD_EGRESS_MODE werden nicht mehr gelesen.

Richtlinienbeispiel (über Panel oder 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

Zwei Hinweise zur Kadenz: Der Modus series füllt die Historie in einem Sammelabruf pro Entität auf (expliziter Bereich), während since_last per_date der inkrementelle Dauerbetrieb ist (nur neue Daten seit dem Watermark jedes Konzepts; Entitäten ohne Watermark werden nicht aufgefüllt — führen Sie zuerst ein Auffüllen mit explizitem Bereich aus). Siehe openspec/changes/add-fund-crawl-control-center/docs/phase7-validation.md für den validierten Piloten (76k NAV-Beobachtungen auf der Live-DB).

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

Proxy-Pool-Operationen (Cluster): seed-proxy-health, probe-cycle, proxy-health.

Tests

uv run --with pytest pytest -q

LLM-Konfiguration (für PDF-Berichtsextraktion)

fd-cn-report verwendet ein LLM, um Finanzkennzahlen aus Jahresberichts-PDFs zu extrahieren. Es läuft in derselben Umgebung wie fd-open-data-mcp und wird über die LLM_*-Umgebungsvariablen in .env / .env.local konfiguriert:

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

Der Standardanbieter ist DeepSeek on Ark. Jede OpenAI-kompatible LLM_BASE_URL (OpenAI, Azure OpenAI, OpenRouter, lokales Ollama) funktioniert ebenfalls — richten Sie LLM_BASE_URL / LLM_API_KEY / LLM_MODEL darauf aus. LLM_API_KEY hat Vorrang vor OPENAI_API_KEY, wenn beide gesetzt sind.

Designhinweise / Einschränkungen

• Vorschlagen-und-bestätigen: Spalte->Konzept-Bindungen tragen confidence + provenance; Bindungen unterhalb der Schwelle werden vom Versand zurückgehalten (Überprüfungswarteschlange). Ein echter Abruf befördert eine Bindung zu sample-confirmed.

• Ranking erfolgt pro (Quelle × Konzept) und stimmt sich anhand von fetch_log selbst ab (begrenzt, sodass ein Fehler eine Quelle nicht entfernen kann).

• Konfliktrichtlinie: ein zwischengespeicherter Wert pro (Konzept, Entität, Datum) mit angehängtem source_used; Werte werden nie über Quellen hinweg zusammengeführt.

• Vektorsuche verwendet JSONB + numpy (pgvector auf dem Ziel-Postgres nicht verfügbar); Konzept- + Entitäts-Einbettungen bilden die Grundlage für semantic_search* und ai_search.

• Echte-Quellen-Failover: Funktionen deklarieren real_sources (z. B. stock_zh_a_hist → [eastmoney, tencent, sina]); wenn eastmoney gesperrt ist, weicht der Dispatcher auf tencent/sina aus. Circuit-Breaker-Schlüssel gelten pro echter Quelle, nicht pro Bibliothek.

• _build_params / _extract_value im Abruf-Runner sind Best-Effort-Ansätze; ein Produktions-Runner verfeinert funktionsspezifische Eigenheiten bei Datumsformat / Nutzlaststruktur.

Siehe openspec/changes/add-fd-open-data-mcp/ für die vollständige Spezifikation und openspec/changes/add-source-proxy-health/ für das Proxy-/Circuit-Breaker-Design.

Mitwirken

So fügen Sie eine neue Datenquelle hinzu:

1. Erstellen Sie ein Manifest gemäß fd-open-data-protocol (YAML/JSON oder ein CATALOG-Dict).

2. Machen Sie es über den Einstiegspunkt fd_open_data_mcp.datasources in der pyproject.toml Ihres Pakets verfügbar, oder führen Sie fd-open-data-mcp register-datasource <path> aus.

3. Wenn die Abruflogik nicht als eingebauter Runner ausgedrückt werden kann, liefern Sie ein run_<source>(command, params) in einem Adapter (oder einem externen Paket) und verzweigen Sie in run_upstream() darauf.

4. fd-open-data-mcp register-discovered nimmt es dann auf; propose-bindings bindet seine Spalten an Konzepte.

Lizenz

MIT