# 국내주식 자동매매 시뮬레이터

한국 주식시장을 대상으로 한 **페이퍼 트레이딩** 자동매매 시스템. 실제 주문 없이 전략을 검증합니다.

MCP 서버를 직접 구현해 **Claude Desktop에서 대화만으로 전략 파라미터를 바꾸고 백테스트를 실행**할 수 있는 것이 특징입니다.

> ⚠️ 학습·연구 목적의 시뮬레이터입니다. 실제 주문은 실행하지 않습니다.

---

## 구조

Docker Compose로 4개 서비스가 함께 뜹니다.

| 서비스 | 역할 |
|---|---|
| `web` | Django 애플리케이션 |
| `worker` | Celery 워커 — 매매 로직 실행 |
| `beat` | Celery Beat — 1분 주기 스케줄링 |
| `redis` | 메시지 브로커 |

헬스체크를 통과한 뒤에 다음 서비스가 시작하도록 기동 순서를 보장했습니다.

## 매매 전략

매수는 두 관문을 **모두** 통과해야 합니다.

1. **변동성 돌파** — 전일 변동폭에 계수를 곱한 기준선을 돌파
2. **XGBoost 확률 필터** — 학습된 모델의 상승 확률이 임계값 이상

매도는 손절·익절 기준에 도달하면 자동 실행됩니다. 모든 임계값은 설정에서 단일 출처로 관리합니다.

## 설계 패턴

**Strategy + Registry**
전략을 인터페이스로 추상화하고 데코레이터로 등록합니다. 새 전략을 추가할 때 기존 코드를 수정할 필요가 없습니다.

**의존성 역전**
주문 실행부를 팩토리로 주입받습니다. 페이퍼 트레이딩과 실거래 구현을 갈아끼울 수 있는 구조입니다.

**Firestore 원자적 배치**
포지션과 잔고 갱신을 하나의 배치로 묶어 부분 실패를 방지합니다.

**알림 실패 격리**
알림 전송이 실패해도 매매 로직은 중단되지 않도록 예외를 흡수합니다.

## MCP 서버

FastMCP 기반 stdio transport로 구현했습니다. Claude Desktop에 연결하면 대화로 시스템을 조작할 수 있습니다.

- 도구 7개 노출 — 포지션 조회, 전략 파라미터 변경, 백테스트 실행 등
- 모든 도구에 `@_safe` 데코레이터를 적용해 예외를 dict로 변환 → 서버 오류로 클라이언트가 죽지 않습니다
- 파라미터를 변경하면 다음 매매 사이클부터 즉시 반영됩니다

## 백테스트

과거 데이터로 전략을 검증하는 엔진을 포함합니다. 승률, 손익비, 누적 수익률을 계산합니다.

## 실행

```bash
cp .env.example .env      # 설정 입력
docker compose up
```

## 기술 스택

`Python` `Django 5.2` `Celery` `Celery Beat` `Redis` `Firebase/Firestore` `XGBoost` `pykrx` `Docker Compose` `FastMCP` `pytest`

## 프로젝트 구조

```
src/
  strategies/    전략 인터페이스 · 레지스트리 · 구현체
  executors/     주문 실행 (페이퍼 / 실거래)
  backtest/      백테스트 엔진
  mcp/           MCP 서버
  notify/        알림
config/          설정 단일 출처
tests/           단위 테스트
```

## 개발 배경

이 프로젝트는 컴퓨터 초기화로 소스를 유실한 적이 있습니다. 다행히 아키텍처와 설계 결정을 정리해 둔 `CLAUDE.md` 문서가 남아 있어, 그 문서를 기준으로 코드를 재구성했습니다. 설계 문서를 남겨두는 습관의 가치를 체감한 경험입니다.