DAAS - 서비스형 데이터(Data As a Service)

금융·경제·통계 데이터를 위한 계층형 데이터 플랫폼 — 통합 MCP 서버 뒤에 단일 SQLite 파일(daas.db)을 두고, 데이터 수집은 하위의 fd-open-data-mcp 업스트림에 위임합니다.

이것은 무엇인가요? Python 데이터 라이브러리(akshare, yfinance, edgar, edinet-tools, dartlab, world_bank_data, ckanapi)를 단일 SQLite 파일 기반의 쿼리 가능하고, 지표를 계산하며, 대시보드로 만들 수 있는 저장소로 바꿔주는 로컬 데이터 플랫폼입니다. Claude Code 스킬(워크플로 매니페스트를 호출하는 얇은 셸)이나 통합 fd-daas-mcp MCP 서버를 통해 구동하며, 두 경로 모두 동일한 데이터베이스를 읽고 씁니다.

업스트림: fd-open-data-mcp 데이터 수집기는 ~/finddata/fd-open-data-mcp에 있는 형제 저장소입니다(install.sh가 자동으로 클론).

문서 사이트: 역할 기반 전체 문서는 docs-site/에 있습니다(MkDocs Material, 영문+중문 이중 언어). uv run mkdocs serve로 로컬에서 읽거나(/DAAS/에서 탐색), uv run mkdocs build --strict로 엄격하게 빌드하세요. 빌드/서빙/배포는 docs-site/README.md를 참조하세요.

아키텍처

엄격한 하향 의존성 — 하위 계층은 상위 계층에 절대 접근하지 않습니다.

L3  user MCP compositions  (composite manifests, served in-proc on fd-daas-mcp)
L2  workflow manifests      (daas.db `workflows` table + engine, run via workflow_run)
L1  fd-daas-mcp            (consolidated infra: daas/cron/alerts/dashboard/composite/research/pdf/gateway/workflow)
L0  fd-open-data-mcp       (sole data-fetch upstream; concept-based semantic fetcher + entity master)

• L0 — fd-open-data-mcp(형제 저장소): 유일한 데이터 수집 표면입니다. 랭킹/장애 조치/캐싱이 있는 개념 기반 의미론적 수집기이며, 엔터티 마스터(entities, entity_datasource_links)를 보유합니다. HTTP :8300(stdio 폴백)으로 서비스됩니다. 이전의 11개 소스별 데이터 수집 MCP를 대체합니다.

• L1 — fd-daas-mcp(이 저장소): 통합 stdio 서버로, 저장소 루트의 .mcp.json에 있는 유일한 항목입니다. 하나의 서버와 하나의 fd-daas-mcp Click CLI 뒤에 9개 그룹에 걸친 161개 도구(daas · cron · alerts · dashboard · composite · research · pdf · gateway · workflow)를 노출합니다. 얇은 통합 계층은 fd-daas-mcp/daas/fd_daas_mcp/(server.py/registry.py/cli.py/selfcheck.py)이며, 각 그룹의 도구 코드는 fd-daas-mcp/<group>-mcp/의 패키지 내에 있습니다.

• L2 — 워크플로 매니페스트: 매니페스트는 daas.db의 workflows 테이블에 있습니다(workflow_register로 등록, workflow_run으로 실행). build_workflow_from_goal은 LLM을 통해 자연어 목표를 매니페스트로 분해합니다.

• L3 — 사용자 MCP 구성: 복합 매니페스트({name, upstreams, tools, workflows, prompt})는 통합 서버의 프로세스 내에서 제공되는 명명된 MCP 표면을 구성합니다. CRUD는 composite_*_manifest를 통해 수행합니다.

수집 스킬(fd-daas-based-data-fetch, fd-daas-fetch-data, fd-daas-research)은 얇은 셸입니다: 매개변수 수집 → workflow_run(name, params) → 체크포인트 처리. 더 이상 Python 데이터 라이브러리를 직접 호출하지 않습니다. 수집은 L1→L0을 통해 아래로 전달됩니다.

전체 아키텍처, 규칙, daas.db 스키마 참조는 CLAUDE.md 및 construction/mcp.md를 참조하세요.

