sales-analytics-mcp

基于 LLM 的分析系统原型：由一个 MCP 服务器和一套技能组成，模型通过这些技能加载表格数据（CSV/Excel/JSON）、清洗数据、生成图表，并撰写带结论的报告。

这里没有也不打算自带聊天界面——服务器接接到现成的客户端（Claude Desktop），整条调用链由模型自己驱动。

关键架构决策：数据帧（DataFrame) 不跨 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 包）安装的，那这个文件夹根本不存在，配置文件位于包的沙箱（sandbox）中：

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

症状：你按“正确”路径修改（或创建）文件，然后无论重启多少次，服务器都不出现在客户端中。为了找这个文件很容易浪费半小时，然后得出“项目不工作”的结论。

判断自己属于哪种情况的可靠方法——按文件名查找：

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，同时以 MCP 原语 prompt 形式提供，名字为 sales_analysis_workflow——客户端可以直接拉取。

第一条消息可以是这样的：

Проанализируй данные о продажах из файла
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 工具表示为 POST /tools/{name}，参数 JSON Schema 与模型看到的一致。它不是 server_http.py 的 HTTP 路由规范（那一种是 MCP 协议，不是常规 REST），而是给确实需要 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)"

这个 commit 中只有两个文件：skills/seasonality.py 和 README.md 中工具表的修改。core/、server_stdio.py、server_http.py 中没有任何改动。重启客户端后该工具作为第十三个工具出现，它的参数 schema 由签名和 docstring 自动生成。

（对这个技能：的测试放在下个 commit 中单独提交，目的是让作为“证据”的 commit diff 尽可能小，通读一遍不会超过半分钟。）