@yoryoboy/bi-mcp 1.3.0 → 1.4.0

package/README.md

@@ -1,244 +1,38 @@
 # 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).
+`bi-mcp` es un servidor MCP de business intelligence para ecommerce en Argentina.
 
-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.
+Permite consultar datos reales de operacion, marketing y adquisicion desde un asistente compatible con MCP, usando lenguaje natural. La idea es que Julian, su equipo o un cliente puedan preguntar por ventas, canales, performance, SEO, anuncios, inventario o riesgos de negocio sin tener que entrar manualmente a cada plataforma.
 
-Hoy el servidor integra Config / Infra, VTEX, Google Analytics 4, Search Console, Google Ads, Meta Ads y benchmarks de referencia para Argentina. La arquitectura ya está preparada para crecer hacia módulos de finanzas.
+## Que podes consultar
 
-## Índice
+Hoy el MCP cubre estas areas:
 
-- [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)
+- **VTEX:** pedidos, stock, inventario por deposito, precios, ofertas y operaciones comerciales.
+- **Google Analytics 4:** revenue medido, trafico, canales, engagement y salud de medicion ecommerce.
+- **Search Console:** queries, paginas, CTR, oportunidades SEO y alertas de visibilidad.
+- **Google Ads:** performance de cuenta y campanas, riesgos, break-even y salud de escalabilidad.
+- **Meta Ads:** discovery de cuentas publicitarias, performance de campanas y ads, series temporales y placements.
+- **Config / Benchmarks Argentina:** referencias locales para IIBB, cuotas, pasarelas, logistica y calendario comercial.
 
-## Qué cubre hoy
+La documentacion completa de capacidades esta en [docs/CAPACIDADES_MCP.md](/home/yoryo/apps/bi-mcp/docs/CAPACIDADES_MCP.md).
 
-El MCP ya tiene capacidades activas para estas áreas:
+## Como se usa
 
-- `Config / Infra`
-  Verificación de salud de la base del MCP y listado de perfiles disponibles.
+Una vez conectado el servidor a tu cliente MCP, podes hacer preguntas como:
 
-- `VTEX`
-  Operación comercial, pedidos, stock, inventario por depósito, precios y ofertas, exigiendo selección explícita del `profileId` correcto.
+- "Como vienen las ventas de esta semana?"
+- "Que canales traen mas revenue?"
+- "Que campanas de Google Ads estan cerca del break-even?"
+- "Que queries SEO tienen muchas impresiones y bajo CTR?"
+- "Hay problemas de stock en productos importantes?"
+- "Que placements de Meta concentran el gasto?"
 
-- `Analytics (GA4)`
-  Tráfico, revenue medido en GA4, mix de canales, engagement y salud de medición.
+No hace falta memorizar nombres tecnicos de herramientas. Las tools existen por detras para que el asistente pueda buscar, cruzar y resumir la informacion.
 
-- `Search Console`
-  Performance SEO, queries, páginas, oportunidades de CTR y alertas de visibilidad.
+## Conexion rapida
 
-- `Google Ads`
-  Performance de cuenta, campañas, series temporales, riesgos, break-even y salud de escalabilidad.
-
-- `Meta Ads`
-  Discovery de businesses y cuentas publicitarias, overview de cuenta, performance de campañas y ads, series temporales y mix de placements.
-
-- `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
-- `Meta Ads`: implementado
-- `Benchmarks Argentina`: implementado
-- `Finance`: pendiente
-- `Diagnostics`: pendiente
-
-En términos de superficie funcional actual:
-
-- `2` tools de Config / Infra
-- `10` tools de VTEX
-- `11` tools de Google Ads
-- `8` tools de Meta 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 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
-- credenciales de Meta Marketing API
-
-## Configuración
-
-La configuración de infraestructura se lee desde `.env`.
-
-Variables relevantes hoy:
-
-- `GOOGLE_OAUTH_CLIENT_ID`
-- `GOOGLE_OAUTH_CLIENT_SECRET`
-- `GOOGLE_OAUTH_REFRESH_TOKEN`
-- `GA4_PROPERTY_ID`
-- `GOOGLE_ADS_DEVELOPER_TOKEN`
-- `GOOGLE_ADS_LOGIN_CUSTOMER_ID`
-- `META_APP_ID`
-- `META_APP_SECRET`
-- `META_ACCESS_TOKEN`
-- `META_API_VERSION`
-- `MCP_TRANSPORT`
-- `PORT`
-- `MCP_URL`
-- `DATABASE_URL`
-- `DB_ENCRYPTION_KEY`
-
-Importante:
-
-- las credenciales VTEX por cliente ya no deben vivir en `.env`
-- `.env` ahora guarda solo infraestructura, secretos globales del servidor y la key de cifrado para persistencia VTEX
-- las credenciales VTEX por perfil se cargan por scripts administrativos hacia Postgres
-- las tools VTEX no usan fallback silencioso a `default`
-- si falta `profileId` o es inválido, responden con una selección guiada de perfiles activos
-
-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
-```
-
-Base local y migraciones:
-
-```bash
-docker compose up -d
-pnpm run db:test
-pnpm run db:migrate
-```
-
-Hard delete administrativo de perfil:
-
-```bash
-pnpm run admin:profile-delete -- --profile-id <id> --confirm-delete <id>
-```
-
-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:
+Despues de publicar o instalar el paquete, una configuracion tipica por `npx` usa transporte `stdio`:
 
 ```json
 {
@@ -266,211 +60,28 @@ Uso vía `npx` después de publicar el paquete:
 }
 ```
 
