@yoryoboy/bi-mcp 1.0.1

package/README.md

@@ -0,0 +1,346 @@
+# bi-mcp
+
+MCP monolítico de business intelligence para ecommerce en Argentina, construido con [`mcp-use`](https://mcp-use.com/docs/typescript/getting-started/quickstart).
+
+Proyecto está pensado para que usuarios puedan consultar datos reales de operación, marketing y adquisición desde un LLM, usando lenguaje natural, y recibir respuestas útiles para análisis, diagnóstico y toma de decisiones.
+
+Hoy el servidor integra VTEX, Google Analytics 4, Search Console, Google Ads y benchmarks de referencia para Argentina. La arquitectura ya está preparada para crecer hacia módulos de finanzas.
+
+## Índice
+
+- [Qué cubre hoy](#qué-cubre-hoy)
+- [Estado actual](#estado-actual)
+- [Arquitectura del proyecto](#arquitectura-del-proyecto)
+- [Principios no negociables](#principios-no-negociables)
+- [Requisitos](#requisitos)
+- [Configuración](#configuración)
+- [Instalación y ejecución](#instalación-y-ejecución)
+- [Estructura del repositorio](#estructura-del-repositorio)
+- [Flujo de trabajo para desarrollo](#flujo-de-trabajo-para-desarrollo)
+- [Documentación clave](#documentación-clave)
+- [Estado del roadmap](#estado-del-roadmap)
+- [Licencia](#licencia)
+
+## Qué cubre hoy
+
+El MCP ya tiene capacidades activas para estas áreas:
+
+- `VTEX`
+  Operación comercial, pedidos, stock, inventario por depósito, precios y ofertas.
+
+- `Analytics (GA4)`
+  Tráfico, revenue medido en GA4, mix de canales, engagement y salud de medición.
+
+- `Search Console`
+  Performance SEO, queries, páginas, oportunidades de CTR y alertas de visibilidad.
+
+- `Google Ads`
+  Performance de cuenta, campañas, series temporales, riesgos, break-even y salud de escalabilidad.
+
+- `Config / Benchmarks AR`
+  Benchmarks argentinos de IIBB, cuotas, pasarelas, logística y calendario comercial.
+
+Además, el repo incluye un prompt de reporte de ventas y la base arquitectónica para sumar módulos de `finance` y `diagnostics`.
+
+Para una explicación orientada a usuario final sobre capacidades, alcance y herramientas disponibles, ver [docs/CAPACIDADES_MCP.md](/home/yoryo/apps/bi-mcp/docs/CAPACIDADES_MCP.md).
+
+## Estado actual
+
+Estado real del repo al día de hoy:
+
+- `VTEX`: implementado
+- `Analytics (GA4)`: implementado
+- `Search Console`: implementado
+- `Google Ads`: implementado
+- `Benchmarks Argentina`: implementado
+- `Finance`: pendiente
+- `Diagnostics`: pendiente
+
+En términos de superficie funcional actual:
+
+- `10` tools de VTEX
+- `11` tools de Google Ads
+- `14` tools de Search Console
+- `11` tools de GA4
+- `1` tool/config de benchmarks
+- `1` prompt de reporte
+
+Cualquier cambio nuevo debe respetar la estructura y reglas definidas en [AGENTS.md](/home/yoryo/apps/bi-mcp/AGENTS.md).
+
+## Arquitectura del proyecto
+
+La decisión principal de arquitectura es simple:
+
+- `Un solo servidor MCP`
+- `Múltiples módulos internos en src/`
+- `Handlers delgados`
+- `Servicios externos agrupados por proveedor`
+- `Cálculo y agregación en código`
+- `LLM consumiendo JSONs livianos ya procesados`
+
+El servidor está registrado en [index.ts](/home/yoryo/apps/bi-mcp/index.ts) y usa `mcp-use` como framework principal.
+
+La estructura actual se organiza así:
+
+- `src/tools/`
+  Tools MCP agrupadas por proveedor o dominio.
+
+- `src/services/`
+  Clientes y wrappers para APIs externas.
+
+- `src/config/`
+  Configuración de infraestructura y benchmarks.
+
+- `src/utils/`
+  Utilidades compartidas para paginación, dinero, currency safety y limpieza de payloads.
+
+- `src/prompts/`
+  Prompts del servidor.
+
+La visión del proyecto es seguir creciendo como monolito modular, no fragmentarlo en múltiples MCPs.
+
+## Principios no negociables
+
+Estas reglas gobiernan cualquier cambio en el repo:
+
+- `Code computes, LLM analyzes`
+  El servidor agrega, resume y calcula. No se deben enviar payloads crudos masivos al modelo.
+
+- `Token efficiency`
+  Se eliminan `null`, arrays vacíos y campos irrelevantes antes de responder.
+
+- `Pagination awareness`
+  Si una respuesta es parcial o paginada, eso debe quedar explicitado.
+
+- `Multi-currency safety`
+  No se mezclan monedas en un mismo agregado.
+
+- `Decimal correction`
+  VTEX devuelve montos en centavos. Hay que corregirlos antes de exponerlos.
+
+- `Argentina-first`
+  Benchmarks, supuestos y lógica de referencia deben seguir el documento de Julián y el contexto argentino.
+
+- `mcp-use only`
+  El servidor usa primitivas de `mcp-use`. No se debe migrar al SDK de MCP directo.
+
+- `pnpm only`
+  Este repositorio usa `pnpm` como package manager oficial.
+
+## Requisitos
+
+Antes de levantar el proyecto, necesitás como mínimo:
+
+- `Node.js` reciente con soporte ESM
+- `pnpm`
+- credenciales de las integraciones que quieras usar
+
+Dependiendo del módulo que quieras probar, el entorno puede requerir:
+
+- credenciales de VTEX
+- OAuth de Google para GA4 y Search Console
+- credenciales de Google Ads
+
+## Configuración
+
+La configuración de infraestructura se lee desde `.env`.
+
+Variables relevantes hoy:
+
+- `VTEX_ACCOUNT_NAME`
+- `VTEX_API_KEY`
+- `VTEX_API_TOKEN`
+- `GOOGLE_OAUTH_CLIENT_ID`
+- `GOOGLE_OAUTH_CLIENT_SECRET`
+- `GOOGLE_OAUTH_REFRESH_TOKEN`
+- `GA4_PROPERTY_ID`
+- `GOOGLE_ADS_DEVELOPER_TOKEN`
+- `GOOGLE_ADS_LOGIN_CUSTOMER_ID`
+- `MCP_TRANSPORT`
+- `PORT`
+- `MCP_URL`
+
+Reglas importantes:
+
+- `.env` es solo para infraestructura y credenciales
+- la configuración de negocio no debe vivir hardcodeada en `.env`
+- no commitear `.env`, `credentials.json` ni `token.json`
+
+La separación esperada es:
+
+- `infraestructura y credenciales` en `.env`
+- `configuración del negocio` en `business-data` cuando ese módulo esté completo
+
+## Instalación y ejecución
+
+Instalación:
+
+```bash
+pnpm install
+```
+
+Desarrollo:
+
+```bash
+pnpm run dev
+```
+
+Build:
+
+```bash
+pnpm run build
+```
+
+Ejecución del build:
+
+```bash
+pnpm run start
+```
+
+Deploy:
+
+```bash
+pnpm run deploy
+```
+
+Uso vía `npx` después de publicar el paquete:
+
+```json
+{
+  "mcpServers": {
+    "bi-mcp-stdio": {
+      "command": "npx",
+      "args": ["-y", "@yoryoboy/bi-mcp"],
+      "env": {
+        "MCP_TRANSPORT": "stdio",
+        "VTEX_ACCOUNT_NAME": "your_vtex_account_name",
+        "VTEX_API_KEY": "your_vtex_api_key",
+        "VTEX_API_TOKEN": "your_vtex_api_token",
+        "GOOGLE_OAUTH_CLIENT_ID": "your_google_oauth_client_id",
+        "GOOGLE_OAUTH_CLIENT_SECRET": "your_google_oauth_client_secret",
+        "GOOGLE_OAUTH_REFRESH_TOKEN": "your_google_oauth_refresh_token",
+        "GA4_PROPERTY_ID": "your_ga4_property_id",
+        "GOOGLE_ADS_DEVELOPER_TOKEN": "your_google_ads_developer_token",
+        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "your_google_ads_login_customer_id"
+      }
+    }
+  }
+}
+```
+
+Puntos importantes para ese modo:
+
+- en configuración por `command`, el transporte correcto es `stdio`, por eso hay que pasar `MCP_TRANSPORT=stdio`
+
+Flujo típico de publicación:
+
+```bash
+pnpm version patch
+pnpm publish --access public
+```
+
+En desarrollo, `mcp-use` expone el inspector para probar el servidor localmente. Si estás usando la configuración por defecto, el flujo típico es abrir:
+
+```text
+http://localhost:3000/inspector
+```
+
+## Estructura del repositorio
+
+Resumen de las rutas más importantes:
+
+```text
+bi-mcp/
+├── AGENTS.md
+├── README.md
+├── docs/
+├── index.ts
+├── src/
+│   ├── config/
+│   ├── services/
+│   │   ├── analytics/
+│   │   ├── google-ads/
+│   │   ├── search-console/
+│   │   └── vtex/
+│   ├── tools/
+│   │   ├── analytics/
+│   │   ├── google-ads/
+│   │   ├── search-console/
+│   │   └── vtex/
+│   ├── prompts/
+│   └── utils/
+├── package.json
+└── pnpm-lock.yaml
+```
+
+Puntos de entrada y referencia:
+
+- [index.ts](/home/yoryo/apps/bi-mcp/index.ts)
+  Registro del servidor, tools y prompts.
+
+- [src/tools/index.ts](/home/yoryo/apps/bi-mcp/src/tools/index.ts)
+  Barrel raíz de tools por módulo.
+
+- [src/config/benchmarks.ts](/home/yoryo/apps/bi-mcp/src/config/benchmarks.ts)
+  Benchmarks argentinos expuestos por el servidor.
+
+## Flujo de trabajo para desarrollo
+
+Si vas a tocar código en este repo, la referencia obligatoria es [AGENTS.md](/home/yoryo/apps/bi-mcp/AGENTS.md).
+
+Resumen operativo:
+
+- leer `AGENTS.md` antes de programar
+- no inventar fórmulas financieras
+- no reimplementar módulos que ya existen
+- no poner lógica de negocio en `index.ts`
+- agrupar `tools/` y `services/` por proveedor o dominio
+- usar schemas Zod en el mismo archivo que el handler
+- registrar las tools en `index.ts`
+- usar naming consistente por prefijo de módulo
+
+Convenciones principales:
+
+- archivos en `kebab-case`
+- tools MCP en `snake_case` con prefijo
+- `schema + handler` en el mismo archivo
+- utilidades compartidas en `src/utils/`
+
+## Documentación clave
+
+El repo ya tiene documentación que define tanto el alcance funcional como las reglas de implementación:
+
+- [AGENTS.md](/home/yoryo/apps/bi-mcp/AGENTS.md)
+  Guía maestra del proyecto, arquitectura, reglas y roadmap.
+
+- [docs/CAPACIDADES_MCP.md](/home/yoryo/apps/bi-mcp/docs/CAPACIDADES_MCP.md)
+  Documento orientado a usuario sobre qué cubre el MCP.
+
+- [docs/Ecommerce Growth & Profit OS – Argentina Edition (V3.md](/home/yoryo/apps/bi-mcp/docs/Ecommerce%20Growth%20%26%20Profit%20OS%20%E2%80%93%20Argentina%20Edition%20%28V3.md)
+  Fuente de verdad para fórmulas financieras, benchmarks y outputs esperados.
+
+- [docs/vtex-key-endpoints.md](/home/yoryo/apps/bi-mcp/docs/vtex-key-endpoints.md)
+  Endpoints VTEX y contratos de referencia.
+
+- [docs/logica-procesamiento-mcp-vtex.md](/home/yoryo/apps/bi-mcp/docs/logica-procesamiento-mcp-vtex.md)
+  Criterios de transformación de respuestas VTEX.
+
+- [docs/flujos-bi-vtex.md](/home/yoryo/apps/bi-mcp/docs/flujos-bi-vtex.md)
+  Qué combinaciones de tools ayudan a responder distintos análisis de negocio.
+
+## Estado del roadmap
+
+La dirección definida del producto es:
+
+1. `Finance`
+   CM1, CM2, CM3, CCC, LTV/CAC y lógica financiera basada en benchmarks locales.
+
+2. `Diagnostics`
+   Kill Switch, score de escalabilidad y outputs ejecutivos.
+
+3. `Evolución del perfil de negocio`
+   Diseño single-profile hoy, pero multi-profile ready en estructura.
+
+## Licencia
+
+MIT. Ver [package.json](/home/yoryo/apps/bi-mcp/package.json).

package/bin/bi-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/index.js";