fd-open-data-mcp

Un MCP de ontología de datos abiertos: una capa de conceptos semánticos sobre datos financieros/económicos de múltiples fuentes. Pides datos en conceptos + entidades (p. ej., "price.close para Moutai", "PIB para China"); el sistema resuelve el concepto a columnas físicas en las fuentes de datos, clasifica las fuentes candidatas por calidad + accesibilidad, obtiene de la mejor (con conmutación por error), almacena en caché por concepto y se actualiza con una frecuencia por concepto.

Consume los registros de fuentes de datos fd-* de finddata y fd-entities-indicators de solo lectura y añade las capas unificadoras encima: enlaces de conceptos, identificadores de entidad por fuente, clasificaciones de fuentes, una caché de valores de lectura directa y (por encima de todo eso) un grafo de entidades + capa de búsqueda vectorial para consultas relacionales y semánticas.

Inglés | 中文

一个开放数据本体 MCP：在多数据源的金融/经济数据之上构建语义概念层。你用概念 + 实体来请求数据（例如"茅台的 price.close"、"中国的 GDP"）；系统将概念解析为各数据源中的物理列，按质量 + 可达性对候选数据源排序，从最佳数据源抓取（带故障转移），按概念缓存，并按每个概念的频率刷新。

Instalación en un clic

Un bloque autocontenido que arranca toda la pila de datos abiertos de finddata (hub + cada paquete de fuentes de datos + base de datos de ontología). Es seguro volver a ejecutarlo; se detiene en el primer error.

# 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

Las descargas de datos en vivo necesitan claves de fuente en el entorno (nunca confirmadas): POLYGON_API_KEY, EDGAR_IDENTITY y el conjunto LLM_* / ES_* para fd-cn-report. Consulta la sección Configuración de cada paquete.

Related MCP server: Sugra API MCP

Arquitectura

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

