# public-data-report-mcp

> 샘플 프로젝트입니다. 공개 데이터 API, 엑셀 자동화, MCP 서버 연결을 한 저장소에서 보여 주려고 만든 예제이며, 고객 작업물이 아닙니다.

키 없이 쓰는 공개 환율 API [Frankfurter](https://frankfurter.dev)(유럽중앙은행 기준 환율)에서 기간별 환율을 모아 **엑셀(.xlsx) 보고서**를 만듭니다. 같은 기능을 두 가지로 씁니다.

1. **CLI 명령** `fx-report`: 터미널이나 예약 작업(cron)에서 실행합니다.
2. **MCP 서버** `fx-report-mcp` (공식 MCP Python SDK, stdio): Claude Code 같은 AI 에이전트가 도구 `make_fx_report`로 부릅니다. 예: "지난 한 달 달러 대비 원화·엔화 환율 보고서를 엑셀로 만들어 줘."

보고서 내용:

- `요약` 시트: 통화별 시작값, 마지막 값, 최저, 최고, 평균, 변동률(%), 영업일 수, 통화별 추이 차트
- `일별 환율` 시트: 날짜별 환율 표 (주말과 휴일은 API가 빼고 줍니다)

![보고서 미리보기](docs/report-preview.png)

*위 이미지는 아래 CLI 예로 실제 만든 `fx-report.xlsx`의 값을 읽어 그린 미리보기입니다.*

## 설치

Python 3.10 이상이 필요합니다.

```bash
git clone https://github.com/ddadasoft/public-data-report-mcp
cd public-data-report-mcp
python3 -m venv .venv
.venv/bin/pip install -e '.[test]'
```

## CLI 실행

```bash
.venv/bin/fx-report --base USD --symbols KRW,JPY,EUR --start 2026-10-14 --end 2026-11-13 -o fx-report.xlsx
```

실제 출력:

```
USD 기준, 2026-10-14 ~ 2026-11-13, 영업일 23일
통화            시작      마지막        최저        최고    변동률
KRW       1,336.7900  1,337.1300  1,324.4500  1,358.7300    +0.03%
JPY         158.4500    160.0000    156.8000    160.0000    +0.98%
EUR           0.8933      0.9048      0.8875      0.9048    +1.29%
저장: fx-report.xlsx
```

옵션:

| 옵션 | 기본값 | 설명 |
|---|---|---|
| `--base` | `USD` | 기준 통화 |
| `--symbols` | `KRW,JPY,EUR` | 쉼표로 구분한 대상 통화 |
| `--start`, `--end` | 오늘부터 `--days`일 전 ~ 오늘 | 기간 (YYYY-MM-DD) |
| `--days` | `30` | `--start`가 없을 때 쓰는 기간 일수 |
| `-o`, `--output` | `fx-report.xlsx` | 저장할 파일 |

지원하지 않는 통화나 자료가 없는 기간을 주면 오류 문장을 출력하고 종료 코드 1로 끝납니다.

## Claude Code에 MCP 서버 연결

설치한 폴더에서 아래 명령을 실행합니다. `--scope project`는 이 폴더의 `.mcp.json`에 설정을 저장합니다.

```bash
claude mcp add fx-report --scope project -- "$(pwd)/.venv/bin/fx-report-mcp"
```

직접 `.mcp.json`을 쓸 때는 다음과 같습니다(경로는 설치 위치로 바꿉니다).

```json
{
  "mcpServers": {
    "fx-report": {
      "command": "/절대/경로/public-data-report-mcp/.venv/bin/fx-report-mcp",
      "args": []
    }
  }
}
```

연결한 뒤 Claude Code에서 "USD 대비 KRW, JPY 환율을 11월 1일부터 13일까지 엑셀로 만들어 줘"라고 요청하면 `make_fx_report` 도구가 파일을 만들고 요약 표를 돌려줍니다. 도구 응답 예:

```
저장: /private/tmp/fx-demo/mcp.xlsx

통화            시작      마지막        최저        최고    변동률
KRW       1,342.9000  1,337.1300  1,334.1000  1,358.7300    -0.43%
JPY         157.9000    160.0000    157.9000    160.0000    +1.33%
```

## 테스트

네트워크 대신 고정 응답을 씁니다.

```bash
.venv/bin/python -m pytest -q
```

## 구조

```
src/report_mcp/
  rates.py    Frankfurter API 호출과 응답 검사
  report.py   요약 계산, 엑셀 작성(openpyxl), 텍스트 표
  cli.py      fx-report 명령
  server.py   fx-report-mcp MCP 서버 (도구 make_fx_report)
tests/test_report.py
```

다른 공개 API(공공데이터, 날씨, 주가 등)로 바꿀 때는 `rates.py`만 바꾸면 엑셀 작성, CLI, MCP 서버는 그대로 씁니다.

## 라이선스

MIT. 환율 데이터의 출처는 Frankfurter API와 유럽중앙은행입니다.