Norma43 MCP Server

norma43-mcp

MCP para extractos bancarios españoles Norma 43 (Cuaderno 43 / AEB43 / CSB43) y conciliación bancaria para agentes de IA. Cobro por créditos con KeyFlint.

Todos los bancos españoles exportan Norma 43; gestorías y departamentos financieros concilian cada mes. Este servidor lee el fichero como lo valida un banco y cruza movimientos con facturas sin adivinar nunca.

Herramientas

Precios configurables: NORMA43_PRICES="parse_norma43=2,reconcile_movements=5".

Importes: cadenas con 2 decimales; negativo = cargo (sale dinero), positivo = abono (entra).

Instalación

Solo necesitas tu licencia KeyFlint (LIC-...). La URL del gateway, su clave pública y el enlace de compra vienen por defecto.

Claude Desktop, 1 clic: descarga norma43-mcp-X.Y.Z.mcpb de la última release, ábrelo con doble clic y pega tu licencia. Sin terminal ni JSON.

Claude Code:

claude mcp add norma43 -e KEYFLINT_LICENSE=LIC-... -- uvx norma43-mcp

Cursor, Windsurf, Claude Desktop (JSON):

{
  "mcpServers": {
    "norma43": {
      "command": "uvx",
      "args": ["norma43-mcp"],
      "env": { "KEYFLINT_LICENSE": "LIC-..." }
    }
  }
}

Opcionales: KEYFLINT_URL, KEYFLINT_PUBLIC_KEYS (si no se pone, se descarga del gateway y se guarda en ~/.keyflint/keyring.json), KEYFLINT_CHECKOUT_URL.

Tarjetas visuales (MCP Apps)

En Claude, ChatGPT, VS Code y Goose cada herramienta de pago y credits_balance se muestran como una tarjeta interactiva en el chat: saldo de créditos con barra y botón para recargar, o resumen del resultado (cifras clave, incidencias, tabla de vista previa y créditos cobrados). Es el recurso ui://norma43/card.html, autocontenido y sin red. El resto de clientes siguen recibiendo el JSON de siempre.

Modo hosted (HTTP, licencia por petición)

docker build -t norma43-mcp .
docker run -p 8080:8080 \
  norma43-mcp

El cliente envía Authorization: Bearer LIC-... (o X-License-Key).

Variables: NORMA43_TRANSPORT (stdio|http), NORMA43_PRICES, NORMA43_MAX_BYTES (por defecto 5 MB), PORT, HOST.

Flujo de cobro por llamada

1. Se decodifica y valida la entrada. Entrada ilegible u opciones inválidas: no se cobra.
2. Se verifica la licencia (Ed25519, offline) antes de gastar CPU.
3. Se parsea el fichero.
4. Se descuentan los créditos (idempotente).
5. Si la herramienta falla después del cobro, se reembolsa.
6. Sin créditos: error -32062 con la URL de compra.

Reglas de conciliación

• Céntimos enteros, sin coma flotante.
• Evidencias: importe exacto (o dentro de amount_tolerance), referencia de factura en el concepto bancario, nombre de la contraparte, distancia de fechas y unicidad.
• Una referencia solo cuenta con ≥4 caracteres; las numéricas, con ≥6 dígitos y límites de dígito.
• Agrupaciones (1:N, N:1) solo si la suma exacta es única y hay evidencia de referencia o nombre; si no, van a suggestions.
• Dos candidatos con la misma puntuación nunca se resuelven: van a ambiguous para revisión humana.

Limitaciones

• La interpretación SEPA de los registros 23 (Anexo 4) solo se aplica en modalidad 3; en las demás se devuelve el texto tal cual.
• El nombre del banco es informativo (tabla de las entidades principales).
• Validado contra la especificación oficial (AEB/CECA/UNACC, junio 2012) y sus ejemplos, con ficheros generados por un escritor independiente; conviene probarlo con extractos reales de cada banco.

Tests

pip install -e ".[test]"
python -m pytest -q

Licencia

Business Source License 1.1. Código visible; el uso en producción requiere una licencia KeyFlint (o ser no comercial). Pasa a Apache 2.0 cuatro años después de cada versión. Ver LICENSE.