# Auto Stock Trading System with MCP

Claude AI와 MCP(Model Context Protocol)를 활용한 한국 주식 자동매매 시스템

## 시스템 아키텍처

- **Frontend**: React + TypeScript + Vite
- **Backend**: Python FastAPI + WebSocket
- **MCP Server**: Claude AI 통합
- **Database**: PostgreSQL
- **Cache**: Redis
- **Message Queue**: RabbitMQ
- **API**: 한국투자증권 API

## 주요 기능

1. **실시간 시장 데이터 수집**
2. **Claude AI 기반 규칙 검증**
3. **자동 매매 실행**
4. **포트폴리오 관리**
5. **실시간 모니터링**

## 프로젝트 구조

```
auto-stock/
├── frontend/          # React 프론트엔드
├── backend/           # FastAPI 백엔드
├── mcp-server/        # MCP 서버
├── docker/            # Docker 설정
├── deploy/            # NAS 배포
├── docs/              # 문서 (아래 목록)
└── scripts/           # 배포 스크립트
```

## 문서

작업 규칙과 전략 명세는 **`CLAUDE.md`** 가 정본이다. 파라미터 값을 확인할 때는 §0(파라미터 우선순위)을 먼저 읽을 것.

| 문서 | 내용 |
|------|------|
| [CLAUDE.md](./CLAUDE.md) | **작업 규칙·전략 명세·미해결 항목 (정본)** |
| [docs/INSTALLATION.md](docs/INSTALLATION.md) | 설치 |
| [docs/USER_GUIDE.md](docs/USER_GUIDE.md) | 사용법 |
| [docs/PROJECT_STRUCTURE.md](docs/PROJECT_STRUCTURE.md) | 코드 구조 |
| [docs/backend_guide.md](docs/backend_guide.md) | 백엔드 가이드 |
| [docs/API_DOCS.md](docs/API_DOCS.md) | API 명세 |
| [docs/API_SAFE_OPERATION.md](docs/API_SAFE_OPERATION.md) | API 안전 운영 |
| [docs/RISK_MANAGEMENT_API.md](docs/RISK_MANAGEMENT_API.md) | 리스크 API |
| [docs/BATCH_GUIDE.md](docs/BATCH_GUIDE.md) | 배치 분석 (cron 3개 잡) |
| [deploy/NAS-SETUP-GUIDE.md](deploy/NAS-SETUP-GUIDE.md) | NAS 배포 |
| [docs/multi_tenant_design.md](docs/multi_tenant_design.md) | 멀티테넌트 설계 |
| [docs/multi_tenant_phase1_review.md](docs/multi_tenant_phase1_review.md) | 멀티테넌트 1단계 검수 |

이력 참고용(현행 아님): [docs/REFACTORING_PLAN.md](docs/REFACTORING_PLAN.md)(폐기), [docs/AUTOTRADE_DIAGNOSIS.md](docs/AUTOTRADE_DIAGNOSIS.md), [docs/SPEED_OPTIMIZATION.md](docs/SPEED_OPTIMIZATION.md)

## 빠른 시작

```bash
# 환경 변수 설정
cp .env.example .env

# 기본값
#  - `DATABASE_URL`은 `.env.example`에 이미 도커 컨테이너(127.0.0.1:5432)를
#    가리키도록 설정되어 있습니다. 로컬 개발 시 별도 수정이 필요 없습니다.
#    원격 DB를 사용하려면 여기에 URL을 덮어쓰십시오.

# Docker로 전체 시스템 시작
./scripts/deploy.sh

# 개발 모드
./scripts/dev.sh
```

## 환경 변수

`.env` 파일에 다음 설정 필요:

- `KOREA_INVESTMENT_APP_KEY`: 한국투자증권 앱키
- `KOREA_INVESTMENT_APP_SECRET`: 한국투자증권 시크릿
- `ANTHROPIC_API_KEY`: Claude API 키
- `DATABASE_URL`: PostgreSQL 연결 URL (기본값은 도커 컨테이너)
- `REDIS_URL`: Redis 연결 URL

## 라이센스

MIT