-Puntos importantes para ese modo:
-
-- en configuración por `command`, el transporte correcto es `stdio`, por eso hay que pasar `MCP_TRANSPORT=stdio`
-- si el servidor va a usar persistencia de secretos en DB, además necesita `DATABASE_URL` y `DB_ENCRYPTION_KEY`
-
-Flujo típico de publicación:
-
-```bash
-pnpm version patch
-pnpm publish --access public
-```
+Si no vas a usar una integracion, sus credenciales pueden no ser necesarias para ese flujo. VTEX usa perfiles y conexiones persistidas en Postgres; sus credenciales por cliente no se configuran directo en `.env`.
 
-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
-```
-
-## Scripts operativos de base y perfiles
-
-Estos scripts viven en `scripts/` y usan Postgres como store de perfiles e integraciones VTEX.
-
-### `test-db-connection.ts`
-
-- propósito: probar que `DATABASE_URL` responde
-- muta datos: no
-- requiere Postgres levantado: sí
-- comando:
-
-```bash
-pnpm run db:test
-```
-
-### `run-migrations.ts`
-
-- propósito: aplicar migraciones SQL pendientes desde `db/migrations/`
-- muta datos: sí, cambia estructura de DB
-- requiere Postgres levantado: sí
-- comando:
-
-```bash
-pnpm run db:migrate
-```
-
-### `admin-profile-upsert.ts`
-
-- propósito: crear o actualizar un perfil
-- muta datos: sí
-- requiere Postgres levantado: sí
-- comando:
-
-```bash
-pnpm run admin:profile-upsert -- --profile-id default --name "Default"
-```
-
-### `admin-profile-list.ts`
-
-- propósito: listar perfiles cargados
-- muta datos: no
-- requiere Postgres levantado: sí
-- comando:
-
-```bash
-pnpm run admin:profile-list
-```
-
-### `admin-vtex-upsert.ts`
-
-- propósito: crear o actualizar la conexión VTEX de un perfil y validarla
-- muta datos: sí
-- requiere Postgres levantado: sí
-- comando:
-
-```bash
-pnpm run admin:vtex-upsert -- \
-  --profile-id default \
-  --account-name miaccount \
-  --api-key xxx \
-  --api-token yyy
-```
+## Variables principales
 
-### `admin-vtex-validate.ts`
+El servidor lee infraestructura y secretos desde variables de entorno:
 
-- propósito: revalidar una conexión VTEX ya guardada
-- muta datos: sí, actualiza estado y timestamps
-- requiere Postgres levantado: sí
-- comando:
-
-```bash
-pnpm run admin:vtex-validate -- --profile-id default
-```
-
-### `admin-vtex-list.ts`
-
-- propósito: listar conexiones VTEX registradas
-- muta datos: no
-- requiere Postgres levantado: sí
-- comando:
-
-```bash
-pnpm run admin:vtex-list
-```
-
-## Estructura del repositorio
-
-Resumen de las rutas más importantes:
-
-```text
-bi-mcp/
-├── AGENTS.md
-├── README.md
-├── db/
-├── docs/
-├── index.ts
-├── scripts/
-├── src/
-│   ├── db/
-│   ├── config/
-│   ├── services/
-│   │   ├── analytics/
-│   │   ├── google-ads/
-│   │   ├── search-console/
-│   │   └── vtex/
-│   ├── tools/
-│   │   ├── config/
-│   │   ├── 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.
-
-- [db/AGENTS.md](/home/yoryo/apps/bi-mcp/db/AGENTS.md)
-  Reglas de la capa de persistencia y de las migraciones SQL.
-
-## 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:
+- `MCP_TRANSPORT`, `PORT`, `MCP_URL`
+- `DATABASE_URL`, `DB_ENCRYPTION_KEY`
+- `GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET`, `GOOGLE_OAUTH_REFRESH_TOKEN`
+- `GA4_PROPERTY_ID`
+- `GOOGLE_ADS_DEVELOPER_TOKEN`, `GOOGLE_ADS_LOGIN_CUSTOMER_ID`
+- `META_APP_ID`, `META_APP_SECRET`, `META_ACCESS_TOKEN`, `META_API_VERSION`
 
-1. `Finance`
-   CM1, CM2, CM3, CCC, LTV/CAC y lógica financiera basada en benchmarks locales.
+La configuracion de negocio no deberia vivir en `.env`.
 
-2. `Diagnostics`
-   Kill Switch, score de escalabilidad y outputs ejecutivos.
+## Documentacion util
 
-3. `Evolución del perfil de negocio`
-   Diseño single-profile hoy, pero multi-profile ready en estructura.
+- [Capacidades del MCP](/home/yoryo/apps/bi-mcp/docs/CAPACIDADES_MCP.md): que puede responder cada modulo.
+- [Fuentes de datos](/home/yoryo/apps/bi-mcp/docs/FUENTES_DE_DATOS.md): de donde salen los datos y que limitaciones tienen.
+- [Glosario financiero](/home/yoryo/apps/bi-mcp/docs/GLOSARIO_FINANCIERO.md): terminos de negocio y finanzas usados por el sistema.
+- [Estado del proyecto](/home/yoryo/apps/bi-mcp/docs/PROJECT_STATUS.md): modulos implementados, pendientes y roadmap.
+- [Guia para agentes](/home/yoryo/apps/bi-mcp/AGENTS.md): reglas para modificar el repo.
 
 ## Licencia