# 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.

## 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

```text
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/PRODUCT_SPEC.md), [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md), and [`docs/SECURITY.md`](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.

```bash
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:

```bash
uv run dichiarazione-mcp --synthetic
```

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

```bash
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`](LICENSE).