# HOLCO FEC Controls

Deterministic, explainable controls for synthetic French accounting export
(FEC-like) data, exposed as a local MCP server for Claude and other compatible
clients.

> Deterministic when possible. AI when necessary. Human when accountable.

This repository is a clean-room public example. It contains no production code,
customer data, credentials or internal HOLCO endpoints. It is not tax advice and
does not certify legal or fiscal compliance.

## Controls

- required column presence;
- parseable `YYYYMMDD` dates;
- decimal debit and credit amounts;
- debit/credit balance for every journal entry;
- duplicate-line detection.

Every finding contains a stable code, severity, line or entry reference and a
human-readable explanation. The AI client presents the result; it does not
silently change the deterministic verdict.

## Control contract

The server separates planning from execution:

1. `plan_fec_control` declares controls, assumptions and decisions that require
   human input;
2. `analyze_fec_text` runs every applicable deterministic control;
3. the result binds evidence to the source with SHA-256 hashes and locators,
   without echoing accounting rows;
4. every planned control is reported as `PASS`, `REVIEW`, `FAIL` or `NOT_RUN`.

Business plausibility is deliberately `NOT_RUN` until an entity-approved policy
or benchmark is provided. A generic model opinion cannot turn a failed
accounting invariant into a pass. Consequently, a technically clean file has a
`deterministic_outcome` of `PASS` but remains globally `REVIEW` while the
declared business check is not run.

## Run the tests

```bash
python -m pip install -e '.[mcp]'
python -m unittest discover -s tests -v
```

## Connect to Claude Desktop

After installation, add this local server to your Claude Desktop MCP
configuration:

```json
{
  "mcpServers": {
    "holco-fec-controls": {
      "command": "holco-fec-mcp"
    }
  }
}
```

Restart Claude Desktop, then ask it to call `analyze_fec_text` with FEC content.
The tool accepts text rather than a filesystem path, preventing unrestricted
file reads by the server. Keep real accounting exports within an environment
whose confidentiality rules you control.

## MCP tools

- `list_fec_controls`: returns the public control catalogue.
- `plan_fec_control`: previews scope, assumptions and human decisions.
- `analyze_fec_text`: analyses tab-separated content and returns structured
  results, evidence hashes, completeness and the stop reason.

See [`examples/synthetic_fec.txt`](examples/synthetic_fec.txt) for a fictitious
balanced entry.

## Normative anchoring

The FEC (fichier des écritures comptables) is defined by article A.47 A-1 of
the French Livre des procédures fiscales and the arrêté of 29 July 2013: 18
normative fields in a fixed order, `YYYYMMDD` dates, and a normalised file
naming scheme. The DGFiP publishes an open-source structural checker, "Test
Compta Demat" (CeCILL licence, official DGFiP GitHub repository); article
1729 D of the CGI defines the sanction for a non-compliant file.

The controls in this repository target a subset of that referential on
synthetic data. Like the DGFiP checker itself, a green result is not an
attestation of conformity and does not bind anyone: it is a reproducible
technical statement about the supplied bytes. The full doctrine mapping of
the HOLCO control framework is maintained in the companion repository
[`holco-finance-controls`](https://github.com/holco-apps/holco-finance-controls)
(`DOCTRINE.md`).

## Licence

MIT. Copyright © 2026 HOLCO INVEST.