# Fin Products Tools (금융상품 조회 MCP·CLI 도구)

**[금융감독원 금융상품한눈에 Open API](https://finlife.fss.or.kr/finlife/main/contents.do?menuNo=700029)를 기반으로 금융상품을 조회하는 MCP·CLI 도구입니다.**    
**예적금, 연금저축, 주택담보대출, 전세자금대출, 개인신용대출 데이터를 일관된 MCP 및 CLI 인터페이스로 조회할 수 있습니다.**

Fin Products Tools is an MCP/CLI tool for querying financial product datasets based on [FSS Open APIs](https://finlife.fss.or.kr/finlife/main/contents.do?menuNo=700029).    
It provides a consistent MCP and CLI interface for these financial product datasets.

## Architecture

- **Client**: `src/fss_tools/clients/fss_client.py`
- **Service/normalization**: `src/fss_tools/services/data_service.py`
- **CLI**: `src/fss_tools/cli/main.py`
- **MCP**: `src/fss_tools/mcp/server.py`

## Implemented API coverage

- **금융상품한눈에** (`finlife`)
  - `saving` (적금)
  - `deposit` (정기예금)
  - `pension_saving` (연금저축)
  - `mortgage` (주택담보대출)
  - `jeonse` (전세자금대출)
  - `personal_loan` (개인신용대출)

## Setup

```bash
cp .env.example .env
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
```

Set env vars:

```bash
export FSS_API_KEY="your_api_key"
export OUTPUT_FORMAT="json"  # or "table"
```

## Commands

```bash
# 기본
fin-products --help

# 금융상품
# 회사 먼저 검색해서 코드 확인
fin-products search-financial-company "농협"

# 회사코드로 정기예금 검색 (회사 코드 생략 시 전체 검색)
# query는 finlife 명세상 financeCd(회사코드/회사명)로 매핑됨
fin-products products --kind deposit --query "농협"
fin-products products --kind deposit --company-code 0013175 --query "농협"
```

## MCP server setup

### 1) Install package

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

### 2) Set environment variables

```bash
export FSS_API_KEY="your_api_key"
export OUTPUT_FORMAT="json"
```

### 3) Run MCP server (stdio)

```bash
fin-products-mcp
```

### 4) Example MCP client config (Claude Desktop)

`claude_desktop_config.json` example:

```json
{
  "mcpServers": {
    "fin-products-tools": {
      "command": "/bin/bash",
      "args": [
        "-lc",
        "cd /path/to/fin-products-tools && source .venv/bin/activate && export FSS_API_KEY=YOUR_API_KEY && fin-products-mcp"
      ]
    }
  }
}
```

## MCP tools

### 1) `search_financial_company(query, page=1, size=20, top_group="020000")`
- 금융회사 검색 (회사코드 조회용)
- 권장 사용: 먼저 회사 검색 → `company_code` 확보 → 상품 툴 정밀 조회

### 2) `search_savings(query=None, company_code=None, page=1, size=20, top_group="020000", all_groups=False)`
- 적금 상품 조회 (`savingProductsSearch`)
- `query`는 내부적으로 `financeCd`로 매핑됨
- `company_code` 지정 시 `query`보다 우선
- `all_groups=True`면 은행(020000)+저축은행(030300) 통합 조회

### 3) `search_deposits(query=None, company_code=None, page=1, size=20, top_group="020000", all_groups=False)`
- 정기예금 상품 조회 (`depositProductsSearch`)
- `query`/`company_code` 우선순위는 위와 동일
- `all_groups=True`면 은행(020000)+저축은행(030300) 통합 조회

### 4) `search_pension_saving(query=None, company_code=None, page=1, size=20, top_group="020000", all_groups=False)`
- 연금저축 상품 조회 (`annuitySavingProductsSearch`)
- 기본: `all_groups=False` → `top_group` 단일 조회
- 통합: `all_groups=True` → 보험(050000)+금융투자(060000) 병합 조회 (중복 제거)

### 5) `search_mortgage(query=None, company_code=None, page=1, size=20, top_group="020000")`
- 주택담보대출 상품 조회 (`mortgageLoanProductsSearch`)

### 6) `search_jeonse(query=None, company_code=None, page=1, size=20, top_group="020000")`
- 전세자금대출 상품 조회 (`rentHouseLoanProductsSearch`)

### 7) `search_personal_loan(query=None, company_code=None, page=1, size=20, top_group="020000")`
- 개인신용대출 상품 조회 (`creditLoanProductsSearch`)

### top_group(권역코드) 참고
- `020000`: 은행
- `030200`: 여신전문
- `030300`: 저축은행
- `050000`: 보험
- `060000`: 금융투자

## Tests

```bash
PYTHONPATH=src python3 -m pytest -q
```