@yoryoboy/bi-mcp 1.0.5 → 1.2.0

package/README.md

@@ -4,7 +4,7 @@ MCP monolítico de business intelligence para ecommerce en Argentina, construido
 
 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.
+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.
 
 ## Índice
 
@@ -25,8 +25,11 @@ Hoy el servidor integra VTEX, Google Analytics 4, Search Console, Google Ads y b
 
 El MCP ya tiene capacidades activas para estas áreas:
 
+- `Config / Infra`
+  Verificación de salud de la base del MCP y listado de perfiles disponibles.
+
 - `VTEX`
-  Operación comercial, pedidos, stock, inventario por depósito, precios y ofertas.
+  Operación comercial, pedidos, stock, inventario por depósito, precios y ofertas, exigiendo selección explícita del `profileId` correcto.
 
 - `Analytics (GA4)`
   Tráfico, revenue medido en GA4, mix de canales, engagement y salud de medición.
@@ -37,6 +40,9 @@ El MCP ya tiene capacidades activas para estas áreas:
 - `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.
 
@@ -52,14 +58,17 @@ Estado real del repo al día de hoy:
 - `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
@@ -140,6 +149,7 @@ 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
 
@@ -147,18 +157,29 @@ 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`
+- `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:
 
@@ -185,6 +206,20 @@ Desarrollo:
 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
@@ -213,15 +248,18 @@ Uso vía `npx` después de publicar el paquete:
       "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"
+        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "your_google_ads_login_customer_id",
+        "META_APP_ID": "your_meta_app_id",
+        "META_APP_SECRET": "your_meta_app_secret",
+        "META_ACCESS_TOKEN": "your_meta_access_token",
+        "META_API_VERSION": "v25.0",
+        "DATABASE_URL": "your_postgres_connection_string",
+        "DB_ENCRYPTION_KEY": "your_64_hex_char_encryption_key"
       }
     }
   }
@@ -231,6 +269,7 @@ 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:
 
@@ -245,6 +284,91 @@ En desarrollo, `mcp-use` expone el inspector para probar el servidor localmente.
 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
+```
+
+### `admin-vtex-validate.ts`
+
+- 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:
@@ -253,9 +377,12 @@ Resumen de las rutas más importantes:
 bi-mcp/
 ├── AGENTS.md
 ├── README.md
+├── db/
 ├── docs/
 ├── index.ts
+├── scripts/
 ├── src/
+│   ├── db/
 │   ├── config/
 │   ├── services/
 │   │   ├── analytics/
@@ -263,6 +390,7 @@ bi-mcp/
 │   │   ├── search-console/
 │   │   └── vtex/
 │   ├── tools/
+│   │   ├── config/
 │   │   ├── analytics/
 │   │   ├── google-ads/
 │   │   ├── search-console/
@@ -284,6 +412,9 @@ Puntos de entrada y referencia:
 - [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).