Metadata-Version: 2.4
Name: jpos-mcp-server
Version: 0.1.0
Summary: The first open-source MCP server for jPOS and ISO 8583. Give AI agents deterministic access to payment protocol expertise.
Project-URL: Homepage, https://github.com/mohisyed/JPOS-MCP
Project-URL: Repository, https://github.com/mohisyed/JPOS-MCP
Project-URL: Issues, https://github.com/mohisyed/JPOS-MCP/issues
Project-URL: Changelog, https://github.com/mohisyed/JPOS-MCP/blob/main/CHANGELOG.md
Author: Mohiuddin Syed
License: MIT
License-File: LICENSE
Keywords: chromadb,claude,fastmcp,fintech,iso-8583,jpos,mcp,model-context-protocol,payment-processing,payments,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: chromadb>=0.5.0
Requires-Dist: fastmcp==3.1.1
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pymupdf>=1.24.0
Requires-Dist: requests>=2.31.0
Requires-Dist: sentence-transformers>=3.0.0
Description-Content-Type: text/markdown

# jPOS MCP Server

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://img.shields.io/badge/tests-114%20passing-brightgreen.svg)]()
[![Coverage](https://img.shields.io/badge/coverage-91%25-brightgreen.svg)]()

![Demo](docs/demo.gif)

*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](#quickstart)
- [Tools](#tools)
- [Architecture](#architecture)
- [Testing](#testing)
- [Knowledge Base (RAG)](#knowledge-base-rag)
- [Docker](#docker)
- [Claude Desktop Setup](#claude-desktop-setup)
- [MCP Inspector](#mcp-inspector)
- [Security](#security)
- [Troubleshooting](#troubleshooting)
- [Roadmap](#roadmap)
- [Contributing](#contributing)

---

## Quickstart

**Prerequisites:** Python 3.11+ and [uv](https://docs.astral.sh/uv/) package manager.

```bash
# 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

```bash
# 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:
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`:

```python
@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

```bash
# 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:

```bash
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

```bash
# 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

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

---

## Claude Desktop Setup

### macOS

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

```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`:

```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:

```bash
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:
```bash
uv sync
```

### `search_jpos` returns "Knowledge base not initialized"

ChromaDB hasn't been populated. Run:
```bash
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:
```bash
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

- [x] **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](docs/roadmap-and-architecture.md) for full details.

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and guidelines.

## License

[MIT](LICENSE)
