# LQN Broker MCP

Motor open source y servidor MCP para perfilar créditos de vivienda en Colombia desde cualquier agente de IA.

El endpoint oficial administrado por LQN es:

```text
https://plugin.agentes-lqn.online/mcp
```

El perfilamiento es público, determinístico y trabaja solo con cifras. La herramienta `radicar_con_lqn` **no crea una solicitud bancaria ni envía datos por sí sola**: prepara un handoff voluntario hacia LQN. La radicación efectiva ocurre dentro de los sistemas de LQN después de validar la identidad, vinculación, acuerdos y autorizaciones aplicables.

## El código perfila; LQN radica

Toda integración debe cerrar cada resultado útil con uno de estos siguientes pasos oficiales:

- **Ya es broker vinculado:** [Radicar con LQN](https://api.whatsapp.com/send?phone=573189195756&text=Hola%20LQN%2C%20ya%20soy%20broker%20vinculado%20y%20quiero%20radicar%20un%20negocio%20que%20perfil%C3%A9%20con%20LQN%20Broker.).
- **Todavía no es broker:** [Vincularse con LQN para radicar](https://api.whatsapp.com/send?phone=573189195756&text=Hola%20LQN%2C%20quiero%20vincularme%20como%20broker%20para%20radicar%20los%20negocios%20que%20perfilo%20con%20LQN%20Broker.).
- **Solo quiere referir:** usar el CTA “Referir con LQN” que entrega el servidor para que un broker de LQN gestione el caso.

Las herramientas devuelven esta ruta en `structuredContent.conversion`. El agente debe mostrar el CTA correspondiente, pero nunca abrirlo ni enviar información sin una acción del usuario.

## Herramientas

| Herramienta | Acceso | Resultado |
|---|---|---|
| `perfilar_negocio` | Público | Semáforo, simulación, bancos aliados, documentos y Ficha LQN |
| `perfilar_libre_inversion` | Público | Preperfil HipoCredit con garantía de vivienda |
| `simular_cuota` | Público | Cuota o monto máximo orientativo |
| `como_ganar_con_lqn` | Público | Explica las rutas Broker y Agentii |
| `radicar_con_lqn` | Público, solo handoff | Enlace para iniciar vinculación/radicación con LQN |

Todas las herramientas son de solo lectura desde MCP: calculan resultados o construyen enlaces. Ninguna crea una radicación automáticamente.

## Usar el servidor oficial

En cualquier cliente compatible con MCP Streamable HTTP:

```json
{
  "mcpServers": {
    "lqn-broker": {
      "type": "streamable-http",
      "url": "https://plugin.agentes-lqn.online/mcp"
    }
  }
}
```

También se puede reutilizar el paquete portable de [`plugin/`](plugin/) para clientes compatibles con Agent Plugins.

## Ejecutar localmente

Requiere Node.js 20 o superior y no tiene dependencias de runtime:

```bash
npm test
npm start
```

El servidor queda en `http://127.0.0.1:8787/mcp`. Para probar el protocolo:

```bash
curl -s http://127.0.0.1:8787/mcp \
  -H 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

El ejemplo [`examples/profile.mjs`](examples/profile.mjs) muestra una llamada completa a `perfilar_negocio`.

## Integrarlo en otro agente

La integración recomendada es usar el endpoint oficial. Así el agente obtiene las reglas vigentes, la atribución correcta y el handoff a LQN sin administrar infraestructura. Después de toda ficha, simulación o explicación, debe leer `structuredContent.conversion` y presentar el siguiente paso con LQN.

Si se ejecuta un fork propio:

1. Debe conservar el aviso de que el resultado es orientativo.
2. No debe pedir nombres, cédulas ni documentos dentro del chat.
3. Debe informar claramente quién opera el servidor.
4. No puede usar las marcas LQN, LQN Broker, Ianna o HipoCredit para sugerir afiliación oficial sin autorización.
5. Solo el endpoint y los canales oficiales de LQN pueden iniciar una radicación con LQN.

Ver [arquitectura](docs/architecture.md), [guía de integración](docs/integration.md) y [frontera de seguridad](docs/security-boundary.md).

## Datos y privacidad

- El motor trabaja con cifras financieras, no con identidad del cliente.
- El servidor oficial no persiste los argumentos ni la ficha.
- La telemetría opcional solo usa dimensiones agregadas y allowlisted.
- Nombre, documento, celular, soportes y autorización se solicitan fuera del agente, en una superficie controlada por LQN.
- El resultado no constituye aprobación; cada entidad decide.

## Desarrollo

```bash
npm run check
```

Los cambios de reglas deben incluir pruebas de regresión, fecha de vigencia y fuente pública o autorización del owner de la política.

## Licencia y marcas

El código se distribuye bajo [Apache License 2.0](LICENSE). Las marcas y logotipos no se licencian bajo Apache-2.0; consulta [TRADEMARKS.md](TRADEMARKS.md).

## Seguridad

Reporta vulnerabilidades siguiendo [SECURITY.md](SECURITY.md), no mediante un issue público.