convez.ai
MCP ServerAutomaçãoAvançado
Brettchr301

Allowance — Plano de Controle para Gastos de Agentes IA

Brettchr301/allowance

Controle de gastos para agentes IA com teto rígido e auditoria tamper-evident

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que implementa o Protocolo de Controle de Gastos de Agentes (ASCP), oferecendo um vault com teto de gastos auditável, mandatos em linguagem natural, aprovações em 3 camadas e ledger append-only. Ideal para agentes IA de longa duração que precisam de limites de custo determinísticos e rastreáveis.

Instalação

$npx convez-ai Brettchr301/allowance

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Limitar gastos de agentes IA em produção com teto hard ceiling
  • Implementar aprovações em cascata (3 tiers) antes de compras de agentes
  • Auditar consumo e atividades de agentes com ledger imutável
  • Definir mandatos de gasto em plain English com acionadores automáticos

Veredito

Implementação técnica sólida de um protocolo financeiro para controle de custos de agentes IA. Python puro sem dependências externas obrigatórias, com testes completos e integração MCP bem documentada. Excelente para equipes que precisam governança financeira rigorosa em sistemas agenticos, especialmente com aprovação humana no loop.

README

A tradução para o português deste README ainda está na fila.

allowance

Reference implementation of the Agentic Spending Control Protocol (ASCP) — the open control plane for bounded agent spending (funded ceiling + mandates

  • activity triggers + human-in-the-loop + tamper-evident audit), independent of which payment rail settles. It rides on MCP for agent access and plugs in front of any settlement rail (non-custodial charge, network agent tokens, AP2, x402, issuer). See PROTOCOL.md for the spec and how hobbyists, payment processors, and model makers can build on it.

A hard-ceiling spending vault, exposed as an MCP server, for long-running AI agents. It gives an agent a sub-budgeted, append-only, double-entry ledger with a non-negotiable available >= 0 invariant, deterministic mandate parsing, an activity-driven buy-timing engine, and an idempotent guarded-buy flow.

The core is pure-Python with no required third-party dependencies — it runs, tests, and demos with only the standard library. The mcp SDK is an optional extra needed only to serve the tools over stdio.

Quick start

# core only — no third-party deps
python -m unittest discover -s tests -q

# list the tool surface (no SDK required)
python -m escrow --help

# install with the MCP SDK to actually serve over stdio
pip install -e ".[mcp]"
allowance-mcp

See INSTALL.md for copy-paste wiring into Claude Code and Codex, plus the JSON schemas for all 8 tools.

Install as a plugin (Claude Code marketplace or Codex MCP) — the repo is a self-contained Claude Code plugin (.claude-plugin/, .mcp.json, commands/) bundling the 23-tool MCP server + slash commands (/allowance-status, /allowance-setup, /allowance-mandate, /allowance-running-low, /allowance-autonomy). See PLUGIN.md. Non-MCP harnesses use the bearer API — see INTEGRATIONS.md.

Tools

escrow_balance, fund_escrow, create_mandate, log_activity, check_triggers, propose_purchase, authorize_and_buy, transaction_history.

Money rule: every monetary value is an integer number of cents. Never float.

Web UI — the control panel

A separate web layer under webapp/ puts a real fintech control panel on top of the engine. The browser talks to a FastAPI /api, which imports the escrow package and treats it as the source of truth for all money:

browser SPA (static/)  ──fetch──▶  FastAPI /api (webapp/)  ──imports──▶  escrow engine
   semantic HTML + CSS + vanilla JS      auth · CSRF · authz · locks            vault · policy · triggers
   no build step                          (separate web.db)                     shopping · audit (engine.db)

The engine is never modified — its 77 tests stay green. The web layer keeps its own SQLite DB (webapp/web.db: users, password hashes, vault-ownership links, proposals, idempotency, velocity) and never touches the frozen engine schema (webapp/engine.db).

Screens

  • Vault — live balance breakdown (funded / held / captured / available) with the hard ceiling shown, a committed-percentage gauge, and fund / withdraw.
  • Mandates — write a spend rule in plain English; a live preview shows the parsed caps, detected category, and trigger kind before you save.
  • Activity & Forecasts — log runs / consumption / inventory and see when each trigger fires (days-to-fire, urgency badge, ready-to-buy).
  • Approval Queue (HITL) — agent-proposed purchases parked for one-click approve / deny; nothing settles until you approve.
  • Ledger — the append-only entries.
  • Audit Trail — the hash-chained log with a one-click verify chain button.

Proposal / HITL approval lifecycle

propose : trigger gate → select best product within caps → policy.authorize
          → PARK a PROPOSED row   (NO money moves; authorize is a pure read)
approve : per-vault lock → re-authorize + velocity check → place_hold →
          checkout → capture  (each idempotent, each audited; on ANY engine
          error the hold is released = zero net spend) → APPROVED
deny    : release any hold (idempotent) → DENIED

The client never supplies an amount — the engine computes the price and re-checks the per-txn cap, remaining sub-budget, and the hard ceiling.

Security & robustness

Built to survive a DAST scan. Controls live in webapp/security.py, webapp/auth.py, and webapp/robustness.py:

  • Auth — PBKDF2-HMAC-SHA256, per-user random salt, 600k iterations, constant-time compare; unknown-user logins do equal work (no timing oracle). No plaintext, no fast/unsalted hashes.
  • Per-vault authorization — assert_owner runs on every vault-scoped endpoint before any engine access; cross-tenant access returns 404 (not 403) so a foreign vault's existence is not disclosed (anti-IDOR).
  • CSRF — double-submit token bound to the signed session, required (constant-time match) on every state-changing request.
  • Security headers — CSP (script-src 'self', object-src 'none', frame-ancestors 'none'), nosniff, X-Frame-Options: DENY, Referrer-Policy, HSTS over TLS; the server banner is stripped.
  • Input validation — strict Pydantic; amounts are validated as int cents server-side and the engine ceiling is always re-checked, never trusted.
  • Rate limiting — per-identity buckets on auth (10/min) and spend (30/min).
  • Per-vault write serialization — an async per-vault lock + SQLite WAL + busy_timeout so concurrent requests can't double-spend.
  • Idempotency — mutating endpoints cache their response per (key, scope); a retry returns the same result without re-executing.
  • Stale-hold reaper — a background task releases holds / expires proposals past a TTL so funds are never stranded.
  • Velocity limits — max buys and max $ per rolling 24h window per vault.
  • Leak-free errors — generic 4xx/5xx codes; stack traces logged server-side only.

Run the app

# 1) seed a demo user + funded vault + mandates + one parked proposal
python -m webapp.seed

# 2) start the server (localhost-only by default)
python -m webapp.server                 # http://127.0.0.1:8800/

# 3) log in with the seeded demo credentials
#      username: demo
#      password: Demo-Passw0rd-2026!

# web-layer tests (engine stays untouched)
python -m pytest tests_web/ -q

For a clean re-seed, delete webapp/web.db* and webapp/engine.db* first, or point AE_WEB_DB / AE_ENGINE_DB at fresh files. Set AE_SESSION_SECRET in production. See DESIGN.md §9 for the full web architecture.

Ver o original no GitHub

Bom para

Relacionados