# Investment Research MCP

TradingCodex를 control/provenance plane으로 두고 공식 공시·시장 데이터와 domain-specific evidence를 MCP sidecar로 결합하는 개인용 evidence-first 투자 리서치 스택입니다. 현재 첫 번째 domain pack은 한국 기업 리서치이며, 삼성바이오로직스·대웅제약·루닛을 각각 CDMO, pharma, AI medical device 모델로 검증했습니다.

## 현재 상태

- **오프라인 adapter·정책 검증:** 통과 — 31개 자동 테스트, 3개 기업 12개 시나리오가 모두 기대 상태와 일치합니다.
- **TradingCodex control plane:** 차단 — 현재 VM은 public package access가 없어 generated runtime을 attach하지 못했습니다.
- **Live DART/KRX/biomedical 검증:** 미실행 — API 키와 외부 네트워크가 없습니다.
- **한국 규제 완전성:** 미완성 — MFDS와 CRIS adapter가 없으므로 한국 승인·안전·허가·국내 임상 완전성을 주장할 수 없습니다.
- 따라서 최종 `validation/latest-results.json`의 전체 상태는 의도적으로 **`incomplete`**입니다.

## 아키텍처

1. **TradingCodex:** 역할 분리, workflow, immutable SourceSnapshot, artifact lineage, 독립 judgment review.
2. **`korea_official_mcp.py`:** OpenDART와 KRX의 HTTPS-only, allowlisted, bounded, fail-closed raw adapter.
3. **`biomed_raw_mcp.py`:** ClinicalTrials.gov, PubMed, openFDA raw adapter. 자동 catalyst score/verdict는 노출하지 않습니다.
4. **Evidence contract:** 모든 외부 응답은 `ok`, `no_data`, `partial`, `auth_missing`, `unavailable`, `not_applicable`, `coverage_gap`, `invalid_request` 중 하나이며, 분석에 사용하기 전에 `record_source_snapshot`으로 보존해야 합니다.

상세 내용은 `docs/ARCHITECTURE.md`, 운영 절차는 `docs/OPERATIONS.md`, 검증 증거는 `docs/VALIDATION.md`, 보안 모델은 `docs/SECURITY.md`를 참조하십시오.

## 바로 확인하기

```bash
cd /projects/sandbox/korean-biotech-research-stack
./scripts/run-tests.sh
```

이 명령은 provider credential을 제거한 결정적 오프라인 테스트를 수행하고 `validation/latest-results.json`을 갱신합니다.

## 네트워크 복구 후 TradingCodex runtime 만들기

```bash
cd /projects/sandbox/korean-biotech-research-stack
./scripts/bootstrap-online.sh
```

첫 attach는 populated seed 디렉터리가 아니라 기본 경로 `runtime/tradingcodex-workspace/`의 빈 디렉터리에 수행됩니다. 스크립트는 `tradingcodex==2.1.3`을 사용하고, integration·role overlay를 설치한 다음 `tcx update`와 `doctor`를 실행합니다. 다른 빈 목적지를 쓰려면 첫 번째 인자로 전달합니다.

Provider credential은 파일에 쓰지 말고 실행 환경에서만 상속하십시오:

```bash
export DART_API_KEY='...'
export KRX_API_KEY='...'
# 선택 사항
export NCBI_API_KEY='...'
export OPENFDA_API_KEY='...'
```

## 기업별 모델

| 기업 | 식별자 | 모델 | 핵심 금지 사항 |
|---|---|---|---|
| 삼성바이오로직스 | `207940`, KOSPI | CDMO plant-cohort FCFF/reverse DCF | drug-pipeline catalyst score 금지 |
| 대웅제약 | `069620`, KOSPI | commercial-base DCF + indication/territory rNPV | registry 등록을 성공으로 간주 금지 |
| 루닛 | `328130`, KOSDAQ | segment/deployment-cohort FCFF | drug-pipeline valuation 금지 |

## 주요 경로

- `integration/servers/` — hardened MCP sidecars
- `integration/companies/` — 3개 기업의 evidence matrix·valuation model
- `integration/workflows/` — 조사 및 SourceSnapshot 계약
- `.tradingcodex/agent-instructions/` — 역할별 project overlay
- `scripts/bootstrap-online.sh` — 별도 generated runtime 설치
- `tests/` — protocol, security, provider semantics, profile, installer 테스트
- `reviews/INDEPENDENT_REVIEW.md` — 4개 독립 리뷰 기록
- `validation/latest-results.json` — machine-readable 최종 상태