sales-analytics-mcp

LLM ベースのアナリティクスシステムのプロトタイプです。MCP サーバーとスキル群を持ち、モデルはそれらを通して表形式データ（CSV/Excel/JSON）の読み込み、クリーニング、グラフ描画を行い、結論付きのレポートを作成します。

独自のチャットインターフェースはここにはなく、その想定もありません。サーバーは既存のクライアント（Claude Desktop）に接続し、呼び出しチェーン全体をモデル自身が進めます。

重要なアーキテクチャ上の決定として、データフレームは LLM の境界を越えません。load_data はデータをセッションストアに保存し、短い 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個のツールとして表示されます。

ツール

要件定義の最初の5つの名前（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 スキーマはモデルが見るものと同じです。これは server_http.py の HTTP ルート仕様ではありません（server_http.py は通常の REST ではなく MCP プロトコルで通信します）。ここにあるのは、OpenAPI を必要とする連携先（たとえば Custom GPT Action）向けの互換表現です。

公開の HTTPS エンドポイントはこの課題の範囲ではデプロイしていません。これは意図した制限です。ARCHITECTURE.md を参照してください。

スキルを追加した後に再生成:

python scripts/generate_openapi.py

開発

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

新しいスキルの追加は、skills/ に新規ファイルを1つ置くだけで済みます。core/ やサーバーのエントリポイントの修正は不要です。具体的な手順は ARCHITECTURE.md の「新しいスキルを追加する方法」セクションにあります。

ライセンス

MIT。

拡張性は、宣言ではなく diff で示されています

最後に追加したスキル analyze_seasonality は、システムの実装とドキュメント化が完了した後に、他のスキルと意図的に分離して追加しました。拡張性を実際に確認できるようにするためです。

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

このコミットには、skills/seasonality.py と README.md のツール表に対する修正の、ちょうど2ファイルだけが含まれています。core/ にも、server_stdio.py や server_http.py にも1行も変更がありません。それでも、クライアントを再起動すると、このツールは13番目として表示され、そのパラメータスキーマもシグネチャと docstring から自動で作られます。

（このスキルのテストは次のコミットで追加しています。証拠としてのコミットの diff を小さく保ち、半分ほどで全体を読み切れるようにするためです。）