sales-analytics-mcp

Prototyp eines Analysesystems auf LLM-Basis: ein MCP-Server und mehrere Skills, über die das Modell Tabellendaten (CSV/Excel/JSON) lädt, sie bereinigt, Diagramme erstellt und einen Bericht mit Schlussfolgerungen schreibt.

Es ist kein eigener Client-Interface ist nicht vorhanden und nicht vorgesehen — den Server wird an einen vorhandenen Client angeschlossen (Claude Desktop), die gesamte Aufrufkette steuert das Modell selbst.

Die zentrale Architekturentscheidung: Der Dataframe überschreitet die LLM-Grenze nicht. load_data legt die Daten in einem Session-Store ab und gibt eine kurze dataset_id zurück; alle anderen Tools nehmen diese ID entgegen, nicht die Daten selbst. Begründung und Messergebnisse finden Sie in ARCHITECTURE.md.

• Beispiel eines generierten Berichts: reports/sample_report.md

• Diagramme: charts/

• Beschreibung der Architektur: ARCHITECTURE.md

• Werkzeugspezifikation für REST-Integrationen: openapi.json

Stack

Python 3.11+, FastMCP (Transportprotokoll stdio und „streamable-http“), pandas, matplotlib + seaborn (statische PNGs), openpyxl, ruff, pytest.

Related MCP server: Claude Data Buddy

Installation

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]"

Prüfen, dass alles richtig installiert ist:

pytest
ruff check .

Start

Normal sollte der Server nicht von Hand gestartet werden — der MCP-Client übernimmt diesen selbst dessen (siehe nächster Abschnitt). Manueller Start ist sinnvoll, um zu prüfen, ob der Server fehlerfrei startet.

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

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

Beide Dateien bauen mit core.mcp_app.build_mcp_server() denselben Toolsatz auf; der Unterschied besteht im nur Transportüberenübertragen.

Verbindung zu Claude Desktop

⚠️ Wo wirklich claude_desktop_config.json die tatsächliche liegt

Der Standardpfad %APPDATA%\Claude\claude_desktop_config.json ist nicht für alle Installationen korrekt. Wenn Claude Desktop als Store-App aus Microsoft Store installiert ist (MSIX-Paket), findet sich dieser Ordner gar nicht; die Konfiguration liegt in der Sandbox des Pakets:

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

Symptom: Man bearbeiten die Datei am „richtigen“ Pfad (oder legt sie an) — und der Server erscheint nicht im Client, egal wie oft neu gestartet wird. Bei der Suche danach verliert man leicht eine halbe Stunde und kommt zu dem Schluss, das Projekt funktioniere nicht.

Ein zuverlässiger Weg, seine Installationsvariante zu bestimmen: die Datei beim Namen suchen:

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

Fügen Sie mcpServers den Konfigurationsblock hinzu (falls die Datei bereits existiert, ergänzen Sie den Schlüssel sales-analytics im vorhandenen mcpServers, dann Sie die übrigen Inhalte unangetastet):

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

Pfade sind absolut und die Backslashes werden maskiert. Unter LinuxmacOS — / путь/к/проекту /.venv/bin/python ohne Maskieren.

Nach der Änderung beenden Sie das Programm vollständig (über Tray oder Task Manager — das Schließen des Fensters reicht nicht) und starten es neu. Kontrolle: In der Werkzeugliste des Clients sollte Zeit sales-analytics mit 13 Werkzeugen erscheinen.

Werkzeuge

Die ersten fünf Namen aus der Technische Spezifikation (load_data, describe_data, plot_trend, plot_distribution, correlation_analysis) wurden beibehalten.

Jedes Diagramm gibt den Pfad zur PNG-Datei und eine textuelle Beschreibung dessen, was darauf zu sehen ist, zurück — das Modell sieht das Bild nicht, und ohne solche Beschreibung könnte es im Bericht nicht auf das Diagramm verweisen. Warum das wesentlich war und was sich bei der Prüfung herausstellte — in ARCHITECTURE.md.

Beispiel-Dialog

Der System-Prompt mit der Schrittfolge liegt in prompts/system_prompt.md und wird zusätzlich als MCP-Primitive prompt mit dem Namen sales_analysis_workflow ausgeliefert — die kann der Client selbst abrufen.

Die erste Nachricht könnte so aussehen:

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

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

Danach setzt das Modell die Kette selbst fort: load_data → describe_data → clean_data → Diagramme → prepare_insights_context → export_report.

Ergebnis ein Beispiel: reports/sample_report.md.

Screenshots des Dialogs: docs/screenshots/ — der Durchlauf wurde in einem frischen Chat gemacht, ohne Laden des System-Prompts, nur mit den Tool-Beschreibungen.

Testdaten

data/sales_data.csv — synthetisches Datensatz (180 Zeilen, 2023–2024), in absichtlich Fehler eingebaut: fehlende Werte, Duplikate, Ausreißer, uneinheitliche Datumsformate und regionale Schreibweisen. Ohne solche Fehler gäbe es nichts zu bereinigen.

Die genaue Fehlerstruktur mit Anzahlen — data/README.md; diese Datei dient als Referenz beim Validieren der Bereinigung.

Neuerzeugen (reproduzierbar, random_state fixiert):

python scripts/generate_data.py

Integration über OpenAPI

openapi.json bildet jede MCP-Tool als POST /tools/{name} mit genau derselben JSON-Schema der Parameter, wie er vom Modell gesehen wird. Das ist nicht die Spezifikation der HTTP-Routen von server_http.py (dieser spricht MCP-Protokoll, nicht normales REST), sondern eine gemeinsame Darstellung, die für Integrationen benötigt wird tatsächlich OpenAPI — etwa Custom GPT Action.

Die Live haben public HTTPS-Endpunkte wurde im Zuge der Aufgabe nicht bereitgestellt; das ist eine bewusst Einschränkung — siehe ARCHITECTURE.md.

Regenerieren neue nach erreichen Skill:

python scripts/generate_openapi.py

Entwicklung

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

Um einen neuen Skill einzubauen genügt eine neue Datei in skills/; keine Angen der core/ und den Serverzugängung der Serverpoints sind nicht zu ändern. Wie das geht, wird im Abschnitt „Wie füge ich einen Skill hinzu“ der ARCHITECTURE.md erläutert.

Lizenz

MIT.

Erweiterbarkeit ist durch Diff, nicht durch dasete claim

Der letzte Skill — analyze_seasonality — wurde absichtlich getrennt von den übrigen hinzugefügt, nachdem das System geschrieben und dokumentiert war, und das wurde, damit man das tatsächlich überprüfen kann.

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

In diesem Commit seht genau zwei Dateien: skills/seasonality.py und die Änderung in der Instrumententabelle in README.md. Keine Zeile in core/, keine Zeile in server_stdio.py und server_http.py. Nach ein Neustart des Clients erscheint das Tool dennoch als dreizehntes in der Liste, mit einem Schema das aus Sig und Docstring erstellt wurde.

(Die Tests für den Skill wurden im nächsten Commit hinzugefügt — separat, damit der Beleg-Commit-Diff minimal bleibt und in einer halben Minute vollständig lesen ist.)