sales-analytics-mcp

LLM 기반 분석 시스템 프로토타입: MCP 서버와 스킬 세트를 통해 모델이 테이블 데이터(CSV/Excel/JSON)를 로드하고, 정리하고, 그래프를 그리고, 결론이 담긴 보고서를 작성합니다.

자체 채팅 인터페이스는 없으며 만들 예정도 없습니다 — 서버는 기존 클라이언트(Claude Desktop)에 연결되며, 전체 호출 체인은 모델이 직접 주도합니다.

핵심 아키텍처 결정: 데이터프레임은 LLM 경계를 넘지 않습니다. load_data는 데이터를 session store에 저장하고 짧은 dataset_id를 반환합니다. 다른 모든 도구는 데이터 자체가 아닌 이 id를 받습니다. 근거와 측정 결과는 ARCHITECTURE.md에 있습니다.

• 생성된 보고서 예시: reports/sample_report.md

• 그래프: charts/

• 아키텍처 설명: ARCHITECTURE.md

• REST 통합용 도구 명세: openapi.json

스택

Python 3.11+, FastMCP (stdio 및 streamable-http 전송), pandas, matplotlib + seaborn (정적 PNG), openpyxl, ruff, pytest.

Related MCP server: Excel MCP Server

설치

git clone https://github.com/ibezgachev/sales-analytics-mcp.git
cd sales-analytics-mcp

python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate

pip install -e ".[dev]"

설치가 제대로 되었는지 확인:

pytest
ruff check .

실행

보통 서버를 수동으로 실행할 필요는 없습니다 — MCP 클라이언트가 직접 실행합니다(다음 섹션 참조). 수동 실행은 서버가 오류 없이 시작되는지 확인할 때 유용합니다.

# транспорт stdio — для локальных клиентов вроде Claude Desktop
python server_stdio.py

# транспорт streamable-http — http://127.0.0.1:8000/mcp
python server_http.py

두 파일 모두 core.mcp_app.build_mcp_server()를 통해 동일한 도구 세트를 구성합니다. 전송 방식만 다릅니다.

Claude Desktop 연결

⚠️ claude_desktop_config.json의 실제 위치

표준 경로 %APPDATA%\Claude\claude_desktop_config.json는 모든 설치 환경에 해당하는 것은 아닙니다. Claude Desktop이 Microsoft Store 앱(MSIX 패키지)으로 설치된 경우 이 폴더는 아예 존재하지 않으며, 설정 파일은 패키지 샌드박스에 있습니다:

%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

증상: "올바른" 경로의 파일을 수정(또는 생성)해도 — 아무리 재시작해도 서버가 클라이언트에 나타나지 않습니다. 이 문제를 찾는 데 30분을 허비하고 프로젝트가 작동하지 않는다고 판단하기 쉽습니다.

자신의 환경을 확실히 확인하는 방법은 파일 이름으로 검색하는 것입니다:

Get-ChildItem -Path $env:LOCALAPPDATA,$env:APPDATA -Recurse -Filter claude_desktop_config.json -ErrorAction SilentlyContinue

mcpServers 블록을 설정 파일에 추가하세요(파일이 이미 있다면 기존 mcpServers 안에 sales-analytics 키를 다른 내용을 덮어쓰지 않고 추가하세요):

{
  "mcpServers": {
    "sales-analytics": {
      "command": "C:\\путь\\к\\проекту\\.venv\\Scripts\\python.exe",
      "args": ["C:\\путь\\к\\проекту\\server_stdio.py"]
    }
  }
}

경로는 절대 경로이며, 백슬래시는 이스케이프 처리되어 있습니다. Linux/macOS에서는 /프로젝트/경로/.venv/bin/python — 이스케이프 없이 사용합니다.

수정 후에는 앱을 완전히 종료(트레이 또는 작업 관리자를 통해 — 창을 닫는 것만으로는 부족합니다)하고 다시 실행하세요. 확인 방법: 클라이언트의 도구 목록에 sales-analytics가 13개의 도구와 함께 나타나야 합니다.

도구

