tossinvest-open-api-mcp: Instructions file for Claude Code

CLAUDE.md — toss-securities-mcp

프로젝트 개요

토스증권 Open API를 감싸는 self-hosted MCP 서버. 사용자가 본인 API 키로 본인 머신에서 실행하며, Claude Desktop/Claude Code에 연결해 자연어로 계좌·시세를 조회한다.

이 프로젝트는 더 큰 시스템의 Phase 1이다:

• Phase 1 (이 저장소): 토스 MCP — 토스증권 계좌 조회
• Phase 2 (별도 저장소 portfolio-aggregator-mcp): 멀티 증권사 통합, FIFO 누적 실현손익, 행동 패턴 분석
• Phase 4: NH QV MCP 추가

최종 목표: "매도하면 사라지는 수익률" 문제를 해결하는 누적 실현손익(Lifetime Realized P/L) 중심의 투자 보고·코칭 에이전트.

기술 스택 (고정 — 변경하지 말 것)

• Python 3.12+
• FastMCP (Anthropic MCP SDK의 고수준 인터페이스)
• httpx (async HTTP)
• Pydantic v2 (스키마)
• uv (패키지 관리)
• pytest + pytest-asyncio (테스트)

아키텍처 원칙

1. MCP 서버는 얇게 — 이 저장소는 "토스 API → 표준화된 JSON" 변환만 담당. 분석 로직(FIFO, 손익 계산)은 절대 여기 넣지 않는다. 그건 Phase 2 Aggregator의 일.
2. 도구는 읽기 전용부터 — 조회 도구(잔고, 보유종목, 거래내역, 시세)만 먼저 구현. 주문(매수/매도) 도구는 명시적 요청 전까지 구현하지 않는다.
3. LLM에 친화적인 도구 설명 — 각 도구의 description은 "언제 이 도구를 호출해야 하는지"를 명확히 (예: "사용자가 '보유 종목', '내 주식' 등을 물을 때 호출").
4. 응답은 구조화 — raw JSON 그대로 반환하지 말고 Pydantic 모델로 파싱 후 필요한 필드만 정리해 반환.

디렉토리 구조

toss-securities-mcp/
├── README.md            # 디스클레이머 필수 (아래 '약관 준수' 참고)
├── LICENSE              # MIT
├── .env.example         # 키 템플릿 (실제 값 절대 X)
├── .gitignore           # .env 반드시 포함
├── pyproject.toml
├── server.py            # MCP 엔트리포인트 (FastMCP)
├── toss_client/
│   ├── __init__.py
│   ├── auth.py          # OAuth 2.0 Client Credentials 토큰 관리
│   ├── api.py           # 토스 API 엔드포인트 래퍼
│   └── schemas.py       # 토스 응답 Pydantic 모델
├── scripts/
│   └── smoke_test.py    # 실 API 읽기 전용 스모크 테스트 (사용자 수동 실행)
└── tests/
    ├── test_auth.py
    └── test_api.py      # httpx MockTransport 사용

인증 (토스 Open API)

• OAuth 2.0 Client Credentials Grant
• 토큰 발급: POST /oauth2/token, application/x-www-form-urlencoded 본문에 grant_type/client_id/client_secret
• refresh token 없음. 만료 시 동일 엔드포인트로 재발급
• client당 유효한 access token은 1개 — 재발급 시 이전 토큰 즉시 무효화 (프로세스 내 단일 TokenManager로 관리)
• 모든 API 호출: Authorization: Bearer {access_token}
• 계좌·자산·주문 API: X-Tossinvest-Account: {accountSeq} 헤더 추가
• 토큰은 메모리 캐시, 만료 60초 전 자동 갱신