설치 및 빠른 시작

요구 사항: Python 3.10+ 및 uv. dartlab 수집에는 3.12가 필요합니다 — uv run --python 3.12 --with dartlab ...으로 실행하세요.

원클릭 설치(DAAS + 업스트림 클론, venv 프로비저닝, daas.db 초기화, .mcp.json 로컬라이즈):

curl -fsSL https://raw.githubusercontent.com/FindDataTechnology/fd-daas-mcp/master/install.sh | sh

환경 변수 재정의: DAAS_DEST(기본 ~/code/DAAS), DAAS_BRANCH, FINDDATA_HOME(기본 ~/finddata). 수동 단계는 아래에 있습니다.

# 1. Provision the root venv (data libs are declared deps)
uv sync

# 2. Provision the database - creates daas.db (full schema + dep-free starter
#    catalog of sources). DAAS_DATABASE_URL is OPTIONAL: unset, it defaults to
#    ./daas.db (writable cwd) or ~/.fd-daas-mcp/daas.db. Set it only to relocate.
fd-daas-mcp/.venv/bin/fd-daas-mcp init       # one-shot provision + seed
fd-daas-mcp/.venv/bin/fd-daas-mcp doctor      # read-only health check (path, schema, row counts)

# 3. Configure credentials - create a repo-root .env for the source keys you need
#    (listed in Environment Variables below). Scripts auto-load .env; no manual export.

# 4. Compute an existing indicator (upserts into observations)
uv run python .claude/skills/fd-daas-based-data-fetch/scripts/run_indicator.py SPY_ma5

# 5. Query daas.db directly (db lives at the resolved DAAS_DATABASE_URL, default ./daas.db)
sqlite3 daas.db "SELECT name, datasource, op FROM indicator_rules LIMIT 10"
sqlite3 daas.db "SELECT source, COUNT(*) FROM observations GROUP BY source"

# 6. Launch / health-check the consolidated server
fd-daas-mcp/bin/fd-daas-mcp-server                       # stdio server (what .mcp.json launches)
fd-daas-mcp/.venv/bin/python -m daas.fd_daas_mcp.selfcheck   # registry + tool health check (target: failed=0)

# 7. Run a workflow manifest (L2 — the fetch path goes L1→L0)
fd-daas-mcp/.venv/bin/python -c "
from daas_mcp_workflow_tools import workflow_run   # or via the MCP tool
print(workflow_run('fetch-and-persist', params_json='{\"entity\":\"SPY\",\"indicator\":\"ma5\"}'))
"

위의 빠른 시작 명령은 이 저장소에서 검증되었습니다: SPY_ma5는 실제 indicator_rules 행이며, fd-daas-mcp 레지스트리는 9개 소스에 걸친 161개 도구(선택적 pdf 그룹의 경우 failed=0, skipped_optional=1)를 보고합니다.

프로젝트 구조

daas/
├── .claude/skills/          # Claude Code skills (fd-daas-based-data-fetch is the core fetch shell)
├── fd-daas-mcp/             # Consolidated MCP server — sole .mcp.json entry (161 tools, 9 groups)
│   ├── alerts-mcp/          #   alert rule engine + 7 notification channels
│   ├── composite-mcp/       #   user MCP composition (curate tools + embed workflows + prompt)
│   ├── cron-mcp/            #   task + schedule registry (DB-backed)
│   ├── daas-mcp/            #   datasource/function/indicator/entity catalog + compute + rules
│   ├── dashboard-mcp/       #   standalone-HTML dashboard registry + query
│   ├── gateway-mcp/         #   L0 upstream registry + call routing (former leader gateway half)
│   ├── workflow-mcp/        #   manifest-based multi-step data workflows (former leader workflow half)
│   ├── pdf-mcp/             #   local PDF/text semantic search (sqlite-vec) [optional]
│   ├── research-mcp/        #   persisted research bundle (collections + indicators + dashboard + report)
│   ├── bin/fd-daas-mcp-server      # launcher
│   └── daas/fd_daas_mcp/   # server.py / registry.py / cli.py / selfcheck.py
├── daas.db                  # Shared SQLite database (ships as a demo dataset: registry + observations + scraw_*)
├── dashboards/              # Standalone HTML dashboards (+ index.html, daas.md)
├── construction/            # Architecture docs (mcp.md — layered L0/L1/L2/L3)
└── .env                     # DAAS_DATABASE_URL, proxy, source auth keys, LLM config, ...

