jPOS MCP Server
mcp-name: io.github.mohisyed/jpos-mcp-server
The first open-source MCP server for jPOS and ISO 8583.
Potencia tu agente
El comando propio del publicador. No es un endpoint de PlugMCP.
Host a copy with our keys and logs.
uvx jpos-mcp-server==0.1.1Claude Code no tiene enlace de instalación para un comando local. Copia el comando de abajo y ejecútalo en una terminal.
claude mcp add mohisyed-jpos-mcp -- uvx jpos-mcp-server==0.1.1Ejecútalo en una terminal.
{ "mcpServers": { "mohisyed-jpos-mcp": { "command": "uvx", "args": [ "jpos-mcp-server==0.1.1" ] } }}claude_desktop_config.json
¿URL remota o un comando en tu máquina? En qué se diferencian las dos instalaciones
Ejecutar en PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
Abrir
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.
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.
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.
┌─────────────────────────────────────────────────────────────────┐
│ 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 │
└──────────────────────────────────────────────────────────────────┘
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.
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:
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.
# 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 .
When adding a tool, cover three categories:
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"
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.
all-mpnet-base-v2 and stored in ChromaDB.ms-marco-MiniLM-L-6-v2) scores each (query, chunk) pair by attending across both inputs. This is significantly more accurate than cosine alone.The cross-encoder loads lazily on first call (~1s). Falls back to keyword-overlap reranking if the model can't load (offline environments).
# 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:
knowledge/sources/*.pdf — page-by-page chunking with cleanupdocs/*.md — section-aware chunking (splits on ## headings)knowledge/sources/*.md — for any additional docs you addIngestion 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.
Drop any .pdf or .md files into knowledge/sources/ and re-run:
uv run python knowledge/ingest.py
Good candidates:
Scores are calibrated for the cross-encoder + mpnet pipeline:
Benchmark across 25 representative queries: 0.886 average score, 100% strong results.
# 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
python:3.11-slimappuser:1001) for security/health{
"mcpServers": {
"jpos-expert": {
"url": "http://localhost:8000/mcp"
}
}
}
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"
}
}
}
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.
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.
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:
This server is designed with PCI DSS awareness:
4111111111111111, 5500005555555559, etc.) are accepted. This runs before any other processing.PaymentSafeFormatter strips fields 2 (PAN), 35 (Track 2), 45 (Track 1), 52 (PIN), 55 (EMV), and 64 (MAC) from all log output.print() would corrupt the protocol.appuser:1001.fastmcp==3.1.1 exact pin prevents supply chain surprises.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
cwd in claude_desktop_config.json is an absolute pathuv is in your PATH (try running uv --version in terminal)Make sure you installed dev dependencies:
uv sync --dev
print() broke the stdio transportAny stdout output corrupts JSON-RPC. Find and remove print() statements. Use logging.getLogger(__name__).info() instead — it writes to stderr.
search_jposFirst 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.
See docs/roadmap-and-architecture.md for full details.
See CONTRIBUTING.md for setup instructions and guidelines.
The first open-source MCP server for jPOS and ISO 8583. Give AI agents deterministic access to payment protocol expertise.
{ "mcpServers": { "mohisyed-jpos-mcp": { "command": "uvx", "args": [ "jpos-mcp-server==0.1.1" ] } }}Herramientas
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
Este registro no indica ninguna variable de entorno obligatoria.
JPOS se ejecuta localmente por stdio.
Última comprobación: 2026-10-28. The first open-source MCP server for jPOS and ISO 8583. Give AI agents deterministic access to payment protocol expertise.