ProfitPilot MCP Server

Multi-Agent Business Intelligence Architecture - Servidor MCP para inteligencia de negocio especializada en E-commerce que combina el framework QUORUM con agentes especializados en decisiones de negocio.

🌟 Características

ProfitPilot es un sistema de inteligencia de negocio multi-agente diseñado específicamente para E-commerce, que combina el framework QUORUM con agentes especializados en decisiones de negocio.

Los 9 Agentes de ProfitPilot

Agente	Rol Principal	Responsabilidades Clave
Data Intelligence Agent	Analista de Datos	Detecta anomalías, patrones de tráfico, métricas de conversión
Revenue & Margin Agent	Analista de Ingresos	Calcula LTV real, CLV, márgenes por canal, cohort analysis
Financial Modeling Agent	CFO Virtual	Cash flow, working capital, payback period, ROI
Competitor Intelligence Agent	Inteligencia Competitiva	Monitorea precios, promociones, tendencias del mercado
Customer Insight Agent	Analista de Cliente	Churn prediction, NPS, comportamiento de compra
Operations & Inventory Agent	Gestor de Operaciones	Forecasting, stock levels, dead stock, lead times
Scenario & Risk Engine	Gestor de Riesgos	Simulación de escenarios, sensibilidad de margen
Execution Agent	Ejecutor Automático	Ajusta bids, reordena inventario, pausa campañas
Global Constraint Strategist	Estratega Global	Identifica cuellos de botella, prioriza decisiones

Roles de Negocio Soportados

Rol	Preguntas Clave
CEO / Founder	¿Cuánto estamos dejando de ganar por fallas en el checkout? ¿Vale la pena abrir un nuevo canal o doblar el actual?
CMO / Director de Marketing	¿Qué canal me da mejor LTV real? ¿Cómo justifico este presupuesto de ads ante el CFO?
Director de Ecommerce	¿Por qué sube el tráfico pero no las conversiones? ¿Qué productos tengo que descontinuar?
Operations / Supply Chain	¿Cuándo necesito reordenar para no quedarme sin stock? ¿Cuál proveedor me está afectando más el margen con demoras?
Growth / Performance Marketer	¿Cuánto puedo pagar por un cliente antes de perder margen? ¿Qué campaña está quemando presupuesto?
CFO / Finanzas	¿Cuál es el cash flow proyectado si escalo ads? ¿Cómo impacta el inventario en capital de trabajo?

🧠 Deep Reasoning (Auto-Reflexión)

ProfitPilot incluye un sistema de Deep Reasoning inspirado en modelos avanzados como OpenAI o1/o3, GPT-5.2 Pro y Gemini 3 Deep Think. Este sistema permite al agente realizar un proceso de auto-reflexión en bucle, haciéndose preguntas a sí mismo hasta llegar a una conclusión sólida.

Cómo Funciona

Problema → Pensamiento Inicial → ¿Suficiente Info?
                                    ↓
                         No → Generar Pregunta → Responder → Repetir
                                    ↓
                         Sí → Respuesta Final → Verificar

El sistema:

1. Genera pensamientos iterativos sobre el problema
2. Se hace preguntas para identificar información faltante
3. Evalúa el progreso (suficiente, progresando, estancado)
4. Cambia de enfoque automáticamente cuando está estancado
5. Aplica auto-crítica para evaluar la calidad de cada pensamiento
6. Sintetiza todo el proceso en una respuesta final

Configuración

En config.json:

{
  "quorum": {
    "deepReasoning": {
      "maxIterations": 5,
      "minConfidence": 0.7,
      "enableSelfCritique": true,
      "enableApproachChange": true,
      "verbose": false
    }
  }
}

Parámetro	Descripción	Default
maxIterations	Máximo de iteraciones de pensamiento	5
minConfidence	Confianza mínima para detener (0-1)	0.7
enableSelfCritique	Habilitar auto-crítica de calidad	true
enableApproachChange	Habilitar cambio de enfoque automático	true
verbose	Mostrar progreso detallado en consola	false

Uso

El Deep Reasoning se activa automáticamente para problemas de complejidad estratégica cuando se habilita en las opciones:

await framework.pipeline(problem, {
  enableDeepReasoning: true,
  deepReasoningConfig: {
    maxIterations: 7,
    minConfidence: 0.8
  }
});

Resultado

El resultado incluye:

• finalAnswer: Respuesta final generada
• thoughtProcess: Array con todas las iteraciones de pensamiento
• iterations: Número de iteraciones realizadas
• finalConfidence: Confianza final alcanzada
• approachChanges: Número de cambios de enfoque
• summary: Resumen con insights clave, información faltante y enfoque utilizado

