jPOS MCP Server

mcp-name: io.github.mohisyed/jpos-mcp-server

The first open-source MCP server for jPOS and ISO 8583.

Claude validating a real ISO 8583 financial transaction request using deterministic tools. No guessing — every answer comes from verified data.

An MCP server that gives AI agents (Claude, Cursor, VS Code Copilot) deterministic, verified access to ISO 8583 field specs, MTI decoding, jPOS packager XML generation, deploy descriptor validation, message building, and jPOS documentation search.

No more guessing packager class names. No more scrolling a 300-page PDF. Call a tool, get the right answer.

Quickstart

Prerequisites: Python 3.11+ and uv package manager.

# 1. Clone and install
git clone https://github.com/mohisyed/JPOS-MCP.git
cd JPOS-MCP
uv sync

# 2. (Optional) Set up the knowledge base for semantic search
mkdir -p knowledge/sources
curl -o knowledge/sources/proguide.pdf https://jpos.org/doc/proguide-draft.pdf
uv run python knowledge/ingest.py

# 3. Add to Claude Desktop (see Claude Desktop Setup below)

All 6 tools work immediately after step 1. Step 2 enables the search_jpos RAG tool with real documentation.

Tools

Tool	Namespace	What It Does	Example Input
`lookup_field`	`iso`	Return full ISO 8583 field spec (name, format, jPOS class, max length)	`field_number: 35`
`decode_mti`	`iso`	Decode MTI into version, class, function, origin + expected response	`mti: "0200"`
`generate_packager`	`jpos`	Generate complete GenericPackager XML from plain English	`"Visa auth fields 2,3,4,7,11,35,41,42 BCD"`
`validate_descriptor`	`jpos`	Lint a Q2 deploy descriptor (channel, QMUX, TM rules)	`xml_content: "<qmux>..."`
`build_message`	`msg`	Validate ISO 8583 field dict (mandatory fields, lengths, PAN safety)	`{"0":"0200", "2":"4111..."}`
`search_jpos`	`docs`	Semantic search over jPOS Programmer's Guide (RAG)	`"How to configure QMUX"`

Why deterministic tools instead of LLM inference?

