sales-analytics-mcp

Prototipado de un sistema analítico basado en LLM: un servidor MCP y un conjunto de skills con los que el modelo carga datos tabulares (CSV/Excel/JSON), los limpia, genera gráficos y escribe un informe con conclusiones.

Aquí no hay ni se prevé una interfaz de chat propia: el servidor se conecta a un cliente ya existente (Claude Desktop) y es el propio modelo el que lleva toda la cadena de llamadas.

La decisión arquitectónica clave: el dataframe no cruza la frontera del LLM. load_data guarda los datos en el session store y devuelve un dataset_id corto; el resto de herramientas reciben ese id, no los datos en sí. La justificación y las mediciones están en ARCHITECTURE.md.

• Ejemplo de informe generado: reports/sample_report.md

• Gráficos: charts/

• Descripción de la arquitectura: ARCHITECTURE.md

• Especificación de herramientas para integraciones REST: openapi.json

Stack

Python 3.11+, FastMCP (transportes stdio y streamable-http), pandas, matplotlib + seaborn (PNG estáticos), openpyxl, ruff, pytest.

Related MCP server: Claude Data Buddy

Instalación

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

Para comprobar que todo ha quedado instalado correctamente:

pytest
ruff check .

Ejecución

Normalmente no es necesario arrancar el servidor a mano: el cliente MCP lo hace por sí solo (ver la siguiente sección). El arranque manual sirve para asegurarse de que el servidor termina con Sin errores.

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

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

Ambos archivos contienen el mismo conjunto de herramientas a través de core.mcp_app.build_mcp_server(); solo cambia el transporte.

Conexión con Claude Desktop

⚠️ Dónde se encuentra realmente claude_desktop_config.json

La ruta estándar %APPDATA%\Claude\claude_desktop_config.json no es válida para todas las instalaciones. Si Claude Desktop conocedorPasó como aplicación de Microsoft Store (paquete MSIX), esa carpeta no existe en absoluto y la configuración está dentro de la sandbox del paquete:

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

Síntoma: modificas el archivo en la ruta «correcta» (o lo creas) y el servidor no aparece en el cliente pro todos los reintentos ni. buscar esto es fácil; el problema conjunto no funciona.

La forma fiable program advised es localiz un el archivo por su nombre:

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

Añade a la configuración el bloque mcpServers (si el archivo ya existe, escribe la clave sales-analytics dentro del mcpServers existente, sin sobrescribir el resto):

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

Rutassolutas, con contrabarras escapadas. En Linux/macOS — /путь/к/проекту/.venv/bin/python sin escapar.

Después de editar cierra del todo la aplicación (desde la bandeja del sistema o el Administrador de tareas: no basta con cerrar la ventana) y vuelve a abrirla. Para comprobarlo: en la lista de herramientas del cliente debe aparecer sales-analytics con 13 herramientas.

Herramientas

Los cinco primeros nombres del pliego de rendimientos técnicos (load_ datos, describe_data, plot_trend, plot_distribution, correlation_analysis) se conservan literalmente.

Cada gráfico devuelve la ruta de la imagen PNG y una descripción textual de lo que se ve en él, el modelo no tiene la imagen y no podría levantarla. Por qué resultó crítico y qué se descubrió al presenciar la extracción está en ARCHITECTURE.md.

Ejemplo de visualización

El prompt del sistema, con el flujo de pasos, está en prompts/system_prompt.md y se apoya además en la primitiva MCP prompt (con sales_analysis_workflow), para que el cliente la use por su cuenta.

El primer mensaje puede ser:

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

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

A partir de ahí el modelo actúa la cadena por sí mismo: load_data → describe_data → clean_data → gráficos → prepare_insights_context → export_report.

El resultado final está en reports/sample_report.md.

Capturas de pantalla de la prueba: docs/screenshots/ — la prueba se ejecutó en un chat en cabo, sin este prompt de sistema, usando únicamente las descripciones de las herramientas.

Datos de prueba

data/sales_data.csv: un conjunto de datos detallado (180 filas, 2023–2024) al que se han introducido defectos deliberadamente: ausencias, duplicados, elementos atípicos, disparidad en formatos de fecha e incoherencias en el los nombres de las regiones. Sin ellos no habría nada que limpiar.

La ubicación exacta de los defectos con sus cantidades está en data/README.md; ese archivo se usa como será de referencia para verificar la limpieza.

Para generar de nuevo (de forma reproducible, con random_state fijado):

python scripts/generate_data.py

Integración a través de OpenAPI

openapi.json expone cada herramienta MCP como un POST /tools/{name} con el mismo esquema JSON de nylon de la modelo: no es una especificación de opciones HTTP de server_http.py (ese habla el protocolo MCP, no REST habitual), sino una presentación compatible del inverso. Una integración con exactamente OpenAPI, por ejemplo Custom Alternative.

No se ha desplegado ningún endpoint público HTTPS activo dentro de la tarea; es una evaluación concreta — véase ARCHITECTURE.md.

Para regenerar tras añadir una skill:

python scripts/generate_openapi.py

Desarrollo

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

Añadir una nueva skill consiste en añadir un archivo nuevo en skills/; no hay que tocar core/ ni los puntos de entrada del servidor. Cómo de exacto —véase la sección «Cómo añadir una nueva skill» de ARCHITECTURE.md.

Licencia

MIT.

La extensibilidad se demuestra con un diff, no con declaraciones

La última skill —analyze_seasonality — se añadió intencionadamente aparte de las demás, ya después de que el sistema estuviera escrito y documentado, precisamente para que esto se pueda comprobar.

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

Ese commit contiene exactamente dos archivos: skills/seasonality.py y el ajuste de la tabla de herramientas de README.md. Sin una sola línea en core/, ni en server_stdio.py ni server_http.py. Aun así, al reiniciar cliente, la herramienta aparece en la lista como documento decimotercero, con un esquema de args construido a partir de la firma y el docstring.

(Las pruebas de la skill se añadieron el siguiente commit, por separado, para que el diff del commit de prueba siguiera que ser mínimo y se pudiera leer todas partes: en texto)