🎛️ Los 4 Modos de Razonamiento

ProfitPilot ofrece 4 modos de razonamiento diferentes, cada uno optimizado para diferentes casos de uso:

Modo	Descripción	Ventajas	Desventajas	Casos de Uso
Retry	Reintenta hasta verificación aprobada, con Deep Reasoning opcional	Simple, bajo costo, respuestas consistentes	No aprende entre intentos	Problemas operacionales y tácticos
Programático	Lógica basada en reglas, keywords y heurísticas sin LLM	Rápido, sin costo, sin dependencia externa	Limitado a patrones conocidos	Preguntas simples, cálculos básicos
Híbrido	Combina programático con LLM según confianza	Balance óptimo costo/calidad, adaptable	Más complejo de configurar	Problemas mixtos (parte simple, parte complejo)
Embebido	Modelos LLM que corren en el proceso Node.js	Privacidad total, sin API externa	Requiere hardware potente, modelos más pequeños	Aplicaciones on-premise, datos sensibles

Configuración

En config.json:

{
  "quorum": {
    "reasoningModes": {
      "defaultMode": "retry",
      "retryConfig": {
        "maxRetries": 3,
        "enableDeepReasoning": true
      },
      "programmaticConfig": {
        "enableKeywordAnalysis": true,
        "enablePatternMatching": true,
        "enableHeuristicRules": true
      },
      "hybridConfig": {
        "llmThreshold": 0.7,
        "programmaticFirst": true
      },
      "embeddedConfig": {
        "modelType": "transformersjs",
        "useWebGPU": false
      }
    }
  }
}

Uso

// Usar modo específico
const result = await framework.reasonWithMode(problem, 'programmatic');

// Usar modo híbrido con configuración personalizada
const hybridResult = await framework.reasonWithMode(problem, 'hybrid', {
  hybridConfig: {
    llmThreshold: 0.8,
    programmaticFirst: true
  }
});

🧩 Arquitectura Chain of Thought (Nuevo)

ProfitPilot ahora soporta dos arquitecturas diferentes:

1. Modo HTTP (Original)

flowchart LR
    A[Claude Desktop<br/>Modelo: Claude] -->|MCP Protocol| B[profitpilot-mcp-server]
    B -->|HTTP Request| C[LM Studio/Ollama<br/>Modelo Externo]
    
    style A fill:#ffd43b
    style C fill:#74c0fc
    style B fill:#a5d8ff

• Requiere: Un LLM externo (LM Studio, Ollama, OpenAI, etc.)
• Ventajas: Control total del modelo, puede usar cualquier modelo local
• Desventajas: Requiere configuración adicional, dependencia de servicio externo

2. Modo Chain of Thought (Nuevo) ⭐

flowchart LR
    A[Cliente MCP<br/>Claude/Cursor/etc] -->|1. Llamada herramienta| B[profitpilot-mcp-server]
    B -->|2. Prompt de razonamiento| A
    A -->|3. Respuesta pensada| B
    B -->|4. Prompt siguiente paso| A
    A -->|5. Respuesta| B
    B -->|6. Resultado final| A
    
    style A fill:#ffd43b
    style B fill:#a5d8ff

• Requiere: Solo el cliente MCP (Claude Desktop, Cursor, etc.)
• Ventajas:
  • ✅ No requiere LLM externo
  • ✅ Usa el modelo del cliente (Claude, GPT-4, etc.)
  • ✅ Compatible con cualquier cliente MCP
  • ✅ Configuración más simple
  • ✅ Menor latencia (sin HTTP)
• Desventajas: Depende del modelo del cliente

Herramientas del Modo Chain of Thought

Herramienta	Descripción
profitpilot_analyze	Inicia una sesión de razonamiento con el problema
profitpilot_continue	Continúa con la respuesta del cliente
profitpilot_status	Obtiene el estado actual de la sesión
profitpilot_reset	Reinicia una sesión

Flujo de Uso (Chain of Thought)

1. Cliente llama a profitpilot_analyze con el problema
2. Servidor genera un prompt estructurado (ej: clasificación de complejidad)
3. Cliente ejecuta el prompt con su propio modelo
4. Cliente llama a profitpilot_continue con la respuesta
5. Servidor procesa y genera el siguiente prompt
6. Se repite hasta completar el análisis (descomposición, agentes, verificación, síntesis)

Configuración

En config.json:

