DART 전자공시의 실측 재무제표와 KRX 시세만으로 한국 상장사를 분석한다. 데이터가 없으면 없다고 답하고, 목표 주가 대신 가정이 명시된 범위를 제시하며, 매수·매도 권고를 하지 않는다.

✨ Features

• 날조 제로 — 모든 수치는 DART 공시·KRX 시세 실측치. 결측은 null + 사유로 명시, 기본값 주입 없음
• 실측 재무제표 — 사업보고서 기반 매출·영업이익·현금흐름 3~10개년, 연결(CFS) 우선/별도(OFS) 폴백 표시
• 보수적 밸류에이션 — 단일 적정가 대신 3시나리오(비관/중립/낙관) 범위, 성장률·멀티플 가정 전부 응답에 포함
• 리스크 우선 — 재무 적신호 6종 자동 검사 + 공시 위험 키워드 하이라이트, 검사 불가 항목도 구분 보고
• 교차 검증 — 시가총액 정합성 검사(주가×주식수 vs 보고 시총) 등 데이터 정합성 검증 내장
• 운영 기본기 — 글로벌 레이트 리밋, DART 쿼터 보호 캐싱, KRX IP 차단 방지 직렬화, 구조화 에러 메시지

🏗️ Architecture

graph LR
    C1[Claude / claude.ai] -->|Streamable HTTP| S
    C2[Claude Desktop / Cursor] -->|Streamable HTTP| S
    subgraph Railway
        S[FastMCP 3 · stateless] --> T[tools/ 등록 계층]
        T --> A[analysis/ 순수 계산<br>ratios · valuation · risk]
        T --> SV[services/ 데이터 클라이언트]
        SV --> CA[(TTL cache)]
    end
    SV -->|재무제표 · 공시| DART[DART OpenAPI]
    SV -->|시세 · 상장목록| KRX[KRX via FinanceDataReader]

계층 원칙: tools/는 등록만(얇게) → services/는 외부 API + 캐싱 → analysis/는 순수함수(가장 두꺼운 테스트). LLM도 서버도 수치를 "암산"하지 않는다 — 모든 계산은 결정론적 함수다.

🚀 Quickstart

배포된 서버 URL 하나면 된다. API 키 불필요(공개 데이터만 제공).

claude.ai — 설정 → 커넥터 → 커스텀 커넥터 추가:

https://korea-stock-analyzer-mcp-production.up.railway.app/mcp

Claude Code:

claude mcp add --transport http korea-stock https://korea-stock-analyzer-mcp-production.up.railway.app/mcp

{
  "mcpServers": {
    "korea-stock": {
      "type": "http",
      "url": "https://korea-stock-analyzer-mcp-production.up.railway.app/mcp"
    }
  }
}

연결 후 이렇게 물어보면 된다:

"삼성전자 최근 5년 재무제표 흐름이랑 리스크 요인 짚어줘"

🛠️ Tools

모든 응답에 데이터 기준일(as_of)과 출처(data_source)가 붙는다.

☁️ Deploy Your Own

Railway 기준 (Dockerfile 자동 감지):

1. 이 레포를 포크 → Railway에서 GitHub 레포 연결
2. 환경변수:

악성 사용자 차단은 별도 환경변수 없이 자동 적용된다. Railway 요청을 자동으로 인식해 IP별 분당 30회, 반복 초과 3회 시 1시간 차단하며, /health도 분당 120회로 제한해 우회 경로를 막는다.

3. Serverless(App Sleeping) 비활성 권장 — 콜드 스타트 시 커넥터 연결 실패 방지

로컬 실행:

uv sync
DART_API_KEY=<key> uv run uvicorn app.main:app --app-dir src --port 8000

테스트:

uv run pytest                          # 단위·경계 테스트 (외부 API 없음)
uv run pytest -m live -o addopts=""    # 실제 KRX/DART 검증 (키 필요)

📊 데이터 출처와 한계

🔒 Disclaimer

본 서버의 출력은 공시·시세 데이터의 산술 가공 결과이며 투자 자문이 아니다. 시나리오 값은 명시된 가정의 계산 결과일 뿐 목표 주가가 아니다. 서버는 매수·매도·비중 판단을 제공하지 않으며, 투자 판단과 책임은 전적으로 이용자에게 있다.

🤝 Contributing

이슈·PR 환영. 원칙 하나만 지켜달라: 데이터가 없으면 없다고 답한다. 추정치 주입·하드코딩 폴백이 들어간 PR은 받지 않는다. 테스트는 uv run pytest 통과 필수.

📜 License

Apache-2.0