fd-open-data-mcp

오픈데이터 온톨로지 MCP: 다중 데이터 소스의 금융/경제 데이터 위에 의미적 개념 계층을 구축하는 시스템입니다. 개념 + 엔터티로 데이터를 요청하면(예: "마오타이의 price.close", "중국의 GDP"), 시스템이 그 개념을 각 데이터 소스의 물리적 컬럼으로 해석하고, 품질 + 접근성에 따라 후보 소스를 순위 매긴 후, 최적의 소스에서 가져옵니다(장애 조치 포함). 개념별로 캐시하고, 개념별 주기에 따라 새로 고칩니다.

finddata fd-* 데이터소스 레지스트리와 fd-entities-indicators 읽기 전용을 소비하며, 그 위에 통합 계층을 추가합니다: 개념 바인딩, 소스별 엔터티 식별자, 소스 순위, 읽기-통과 값 캐시, 그리고 그 위에 엔터티 그래프 + 벡터 검색 계층을 추가합니다.

영어 | 중국어

오픈데이터 온톨로지 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는 종단 간 진입점입니다: 의미 검색 → 그래프 탐색 → 값 쿼리를 한 번에 처리합니다.

데이터 소스

소스는 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

두 가지 주기 참고: series 모드는 엔터티당 하나의 대량 가져오기로 기록을 백필합니다(명시적 범위), 반면 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는 연간 보고서 PDF에서 금융 지표를 추출하기 위해 LLM을 사용합니다. 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

기본 프로바이더는 Ark의 DeepSeek입니다. 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로 승격합니다.

• 순위는 (소스 × 개념)별로, fetch_log에서 자체 조정합니다(한 번의 실패가 소스를 제거할 수 없도록 제한됨).

• 충돌 정책: (개념, 엔터티, 날짜)당 하나의 캐시 값에 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