Achlens

Achlens

[PyPI] [Python] [License] [CI]

Achlens is a local-first Python MCP server and CLI for inspecting synthetic ACH files. It parses fixed-width records, validates structure and control totals, explains findings, masks sensitive fields, repairs derived controls, and generates deterministic test files. It never transmits ACH files or makes bank/network calls.

Use synthetic data only. This project is not a bank gateway, compliance advisor, or transmission system.

Quick Start

uv syncuv run achlens --helpuv run achlens validate tests/fixtures/golden/sample_valid.achuv run achlens generate --sec PPD --entries 5 --seed 7 > synthetic.ach

In Windows PowerShell, use an explicit ASCII encoding because PowerShell's default > redirection can write UTF-16 output that is not valid ACH text:

uvx achlens generate --sec PPD --entries 5 --seed 7 |	Set-Content -Encoding ascii synthetic.ach

Run the MCP server over stdio:

uv run achlens serve

MCP Client Setup

Install the published package with uvx; it starts the server locally over stdio and does not transmit ACH files.

VS Code and Copilot

Create .vscode/mcp.json in your workspace:

{  "servers": {    "achlens": {      "type": "stdio",      "command": "uvx",      "args": ["achlens"]    }  }}

Claude Desktop

Add the following entry to the mcpServers object in Claude Desktop's MCP configuration:

{  "achlens": {    "command": "uvx",    "args": ["achlens"]  }}

By default, MCP tools accept ACH content directly but cannot read local paths. To allow read-only access to a specific directory, set ACHLENS_ALLOWED_ROOTS in the server environment to that directory. Use synthetic ACH data only.

The MCP server exposes validation, summaries, parsed-record paging, control explanations, routing checks, code lookup, synthetic generation, and control repair. See docs/tools.md for the current tool surface.

Sensitive fields are masked by default. Configure ACHLENS_ALLOWED_ROOTS to enable MCP path inputs; otherwise provide file content directly. See SECURITY.md for the data and write boundaries.

Development

This project uses uv.

uv syncuv run achlens --helpPYTHONPATH=. uv run pytest -quv run ruff check .uv run ruff format --check .uv run mypy --strict src

Without uv

The CLI and test suite also work with plain pip:

pip install -e . pytestachlens --helpachlens validate tests/fixtures/golden/sample_valid.achachlens generate --sec PPD --entries 5 --seed 7PYTHONPATH=. pytest

Set PYTHONPATH=. from the repository root when running tests so fixture and script imports resolve. In Windows PowerShell, use $env:PYTHONPATH = "."; pytest.

Never add real payment data, account numbers, or ACH files to this repository.