명세서의 처음 다섯 개 이름(load_data, describe_data, plot_trend, plot_distribution, correlation_analysis)은 그대로 유지되었습니다.

각 그래프는 PNG 경로와 그래프에 보이는 내용에 대한 텍스트 설명을 반환합니다 — 모델은 이미지를 볼 수 없으므로 설명 없이는 보고서에서 그래프를 참조할 수 없습니다. 이것이 왜 중요했는지, 그리고 검증 중에 무엇이 밝혀졌는지는 ARCHITECTURE.md에 있습니다.

대화 예시

단계별 시퀀스가 담긴 시스템 프롬프트는 prompts/system_prompt.md에 있으며, sales_analysis_workflow라는 이름의 MCP 프리미티브 prompt로도 중복 제공됩니다 — 클라이언트가 직접 가져올 수 있습니다.

첫 메시지는 다음과 같을 수 있습니다:

Проанализируй данные о продажах из файла
C:\путь\к\проекту\data\sales_data.csv

Загрузи их, посмотри структуру, почисти от дефектов, построй графики
и дай развёрнутый отчёт с выводами и практическими рекомендациями.

이후 모델이 체인을 직접 주도합니다: load_data → describe_data → clean_data → 그래프 → prepare_insights_context → export_report.

결과물은 reports/sample_report.md에 있습니다.

대화 스크린샷: docs/screenshots/ — 시스템 프롬프트를 로드하지 않고 도구 설명만으로 깨끗한 채팅에서 실행한 결과입니다.

테스트 데이터

data/sales_data.csv — 의도적으로 결함을 넣은 합성 데이터셋(180행, 2023–2024): 결측값, 중복, 이상치, 날짜 형식 불일치, 지역명 표기 불일치. 이 결함들이 없으면 정리할 것이 없습니다.

결함의 정확한 구성과 수량은 data/README.md에 있습니다. 이 파일은 정리 검증의 기준이 됩니다.

재생성(재현 가능, random_state 고정):

python scripts/generate_data.py

OpenAPI 통합

openapi.json은 각 MCP 도구를 모델이 보는 것과 동일한 JSON 스키마의 POST /tools/{name}으로 표현합니다. 이는 server_http.py의 HTTP 라우트 명세가 아닙니다(그것은 일반 REST가 아닌 MCP 프로토콜을 사용합니다). OpenAPI가 필요한 통합 — 예: Custom GPT Action — 을 위한 호환 표현입니다.

과제 범위 내에서는 공개 HTTPS 엔드포인트를 배포하지 않았습니다. 이는 의도적인 제한입니다 — ARCHITECTURE.md 참조.

스킬 추가 후 재생성:

python scripts/generate_openapi.py

개발

ruff check .          # линтер
ruff format .         # форматтер
pytest                # тесты

새 스킬 추가는 skills/에 새 파일 하나를 만드는 것뿐입니다. core/와 서버 진입점의 수정은 필요 없습니다. 방법은 ARCHITECTURE.md의 "새 스킬 추가 방법" 섹션에 있습니다.

라이선스

MIT.

확장성은 선언이 아닌 diff로 증명됩니다

마지막 스킬인 analyze_seasonality는 시스템이 작성되고 문서화된 이후에 의도적으로 다른 스킬들과 분리되어 추가되었습니다. 바로 이 점을 검증할 수 있도록 하기 위해서입니다.

git show --stat "$(git log --format=%H --grep='скилл анализа сезонности' -1)"

이 커밋에는 정확히 두 개의 파일이 있습니다: skills/seasonality.py와 README.md의 도구 표 수정. core/에는 한 줄도, server_stdio.py와 server_http.py에는 한 줄도 없습니다. 그런데도 클라이언트를 재시작하면 도구가 시그니처와 독스트링에서 생성된 파라미터 스키마와 함께 열세 번째로 목록에 나타납니다.

(스킬 테스트는 다음 커밋에서 추가되었습니다 — 증명 커밋의 diff를 최소화하여 30초 안에 전체를 읽을 수 있도록 하기 위해 별도로 분리했습니다.)