hot-deal-mcp-py

Java(Spring AI) hot-deal-mcp 서버를 파이썬으로 포팅한 것입니다. 공식 mcp SDK(FastMCP)로 Tool 을 정의하고, streamable-HTTP ASGI 앱을 FastAPI 에 마운트해 /mcp 로 제공합니다.

MCP Tool (4종, Java 와 동일)

Tool	설명
`getCreditCardRecommendationsWithSelector`	업종 코드(1~24) · 연회비 구간 · 카드 종류 · 정렬 기준으로 신한카드 추천. 조건이 불충분하면 선택 위젯 반환
`getCreditCardDetail`	지정한 카드 한 장의 혜택/연회비 상세 위젯
`getPopularCreditCards`	인기 TOP5 (파라미터 없음)
`getFinancialLifeKnowledgeArticles`	금융생활지식 콘텐츠 (트렌드 / 금융 / 카드연구소)

Tool 응답은 모두 {"widget": ..., "copy_text": ...} JSON 문자열입니다(PlayMCP 형식). 카드 데이터는 app/data/data.json (Java src/main/resources/data.json 과 동일)에서 로드합니다.

실행

./run.sh                 # http://localhost:8080/mcp
PORT=8081 ./run.sh

또는 직접:

uv run uvicorn app.main:app --host 0.0.0.0 --port 8080
uv run python -m app.mcp_server      # FastAPI 없이 FastMCP 단독 구동

테스트

uv run pytest

구동 스모크 테스트

서버를 띄운 뒤 MCP 핸드셰이크 + 툴 4종을 실제 호출해 응답을 확인한다.

uv run uvicorn app.main:app --port 8080      # 터미널 1
uv run python scripts/smoke_test.py          # 터미널 2 (PORT 로 포트 변경 가능)

PlayMCP / ngrok

ngrok http 8080

등록 주소: https://YOUR-NGROK-DOMAIN.ngrok-free.app/mcp

구조

app/
  main.py                     FastAPI 진입점 (+ /mcp 마운트, /health)
  mcp_server.py               FastMCP 인스턴스 + 툴 등록 + 스키마 정규화
  deps.py                     공유 서비스 싱글턴 (DI 컨테이너)
  tools/
    __init__.py               REGISTER_TOOLS — 등록 함수 화이트리스트
    common.py                 json_widget() 공통 헬퍼
    card_finer_tools.py       getCreditCardRecommendationsWithSelector
    card_search_tools.py      getCreditCardDetail
    finance_tips_tools.py     getFinancialLifeKnowledgeArticles
    popular_card_tools.py     getPopularCreditCards
  domain/                     Industry / AnnualFeeBand / CardSortOrder /
                              CreditCardName / FinancialKnowledgeCategory
  services/                   card_repository, card_guide_service,
                              popular_card_service, financial_knowledge_service
  widgets/                    PlayMcpWidgetFactory 포팅 (툴별로 분리)
    common.py                 응답 래퍼 / 셀렉터 버튼 / onClickAction 공용 조각
    card_finer_widgets.py     업종·연회비 셀렉터 + 카드 추천 목록
    card_search_widgets.py    카드명 되묻기 + 카드 상세
    finance_tips_widgets.py   금융생활지식 목록
    popular_card_widgets.py   인기 TOP5 목록
  data/data.json              신한카드 원본 데이터
python_tests/                 pytest (JUnit 테스트 포팅)

툴 켜고 끄기

app/tools/__init__.py 의 REGISTER_TOOLS 리스트에 있는 등록 함수만 서버에서 실행된다. 각 툴 모듈은 register_<모듈>_tools(mcp) 함수를 제공하고, 그 안에서 @mcp.tool(...) 로 실제 툴 함수를 등록한다. 특정 툴을 비활성화하려면 리스트에서 빼면 되고, tools/list 에도 노출되지 않는다.

REGISTER_TOOLS = [
    register_card_finer_tools,
    register_card_search_tools,
    # register_finance_tips_tools,   # ← 주석 처리하면 이 툴만 꺼짐
    register_popular_card_tools,
]

hot-deal-mcp-py

hot-deal-mcp-py

MCP Tool (4종, Java 와 동일)

실행

테스트

구동 스모크 테스트

PlayMCP / ngrok

구조

툴 켜고 끄기

Latest Blog Posts

MCP directory API