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

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

1. Check that cwd in claude_desktop_config.json is an absolute path
2. Make sure uv is in your PATH (try running uv --version in terminal)
3. 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