# BusinessLink en asistentes de IA (servidor MCP)

BusinessLink tiene un servidor **MCP** (Model Context Protocol) para que Claude, ChatGPT, Cursor, Claude Code y otros asistentes puedan consultar RNC, emitir comprobantes en sandbox, revisar las facturas recibidas de proveedores y administrar el secuenciador de e-NCF, hablando en lenguaje natural.

- URL del servidor (HTTP, Streamable HTTP): `https://api.businesslink.do/mcp`
- Autenticación: su clave de API de BusinessLink en la cabecera `Authorization: Bearer bl_test_...`
- Empiece siempre con una clave **`bl_test_`** (sandbox: nada llega a la DGII).
- Código y guía de instalación local: carpeta `mcp_server/` del repositorio de BusinessLink.

## Herramientas

| Herramienta | Qué hace | Escribe |
|---|---|---|
| `mi_empresa` | Empresa, modo (test/live) y permisos de la clave | no |
| `consultar_rnc`, `buscar_rnc` | Directorio de RNC de la DGII (por número o por nombre) | no |
| `tasa_cambio` | Dólar y euro, Banco Central | no |
| `estado_dgii` | Estado y mantenimiento de los servicios de la DGII | no |
| `emitir_factura` | Emite un e-CF (factura simple; BusinessLink calcula e ITBIS y numera) | sí |
| `emitir_ecf_completo` | Emite el JSON completo de la DGII (ERP) | sí |
| `consultar_factura`, `consultar_facturas` | Estado de uno o varios comprobantes emitidos | no |
| `descargar_factura` | XML firmado o PDF de un comprobante emitido | no |
| `listar_recibidos` | Facturas de proveedores (compras), con filtros y sincronización incremental | no |
| `consultar_recibido` | Documento completo de una compra: líneas, impuestos, totales | no |
| `descargar_recibido` | XML firmado o PDF del proveedor | no |
| `leer_ecf_xml` | Lee un XML de e-CF suelto y valida su firma | no |
| `listar_secuencias` | Rangos de e-NCF y números disponibles | no |
| `registrar_secuencia` | Registra un rango autorizado por la DGII | sí |
| `anular_secuencia` | Deja de usar un rango | sí |
| `listar_webhooks`, `registrar_webhook` | Webhooks firmados para el resultado de la DGII | sí (registrar) |
| `buscar_documentacion` | Busca en estas guías (no necesita clave) | no |

## Seguridad

- Las herramientas que escriben con una clave `bl_live_` (producción) exigen `confirmar_produccion=true`, que el asistente solo debe enviar después de la confirmación explícita de la persona.
- Emitir exige `idempotency_key`: reintentar con el mismo valor nunca emite dos comprobantes.
- Cree claves con los permisos mínimos. Para solo consultar, `rnc:leer`, `facturas:leer` y `recibidos:leer` bastan.
- El servidor no guarda la clave: la reenvía a `https://api.businesslink.do/v1` en cada llamada.

## Cómo conectarlo

### Claude Code

```bash
claude mcp add --transport http businesslink https://api.businesslink.do/mcp \
  --header "Authorization: Bearer $BL_API_KEY"
```

### Cursor / otros clientes con cabeceras (`mcp.json`)

```json
{
  "mcpServers": {
    "businesslink": {
      "url": "https://api.businesslink.do/mcp",
      "headers": {"Authorization": "Bearer bl_test_XXXXXXXX"}
    }
  }
}
```

### Claude Desktop (local, stdio)

```json
{
  "mcpServers": {
    "businesslink": {
      "command": "python",
      "args": ["-m", "businesslink_mcp", "--stdio"],
      "env": {"BL_API_KEY": "bl_test_XXXXXXXX"}
    }
  }
}
```

(Instale antes el paquete: `pip install ./mcp_server`.)

### Claude.ai y ChatGPT (conectores web)

Los conectores personalizados de Claude.ai y ChatGPT piden inicio de sesión OAuth y no permiten una cabecera fija. El inicio de sesión OAuth de BusinessLink está en desarrollo; mientras tanto use Claude Code, Cursor, Claude Desktop u otro cliente con cabeceras, o llame a la API REST directamente (ver [inicio-rapido.md](https://www.businesslink.do/docs/inicio-rapido.md)).

## Ejemplos de lo que se le puede pedir

- "Busca el RNC de Ferretería Americana y dime si está activo."
- "Emite una factura de prueba E31 a 101000228 por 2 horas de consultoría a RD$1,500 más ITBIS."
- "Lista las facturas que me enviaron los proveedores esta semana y dime cuáles no cuadran."
- "¿Cuántos e-NCF E31 me quedan disponibles y cuándo vence el rango?"
- "Hazme una nota de crédito por devolución de la factura E310000000123."
