# 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`](config.json):

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

```typescript
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`](config.json):

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

```typescript
// 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)

```mermaid
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) ⭐

```mermaid
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`](config.json):

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

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

```json
{
  "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

```bash
cd profitpilot-mcp-server
npm install
```

### 2. Compilar el proyecto

```bash
npm run build
```

### 3. Configurar el servidor LLM

Elige tu proveedor y configúralo en [`config.json`](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`](config.json) según tu proveedor:

```json
{
  "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`

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

```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`](src/types.ts) - Tipos principales del sistema
- [`lmstudio-client.ts`](src/lmstudio-client.ts) - Cliente para LM Studio API
- [`quorum-framework.ts`](src/quorum-framework.ts) - Framework QUORUM base
- [`profitpilot-framework.ts`](src/profitpilot-framework.ts) - Framework ProfitPilot específico
- [`agents/`](src/agents/) - Agentes especializados
- [`index.ts`](src/index.ts) - Entry point del servidor MCP

## 🤝 Contribuciones

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

## 📄 Licencia

MIT License - Ver archivo [LICENSE](LICENSE) para más detalles.

---

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