jPOS MCP Server

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.

---

Table of Contents

• Quickstart
• Tools
• Architecture
• Testing
• Knowledge Base (RAG)
• Docker
• Claude Desktop Setup
• MCP Inspector
• Security
• Troubleshooting
• Roadmap
• Contributing

---

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

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:

---

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)

Writing new tests

When adding a tool, cover three categories:

1. Happy path — valid input returns expected output
2. Invalid input — bad types, out-of-range values, malformed data return structured errors
3. 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

1. 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.
2. Embedding — Each chunk is encoded into a 768-dimensional vector using all-mpnet-base-v2 and stored in ChromaDB.
3. 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.
4. Stage 1 retrieval — Top 25 candidates fetched via cosine similarity.
5. 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.
6. 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:

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/Cla