contabridge-mcp 0.1.0__tar.gz

contabridge_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:        ContaBridge MCP (contabridge-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.

contabridge_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: contabridge-mcp
+Version: 0.1.0
+Summary: MCP server for Spanish accounting import files: convert journals between A3 (SUENLACE.DAT), ContaPlus, Sage 50 and CSV, and turn Norma 43 bank statements into journal entries. Billed per call with KeyFlint credits.
+Author: ArceeDev
+License-Expression: BUSL-1.1
+Project-URL: Homepage, https://github.com/ArceeDev/contabridge-mcp
+Project-URL: Source, https://github.com/ArceeDev/contabridge-mcp
+Keywords: mcp,contabilidad,a3,a3asesor,suenlace,contaplus,sage,libro-diario,asientos,norma43,gestoria,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
+
+# contabridge-mcp
+
+An MCP server that moves bookkeeping between Spanish accounting programs, built for AI agents that work for gestorías and accounting firms with many clients. It does not store any data between calls, and every result is deterministic.
+
+| Tool | Credits | What it does |
+| --- | --- | --- |
+| `convert_journal` | 2 | Converts a libro diario between **a3ASESOR/a3ECO/a3CON** (`SUENLACE.DAT`), **Sage ContaPlus / Sage 50** (Diario CSV of 142 fields, or XDiario ASCII) and **spreadsheet CSV** (Holded, Excel, any ERP). It resizes subaccounts (`4300001` → `43000001`, `430.1` → `43000001`), renames accounts and renumbers entries. |
+| `bank_to_journal` | 3 | Turns a **Norma 43** bank statement into journal entries against the 572 subaccount. Ordered rules map movements to counterpart accounts (by text, regex, AEB concept or direction), and movements that match no rule go to 555 and are listed. |
+| `build_journal` | 2 | Writes entries the agent composed (invoices, payroll, accruals) in any of the formats. |
+| `validate_journal` | 1 | Runs the checks A3 and ContaPlus run on import: balanced entries, debit or credit on each line (never both), PGC groups, fiscal year, mixed account lengths. |
+| `resize_account`, `detect_format`, `pricing`, `credits_balance` | 0 | Free helpers. |
+
+Output files are returned as `content` and as `content_base64`. The base64 version is Windows-1252 with CRLF line endings (UTF-8 with BOM for CSV), which is what these programs import.
+
+Charging works like this:
+- A file that would be rejected (unbalanced, unreadable, missing columns) is refused **before** any credits are charged.
+- A failure after charging is refunded.
+
+## Formats and sources
+
+- **A3**: "Enlace contable de entrada. Descripción de registros" (Wolters Kluwer). Record type 0, format 5 (512 bytes) and format 4 (256 bytes). When reading, invoice records (types 1, 2 and 9) are skipped and reported in a warning.
+- **ContaPlus**: "Protocolo de comunicación de programas de gestión con ContaPlus" (Sage, 2023). Writes Asien, Fecha, SubCta, Contra, Concepto, Documento, MonedaUso=2, EuroDebe and EuroHaber. The fixed-width ASCII variant (32 fields) uses the same layout as the open-source BulmaGés exporter.
+- **CSV**: columns are detected in Spanish and English (`fecha`, `cuenta`, `debe`, `haber`, `importe`+`d/h`…), or set with `column_map`. A file without an entry number is grouped into entries by accumulating lines until they balance.
+
+## Install
+
+All you need is your KeyFlint license (`LIC-...`). The gateway URL, its public key and the checkout link have defaults.
+
+**Claude Desktop, one click:** download `contabridge-mcp-X.Y.Z.mcpb` from the [latest release](https://github.com/ArceeDev/contabridge-mcp/releases/latest), double-click it and paste your license. No terminal, no JSON.
+
+**Claude Code:**
+
+```bash
+claude mcp add contabridge -e KEYFLINT_LICENSE=LIC-... -- uvx contabridge-mcp
+```
+
+**Cursor, Windsurf, Claude Desktop (JSON):**
+
+```json
+{
+  "mcpServers": {
+    "contabridge": {
+      "command": "uvx",
+      "args": ["contabridge-mcp"],
+      "env": { "KEYFLINT_LICENSE": "LIC-..." }
+    }
+  }
+}
+```
+
+Optional: `KEYFLINT_URL`, `KEYFLINT_PUBLIC_KEYS` (fetched from the gateway and cached in `~/.keyflint/keyring.json` when unset), `KEYFLINT_CHECKOUT_URL`.
+
+Hosted mode: `CONTABRIDGE_TRANSPORT=http contabridge-mcp --http` (license per request, `Authorization: Bearer LIC-...`).
+
+Tuning: `CONTABRIDGE_PRICES` (`convert_journal=3,bank_to_journal=5`), `CONTABRIDGE_MAX_BYTES`.
+
+## Claude skill
+
+`skills/contabridge/SKILL.md` (zipped in `distribution/contabridge-skill.zip`) tells the agent which tool to use, which account length to ask for, and how to save the file.
+
+## Tests
+
+```bash
+pip install -e '.[test]' && pytest
+```
+
+The tests use a fake KeyFlint gateway and locally signed licenses, so they need no network. A3 and ContaPlus layouts are checked position by position against the official specifications.
+
+## License
+
+Business Source License 1.1. Source available; production use needs a KeyFlint license (or must be non-commercial). Each version becomes Apache 2.0 four years after release. See [LICENSE](LICENSE).

contabridge_mcp-0.1.0/README.md

@@ -0,0 +1,71 @@
+# contabridge-mcp
+
+An MCP server that moves bookkeeping between Spanish accounting programs, built for AI agents that work for gestorías and accounting firms with many clients. It does not store any data between calls, and every result is deterministic.
+
+| Tool | Credits | What it does |
+| --- | --- | --- |
+| `convert_journal` | 2 | Converts a libro diario between **a3ASESOR/a3ECO/a3CON** (`SUENLACE.DAT`), **Sage ContaPlus / Sage 50** (Diario CSV of 142 fields, or XDiario ASCII) and **spreadsheet CSV** (Holded, Excel, any ERP). It resizes subaccounts (`4300001` → `43000001`, `430.1` → `43000001`), renames accounts and renumbers entries. |
+| `bank_to_journal` | 3 | Turns a **Norma 43** bank statement into journal entries against the 572 subaccount. Ordered rules map movements to counterpart accounts (by text, regex, AEB concept or direction), and movements that match no rule go to 555 and are listed. |
+| `build_journal` | 2 | Writes entries the agent composed (invoices, payroll, accruals) in any of the formats. |
+| `validate_journal` | 1 | Runs the checks A3 and ContaPlus run on import: balanced entries, debit or credit on each line (never both), PGC groups, fiscal year, mixed account lengths. |
+| `resize_account`, `detect_format`, `pricing`, `credits_balance` | 0 | Free helpers. |
+
+Output files are returned as `content` and as `content_base64`. The base64 version is Windows-1252 with CRLF line endings (UTF-8 with BOM for CSV), which is what these programs import.
+
+Charging works like this:
+- A file that would be rejected (unbalanced, unreadable, missing columns) is refused **before** any credits are charged.
+- A failure after charging is refunded.
+
+## Formats and sources
+
+- **A3**: "Enlace contable de entrada. Descripción de registros" (Wolters Kluwer). Record type 0, format 5 (512 bytes) and format 4 (256 bytes). When reading, invoice records (types 1, 2 and 9) are skipped and reported in a warning.
+- **ContaPlus**: "Protocolo de comunicación de programas de gestión con ContaPlus" (Sage, 2023). Writes Asien, Fecha, SubCta, Contra, Concepto, Documento, MonedaUso=2, EuroDebe and EuroHaber. The fixed-width ASCII variant (32 fields) uses the same layout as the open-source BulmaGés exporter.
+- **CSV**: columns are detected in Spanish and English (`fecha`, `cuenta`, `debe`, `haber`, `importe`+`d/h`…), or set with `column_map`. A file without an entry number is grouped into entries by accumulating lines until they balance.
+
+## Install
+
+All you need is your KeyFlint license (`LIC-...`). The gateway URL, its public key and the checkout link have defaults.
+
+**Claude Desktop, one click:** download `contabridge-mcp-X.Y.Z.mcpb` from the [latest release](https://github.com/ArceeDev/contabridge-mcp/releases/latest), double-click it and paste your license. No terminal, no JSON.
+
+**Claude Code:**
+
+```bash
+claude mcp add contabridge -e KEYFLINT_LICENSE=LIC-... -- uvx contabridge-mcp
+```
+
+**Cursor, Windsurf, Claude Desktop (JSON):**
+
+```json
+{
+  "mcpServers": {
+    "contabridge": {
+      "command": "uvx",
+      "args": ["contabridge-mcp"],
+      "env": { "KEYFLINT_LICENSE": "LIC-..." }
+    }
+  }
+}
+```
+
+Optional: `KEYFLINT_URL`, `KEYFLINT_PUBLIC_KEYS` (fetched from the gateway and cached in `~/.keyflint/keyring.json` when unset), `KEYFLINT_CHECKOUT_URL`.
+
+Hosted mode: `CONTABRIDGE_TRANSPORT=http contabridge-mcp --http` (license per request, `Authorization: Bearer LIC-...`).
+
+Tuning: `CONTABRIDGE_PRICES` (`convert_journal=3,bank_to_journal=5`), `CONTABRIDGE_MAX_BYTES`.
+
+## Claude skill
+
+`skills/contabridge/SKILL.md` (zipped in `distribution/contabridge-skill.zip`) tells the agent which tool to use, which account length to ask for, and how to save the file.
+
+## Tests
+
+```bash
+pip install -e '.[test]' && pytest
+```
+
+The tests use a fake KeyFlint gateway and locally signed licenses, so they need no network. A3 and ContaPlus layouts are checked position by position against the official specifications.
+
+## License
+
+Business Source License 1.1. Source available; production use needs a KeyFlint license (or must be non-commercial). Each version becomes Apache 2.0 four years after release. See [LICENSE](LICENSE).

contabridge_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "contabridge-mcp"
+version = "0.1.0"
+description = "MCP server for Spanish accounting import files: convert journals between A3 (SUENLACE.DAT), ContaPlus, Sage 50 and CSV, and turn Norma 43 bank statements into journal entries. 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", "contabilidad", "a3", "a3asesor", "suenlace", "contaplus", "sage", "libro-diario", "asientos", "norma43", "gestoria", "spain"]
+dependencies = [
+    "mcp>=2.0",
+    "keyflint-verify[fast]>=1.2.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[project.scripts]
+contabridge-mcp = "contabridge_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/ArceeDev/contabridge-mcp"
+Source = "https://github.com/ArceeDev/contabridge-mcp"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+pythonpath = ["src", "tests"]

contabridge_mcp-0.1.0/setup.cfg

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

contabridge_mcp-0.1.0/src/contabridge_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""ContaBridge MCP: Spanish accounting import files (A3, ContaPlus, Sage 50, CSV) and Norma 43 to journal."""
+
+__version__ = "0.1.0"

contabridge_mcp-0.1.0/src/contabridge_mcp/__main__.py

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

contabridge_mcp-0.1.0/src/contabridge_mcp/bank.py

@@ -0,0 +1,151 @@
+"""Norma 43 bank movements -> journal entries, with deterministic first-match rules."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from . import ids, n43
+from .journal import Entry, JournalError, Line, parse_date
+
+
+@dataclass
+class Rule:
+    account: str
+    contains: list[str]
+    regex: re.Pattern[str] | None
+    common_concept: str
+    direction: str
+    concept: str
+    index: int
+
+    def matches(self, text: str, m: n43.Movement) -> bool:
+        if self.direction and self.direction != ("cargo" if m.cents < 0 else "abono"):
+            return False
+        if self.common_concept and self.common_concept != m.common_concept:
+            return False
+        low = text.lower()
+        if self.contains and not any(c in low for c in self.contains):
+            return False
+        if self.regex and not self.regex.search(text):
+            return False
+        return True
+
+
+try:  # Python 3.11+
+    from re import _constants as _sre_c, _parser as _sre_p  # type: ignore[attr-defined]
+except ImportError:  # pragma: no cover - Python 3.10
+    import sre_constants as _sre_c  # type: ignore[no-redef]
+    import sre_parse as _sre_p  # type: ignore[no-redef]
+
+MAX_REGEX_LEN = 300
+_REPEATS = (_sre_c.MAX_REPEAT, _sre_c.MIN_REPEAT, getattr(_sre_c, "POSSESSIVE_REPEAT", None))
+
+
+def _risky(items: Any, in_repeat: bool = False) -> bool:
+    """True for backreferences or a repeat nested in another repeat: the shapes behind catastrophic
+    backtracking, e.g. (a+)+ or (a*)*b, which would hold the server's CPU for minutes."""
+    for op, av in items:
+        if op in (_sre_c.GROUPREF, getattr(_sre_c, "GROUPREF_EXISTS", None)):
+            return True
+        if op in _REPEATS and op is not None:
+            lo, hi, sub = av
+            many = hi is _sre_c.MAXREPEAT or hi > 1
+            if many and in_repeat:
+                return True
+            if _risky(sub, in_repeat or many):
+                return True
+        elif op is _sre_c.SUBPATTERN:
+            if _risky(av[-1], in_repeat):
+                return True
+        elif op is _sre_c.BRANCH:
+            if any(_risky(b, in_repeat) for b in av[1]):
+                return True
+        elif op in (_sre_c.ASSERT, _sre_c.ASSERT_NOT):
+            if _risky(av[1], in_repeat):
+                return True
+    return False
+
+
+def compile_rule_regex(rx: str, where: str) -> re.Pattern[str]:
+    if len(rx) > MAX_REGEX_LEN:
+        raise JournalError(f"{where}: regex demasiado larga (máx. {MAX_REGEX_LEN} caracteres)")
+    try:
+        pattern = re.compile(rx, re.IGNORECASE)
+    except re.error as exc:
+        raise JournalError(f"{where}: regex no válida ({exc})") from exc
+    if _risky(_sre_p.parse(rx)):
+        raise JournalError(f"{where}: regex con cuantificadores anidados o referencias (p. ej. (a+)+); "
+                           "simplifícala o usa 'contains'")
+    return pattern
+
+
+def build_rules(items: list[dict[str, Any]]) -> list[Rule]:
+    out = []
+    for i, it in enumerate(items or [], 1):
+        if not isinstance(it, dict) or not str(it.get("account", "")).strip():
+            raise JournalError(f"regla {i}: falta 'account'")
+        contains = it.get("contains") or []
+        if isinstance(contains, str):
+            contains = [contains]
+        rx = it.get("regex") or ""
+        pattern = compile_rule_regex(str(rx), f"regla {i}") if rx else None
+        direction = str(it.get("direction", "") or "").lower()
+        if direction not in ("", "cargo", "abono"):
+            raise JournalError(f"regla {i}: direction debe ser 'cargo' o 'abono'")
+        cc = str(it.get("common_concept", "") or "").strip()
+        if not (contains or pattern or cc or direction):
+            raise JournalError(f"regla {i}: indica al menos contains, regex, common_concept o direction")
+        out.append(Rule(account=str(it["account"]).strip(), contains=[str(c).lower() for c in contains],
+                        regex=pattern, common_concept=cc.zfill(2) if cc else "", direction=direction,
+                        concept=str(it.get("concept", "") or ""), index=i))
+    return out
+
+
+def _bank_account(acc: n43.Account, bank_account: str, bank_accounts: dict[str, str]) -> str:
+    ccc = acc.ccc or ""
+    iban = (ids.iban_from_ccc(ccc) or "") if ccc else ""
+    for key, value in (bank_accounts or {}).items():
+        k = re.sub(r"\s", "", key).upper()
+        if k and (k == iban or k == ccc or iban.endswith(k) or ccc.endswith(k)):
+            return value.strip()
+    if not bank_account:
+        raise JournalError(f"no hay subcuenta 572 para la cuenta bancaria {iban or ccc}: indica bank_account")
+    return bank_account.strip()
+
+
+def movements_to_entries(res: n43.ParseResult, bank_account: str, rules: list[Rule],
+                         suspense_account: str, bank_accounts: dict[str, str] | None = None,
+                         use_value_date: bool = False) -> tuple[list[Entry], dict[str, Any]]:
+    entries: list[Entry] = []
+    unmatched: list[dict[str, Any]] = []
+    hits: dict[int, int] = {}
+    for acc in res.accounts:
+        bank = _bank_account(acc, bank_account, bank_accounts or {})
+        for m in acc.movements:
+            text = m.description()
+            when = (m.value_date if use_value_date else m.operation_date) or m.operation_date or m.value_date
+            if not when:
+                raise JournalError(f"movimiento {m.id} sin fecha")
+            rule = next((r for r in rules if r.matches(text, m)), None)
+            if rule:
+                hits[rule.index] = hits.get(rule.index, 0) + 1
+                other = rule.account
+            else:
+                other = suspense_account
+                unmatched.append({"movement": m.id, "date": when, "amount": n43.fmt_cents(m.cents),
+                                  "description": text})
+            concept = (rule.concept if rule and rule.concept else text)[:60]
+            doc = (m.document_number or "").lstrip("0") or (m.reference1 or "").lstrip("0")
+            amount = abs(m.cents)
+            bank_line = Line(account=bank, debit=amount if m.cents > 0 else 0, credit=amount if m.cents < 0 else 0,
+                             concept=concept, document=doc)
+            other_line = Line(account=other, debit=amount if m.cents < 0 else 0, credit=amount if m.cents > 0 else 0,
+                              concept=concept, document=doc)
+            lines = [other_line, bank_line] if m.cents < 0 else [bank_line, other_line]
+            entries.append(Entry(number=None, date=parse_date(when), lines=lines))
+    stats = {"movements": len(entries), "matched": len(entries) - len(unmatched), "unmatched": unmatched,
+             "rule_hits": {f"regla {k}": v for k, v in sorted(hits.items())},
+             "suspense_account": suspense_account}
+    return entries, stats

contabridge_mcp-0.1.0/src/contabridge_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("CONTABRIDGE_TRANSPORT", "stdio") != "stdio")