Ocho áreas de capacidad (consulta 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.

Instalación

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

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

La ruta de la base de datos por defecto es fd_open_data_mcp/metadata/daas.db; se puede sobrescribir con FD_OPEN_DATA_MCP_DATABASE_URL. FINDDATA_ROOT (por defecto: el directorio padre finddata/) localiza los proveedores fd-*.

SEC EDGAR requiere EDGAR_IDENTITY="your_email@example.com" en el entorno antes de su uso (la SEC exige un User-Agent para el acceso anónimo).

Inicio rápido

# 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

Servidor MCP

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

La superficie de herramientas MCP está organizada en ocho áreas de capacidad (usa la lista de herramientas de tu cliente MCP para el conjunto autoritativo):

ai_search es el punto de entrada de extremo a extremo: búsqueda semántica → recorrido de grafos → consulta de valores, en una sola llamada.

Fuentes de datos

Las fuentes están conectadas en fd_open_data_mcp/fetch/runner.py::run_upstream(), una cadena fuente→ejecutor codificada. La tabla siguiente refleja el estado real de cada adaptador, no un estado aspiracional.

Producción (con respaldo de red)

Los paquetes de fuentes de datos externos (polygon, datacommons) se importan de forma diferida en el momento de la obtención, por lo que fd-open-data-mcp no depende de sus SDK a menos que se realice una obtención real.

Simulacro / marcador de posición

Estos adaptadores existen y se pueden despachar, pero devuelven datos de marcador de posición — son andamios para futuros trabajos de raspado, no fuentes de datos utilizables:

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

Nota: el CLI fd-open-data-mcp list-sources marca cada adaptador como "✅ Full support". Esa etiqueta no es una garantía de integración — solo comprueba que existe un archivo de adaptador. Trata la lista de simulacros anterior como autoritativa.

Registros de solo lectura

Centro de control de rastreo (panel + reconciliador)

Las políticas describen qué rastrear: conceptos × alcance de entidad × rango de fechas × frecuencia × modo. Un CrawlPolicy se crea desde el panel, el reconciliador lo compila en un CrawlPlan y scraw-fd-open-data-mcp lo ejecuta en 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

Variables de entorno:

• PANEL_TOKEN — si se establece, /panel/* lo requiere (cabecera X-Panel-Token, ?token= o cookie).

• POLICY_MAX_FETCHES (por defecto 50000) — salvaguarda del tamaño del plan; una política pendiente cuya estimación de obtención lo supere se rechaza (se registra como ejecución fallida) a menos que la política tenga force establecido.

• RECONCILER_LAUNCHER — scrapyd (por defecto) o k8s (K8sJobLauncher).

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

• FD_PROXY_FORWARDER — sin establecer para desarrollo local (el shim de inyección devuelve un centinela directo → salida directa; el reenviador independiente fd-proxy-service es el propietario de la selección de proxy en los rastreos de clúster). Las variables heredadas FD_PROXY_POOL/FD_EGRESS_MODE ya no se leen.

Ejemplo de política (a través del panel, o del 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

Dos notas de cadencia: el modo series rellena el historial en una sola obtención masiva por entidad (rango explícito), mientras que since_last per_date es el modo incremental de estado estacionario (solo fechas nuevas desde el marcador de agua de cada concepto; las entidades sin marcador de agua no se rellenan — ejecuta primero un relleno de rango explícito). Consulta openspec/changes/add-fund-crawl-control-center/docs/phase7-validation.md para el piloto validado (76 000 observaciones de valor liquidativo en la base de datos en vivo).

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

Operaciones de pool de proxy (clúster): seed-proxy-health, probe-cycle, proxy-health.

Pruebas

uv run --with pytest pytest -q

Configuración de LLM (para extracción de informes PDF)

fd-cn-report usa un LLM para extraer indicadores financieros de PDF de informes anuales. Se ejecuta en el mismo entorno que fd-open-data-mcp y se configura mediante las variables de entorno LLM_* en .env / .env.local:

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

El proveedor por defecto es DeepSeek en Ark. Cualquier LLM_BASE_URL compatible con OpenAI (OpenAI, Azure OpenAI, OpenRouter, Ollama local) también funciona: apunta LLM_BASE_URL / LLM_API_KEY / LLM_MODEL a ella. LLM_API_KEY tiene prioridad sobre OPENAI_API_KEY si ambos están establecidos.

Notas de diseño / limitaciones

• Proponer y confirmar: los enlaces columna->concepto llevan confidence + provenance; los enlaces por debajo del umbral se retiran del despacho (cola de revisión). Una obtención real promueve un enlace a sample-confirmed.

• La clasificación es por (fuente × concepto), se autoajusta desde fetch_log (acotada para que un fallo no pueda eliminar una fuente).

• Política de conflictos: un valor en caché por (concepto, entidad, fecha) con source_used adjunto; los valores nunca se fusionan entre fuentes.

• La búsqueda vectorial usa JSONB + numpy (pgvector no está disponible en el Postgres de destino); los embeddings de concepto + entidad alimentan semantic_search* y ai_search.

• Conmutación por error de fuente real: las funciones declaran real_sources (p. ej., stock_zh_a_hist → [eastmoney, tencent, sina]); cuando eastmoney está bloqueado, el despachador conmuta a tencent/sina. Las claves del interruptor de circuito son por fuente real, no por biblioteca.

• _build_params / _extract_value en el ejecutor de obtención son de mejor esfuerzo; un ejecutor de producción refina las peculiaridades de formato de fecha / forma de carga útil por función.

Consulta openspec/changes/add-fd-open-data-mcp/ para la especificación completa y openspec/changes/add-source-proxy-health/ para el diseño del proxy/interruptor de circuito.

Contribuir

Para añadir una nueva fuente de datos:

1. Crea un manifiesto según fd-open-data-protocol (YAML/JSON o un diccionario CATALOG).

2. Exponlo a través del punto de entrada fd_open_data_mcp.datasources en el pyproject.toml de tu paquete, o fd-open-data-mcp register-datasource <ruta>.

3. Si la lógica de obtención no se puede expresar como un ejecutor integrado, envía un run_<source>(command, params) en un adaptador (o un paquete externo) y haz una bifurcación en run_upstream().

4. fd-open-data-mcp register-discovered lo ingiere; propose-bindings enlaza sus columnas a conceptos.

Licencia

MIT