norma43-mcp 0.1.0__tar.gz

norma43_mcp-0.1.0/LICENSE

@@ -0,0 +1,70 @@
+License text copyright (c) 2020 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Parameters
+
+Licensor:             ArceeDev (KeyFlint, https://keyflint.dev, legal@keyflint.dev)
+Licensed Work:        Norma 43 MCP (norma43-mcp), version 0.1.0 or later.
+                      The Licensed Work is (c) 2026 ArceeDev.
+Additional Use Grant: You may make production use of the Licensed Work:
+                      (a) with a valid KeyFlint license for the Licensed Work
+                          obtained from the Licensor (https://mcp.keyflint.dev),
+                          with tool calls metered through the Licensor's
+                          KeyFlint gateway; or
+                      (b) for personal, educational, research or evaluation
+                          purposes that are not commercial.
+                      This grant does not cover removing, disabling or
+                      bypassing the license verification or credit metering,
+                      nor offering the Licensed Work, or a modified version of
+                      it, to third parties on a hosted, embedded or resold
+                      basis.
+Change Date:          2030-11-05
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact the Licensor at legal@keyflint.dev or https://keyflint.dev.
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.

norma43_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: norma43-mcp
+Version: 0.1.0
+Summary: MCP server for Spanish bank statements (Norma 43 / Cuaderno 43) and bank reconciliation. Billed per call with KeyFlint credits.
+Author: ArceeDev
+License-Expression: BUSL-1.1
+Project-URL: Homepage, https://github.com/ArceeDev/norma43-mcp
+Project-URL: Source, https://github.com/ArceeDev/norma43-mcp
+Keywords: mcp,norma43,cuaderno43,aeb43,conciliacion-bancaria,bank-reconciliation,sepa,iban,spain
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=2.0
+Requires-Dist: keyflint-verify[fast]>=1.2.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Dynamic: license-file
+
+# 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](https://keyflint.com).
+
+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
+
+| Tool | Créditos | Qué hace |
+|---|---|---|
+| `parse_norma43` | 1 | Cuentas, IBAN calculado, banco, titular, saldos, movimientos, textos 23 y campos SEPA (modalidad 3). Comprueba totales del registro 33, saldo inicial + movimientos = final, recuento del 88, fechas, signos y formatos. |
+| `norma43_to_csv` | 1 | CSV listo para Excel español (`;`, coma decimal), protegido contra inyección de fórmulas. |
+| `reconcile_movements` | 3 | Conciliación 1:1, 1:N (una transferencia paga varias facturas) y N:1 (pagos parciales). Puntuación 0-100, confianza y evidencias. Empates → `ambiguous`. |
+| `validate_identifier` | 0 | IBAN, CCC, NIF/NIE/CIF, identificador de acreedor SEPA, Referencia 1. |
+| `sepa_creditor_id` | 0 | Identificador de acreedor SEPA (AT-02) a partir del NIF. |
+| `pricing`, `credits_balance` | 0 | Precios y saldo de la licencia. |
+
+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](https://github.com/ArceeDev/norma43-mcp/releases/latest), ábrelo con doble clic y pega tu licencia. Sin terminal ni JSON.
+
+**Claude Code:**
+
+```bash
+claude mcp add norma43 -e KEYFLINT_LICENSE=LIC-... -- uvx norma43-mcp
+```
+
+**Cursor, Windsurf, Claude Desktop (JSON):**
+
+```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`.
+
+## Modo hosted (HTTP, licencia por petición)
+
+```bash
+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
+
+```bash
+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](LICENSE).

norma43_mcp-0.1.0/README.md

@@ -0,0 +1,94 @@
+# 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](https://keyflint.com).
+
+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
+
+| Tool | Créditos | Qué hace |
+|---|---|---|
+| `parse_norma43` | 1 | Cuentas, IBAN calculado, banco, titular, saldos, movimientos, textos 23 y campos SEPA (modalidad 3). Comprueba totales del registro 33, saldo inicial + movimientos = final, recuento del 88, fechas, signos y formatos. |
+| `norma43_to_csv` | 1 | CSV listo para Excel español (`;`, coma decimal), protegido contra inyección de fórmulas. |
+| `reconcile_movements` | 3 | Conciliación 1:1, 1:N (una transferencia paga varias facturas) y N:1 (pagos parciales). Puntuación 0-100, confianza y evidencias. Empates → `ambiguous`. |
+| `validate_identifier` | 0 | IBAN, CCC, NIF/NIE/CIF, identificador de acreedor SEPA, Referencia 1. |
+| `sepa_creditor_id` | 0 | Identificador de acreedor SEPA (AT-02) a partir del NIF. |
+| `pricing`, `credits_balance` | 0 | Precios y saldo de la licencia. |
+
+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](https://github.com/ArceeDev/norma43-mcp/releases/latest), ábrelo con doble clic y pega tu licencia. Sin terminal ni JSON.
+
+**Claude Code:**
+
+```bash
+claude mcp add norma43 -e KEYFLINT_LICENSE=LIC-... -- uvx norma43-mcp
+```
+
+**Cursor, Windsurf, Claude Desktop (JSON):**
+
+```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`.
+
+## Modo hosted (HTTP, licencia por petición)
+
+```bash
+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
+
+```bash
+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](LICENSE).

