# perfex-crm-mcp

Servidor **MCP (Model Context Protocol)** que conecta **cualquier IA** con tu **Perfex CRM** — sin API keys, usando los endpoints públicos de Perfex (`/forms/wtl`, `/forms/ticket`, `/forms/quote`).

## 🧠 ¿Qué inteligencias conecta?

| IA | Cómo se conecta |
|---|---|
| **Claude** (Desktop / Claude Code) | `claude mcp add` |
| **Codex** (OpenAI CLI) | `codex mcp add` |
| **Hermes Agent** (Nous Research) | configuración MCP del agente |
| **Paperclip** | adapter MCP / claude_local con MCP config |

Todas usan el mismo protocolo estándar MCP → una sola integración, cuatro inteligencias.

## 🔧 Herramientas expuestas

### Sin API key (endpoints públicos)
| Herramienta | Qué hace | Endpoint Perfex |
|---|---|---|
| `create_lead` | Crea un lead (cliente potencial) | `POST /forms/wtl/{key}` |
| `create_ticket` | Crea un ticket de soporte | `POST /forms/ticket` |
| `request_quote` | Solicita un presupuesto | `POST /forms/quote/{key}` |
| `perfex_health` | Comprueba que el CRM responde | `GET /` |

### Con API REST completa (PERFEX_API_KEY o PERFEX_MCP_TOKEN)
| Herramienta | Qué hace |
|---|---|
| `list_leads` | Lista leads (filtro por nombre/email/empresa) |
| `create_lead_api` | Crea lead con todos los campos (estado, responsable, fuente...) |
| `list_clients` | Lista clientes |
| `create_client` | Crea cliente + contacto primario |
| `list_invoices` | Lista facturas (filtro por estado) |
| `list_payments` | Lista pagos |
| `list_projects` | Lista proyectos |
| `list_tasks` | Lista tareas |
| `create_task` | Crea tarea (en proyecto opcional) |
| `crm_stats` | Estadísticas: leads, clientes, facturas, pagos, proyectos, tareas |

## 📦 Instalación

```bash
git clone https://github.com/yunyminaya/perfex-crm-mcp.git
cd perfex-crm-mcp
npm install
npm run build
```

## ⚙️ Configuración (env vars)

| Variable | Obligatoria | Descripción |
|---|---|---|
| `PERFEX_URL` | ✅ | Base del CRM, ej: `https://crm.example.com` |
| `PERFEX_FORM_KEY` | para leads | Key del formulario web-to-lead (`forms/wtl/{key}`) |
| `PERFEX_QUOTE_KEY` | para quotes | Key del formulario de presupuestos |
| `PERFEX_API_KEY` | para API completa | API key del **módulo REST oficial** (CodeCanyon #25278359) |
| `PERFEX_MCP_TOKEN` | para API completa | Token del **Mcp_api.php casero** (perfex-module/, gratis) |
| `PERFEX_LEAD_SOURCE` | no | Fuente por defecto de leads (default `MCP`) |
| `PERFEX_TICKET_DEPARTMENT` | no | Departamento por defecto para tickets |
| `PERFEX_TICKET_PRIORITY` | no | Prioridad por defecto para tickets |
| `PERFEX_TIMEOUT_MS` | no | Timeout (default 15000) |

**Dos formas de activar la API REST completa** (elige una):
1. **Módulo oficial de CodeCanyon** (`REST API for Perfex CRM`, #25278359) → genera API key en Perfex admin → API → define `PERFEX_API_KEY`. Da las 181 operaciones del módulo.
2. **Mcp_api.php incluido** (gratis) → copia `perfex-module/Mcp_api.php` a `application/controllers/`, define `MCP_API_TOKEN` en `app-config.php`, y usa `PERFEX_MCP_TOKEN`. Cubre leads, clientes, facturas, pagos, proyectos, tareas y stats.

**Cómo conseguir PERFEX_FORM_KEY:** Perfex admin → **Leads → Web Forms** → crear formulario → copiar la key (último segmento de la URL `forms/wtl/{key}`).

## 🔌 Conectar cada IA

### Claude Desktop
```json
// claude_desktop_config.json
{
  "mcpServers": {
    "perfex-crm": {
      "command": "node",
      "args": ["/ruta/a/perfex-crm-mcp/dist/index.js"],
      "env": {
        "PERFEX_URL": "https://crm.example.com",
        "PERFEX_FORM_KEY": "tu-key"
      }
    }
  }
}
```

### Claude Code (CLI)
```bash
claude mcp add perfex-crm -- node /ruta/a/perfex-crm-mcp/dist/index.js
# o con env:
claude mcp add perfex-crm --env PERFEX_URL=https://crm.example.com --env PERFEX_FORM_KEY=tu-key -- node /ruta/a/perfex-crm-mcp/dist/index.js
```

### Codex (OpenAI CLI)
```bash
codex mcp add perfex-crm -- node /ruta/a/perfex-crm-mcp/dist/index.js
```

### Hermes Agent
Añade el servidor en la config MCP de Hermes (`~/.hermes/config.yaml` o el gestor de MCP del agente):
```yaml
mcp:
  servers:
    perfex-crm:
      command: node
      args: ["/ruta/a/perfex-crm-mcp/dist/index.js"]
      env:
        PERFEX_URL: "https://crm.example.com"
        PERFEX_FORM_KEY: "tu-key"
```

### Paperclip
Configura el servidor MCP en el adapter del agente (adapterConfig → mcpServers), igual que Claude Code — los agentes Paperclip que usan `claude_local` heredan los MCP configurados.

## 🚀 Uso

Tras conectar, cualquiera de las IAs puede hacer:

```
"Crear un lead en el CRM: Juan Pérez, juan@empresa.com, tel 555-1234, interesado en facturación"
→ create_lead { name: "Juan Pérez", email: "juan@empresa.com", ... }

"Crear un ticket: María no recibe los emails de factura"
→ create_ticket { name: "María", email: "...", subject: "...", message: "..." }

"¿El CRM está accesible?"
→ perfex_health
```

## ⚠️ Notas

- **Sin API keys**: usa los endpoints públicos de Perfex (Web-to-Lead / tickets). Si el formulario tiene **reCAPTCHA activado**, las IAs no podrán crearlo — desactívalo en el formulario.
- **Content-Type**: los endpoints exigen `application/x-www-form-urlencoded` (no JSON).
- **Tickets**: exigen header `X-Requested-With: XMLHttpRequest` (ya lo envía el servidor).
- **422 = campos requeridos faltantes**: revisa qué campos marca el formulario como obligatorios.

## 📁 Estructura

```
perfex-crm-mcp/
├── src/
│   ├── index.ts          # Servidor MCP (herramientas)
│   └── perfex-client.ts  # Cliente de endpoints públicos de Perfex
├── package.json
├── tsconfig.json
└── README.md
```