Dichiarazione-MCP

Local-first MCP server for assisting a user with the preparation and review of Italian tax declarations through a controlled browser session.

Status: pre-alpha architecture and safety scaffold. This repository does not yet provide a production-ready tax service and must not be used to submit real declarations or payments.

Product goal

The server will let an LLM:

• work inside a user-authenticated Agenzia delle Entrate browser session;

• inspect and organize tax documents;

• read, compare, and edit declaration drafts;

• run deterministic validations and prepare a review package;

• stop at a hard approval boundary before any external, legally relevant action.

The user performs or approves SPID authentication. Credentials, OTPs, session cookies, and browser storage are never exposed through MCP tools or model context.

Related MCP server: Networking MCP

Non-negotiable boundary

The agent may autonomously read and edit draft state. It may not, without a separate local approval bound to an exact immutable snapshot:

• submit, cancel, or amend a declaration;

• transmit or pay an F24;

• change an IBAN or payment destination;

• create, revoke, or alter a delegation;

• send an application, response, or communication with legal effect;

• perform any action that creates a protocol, receipt, debit, or irreversible external effect.

Planned architecture

LLM client
   │ MCP
   ▼
Local MCP server
   ├── capability policy and typed tools
   ├── document/tax workflow services
   ├── review and approval service
   ├── append-only redacted audit trail
   └── browser adapter (Playwright)
             │
             ▼
  user-controlled Chromium profile
             │
             ▼
     Agenzia delle Entrate portals

See docs/PRODUCT_SPEC.md, docs/ARCHITECTURE.md, and docs/SECURITY.md.

Safe synthetic mode

The repository includes an explicit, network-free synthetic composition for local development. It uses only in-memory data and stops after creating the immutable review package; it cannot issue an approval or perform an external effect.

uv sync --extra dev
uv run dichiarazione-mcp-synthetic-demo

The demo reads versioned normalized evidence, selects only opaque evidence IDs, performs a receipt-backed mutation, reverts it exactly once, reapplies the reviewed change, and stops at review_prepared. Its JSON summary includes the opaque mutation/reversion IDs and keeps external_effect_exposed equal to false. To run the same synthetic composition as a local stdio MCP server:

uv run dichiarazione-mcp --synthetic

The ordinary entry point remains fail-closed unless --synthetic is supplied:

uv run dichiarazione-mcp

In explicit synthetic mode, read_normalized_evidence exposes only the versioned bounded evidence contract: opaque IDs, allowlisted draft fields, canonical values, hashes, flags, and opaque provenance references. Raw documents, HTML, paths, source text, summaries/instructions, credentials, cookies, selectors, and browser artifacts are absent from its schema. The server derives the synthetic guarantee from its trusted composition and verifies the current draft's synthetic_data=true; it does not trust a client-supplied mode flag.

mutate_declaration_draft returns a typed {draft, receipt} result. The immutable receipt binds the opaque mutation ID, current session, masked identity/delegation, declaration reference, field, canonical before/after values, and adjacent versions. revert_declaration_mutation accepts that exact receipt plus the optimistic current version and consumes it once. Fabrication, tampering, replay, session or identity rotation, value/version drift, and provider mismatch fail closed. Any inconsistency observed only after a possible write or revert becomes the non-retriable draft_mutation_uncertain error with reconciliation_required=true; the server never retries automatically.

In fail-closed mode the same MCP tool surface exists, but dependency-backed operations—including normalized evidence—return a safe dependency_unavailable error. Neither mode contacts Poste, SPID, Agenzia delle Entrate, or any other network service.

Development model

Implementation is split among three developers, one AI engineer, and two independent reviewers. The Manager owns integration, commits, and pushes. Agents must not commit or push independently.

License

Apache-2.0. See LICENSE.