norma43_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "norma43-mcp"
+version = "0.1.0"
+description = "MCP server for Spanish bank statements (Norma 43 / Cuaderno 43) and bank reconciliation. Billed per call with KeyFlint credits."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "BUSL-1.1"
+license-files = ["LICENSE"]
+authors = [{ name = "ArceeDev" }]
+keywords = ["mcp", "norma43", "cuaderno43", "aeb43", "conciliacion-bancaria", "bank-reconciliation", "sepa", "iban", "spain"]
+dependencies = [
+    "mcp>=2.0",
+    "keyflint-verify[fast]>=1.2.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[project.scripts]
+norma43-mcp = "norma43_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/ArceeDev/norma43-mcp"
+Source = "https://github.com/ArceeDev/norma43-mcp"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+pythonpath = ["src", "tests"]

norma43_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

norma43_mcp-0.1.0/src/norma43_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Norma 43 MCP: Spanish bank statements (Cuaderno 43) and bank reconciliation for AI agents."""
+
+__version__ = "0.1.0"

norma43_mcp-0.1.0/src/norma43_mcp/__main__.py

@@ -0,0 +1,3 @@
+from .server import main
+
+main()

norma43_mcp-0.1.0/src/norma43_mcp/billing.py

@@ -0,0 +1,167 @@
+"""Per-call credit billing on top of keyflint_verify.mcp.KeyFlint.
+
+stdio: the license comes from KEYFLINT_LICENSE (one buyer per process).
+HTTP:  the license comes from each request (``Authorization: Bearer LIC-...`` or
+``X-KeyFlint-License``), so one hosted server bills many buyers.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import pathlib
+import threading
+import uuid
+from collections import OrderedDict
+from contextlib import asynccontextmanager
+from typing import Any, AsyncIterator, Mapping, Optional
+
+from keyflint_verify.mcp import LICENSE_INVALID, KeyFlint, LicenseError
+
+LICENSE_HEADERS = ("x-license-key", "authorization")
+_MAX_CLIENTS = 1024
+
+DEFAULT_GATEWAY = "https://licenses.keyflint.dev"
+DEFAULT_CHECKOUT = "https://mcp.keyflint.dev/precios/"
+_KEYRING_TTL = 6 * 3600
+
+
+def _env(name: str) -> str:
+    return (os.environ.get("KEYFLINT_" + name) or os.environ.get("KEYFORGE_" + name) or "").strip()
+
+
+def _fetch_keyring(gateway: str) -> str:
+    """Gateway public keyring, cached in ~/.keyflint (stale copy used when offline)."""
+    import hashlib
+    import json
+    import time
+    import urllib.request
+
+    cache = pathlib.Path(os.environ.get("KEYFLINT_KEYRING_CACHE")
+                         or pathlib.Path.home() / ".keyflint" / "keyring.json")
+    slot = hashlib.sha256(gateway.encode()).hexdigest()[:16]
+    try:
+        stored = json.loads(cache.read_text("utf-8"))
+    except (OSError, ValueError):
+        stored = {}
+    entry = stored.get(slot) or {}
+    if entry.get("keyring") and time.time() - float(entry.get("at", 0)) < _KEYRING_TTL:
+        return str(entry["keyring"])
+    try:
+        req = urllib.request.Request(gateway + "/api/v1/licenses/public-key",
+                                     headers={"Accept": "application/json"})
+        with urllib.request.urlopen(req, timeout=4) as resp:  # noqa: S310 - https gateway
+            keyring = str(json.loads(resp.read().decode("utf-8"))["data"]["keyring"]).strip()
+    except Exception:  # noqa: BLE001 - offline: fall back to the cached keyring
+        return str(entry.get("keyring") or "")
+    if keyring:
+        try:
+            stored[slot] = {"keyring": keyring, "at": time.time()}
+            cache.parent.mkdir(parents=True, exist_ok=True)
+            cache.write_text(json.dumps(stored), "utf-8")
+        except OSError:
+            pass
+    return keyring
+
+
+def apply_defaults() -> None:
+    """Only KEYFLINT_LICENSE is required: gateway, keyring and checkout default to KeyFlint's."""
+    if not _env("URL"):
+        os.environ["KEYFLINT_URL"] = DEFAULT_GATEWAY
+    if not _env("CHECKOUT_URL"):
+        os.environ["KEYFLINT_CHECKOUT_URL"] = DEFAULT_CHECKOUT
+    if not (_env("PUBLIC_KEYS") or _env("PUBLIC_KEY")):
+        keyring = _fetch_keyring(_env("URL").rstrip("/"))
+        if keyring:
+            os.environ["KEYFLINT_PUBLIC_KEYS"] = keyring
+
+
+def license_from_headers(headers: Optional[Mapping[str, str]]) -> Optional[str]:
+    if not headers:
+        return None
+    lower = {k.lower(): v for k, v in headers.items()}
+    raw = lower.get("x-license-key") or ""
+    if not raw:
+        auth = lower.get("authorization") or ""
+        if auth[:7].lower() == "bearer ":
+            raw = auth[7:]
+    raw = raw.strip()
+    return raw or None
+
+
+class Billing:
+    """Resolves the buyer's license and debits credits around a tool body."""
+
+    def __init__(self, *, hosted: bool = False, **kf_kwargs: Any) -> None:
+        self.hosted = hosted
+        if "public_keys" not in kf_kwargs:
+            apply_defaults()
+        self._kf_kwargs = kf_kwargs
+        self._env_kf = KeyFlint(**kf_kwargs)
+        self._clients: "OrderedDict[str, KeyFlint]" = OrderedDict()
+        self._lock = threading.Lock()
+
+    @property
+    def checkout_url(self) -> Optional[str]:
+        return self._env_kf.checkout_url
+
+    def client(self, headers: Optional[Mapping[str, str]] = None) -> KeyFlint:
+        key = license_from_headers(headers)
+        if key is None:
+            if self.hosted:
+                text = "Send your KeyFlint license as 'Authorization: Bearer LIC-...'."
+                if self.checkout_url:
+                    text += f" Get one: {self.checkout_url}"
+                raise LicenseError(LICENSE_INVALID, text, {"reason": "ERR_EMPTY_TOKEN",
+                                                           "checkout_url": self.checkout_url})
+            return self._env_kf
+        with self._lock:
+            kf = self._clients.get(key)
+            if kf is None:
+                # Hosted: server clock is trusted, no node lock (the buyer's machine is not ours).
+                kf = KeyFlint(license_key=key, machine_id=None, clock_guard=False,
+                              public_keys=self._env_kf.public_keys, gateway_url=self._env_kf.gateway_url,
+                              checkout_url=self._env_kf.checkout_url, timeout=self._env_kf.timeout)
+                self._clients[key] = kf
+                if len(self._clients) > _MAX_CLIENTS:
+                    self._clients.popitem(last=False)
+            else:
+                self._clients.move_to_end(key)
+            return kf
+
+    @asynccontextmanager
+    async def charge(self, credits: int, tool: str, headers: Optional[Mapping[str, str]] = None,
+                     features: Optional[list[str]] = None) -> AsyncIterator[dict[str, Any]]:
+        """Offline license check, debit, run body; refund if the body raises."""
+        kf = self.client(headers)
+        kf.check(features)
+        idem = f"n43-{uuid.uuid4().hex}"
+        receipt = await asyncio.to_thread(kf.deduct, credits, idempotency_key=idem, event_type=f"mcp:{tool}")
+        try:
+            yield receipt
+        except BaseException:
+            await asyncio.to_thread(kf.refund, idem, "tool_error")
+            raise
+
+    async def balance(self, headers: Optional[Mapping[str, str]] = None) -> dict[str, Any]:
+        import json
+        import urllib.parse
+        import urllib.request
+
+        kf = self.client(headers)
+        kf.check()
+        if not kf.gateway_url:
+            raise LicenseError(-32063, "KEYFLINT_URL is not set.", {"reason": "GATEWAY_NOT_CONFIGURED"})
+        url = f"{kf.gateway_url}/api/v1/quota/balance?" + urllib.parse.urlencode({"license_key": kf.license_key})
+
+        def _get() -> dict[str, Any]:
+            req = urllib.request.Request(url, headers={"Accept": "application/json"})
+            with urllib.request.urlopen(req, timeout=kf.timeout) as resp:  # noqa: S310 - configured URL
+                data = json.loads(resp.read().decode("utf-8") or "{}")
+                return dict(data.get("data", data))
+
+        return await asyncio.to_thread(_get)
+
+
+def from_env() -> Billing:
+    return Billing(hosted=os.environ.get("NORMA43_TRANSPORT", "stdio") != "stdio")