bi-mcp

MCP monolítico de business intelligence para ecommerce en Argentina, construido con mcp-use.

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
• Estado actual
• Arquitectura del proyecto
• Principios no negociables
• Requisitos
• Configuración
• Instalación y ejecución
• Estructura del repositorio
• Flujo de trabajo para desarrollo
• Documentación clave
• Estado del roadmap
• 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.

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.

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

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:

pnpm install

Desarrollo:

pnpm run dev

Build:

pnpm run build

Ejecución del build:

pnpm run start

Deploy:

pnpm run deploy

Uso vía npx después de publicar el paquete:

{
  "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:

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:

http://localhost:3000/inspector

Estructura del repositorio

Resumen de las rutas más importantes:

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 Registro del servidor, tools y prompts.

• src/tools/index.ts Barrel raíz de tools por módulo.

• 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.

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 Guía maestra del proyecto, arquitectura, reglas y roadmap.

• docs/CAPACIDADES_MCP.md Documento orientado a usuario sobre qué cubre el MCP.

• docs/Ecommerce Growth & Profit OS – Argentina Edition (V3.md Fuente de verdad para fórmulas financieras, benchmarks y outputs esperados.

• docs/vtex-key-endpoints.md Endpoints VTEX y contratos de referencia.

• docs/logica-procesamiento-mcp-vtex.md Criterios de transformación de respuestas VTEX.

• 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.