# Finance MCP Server - 실시간 금융 정보 MCP 서버

MCP(Model Context Protocol)를 활용한 실시간 금융 정보 제공 서버입니다.

## MCP란?

**Model Context Protocol (MCP)**는 AI 애플리케이션이 외부 데이터 소스 및 도구와 표준화된 방법으로 통신할 수 있게 하는 오픈 프로토콜입니다.

### MCP 아키텍처

```
┌─────────────────┐          ┌─────────────────┐
│  MCP Client     │          │   MCP Server    │
│  (Claude Code)  │ ◄─────► │  (이 프로젝트)  │
│                 │  JSON-   │                 │
│                 │   RPC    │  - Resources    │
│                 │          │  - Tools        │
│                 │          │  - Prompts      │
└─────────────────┘          └─────────────────┘
```

## 제공하는 금융 정보

### 실시간 데이터:
- 💱 **환율**: USD/KRW (달러/원), JPY/KRW (엔/원)
- ₿ **비트코인**: 실시간 BTC 가격 (KRW, USD)
- 🥇 **금시세**: 3.75그램 기준 금 가격
- 📈 **S&P 500**: 미국 주요 지수

### 데이터 소스:
- 환율: Open Exchange Rates API
- 암호화폐/금: CoinGecko API
- S&P 500: Yahoo Finance

## 이 서버가 제공하는 기능

### 1. Resources (리소스)
- `finance://USD/KRW` - 달러/원 환율
- `finance://JPY/KRW` - 엔/원 환율
- `finance://BTC` - 비트코인 가격
- `finance://GOLD` - 금 시세
- `finance://SP500` - S&P 500 지수

### 2. Tools (도구)
- `get_exchange_rate` - 특정 환율 조회
- `get_bitcoin_price` - 비트코인 가격 조회
- `get_gold_price` - 금 시세 조회
- `get_sp500` - S&P 500 지수 조회
- `get_all_prices` - 모든 금융 정보 한번에 조회

## 설치 및 실행

### 1. 의존성 설치
```bash
npm install
```

### 2. 빌드
```bash
npm run build
```

### 3. Claude Desktop에 MCP 서버 등록

`~/Library/Application Support/Claude/claude_desktop_config.json` 파일을 편집:

```json
{
  "mcpServers": {
    "finance": {
      "command": "node",
      "args": ["/Users/jongunpark/PracticeDev/testMCP/build/index.js"]
    }
  }
}
```

**중요**: 경로를 실제 프로젝트의 절대 경로로 변경하세요!

### 4. Claude Desktop 재시작

Claude Desktop을 재시작하면 금융 정보 MCP 서버가 연결됩니다.

## 사용 예시

Claude Desktop이나 Claude Code에서 다음과 같이 사용할 수 있습니다:

```
"현재 달러 환율 알려줘"
→ get_exchange_rate 도구 사용

"비트코인 가격은?"
→ get_bitcoin_price 도구 사용

"금시세 확인해줘"
→ get_gold_price 도구 사용

"모든 금융 정보 보여줘"
→ get_all_prices 도구 사용
```

## 코드 구조 설명

### 핵심 개념

1. **실시간 데이터 fetching**
   ```typescript
   // 외부 API에서 실시간 데이터 가져오기
   async function getExchangeRates() {
     const response = await fetch('https://open.er-api.com/v6/latest/USD');
     const data = await response.json();
     // ...
   }
   ```

2. **MCP Tools 제공**
   ```typescript
   server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
       tools: [
         {
           name: "get_bitcoin_price",
           description: "실시간 비트코인 가격을 가져옵니다",
           inputSchema: { /* ... */ }
         },
         // ...
       ]
     };
   });
   ```

3. **Tool 실행**
   ```typescript
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     switch (request.params.name) {
       case "get_bitcoin_price":
         // 비트코인 가격 조회 및 반환
         break;
       // ...
     }
   });
   ```

## API 제한 사항

### 무료 API 사용:
- **환율 API**: 월 1,500 요청 제한 (무료 티어)
- **CoinGecko**: 분당 10-50 요청 제한
- **Yahoo Finance**: 비공식 API, 제한 가능성 있음

### 권장사항:
- 프로덕션 환경에서는 유료 API 사용 권장
- 필요시 캐싱 로직 추가
- Rate limiting 구현 고려

## 확장 아이디어

이 MCP 서버를 바탕으로 다음과 같이 확장할 수 있습니다:

- 더 많은 환율 쌍 추가 (EUR/KRW, CNY/KRW 등)
- 다른 암호화폐 추가 (Ethereum, Ripple 등)
- 한국 주식 시세 (KOSPI, KOSDAQ)
- 원자재 시세 (은, 구리, 원유 등)
- 과거 데이터 조회 및 차트 생성
- 알림 기능 (가격 변동 알림)

## 트러블슈팅

### API 호출 실패 시:
- 인터넷 연결 확인
- API 서비스 상태 확인
- Rate limit 초과 여부 확인

### MCP 서버 연결 안될 때:
- 빌드가 성공했는지 확인 (`npm run build`)
- 설정 파일의 경로가 정확한지 확인
- Claude Desktop 완전히 재시작
- 로그 확인: `~/Library/Logs/Claude/mcp*.log`

## 참고 자료

- [MCP 공식 문서](https://modelcontextprotocol.io)
- [MCP SDK GitHub](https://github.com/modelcontextprotocol/sdk)
- [CoinGecko API 문서](https://www.coingecko.com/en/api/documentation)
- [Open Exchange Rates API](https://www.exchangerate-api.com/)

## 라이선스

MIT License