achlens

Achlens

Achlens は、合成 ACH ファイルを検査する、ローカルファーストの Python 製 MCP サーバーおよび CLI です。固定幅レコードを解析し、構造と制御合計を検証し、検出結果を説明して、機密フィールドをマスキングし、派生した制御値を修復し、決定的なテストファイルを生成します。ACH ファイルを送信したり、銀行やネットワークへの呼び出しを行ったりすることはありません。

合成データのみを使用してください。このプロジェクトは、銀行ゲートウェイ、コンプライアンスアドバイザー、または送信システムではありません。

クイックスタート

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

Windows PowerShell では、明示的に ASCII エンコーディングを指定してください。PowerShell の既定の > リダイレクトでは、ACH テキストとして有効でない UTF-16 出力が書き込まれることがあります。

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

stdio 経由で MCP サーバーを実行します。

uv run achlens serve

MCP クライアントの設定

公開パッケージを uvx でインストールします。サーバーはローカルで stdio 経由に起動し、ACH ファイルを送信しません。

VS Code と Copilot

ワークスペースに .vscode/mcp.json を作成します。

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

Claude Desktop

Claude Desktop の MCP 設定にある mcpServers オブジェクトに、次のエントリを追加します。

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

既定では、MCP ツールは ACH の内容を直接受け取りますが、ローカルパスを読み取ることはできません。特定のディレクトリへの読み取り専用アクセスを許可するには、サーバー環境で ACHLENS_ALLOWED_ROOTS にそのディレクトリを設定します。合成 ACH データのみを使用してください。

MCP サーバーは、検証、概要、解析済みレコードのページ表示、制御値の説明、ルーティングチェック、コード検索、合成データ生成、制御値の修復を提供します。現在のツール一覧については、docs/tools.md を参照してください。

機密フィールドは既定でマスキングされます。MCP のパス入力を有効にするには ACHLENS_ALLOWED_ROOTS を設定してください。設定しない場合は、ファイルの内容を直接指定してください。データと書き込みの境界については、SECURITY.md を参照してください。

開発

このプロジェクトでは uv を使用します。

uv sync
uv run achlens --help
PYTHONPATH=. uv run pytest -q
uv run ruff check .
uv run ruff format --check .
uv run mypy --strict src

uv を使用しない場合

CLI とテストスイートは、通常の pip でも動作します。

pip install -e . pytest
achlens --help
achlens validate tests/fixtures/golden/sample_valid.ach
achlens generate --sec PPD --entries 5 --seed 7
PYTHONPATH=. pytest

テストを実行する際は、フィクスチャとスクリプトのインポートを解決できるよう、リポジトリのルートで PYTHONPATH=. を設定してください。Windows PowerShell では、$env:PYTHONPATH = "."; pytest を使用します。

実際の決済データ、口座番号、ACH ファイルを、このリポジトリに追加しないでください。