{
  "mode": "chain-of-thought",
  "modeDescription": "Chain of Thought: Usa el modelo del cliente MCP | http: Usa un LLM externo vía HTTP"
}

Configuración de Claude Desktop

Para usar el modo Chain of Thought, agrega esto a tu configuración:

{
  "mcpServers": {
    "profitpilot-cot": {
      "command": "node",
      "args": ["/ruta/a/profitpilot-mcp-server/dist/index-cot.js"],
      "description": "Modo Chain of Thought: Usa el modelo de Claude Desktop"
    }
  }
}

Para usar el modo HTTP original:

{
  "mcpServers": {
    "profitpilot": {
      "command": "node",
      "args": ["/ruta/a/profitpilot-mcp-server/dist/index.js"],
      "description": "Modo HTTP: Requiere LM Studio u otro LLM externo"
    }
  }
}

📋 Requisitos

• Node.js >= 18.0.0
• Modo HTTP: Un servidor LLM compatible con OpenAI API (ver opciones abajo)
• Modo Chain of Thought: Solo un cliente MCP (Claude Desktop, Cursor, etc.)

Proveedores de LLM Soportados

El servidor MCP es neutro y compatible con cualquier API que siga el estándar OpenAI:

Proveedor	URL Base	Notas
LM Studio	http://localhost:1234	Modelos locales
Ollama	http://localhost:11434	Modelos locales
OpenAI	https://api.openai.com/v1	Requiere API key
vLLM	http://localhost:8000	Modelos locales
Text Generation WebUI	http://localhost:5000	Modelos locales
Cualquier servidor compatible con OpenAI API	-	-

🚀 Instalación

1. Instalar dependencias

cd profitpilot-mcp-server
npm install

2. Compilar el proyecto

npm run build

3. Configurar el servidor LLM

Elige tu proveedor y configúralo en config.json:

Opción A: LM Studio (Modelos Locales)

1. Abre LM Studio
2. Carga un modelo (ej. Qwen2.5 32B, Llama 3.3 70B)
3. Habilita el servidor API en http://localhost:1234
4. Verifica que el endpoint /v1/models esté disponible

Opción B: Ollama (Modelos Locales)

1. Instala Ollama: https://ollama.ai
2. Ejecuta: ollama pull llama3 (o tu modelo preferido)
3. Asegúrate que el servidor esté corriendo en http://localhost:11434

Opción C: OpenAI (Cloud)

1. Obtén una API key de OpenAI
2. Configura la URL base y API key en config.json

4. Configurar el servidor MCP

Edita config.json según tu proveedor:

{
  "llm": {
    "baseUrl": "http://localhost:1234",
    "defaultModel": "qwen2.5:32b",
    "timeout": 60000,
    "maxRetries": 3,
    "apiKey": ""
  },
  "quorum": {
    "effortRouter": {
      "tactical": { "maxRetries": 1, "agents": ["data-intelligence", "operations"], "subtasks": 1 },
      "operational": { "maxRetries": 2, "agents": ["data-intelligence", "revenue", "customer"], "subtasks": 2 },
      "strategic": { "maxRetries": 3, "agents": ["financial", "scenario", "global-constraint"], "subtasks": 3 }
    }
  }
}

Nota: El campo lmStudio se mantiene por compatibilidad hacia atrás, pero se recomienda usar llm.

🔧 Uso con Claude Desktop

Agrega el servidor a tu configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "profitpilot": {
      "command": "node",
      "args": ["/Users/home/Downloads/Copia de agente-heavy/profitpilot-mcp-server/dist/index.js"]
    }
  }
}

Windows: %APPDATA%\\Claude\\claude_desktop_config.json

{
  "mcpServers": {
    "profitpilot": {
      "command": "node",
      "args": ["C:\\Users\\tu-usuario\\Downloads\\Copia de agente-heavy\\profitpilot-mcp-server\\dist\\index.js"]
    }
  }
}

🛠️ Herramientas MCP Disponibles

profitpilot_analyze

Ejecuta el pipeline completo de ProfitPilot para resolver problemas de negocio de ecommerce usando multi-agent reasoning.

Parámetros:

• problem (string, requerido): El problema o pregunta de negocio a resolver
• role (string, opcional): Rol de negocio (ceo, cmo, ecommerce, operations, growth, cfo)
• verbose (boolean, opcional): Mostrar progreso detallado del pipeline
• model (string, opcional): Modelo específico a usar
• temperature (number, opcional): Temperatura para generación (0-1)
• enableDeepReasoning (boolean, opcional): Habilitar Deep Reasoning para problemas estratégicos
• reasoningMode (string, opcional): Modo de razonamiento (retry, programmatic, hybrid, embedded)