daas.db 데이터 모델

DAAS_DATABASE_URL의 경로에 있는 단일 SQLite 파일입니다(상대 sqlite:/// 경로는 저장소 루트 기준으로 해석되며, FK 계단식 삭제를 위해 PRAGMA foreign_keys=ON, "database is locked"를 피하기 위해 PRAGMA journal_mode=WAL + busy_timeout=10000 사용). 테이블은 역할별로 그룹화됩니다:

저장소 루트에서 직접 쿼리: sqlite3 daas.db "SELECT …".

스킬 (.claude/skills/)

스킬은 일반 Markdown(SKILL.md) + Python 스크립트입니다. 수집 스킬은 매개변수를 수집하고 workflow_run을 호출하는 얇은 셸입니다. 더 이상 Python 데이터 라이브러리를 직접 호출하지 않습니다(수집은 L1→L0).

MCP 도구 그룹 (fd-daas-mcp)

통합 서버는 9개 그룹에 걸친 161개 도구(선택적 pdf 그룹의 경우 failed=0, skipped_optional=1)를 노출합니다. 카탈로그는 그룹 수준입니다(도구별 세부 정보는 서버 자체 인트로스펙션/selfcheck 참조).

레거시 leader 그룹은 해체되었습니다. 게이트웨이 라우팅 부분은 gateway_*가, 워크플로우 매니페스트 부분은 workflow_*가 되었습니다. 하네스 레지스트리 / 스냅샷 / 프로비넌스 기능은 삭제되었습니다.

실행: fd-daas-mcp/bin/fd-daas-mcp-server (stdio). 서버와 fd-daas-mcp CLI 모두 registry.build()를 사용하므로 두 인터페이스는 서로 어긋날 수 없습니다.

환경 변수

단일 저장소 루트 .env 파일에 모든 구성이 들어 있으며, 스크립트와 MCP 서버가 이를 자동으로 로드합니다. (선택 사항으로 표시된 키는 해당 기능을 활성화할 때만 필요합니다.)

AI 에이전트용

이 저장소에서 작업하는 AI 에이전트(예: Claude Code)라면:

• 워크플로우 경로로 데이터를 가져오세요. fd-daas-based-data-fetch를 사용하세요: sqlite3를 사용하여 daas.db에서 엔티티 + 지표를 확인한 다음 workflow_run(name, params)을 호출합니다 — 매니페스트는 gateway_call → fd-open-data-mcp(L0)를 통해 페치를 라우팅하고 scraw_<slug> / observations에 영속화합니다. 다단계 페치의 경우 build_workflow_from_goal이 매니페스트를 생성합니다.

• 워크플로우: 확인 → 페치(L0 경유) → 영속화. daas.db에서 엔티티+지표를 확인하고, 게이트웨이를 통해 페치하며, scraw_<slug>(원시 데이터) 또는 observations(계산된 지표)에 영속화합니다.

• 그 외 모든 작업에는 MCP 서버를 사용하세요 — 카탈로그 탐색, 지표/컬렉션/규칙 생성, cron 스케줄링, 알림, 대시보드 구축/검색, PDF 의미 검색, 컴포지트 작성, 연구 번들. 이들은 fd-daas-mcp 도구(9개 그룹, 161개)입니다.

• 저장소 루트에서 sqlite3로 daas.db를 쿼리하세요(sqlite3 daas.db "…"). FK 캐스케이드를 위해 PRAGMA foreign_keys=ON을 사용하세요.

• 권위 있는 아키텍처 + 스키마 참조: CLAUDE.md(모든 테이블을 나열하는 ## daas.db 섹션이 있음) 및 construction/mcp.md(계층형 L0/L1/L2/L3 참조).

라이선스

Apache 2.0.