# @lcapps/mcp-crm

[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

Conecta tu CRM de LCApps con Claude y otros asistentes de IA.

## Cuál de las dos formas necesitas

Hay dos maneras de conectar, y la mayoría de la gente quiere la primera.

| | Conector | Este paquete |
|---|---|---|
| Qué haces | pegar una dirección | instalar y editar un fichero |
| Hace falta saber | nada | manejar la configuración del cliente |
| Consultar y crear datos | sí | sí |
| Los PDF se guardan en tu ordenador | no | sí |

**Empieza por el conector.** Si más adelante necesitas que las facturas y presupuestos se guarden como fichero, vuelve aquí.

## Conectar sin instalar nada

Necesitas la dirección de tu CRM. Es la de siempre, cambiando el principio por `mcp`:

| Si entras en | Tu dirección es |
|---|---|
| `app.lcrm.es` | `https://mcp.lcrm.es/mcp` |
| `app.audyum.com` | `https://mcp.audyum.com/mcp` |
| `app.anturcrm.com` | `https://mcp.anturcrm.com/mcp` |
| `app.agenvis.com` | `https://mcp.agenvis.com/mcp` |
| `app.skyplannerhub.com` | `https://mcp.skyplannerhub.com/mcp` |

Los pasos:

1. Abre Claude y entra en sus **ajustes**.
2. Busca el apartado de **conectores** y elige añadir uno personalizado.
3. Pega la dirección de la tabla y guarda.
4. Claude abrirá tu CRM en el navegador para que **inicies sesión y autorices**. Es tu sesión de siempre, con tu usuario.
5. Revisa lo que te pide y acepta.

Ya está. Pregúntale por tus clientes, tus facturas o tus gastos.

### Si algo no va

| Lo que ves | Qué pasa |
|---|---|
| «no tengo acceso a nada» | A tu organización le falta activar el módulo del agente. Habla con tu administrador. |
| No aparecen clientes, o facturas, o tareas | Esa parte del CRM no está contratada o activada para tu organización. |
| Deja de responder tras un rato parado | La conexión caduca a los 30 minutos. Vuelve a preguntar y se reabre sola. |
| Te pide autorizar otra vez | Normal si ha pasado tiempo. Autoriza de nuevo. |

Verás solo lo que tu usuario puede ver en el CRM. Conectar no da permisos nuevos.

## Guardar los documentos en tu ordenador

Para esto sí hace falta este paquete. Un conector normal no puede escribir en tu disco, así que un PDF llega dentro de la respuesta y se queda ahí.

Este programa se ejecuta en tu ordenador, reenvía la conversación al servidor y guarda los ficheros que lleguen, dejándole a Claude la ruta donde quedaron.

Necesitas [Node.js](https://nodejs.org) instalado. Después, en la configuración de tu cliente:

```json
{
  "mcpServers": {
    "lcrm-int": {
      "command": "npx",
      "args": ["-y", "@lcapps/mcp-crm"],
      "env": { "LCRM_MCP_URL": "https://mcp-int.lcrm.es/mcp" }
    },
    "lcrm-test": {
      "command": "npx",
      "args": ["-y", "@lcapps/mcp-crm"],
      "env": { "LCRM_MCP_URL": "https://mcp-test.lcrm.es/mcp" }
    },
    "lcrm": {
      "command": "npx",
      "args": ["-y", "@lcapps/mcp-crm"],
      "env": { "LCRM_MCP_URL": "https://mcp.lcrm.es/mcp" }
    }
  }
}
```

Las tres entradas pueden estar activas a la vez. Las credenciales se guardan por servidor, así que autorizar una no cierra la sesión de las otras.

Dónde está el fichero de configuración:

- Claude Desktop en macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Claude Desktop en Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Cursor: en sus ajustes de MCP

`--url https://…/mcp` sirve como alternativa a la variable de entorno.

## Autorización

La primera vez se abre el navegador para que autorices el acceso. El paquete se registra como cliente OAuth, espera la respuesta en `http://localhost:33420/callback` y guarda las credenciales en `~/.lcrm/credentials/<servidor>.json` con permisos `0600`. Después reutiliza el token de refresco, así que el navegador solo aparece una vez por servidor.

También puedes lanzarlo a mano:

```bash
LCRM_MCP_URL=https://mcp.lcrm.es/mcp npx -y @lcapps/mcp-crm login
LCRM_MCP_URL=https://mcp.lcrm.es/mcp npx -y @lcapps/mcp-crm logout
```

## Dónde acaban los ficheros

Los documentos que devuelve el CRM se guardan en `~/Downloads/lcrm-mcp/` y el asistente recibe la ruta. El nombre viene del propio CRM —`budget_26_010.pdf` y similares— reducido a un único segmento seguro: el servidor no decide dónde se escribe. Nunca se sobrescribe un fichero existente; se añade un sufijo `-1`, `-2`.

## Variables de entorno

| Variable | Obligatoria | Por defecto | Para qué |
|---|---|---|---|
| `LCRM_MCP_URL` | sí | — | Dirección del servidor, p. ej. `https://mcp.lcrm.es/mcp` |
| `LCRM_MCP_DOWNLOAD_DIR` | no | `~/Downloads/lcrm-mcp` | Dónde se guardan los documentos |
| `LCRM_MCP_CALLBACK_PORT` | no | `33420` | Puerto local para la respuesta de autorización |

Cambiar el puerto cambia la dirección de retorno, así que habrá que autorizar de nuevo.

## Desarrollo

```bash
npm install
npm run typecheck
npm test
npm run build
```

## Licencia

MIT — ver [LICENSE](LICENSE).