MCP Data Agent

판매 데이터베이스에 대해 데이터 분석가 도구를 노출하는 실제 Model Context Protocol (MCP) 서버와, 런타임에 해당 도구를 발견하고 질문에 답하기 위해 어떤 도구를 호출할지 결정하는 LLM 에이전트(Gemini)입니다. MCP의 실제 요점은 도구 정의가 에이전트에 하드코딩되지 않고 서버에 있다는 것입니다.

실제 MCP 구현인 이유 (모의 구현이 아님)

• src/mcp_server.py는 공식 mcp Python SDK를 기반으로 구축된 진짜 MCP 서버로, 표준 stdio 전송을 통해 4개의 도구(list_tables, run_sql_query, get_column_stats, plot_bar_chart)를 노출합니다.

• src/smoke_test_client.py는 LLM이 전혀 관여하지 않는 프로토콜 수준 테스트입니다. 서버를 실제 하위 프로세스로 실행하고, stdio로 연결하며, list_tools()를 호출하고, 실제 MCP 와이어 프로토콜을 통해 run_sql_query를 호출합니다. 이는 서버가 그 위의 에이전트가 작동하는지와 무관하게 작동한다는 것을 증명합니다.

• src/mcp_client_agent.py는 에이전트입니다. 서버의 도구를 나열하고, 해당 JSON 스키마를 직접 Gemini 함수 선언으로 변환하며(parameters_json_schema=tool.input_schema — 수동 스키마 변환 없음), 표준 도구 호출 루프를 실행합니다: 모델에 요청 → 실제 MCP 세션을 통해 요청된 도구 호출 실행 → 결과를 다시 피드백 → 모델이 최종 답변을 줄 때까지 반복.

Related MCP server: agente-ecommerce-mcp-memoria

Python 3.10+ 필요

mcp 패키지는 Python 3.9를 지원하지 않습니다. 기본 python이 더 오래된 버전이라면 아래 모든 명령에 py -3.12(또는 보유한 3.10 이상 인터프리터)를 사용하세요.

파이프라인

pip install -r requirements.txt
python src/generate_data.py          # -> data/sales.db (3,000 synthetic orders)
python src/smoke_test_client.py      # protocol-only sanity check, no LLM
python src/mcp_client_agent.py "Which category has the highest revenue?"

GEMINI_API_KEY가 설정되지 않은 경우 mcp_client_agent.py는 수동 대체를 실행합니다: 라이브 서버에서 발견된 도구를 나열하고 하나를 직접 호출하므로 API 키 없이도 MCP 연결을 시연할 수 있습니다. 키가 있으면(.env.example을 .env로 복사) 전체 에이전트 루프를 실행합니다.

테스트

tests/test_pipeline.py는 서버의 도구 함수를 직접 호출합니다(스키마 검사, SELECT가 아닌 SQL 문 거부, 통계). 그리고 — 이것이 작동하는 MCP 구현임을 증명하는 실제 증거 — smoke_test_client.py를 실행합니다. 이 클라이언트는 서버를 실제 하위 프로세스로 시작하고 실제 stdio 프로토콜로 통신합니다. API 키가 필요 없으므로 Python 3.12에서 모든 푸시마다 CI에서 실행됩니다.

pip install -r requirements.txt pytest
pytest tests/ -v

서버가 노출하는 도구

검증됨 vs. 독립적으로 검증되지 않음

• 검증됨: MCP 서버 및 프로토콜 연결(도구 발견, stdio를 통한 도구 실행) — smoke_test_client.py가 LLM 없이 종단 간 실행하며, mcp_client_agent.py의 수동 대체 경로도 동일한 실제 프로토콜을 사용합니다.

• 현재 google-genai SDK에 대해 구현되었지만 이 환경에서 라이브 키로 실행되지 않음: Gemini 도구 호출 루프 자체. 함수 선언 및 함수 응답 유형은 설치된 SDK에서 직접 확인했지만, 실제 다중 턴 호출에는 이 환경에 없는 API 키가 필요합니다. 자체 GEMINI_API_KEY로 실행하여 해당 경로를 테스트하세요.

프로젝트 구조

data/     generated sales.db
src/      mcp_server, smoke_test_client, mcp_client_agent, generate_data
reports/  charts saved by plot_bar_chart

스택

Python 3.12 · mcp (공식 Model Context Protocol SDK) · google-genai · SQLite · matplotlib

라이선스

MIT — LICENSE 참조.