fd-open-data-mcp

MCP с открытой онтологией данных: семантический слой концепций поверх финансово-экономических данных из множества источников. Вы запрашиваете данные в виде концепций + сущностей (например, "price.close для Moutai", "GDP для Китая"); система сопоставляет концепцию с физическими колонками в разных источниках, ранжирует источники-кандидаты по качеству и доступности, получает данные из лучшего источника (с отработкой отказа), кэширует по концепции и обновляет с частотой, заданной для каждой концепции.

Он использует реестры источников данных finddata fd-* и fd-entities-indicators только для чтения и добавляет поверх унифицирующие слои: привязки концепций, идентификаторы сущностей для каждого источника, ранжирование источников, кэш значений со сквозным чтением, а также (поверх всего этого) граф сущностей и слой векторного поиска для реляционных и семантических запросов.

English | 中文

MCP с открытой онтологией данных: семантический слой концепций поверх финансово-экономических данных из множества источников. Вы запрашиваете данные в виде концепций + сущностей (например, "price.close для Moutai", "GDP для Китая"); система преобразует концепции в физические столбцы в различных источниках, ранжирует источники-кандидаты по качеству и доступности, получает данные из лучшего источника (с отработкой отказов), кэширует по концепциям и обновляет с частотой, заданной для каждой концепции.

Установка в один клик

Единый автономный блок, который разворачивает весь стек открытых данных finddata (хаб + все пакеты источников данных + онтологическая БД). Безопасен для повторного запуска; останавливается при первой ошибке.

# 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 и набор LLM_* / ES_* для fd-cn-report. См. раздел Configuration в каждом пакете.

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

Восемь областей возможностей (см. 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

Путь к БД по умолчанию — 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 организована в восемь областей возможностей (используйте список инструментов в вашем MCP-клиенте как авторитетный набор):

ai_search — это сквозная точка входа: семантический поиск → обход графа → запрос значений, одним вызовом.

Источники данных

Источники подключаются в 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.

Примечание: CLI-команда fd-open-data-mcp list-sources помечает каждый адаптер как «✅ Full support». Эта пометка не является гарантией интеграции — она лишь проверяет, что файл адаптера существует. Считайте список заглушек выше авторитетным.

Реестры только для чтения

Центр управления краулингом (панель + реконсилятор)

Политики описывают что обходить: концепции × охват сущностей × диапазон дат × частота × режим. 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= или cookie).

• 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

Два замечания о ритме: режим series заполняет историю одним массовым запросом на сущность (явный диапазон), тогда как since_last per_date — это установившийся инкрементальный режим (только новые даты с контрольной точки каждой концепции; сущности без контрольной точки не заполняются — сначала выполните заполнение с явным диапазоном). См. openspec/changes/add-fund-crawl-control-center/docs/phase7-validation.md о провалидированном пилоте (76 000 наблюдений NAV на живой БД).

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, и настраивается через переменные LLM_* в .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

Провайдер по умолчанию — DeepSeek on Ark. Подойдёт любой OpenAI-совместимый LLM_BASE_URL (OpenAI, Azure OpenAI, OpenRouter, локальный Ollama) — укажите в LLM_BASE_URL / LLM_API_KEY / LLM_MODEL соответствующие значения. LLM_API_KEY имеет приоритет над OPENAI_API_KEY, если заданы оба.

Проектные заметки / ограничения

• Предложение и подтверждение: привязки «колонка → концепция» содержат confidence + provenance; привязки ниже порога не допускаются к отправке (очередь проверки). Реальная выборка повышает привязку до sample-confirmed.

• Ранжирование выполняется по (source × concept), самонастраивается на основе fetch_log (с ограничением, чтобы один сбой не мог удалить источник).

• Политика конфликтов: одно кэшированное значение на (concept, entity, date) с прикреплённым source_used; значения никогда не объединяются между источниками.

• Векторный поиск использует JSONB + numpy (pgvector недоступен на целевой Postgres); эмбеддинги концепций и сущностей обеспечивают работу semantic_search* и ai_search.

• Отказоустойчивость реальных источников: функции объявляют real_sources (например, stock_zh_a_hist → [eastmoney, tencent, sina]); когда eastmoney заблокирован, диспетчер переключается на tencent/sina. Ключи circuit breaker задаются для каждого реального источника, а не для библиотеки.

• _build_params / _extract_value в исполнителе выборки реализованы по принципу best-effort; боевой исполнитель уточняет особенности форматов дат и структуры полезной нагрузки для каждой функции.

См. openspec/changes/add-fd-open-data-mcp/ для полной спецификации и openspec/changes/add-source-proxy-health/ для проектирования прокси/circuit breaker.

Участие в разработке

1. Создайте манифест в соответствии с fd-open-data-protocol (YAML/JSON или словарь CATALOG).

2. Предоставьте его через entry-point fd_open_data_mcp.datasources в вашем pyproject.toml или с помощью fd-open-data-mcp register-datasource <path>.

3. Если логику выборки нельзя выразить встроенным исполнителем, поставляйте run_<source>(command, params) в адаптере (или внешнем пакете) и добавьте ветвление для неё в run_upstream().

4. Затем fd-open-data-mcp register-discovered импортирует его; propose-bindings привязывает его колонки к концепциям.

Лицензия

MIT