Skip to content

v0.1.0 — Initial Release

Latest
Latest

Choose a tag to compare

View all tags
@mohisyed mohisyed released this 12 Apr 20:14
· 4 commits to main since this release
v0.1.0
53b6284

jPOS MCP Server v0.1.0 — Initial Release

The first open-source MCP server for jPOS and ISO 8583. Give AI agents (Claude, Cursor, VS Code Copilot) deterministic, verified access to payment protocol expertise.

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

Highlights

  • 6 tools spanning ISO 8583 lookups, jPOS XML generation, message validation, and semantic search
  • 114 tests (unit + MCP integration + E2E workflows + message-type patterns + container field coverage) passing with 91% coverage
  • Hybrid RAG pipeline with cross-encoder reranking — 0.903 average score, 100% strong on a 28-query benchmark
  • 779 chunks indexed across the jPOS Programmer's Guide, ISO 8583-1:2003 spec, Wikipedia reference, jPOS tutorial pages, and project docs
  • PCI-aware by design — Luhn-based real PAN rejection, sensitive field redaction in logs, stderr-only output to keep stdio JSON-RPC clean
  • Docker-ready with non-root user, healthcheck, persistent ChromaDB volume
  • Production-grade infra — GitHub Actions CI + security scan, SECURITY.md, issue templates, structured PR template

Tools

Tool Namespace What It Does
lookup_field iso Return full ISO 8583 field spec (name, format, jPOS class, max length, mandatory MTIs, PCI flags)
decode_mti iso Decode 4-digit MTI into version, class, function, origin + expected response
generate_packager jpos Generate complete GenericPackager XML from plain English (deterministic — never hallucinates)
validate_descriptor jpos Lint a Q2 deploy descriptor (channel-adaptor, QMUX, txnmgr rules)
build_message msg Validate ISO 8583 field dict (mandatory fields, lengths, PAN safety)
search_jpos docs Hybrid semantic + cross-encoder search over jPOS docs and ISO 8583 spec
health (root) Server version, tool count, ChromaDB chunk count

RAG Pipeline

Two-stage hybrid retrieval:

  1. Stage 1: all-mpnet-base-v2 (768D) bi-encoder fetches top 25 candidates by cosine similarity
  2. Stage 2: cross-encoder/ms-marco-MiniLM-L-6-v2 reranks by attending across (query, chunk) pairs simultaneously
  3. Query expansion adds domain context to short or jargon-heavy queries before embedding
  4. Rank-aware display score boosts top picks so the cross-encoder's confident choices surface clearly

Falls back to keyword-overlap reranking if the model can't load (offline environments).

Installation

Claude Desktop (stdio)

git clone https://github.com/mohisyed/JPOS-MCP.git
cd JPOS-MCP
uv sync

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Docker (HTTP)

docker compose -f docker/docker-compose.yml up -d --build

Knowledge base setup (optional, for search_jpos)

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

Production Audit

All 7 audit phases pass:

Phase Result
Code quality ruff clean, 114/114 tests, 91% coverage
Server startup stdio + HTTP transports both verified
End-to-end MCP 21 E2E workflow tests pass through real FastMCP Client
Data integrity 129 fields, no broken refs, PCI fields documented
Security 6 real PANs caught, separators handled, all test PANs allowed, redaction verified, zero print()
Performance 1-10 microseconds per call, timeout fires within 1ms of deadline
RAG quality 28/28 strong queries (100%), 0.903 average score

Security

  • Real PANs are rejected by core/validators.py using the Luhn algorithm. Only test PANs in SAFE_TEST_PANS are allowed.
  • Sensitive ISO 8583 fields (DE2, DE35, DE45, DE52, DE55, DE64) are auto-redacted from all log output.
  • stderr-only logging — stdio JSON-RPC stream is never corrupted by tool output.
  • Non-root Docker container runs as appuser:1001.
  • fastmcp==3.1.1 pinned exactly, weekly pip-audit CVE scan via GitHub Actions.

See SECURITY.md for vulnerability reporting and PCI handling details.

What's Next (V2)

  • Java sidecar for live ISOMsg pack/unpack via Spring Boot
  • Custom interchange spec overrides (custom_spec/ layered system)
  • jpos_log_parser tool
  • OAuth 2.1 bearer auth for HTTP transport
  • PyPI publish (pip install jpos-mcp-server)
  • MCP Registry submission

Links

License

MIT

Assets 2
Loading