pactus-mcp 1.0.0__tar.gz

pactus_mcp-1.0.0/.gitattributes

@@ -0,0 +1,6 @@
+* text=auto eol=lf
+*.xsd binary
+*.xml text eol=lf
+*.py text eol=lf
+*.toml text eol=lf
+*.md text eol=lf

pactus_mcp-1.0.0/.github/dependabot.yml

@@ -0,0 +1,40 @@
+version: 2
+updates:
+  # Python dependencies via uv (Dependabot reads pyproject.toml + uv.lock natively)
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "07:00"
+      timezone: "Europe/Kyiv"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "python"
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+    groups:
+      # Group all dev-tooling updates into one PR per week
+      dev-tooling:
+        patterns:
+          - "ruff"
+          - "mypy"
+          - "pytest*"
+
+  # GitHub Actions — keeps the SHAs we pinned from rotting
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "07:00"
+      timezone: "Europe/Kyiv"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "github-actions"
+    commit-message:
+      prefix: "ci"
+      include: "scope"

pactus_mcp-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,150 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Lint, type-check, tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+
+      - name: Install Python 3.12
+        run: uv python install 3.12
+
+      - name: Check lockfile is in sync with pyproject.toml
+        run: uv lock --check
+
+      - name: Sync dependencies (including [semantic] extras)
+        run: uv sync --frozen --all-extras
+
+      - name: Generate xsdata Pydantic models
+        run: uv run python scripts/generate_models.py
+
+      - name: Verify generated models match canonical hashes
+        working-directory: src/pactus/generated
+        run: sha256sum -c GENERATED_HASHES.txt
+
+      - name: Ruff lint
+        run: uv run ruff check
+
+      - name: Ruff format check
+        run: uv run ruff format --check
+
+      - name: Mypy strict
+        run: uv run mypy
+
+      - name: Run pytest with coverage gate
+        run: uv run pytest -q
+
+  sbom:
+    name: SBOM generation
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Generate SBOM (CycloneDX 1.6)
+        uses: anchore/sbom-action@e22c389904149dbc22b58101806040fa8d37a610 # v0.24.0
+        with:
+          format: cyclonedx-json
+          output-file: pactus-mcp.cdx.json
+          upload-artifact: false
+
+      - name: Generate SBOM (SPDX 3.0.1)
+        uses: anchore/sbom-action@e22c389904149dbc22b58101806040fa8d37a610 # v0.24.0
+        with:
+          format: spdx-json
+          output-file: pactus-mcp.spdx.json
+          upload-artifact: false
+
+      - name: Upload SBOM artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: sbom
+          path: |
+            pactus-mcp.cdx.json
+            pactus-mcp.spdx.json
+
+  vuln-scan:
+    name: Grype vulnerability scan
+    needs: sbom
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Download SBOM artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: sbom
+
+      # Grype scans the full SBOM including dev dependencies; there is no
+      # mechanism to exclude dev-only packages at this layer. A finding in a
+      # dev dep (e.g. pytest, ruff) will fail this job.
+      - name: Grype scan (fail on high+)
+        uses: anchore/scan-action@e1165082ffb1fe366ebaf02d8526e7c4989ea9d2 # v7.4.0
+        with:
+          sbom: pactus-mcp.cdx.json
+          severity-cutoff: high
+          fail-build: true
+
+  workflow-audit:
+    name: Workflow audit (zizmor)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Install zizmor
+        run: pipx install zizmor
+
+      - name: Verify zizmor version
+        run: zizmor --version
+
+      - name: Audit workflows
+        run: zizmor .github/workflows/
+
+  dependency-review:
+    name: Dependency review
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Dependency review
+        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
+        with:
+          fail-on-severity: high