LLMs can guess that field 35 uses IFA_LLVAR, but they sometimes hallucinate class names like IFA_LLTRACK2 (doesn't exist). Our tools read from data/iso_fields.json — a verified lookup table — so the answer is always correct. The AI decides which tool to call; our code provides the facts.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      AI AGENT CLIENTS                           │
│  Claude Desktop  ·  Claude API  ·  Cursor  ·  VS Code Copilot  │
└──────────────────────────┬──────────────────────────────────────┘
                           │  MCP Protocol (JSON-RPC 2.0)
              stdio (local) / Streamable HTTP (Docker)
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│           jpos-mcp-server  (Python / FastMCP v3.1.1)            │
│                                                                  │
│  main.py                                                         │
│  ├── iso_server    [iso]   lookup_field, decode_mti              │
│  ├── jpos_server   [jpos]  generate_packager, validate_descriptor│
│  ├── msg_server    [msg]   build_message                         │
│  └── rag_server    [docs]  search_jpos                           │
│                                                                  │
│  ┌──────────────┐   ┌─────────────────────────────────────────┐  │
│  │  DATA LAYER   │   │  KNOWLEDGE LAYER                        │  │
│  │  iso_fields   │   │  ChromaDB + sentence-transformers       │  │
│  │  mti_table    │   │  Chunked jPOS Programmer's Guide        │  │
│  │  mandatory    │   │  + project docs (ISO 8583 deep dive)    │  │
│  └──────────────┘   └─────────────────────────────────────────┘  │
│  core/ — timeout guardrails, PAN detection, safe logging         │
└──────────────────────────────────────────────────────────────────┘

Sub-server composition

The server is split into 4 domain-specific sub-servers mounted via FastMCP.mount(). Each sub-server is independently testable — a bug in the RAG pipeline doesn't prevent ISO field lookups from working. Adding a new domain is one file + one mount() call in main.py.

Timeout guardrails

Every tool is wrapped with @with_timeout() using asyncio.wait_for(). If a tool hangs (e.g., ChromaDB cold start), it returns a structured error dict instead of blocking the entire MCP server. Timeout tiers:

Tier	Timeout	Tools
Fast	2s	`lookup_field`, `decode_mti`
Medium	5s	`build_message`, `validate_descriptor`
Slow	10s	`generate_packager`
RAG	15s	`search_jpos`

Testing

Why we test

Payment systems have zero tolerance for wrong answers. A bad packager class name (IFA_LLVAR vs IFB_LLHEX) causes cryptic byte-level parsing errors that take hours to debug. Our tests verify that every tool returns correct, deterministic results across all input types.

Running tests

# Install dev dependencies (pytest, ruff, black, coverage)
uv sync --dev

# Run all 114 tests (unit + MCP integration + E2E workflows)
uv run pytest tests/ -v

# Run a single test file
uv run pytest tests/test_iso.py -v

# Run a single test function
uv run pytest tests/test_iso.py::test_decode_mti_request -v

# Run with coverage report (target: 80%+, current: 91%)
uv run pytest tests/ --cov=servers --cov=core --cov-report=term-missing

# Lint (must pass with zero errors)
uv run ruff check .

# Format
uv run black .

Test structure (114 tests, 3 layers)

File	Layer	What it covers
`test_iso.py`	unit	`lookup_field`, `decode_mti` — valid/invalid fields, MTI categories
`test_jpos_tools.py`	unit	`generate_packager` (BCD/ASCII), `validate_descriptor` (QMUX, channel-adaptor, txnmgr, malformed XML)
`test_message.py`	unit	`build_message` — valid messages, missing fields, length violations, PAN rejection
`test_rag.py`	unit	Query expansion, mock collection responses, empty collection handling
`test_timeout.py`	unit	`@with_timeout` — guardrail fires, fast passes, exceptions caught
`test_validators.py`	unit	`luhn_check`, `contains_likely_real_pan` — Luhn edge cases, separators, test PAN whitelist
`test_logging.py`	unit	`PaymentSafeFormatter` redaction, stderr handler config
`test_mcp_integration.py`	integration	Tool registration, JSON Schema generation, end-to-end MCP protocol calls
`test_e2e.py`	E2E workflow	Multi-step workflows: Visa auth packager build, reversal debugging, deploy descriptor validation, security boundary, RAG via MCP, system health, error handling

Writing new tests

When adding a tool, cover three categories:

Happy path — valid input returns expected output
Invalid input — bad types, out-of-range values, malformed data return structured errors
Edge cases — boundary values, empty inputs, PCI-sensitive data

All tools are async def, so use @pytest.mark.asyncio:

@pytest.mark.asyncio
async def test_my_new_tool():
    result = await my_tool("valid input")
    assert result["expected_key"] == "expected_value"

Knowledge Base (RAG)

The search_jpos tool uses two-stage hybrid retrieval over jPOS documentation: a bi-encoder (mpnet) for fast candidate retrieval, followed by a cross-encoder reranker for high-precision ordering.

How it works

Ingestion — PDFs and markdown files are cleaned (boilerplate, TOC dot-leaders, page headers stripped) and split into 200-word chunks with 40-word overlap. Low-signal chunks are filtered out at ingest time.
Embedding — Each chunk is encoded into a 768-dimensional vector using all-mpnet-base-v2 and stored in ChromaDB.
Query expansion — Short or jargon-heavy queries (e.g. "STAN", "IFB_LLHEX") get domain context added before embedding so the model has enough signal to disambiguate.
Stage 1 retrieval — Top 25 candidates fetched via cosine similarity.
Stage 2 rerank — Cross-encoder (ms-marco-MiniLM-L-6-v2) scores each (query, chunk) pair by attending across both inputs. This is significantly more accurate than cosine alone.
Display score — Combination of cross-encoder + cosine + rank-position bonus, returned as the top 5 chunks.

The cross-encoder loads lazily on first call (~1s). Falls back to keyword-overlap reranking if the model can't load (offline environments).

Setting up the knowledge base

# Download the jPOS Programmer's Guide (5.3MB PDF)
mkdir -p knowledge/sources
curl -o knowledge/sources/proguide.pdf https://jpos.org/doc/proguide-draft.pdf

# Run ingestion (first run downloads ~80MB mpnet + ~80MB cross-encoder)
uv run python knowledge/ingest.py

The ingest script processes:

PDFs from knowledge/sources/*.pdf — page-by-page chunking with cleanup
Markdown from docs/*.md — section-aware chunking (splits on ## headings)
Markdown from knowledge/sources/*.md — for any additional docs you add

Ingestion is idempotent — running it again skips existing chunks and only adds new ones.

Default knowledge base after a full ingest: ~786 chunks across the jPOS Programmer's Guide, ISO 8583-1:2003 spec, Wikipedia reference, jPOS tutorial pages, and project docs.

Adding your own documents

Drop any .pdf or .md files into knowledge/sources/ and re-run:

uv run python knowledge/ingest.py

Good candidates:

ISO 8583 reference guides
Your organization's interchange spec documentation
jPOS tutorial pages (save as markdown)
GenericPackager XML examples with annotations

Search quality

Scores are calibrated for the cross-encoder + mpnet pipeline:

Score	Quality	Meaning
0.55+	Strong	Direct answer in the chunk
0.40–0.55	Good	Relevant context, may need synthesis
0.25–0.40	Partial	Tangentially related
<0.25	(filtered)	Below noise floor — not returned

Benchmark across 25 representative queries: 0.886 average score, 100% strong results.

Docker

Build and run

# Build and start (HTTP transport)
docker compose -f docker/docker-compose.yml up -d --build

# View logs
docker compose -f docker/docker-compose.yml logs -f

# Re-ingest docs after adding new sources
docker compose -f docker/docker-compose.yml exec jpos-mcp uv run python knowledge/ingest.py

# Check health
docker compose -f docker/docker-compose.yml exec jpos-mcp curl -sf http://localhost:8000/health

Docker architecture

Base image: python:3.11-slim
Embedding model pre-downloaded at build time (avoids 30-60s cold start)
Non-root user (appuser:1001) for security
Persistent volume for ChromaDB data (survives container restarts)
Healthcheck every 30s on /health

Claude Desktop with Docker

{
  "mcpServers": {
    "jpos-expert": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Claude Desktop Setup

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jpos-expert": {
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "/ABSOLUTE/PATH/TO/JPOS-MCP"
    }
  }
}

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "jpos-expert": {
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "C:\\ABSOLUTE\\PATH\\TO\\JPOS-MCP"
    }
  }
}

After saving, restart Claude Desktop. All tools appear in the hammer (tools) menu.

Verifying it works

Ask Claude: "What's the jPOS packager class for field 35?"

Claude should call lookup_field(35) and return the exact spec — IFA_LLVAR for ASCII, IFB_LLHEX for BCD — not a guess.

MCP Inspector

The MCP Inspector is a browser-based UI for testing tools interactively:

uv run fastmcp dev inspector main.py:mcp

This opens a browser at http://localhost:6274 where you can:

See all registered tools and their JSON Schema
Call any tool with custom inputs
Inspect responses in real time
Debug tool errors without needing Claude Desktop

Security

This server is designed with PCI DSS awareness:

Real PANs are rejected — The Luhn algorithm detects real card numbers in any tool input. Only test PANs (4111111111111111, 5500005555555559, etc.) are accepted. This runs before any other processing.
Sensitive fields redacted from logs — PaymentSafeFormatter strips fields 2 (PAN), 35 (Track 2), 45 (Track 1), 52 (PIN), 55 (EMV), and 64 (MAC) from all log output.
stderr-only logging — stdout is reserved for the JSON-RPC stream (stdio transport). A single print() would corrupt the protocol.
Non-root Docker — Container runs as appuser:1001.
No credentials — The server stores no keys, tokens, or secrets.
Pinned dependencies — fastmcp==3.1.1 exact pin prevents supply chain surprises.
Hardcoded tool descriptions — Tool descriptions are in Python decorators, never loaded from external data (prevents injection).

What must never pass through this server

Data	Reason
Real PANs	PCI DSS Requirement 3
Track 1/2/3 data	Prohibited after authorization
CVV/CVV2/CVC2	PCI DSS 3.2.1
Real cryptographic keys	HSM-managed only
PIN blocks	Must not traverse uncontrolled layers

Troubleshooting

`ModuleNotFoundError: No module named 'fastmcp'`

Dependencies aren't installed. Run:

uv sync

`search_jpos` returns "Knowledge base not initialized"

ChromaDB hasn't been populated. Run:

mkdir -p knowledge/sources
curl -o knowledge/sources/proguide.pdf https://jpos.org/doc/proguide-draft.pdf
uv run python knowledge/ingest.py

Claude Desktop doesn't show tools

Check that cwd in claude_desktop_config.json is an absolute path
Make sure uv is in your PATH (try running uv --version in terminal)
Restart Claude Desktop completely (quit + reopen, not just close window)

Tests fail with import errors

Make sure you installed dev dependencies:

uv sync --dev

`print()` broke the stdio transport

Any stdout output corrupts JSON-RPC. Find and remove print() statements. Use logging.getLogger(__name__).info() instead — it writes to stderr.

Timeout errors on `search_jpos`

First call after startup can take 5-10s (ChromaDB + embedding model cold start). The 15s timeout accommodates this. If it persists, check that knowledge/chroma_db/ exists and has data.

Roadmap

V1 — MVP — 6 tools, Claude Desktop, Docker, 114 tests (91% coverage), cross-encoder reranked RAG, GitHub Actions CI/security, issue templates, SECURITY.md
V2 — Enhanced — Java sidecar (live pack/unpack), custom interchange specs, jPOS log parser, OAuth 2.1, PyPI package, MCP registry submission
V3 — Platform — Hosted deployment, multi-spec (Visa/MC/Amex/Discover), horizontal scaling, transaction analytics

See docs/roadmap-and-architecture.md for full details.

Contributing

See CONTRIBUTING.md for setup instructions and guidelines.

License

MIT

Name		Name	Last commit message	Last commit date
.claude		.claude
.github		.github
core		core
data		data
docker		docker
docs		docs
examples		examples
knowledge		knowledge
servers		servers
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
main.py		main.py
pyproject.toml		pyproject.toml
server.json		server.json
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation

jPOS MCP Server

Table of Contents

Quickstart

Tools

Why deterministic tools instead of LLM inference?

Architecture

Sub-server composition

Timeout guardrails

Testing

Why we test

Running tests

Test structure (114 tests, 3 layers)

Writing new tests

Knowledge Base (RAG)

How it works

Setting up the knowledge base

Adding your own documents

Search quality

Docker

Build and run

Docker architecture

Claude Desktop with Docker

Claude Desktop Setup

macOS

Windows

Verifying it works

MCP Inspector

Security

What must never pass through this server

Troubleshooting

ModuleNotFoundError: No module named 'fastmcp'

search_jpos returns "Knowledge base not initialized"

Claude Desktop doesn't show tools

Tests fail with import errors

print() broke the stdio transport

Timeout errors on search_jpos

Roadmap

Contributing

License

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`ModuleNotFoundError: No module named 'fastmcp'`

`search_jpos` returns "Knowledge base not initialized"

`print()` broke the stdio transport

Timeout errors on `search_jpos`