Ejemplo:

¿Debería doblar el presupuesto de ads en Meta o expandir a TikTok?

profitpilot_revenue

Analiza revenue y márgenes del ecommerce.

Parámetros:

• timeframe (string, requerido): Período de tiempo a analizar
• channels (array, opcional): Canales específicos a analizar

Ejemplo:

Analiza revenue y márgenes para los últimos 30 días en Meta Ads y Google Ads

profitpilot_forecast

Genera forecast de ventas e inventario.

Parámetros:

• horizon (number, requerido): Horizonte de forecast en días
• products (array, opcional): Productos específicos a forecast
• confidence (number, opcional): Nivel de confianza deseado (0-1)

Ejemplo:

Genera forecast de ventas para los próximos 90 días

profitpilot_scenario

Simula escenarios de negocio para evaluar riesgos y oportunidades.

Parámetros:

• scenarioType (string, requerido): Tipo de escenario (cpa_change, price_change, stock_delay, competitor_action, custom)
• parameters (object, requerido): Parámetros del escenario

Ejemplo:

Simula qué pasa si Meta sube el CPA 20%

profitpilot_optimize

Genera acciones de optimización para el ecommerce.

Parámetros:

• target (string, requerido): Objetivo de optimización
• constraints (object, opcional): Restricciones para la optimización
• autoExecute (boolean, opcional): Ejecutar acciones automáticamente

Ejemplo:

Optimiza para maximizar ROAS con un presupuesto de $10,000

profitpilot_risk

Evalúa riesgos de decisiones de negocio.

Parámetros:

• decision (string, requerido): Decisión a evaluar
• factors (array, opcional): Factores a considerar

Ejemplo:

Evalúa los riesgos de expandir a TikTok

profitpilot_competitor

Analiza competidores y mercado.

Parámetros:

• competitors (array, requerido): Lista de competidores a analizar
• metrics (array, opcional): Métricas específicas a analizar

Ejemplo:

Analiza precios y estrategias de Competidor A y Competidor B

profitpilot_customer

Analiza segmentos de clientes y comportamiento.

Parámetros:

• segment (string, opcional): Segmento específico a analizar
• metrics (array, opcional): Métricas específicas a analizar

Ejemplo:

Analiza segmentos de clientes y riesgo de churn

profitpilot_constraints

Analiza cuellos de botella globales usando Teoría de Restricciones.

Parámetros: Ninguno

Ejemplo:

Identifica el cuello de botella que frena el crecimiento

📊 Arquitectura del Sistema

INPUT → [Effort Router] → [Decomposer] → [Agent Pool] → [Synthesis] → [Verification] → OUTPUT
         TÁCTICA/          Subtareas      9 Agentes       Consenso         Puntaje 1-10
         OPERACIONAL/                       Especializados
         ESTRATÉGICA

Pipeline QUORUM

1. Effort Router: Clasifica la complejidad del problema (táctica/operativa/estratégica)
2. Decomposer: Descompone el problema en sub-tareas independientes
3. Agent Pool: Ejecuta múltiples agentes especializados en paralelo
4. Synthesis Engine: Sintetiza las respuestas con balanced prompting
5. Verification Pass: Verifica la calidad antes de responder (puntaje 1-10)
6. Retry Loop: Reintenta si la verificación falla

💡 Diferenciadores Clave de ProfitPilot

1. CFO Agent: Único sistema que modela cash flow y working capital, no solo métricas de marketing
2. Global Constraint Engine: Identifica cuellos de botella cross-departamento usando teoría de restricciones
3. Scenario & Risk Engine: Simulación de escenarios con sensibilidad de margen
4. Execution Agent: Capacidad de ejecución automática (opcional) para acciones tácticas
5. Role-Based Routing: Respuestas adaptadas al rol del usuario (CEO, CMO, CFO, etc.)

📚 Documentación

• types.ts - Tipos principales del sistema
• lmstudio-client.ts - Cliente para LM Studio API
• quorum-framework.ts - Framework QUORUM base
• profitpilot-framework.ts - Framework ProfitPilot específico
• agents/ - Agentes especializados
• index.ts - Entry point del servidor MCP

🤝 Contribuciones

Este proyecto está en desarrollo activo. Las contribuciones son bienvenidas.

📄 Licencia

MIT License - Ver archivo LICENSE para más detalles.

---

ProfitPilot MCP Server © 2026 - Multi-Agent Business Intelligence Architecture for E-commerce