pactus_mcp-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,96 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      target:
+        description: 'Publish target'
+        required: true
+        type: choice
+        options:
+          - testpypi
+          - pypi
+
+# Deny all permissions at the workflow level; each job grants only what it needs.
+permissions: {}
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: false
+
+      - name: Install Python 3.12
+        run: uv python install 3.12
+
+      - name: Build
+        run: uv build
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      # id-token: write above enables OIDC; pypa/gh-action-pypi-publish generates
+      # Sigstore attestations automatically when that permission is set.
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
+
+      - name: Create GitHub Release
+        if: github.event_name == 'push'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: gh release create "$TAG" dist/* --title "$TAG"

pactus_mcp-1.0.0/.gitignore

@@ -0,0 +1,17 @@
+.idea/
+.env
+*.env
+build/
+.claude/settings.local.json
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.ty_cache/
+.coverage
+htmlcov/
+legacy/
+dist/
+*.egg-info/

pactus_mcp-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12

pactus_mcp-1.0.0/.xsdata.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Config xmlns="http://pypi.org/project/xsdata">
+  <Output maxLineLength="100" subscriptableTypes="true" unionType="true">
+    <Package>pactus.generated</Package>
+    <Format repr="true" eq="true" order="false" unsafeHash="false" frozen="false" slots="false" kwOnly="false">pydantic</Format>
+    <Structure>filenames</Structure>
+    <DocstringStyle>reStructuredText</DocstringStyle>
+    <RelativeImports>true</RelativeImports>
+    <CompoundFields defaultName="choice"/>
+  </Output>
+  <Conventions>
+    <ClassName case="pascalCase" safePrefix="type"/>
+    <FieldName case="snakeCase" safePrefix="value"/>
+    <ConstantName case="screamingSnakeCase" safePrefix="value"/>
+    <ModuleName case="snakeCase" safePrefix="mod"/>
+    <PackageName case="snakeCase" safePrefix="pkg"/>
+  </Conventions>
+</Config>

pactus_mcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denis Karlinsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pactus_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: pactus-mcp
+Version: 1.0.0
+Summary: Production-grade MCP server for ISO 20022 payment message processing
+Project-URL: Repository, https://github.com/deniskarlinsky/iso20022-mcp
+Project-URL: Documentation, https://github.com/deniskarlinsky/iso20022-mcp#readme
+Author: Denis Karlinsky
+License: MIT
+License-File: LICENSE
+Keywords: camt053,fintech,iso20022,mcp,pacs008,pain001,payments,swift
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.12
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: lxml>=5.0
+Requires-Dist: pydantic>=2.6
+Requires-Dist: xsdata-pydantic>=24.5
+Requires-Dist: xsdata[cli,lxml]>=26.2
+Provides-Extra: semantic
+Requires-Dist: numpy>=1.26; extra == 'semantic'
+Requires-Dist: sentence-transformers>=3.0; extra == 'semantic'
+Description-Content-Type: text/markdown
+
+# Pactus
+
+[![CI](https://github.com/deniskarlinsky/iso20022-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/deniskarlinsky/iso20022-mcp/actions/workflows/ci.yml)
+
+Pactus is an MCP server for parsing ISO 20022 payment messages directly from chat. It exposes five tools that let AI assistants inspect `pacs.008`, `pacs.002`, `pain.001`, and `camt.053` messages — the message types at the centre of the CBPR+ migration — without leaving the conversation. It is aimed at developers and bank-integration teams who need to read, debug, or explain ISO 20022 traffic during the transition away from MT messages.
+
+## Status
+
+Stable. Version 1.0.0 is on PyPI.
+
+```bash
+pip install pactus-mcp
+# or
+uv add pactus-mcp
+```
+
+## Quick start
+
+```bash
+git clone https://github.com/deniskarlinsky/iso20022-mcp
+cd iso20022-mcp
+uv sync
+uv run pytest
+```
+
+## Connecting to Claude Desktop
+
+Add Pactus to your Claude Desktop config:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux:** `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "pactus": {
+      "command": "uv",
+      "args": ["run", "--directory", "/absolute/path/to/iso20022-mcp", "pactus-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The Pactus tools will appear in the tools menu.
+
+## Available tools
+
+| Tool | Message type | Purpose |
+|---|---|---|
+| `ping` | — | Health check; returns service name and version. |
+| `parse_pacs008` | `pacs.008.001.08` | Parse a FI-to-FI Customer Credit Transfer. |
+| `parse_pacs002` | `pacs.002.001.10` | Parse a FI-to-FI Payment Status Report. |
+| `parse_pain001` | `pain.001.001.09` | Parse a Customer Credit Transfer Initiation. |
+| `parse_camt053` | `camt.053.001.08` | Parse a Bank-to-Customer Account Statement. |
+
+All four parse tools return a structured Pydantic model on success, or `{"error": "..."}` on failure. Errors never raise; the agent can explain what went wrong.
+
+## Tool reference
+
+### parse_pacs008
+
+`pacs.008` is the primary interbank credit transfer message and the mandatory format for all CBPR+ cross-border traffic from November 2025. It carries one or more credit transfer instructions between financial institutions, each with settlement amount, charge bearer, debtor, and creditor agents.
+
+<details>
+<summary>Example response</summary>
+
+```json
+{
+  "group_header": {
+    "message_id": "MSG20240508001",
+    "creation_datetime": "2024-05-08T10:00:00",
+    "number_of_transactions": 1,
+    "settlement_method": "CLRG"
+  },
+  "transactions": [
+    {
+      "end_to_end_id": "E2E20240508001",
+      "transaction_id": "TX20240508001",
+      "settlement_amount": {"value": "1000.00", "currency": "USD"},
+      "charge_bearer": "SHAR",
+      "debtor": {"name": "Acme Corporation"},
+      "debtor_agent": {"bic": "CHASUS33"},
+      "creditor": {"name": "Global Supplies Ltd"},
+      "creditor_agent": {"bic": "DEUTDEDB"}
+    }
+  ]
+}
+```
+
+</details>
+
+### parse_pacs002
+
+`pacs.002` is the status report sent in response to a `pacs.008`. It reports whether each transaction was accepted, rejected, or is in an intermediate state. Rejections carry one or more structured reason codes (e.g. `AC01` incorrect account, `AG01` transaction forbidden) that explain the outcome.
+
+<details>
+<summary>Example response</summary>
+
+```json
+{
+  "group_header": {
+    "message_id": "STS20260510001",
+    "creation_datetime": "2026-05-10T14:30:00"
+  },
+  "original_group_info": {
+    "original_message_id": "MSG20240508001",
+    "original_message_name_id": "pacs.008.001.08",
+    "original_creation_datetime": "2024-05-08T10:00:00",
+    "group_status": "ACSC"
+  },
+  "transaction_statuses": [
+    {
+      "original_end_to_end_id": "E2E-001",
+      "original_transaction_id": "TX-001",
+      "status": "ACSC",
+      "status_reasons": [],
+      "acceptance_datetime": "2026-05-10T14:29:45"
+    }
+  ]
+}
+```
+
+</details>
+
+### parse_pain001
+
+`pain.001` is the initiating message in a credit transfer flow, sent by a corporate or customer to their bank. It groups transactions into one or more `PaymentInformation` batches that share a debtor account, execution date, and service level. The LLM sees the full hierarchy: group header → batches → transactions.
+
+<details>
+<summary>Example response</summary>
+
+```json
+{
+  "group_header": {
+    "message_id": "PAIN20260510-001",
+    "creation_datetime": "2026-05-10T09:00:00",
+    "number_of_transactions": 1,
+    "control_sum": "1500.00",
+    "initiating_party_name": "ACME Corp"
+  },
+  "payment_informations": [
+    {
+      "payment_information_id": "BATCH-2026-05-10-A",
+      "payment_method": "TRF",
+      "requested_execution_date": "2026-05-12",
+      "debtor": {"name": "ACME Corp"},
+      "debtor_account_iban": "DE89370400440532013000",
+      "debtor_agent": {"bic": "DEUTDEFFXXX"},
+      "charge_bearer": "SLEV",
+      "service_level_code": "SEPA",
+      "transactions": [
+        {
+          "end_to_end_id": "E2E-PAIN-001",
+          "amount": {"value": "1500.00", "currency": "EUR"},
+          "creditor": {"name": "Acme Supplier SARL"},
+          "creditor_account_iban": "FR1420041010050500013M02606",
+          "remittance_info": ["Invoice 2026-0042"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+</details>
+
+### parse_camt053
+
+`camt.053` is the structured account statement sent by a bank to its customer. It reports opening and closing balances and individual debit/credit entries for a period, each optionally broken down to individual transaction details. It is the primary source for automated bank reconciliation.
+
+<details>
+<summary>Example response</summary>
+
+```json
+{
+  "group_header": {
+    "message_id": "CAMT053-SINGLE-001",
+    "creation_datetime": "2026-05-10T08:00:00"
+  },
+  "statements": [
+    {
+      "statement_id": "STMT-2026-05-09-001",
+      "account_iban": "DE89370400440532013000",
+      "account_currency": "EUR",
+      "balances": [
+        {
+          "type_code": "OPBD",
+          "amount": {"value": "10000.00", "currency": "EUR"},
+          "credit_debit": "CRDT",
+          "balance_date": "2026-05-09"
+        }
+      ],
+      "entries": [
+        {
+          "entry_ref": "NTRY-001",
+          "amount": {"value": "1500.00", "currency": "EUR"},
+          "credit_debit": "DBIT",
+          "status": "BOOK",
+          "booking_date": "2026-05-09",
+          "bank_tx_domain": "PMNT",
+          "bank_tx_family": "ICDT",
+          "bank_tx_subfamily": "ESCT"
+        }
+      ]
+    }
+  ]
+}
+```
+
+</details>
+
+## Security model
+
+- **XXE and entity-expansion hardening:** All four parsers reject input containing `<!DOCTYPE>` or `<!ENTITY>` declarations before any XML parsing occurs. This blocks XXE file-read, SSRF, and billion-laughs DoS patterns.
+- **Build integrity:** Generated xsdata models are SHA-256 verified in CI on every commit (`sha256sum -c GENERATED_HASHES.txt`). Regeneration is reproducible from the vendored XSDs.
+- **Supply chain:** GitHub Actions workflows use SHA-pinned action references (commit-hash `@` pins, not mutable tags).
+- **Distribution integrity:** PyPI artifacts are published via OIDC Trusted Publishing and signed with Sigstore. SBOMs (CycloneDX and SPDX) are generated and vulnerability-scanned on every CI run; release artifacts include the SBOM.
+- **Vulnerability disclosure:** See [SECURITY.md](SECURITY.md).
+
+## Architecture
+
+Pactus uses a hexagonal layout: `pactus/core/` is pure business logic with no MCP awareness, `mcp_server.py` is a thin FastMCP wrapper, and the generated xsdata models live in `pactus/generated/` and never escape `parsers.py`. See [architecture.md](architecture.md) for the diagram.
+
+## Development
+
+```bash
+uv run ruff check
+uv run ruff format
+uv run mypy
+uv run pytest
+```
+
+The project targets `mypy --strict`.
+
+## License
+
+MIT