JPOS-MCP: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

jPOS MCP Server — a Model Context Protocol server that provides deterministic ISO 8583 and jPOS framework lookups to AI agents. Tools replace AI inference with verified data from JSON files and a ChromaDB-backed RAG pipeline over jPOS documentation.

Status: V1 MVP complete. 6 tools implemented, 114 tests (91% coverage), Docker-ready, RAG pipeline with ~786 chunks indexed and cross-encoder reranking.

Build & Run Commands

# Install dependencies
uv sync --dev

# Run server (stdio transport, for Claude Desktop)
uv run python main.py

# Run server (HTTP transport, for Docker/team)
MCP_TRANSPORT=http MCP_PORT=8000 uv run python main.py

# Open MCP Inspector (browser-based test UI)
uv run fastmcp dev inspector main.py:mcp

# Run all tests
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_lookup_field_valid -v

# Coverage
uv run pytest tests/ --cov=servers --cov=core

# Lint
ruff check .

# Format
black .

# Ingest docs into ChromaDB (PDFs from knowledge/sources/, markdown from docs/)
# First run downloads ~90MB embedding model
uv run python knowledge/ingest.py

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

Architecture

The server uses FastMCP v3.1.1 with sub-server composition. main.py mounts four domain-specific servers under namespaces:

• servers/iso.py → namespace iso — lookup_field, decode_mti (static JSON lookups from data/)
• servers/jpos_tools.py → namespace jpos — generate_packager, validate_descriptor (XML generation/validation)
• servers/message.py → namespace msg — build_message (field dict validation with PAN detection)
• servers/rag.py → namespace docs — search_jpos (ChromaDB semantic search over jPOS Programmer's Guide)

Each sub-server is independently testable. A bug in RAG doesn't affect ISO tools.