PTPGE MCP Server

A read-only Model Context Protocol server that exposes the PTPGE specification — the open vocabulary of print — to AI agents.

The vocabulary (terms with permanent URIs, product templates, variables, schemas and registers) is published under CC BY 4.0 at https://api.ptpge.org/v1/. This server loads it, keeps it in memory, reloads when the dataset version changes, and offers it to agents as a small set of MCP tools: search a term, read a term, read a product envelope, validate a configuration, resolve a colour notation, compute and expand a configuration fingerprint (ptpge-cfs/1).

Live, open, no key: https://mcp.ptpge.org/mcp (Streamable HTTP). open.mcp.ptpge.org is an alias.

Add it to your assistant

• Claude (web or desktop): Settings → Connectors → Add custom connector → https://mcp.ptpge.org/mcp
• ChatGPT: Settings → Connectors → Add (developer mode) → same URL
• Claude Code: claude mcp add ptpge --transport http https://mcp.ptpge.org/mcp

Then ask, in any language: «What is a roll fold?» or «Fingerprint an A4 tri-fold brochure, 170 g silk, 4/4».

Tools

Tool	What it does
ptpge_search_terms	Free-text search over the vocabulary, tokenised and language-independent. Hits carry URI, label, level, group, kind (term · supplier · vendor · schema) and score. Deprecated terms are skipped unless asked for.
ptpge_get_term	One term in full: definition, relations (broader / narrower / related), mappings, properties, notation. Accepts a full URI or a relative path.
ptpge_get_version	Dataset version, term counts, licence, scheme URL, server version.
ptpge_browse	Walk the hierarchy from a node.
ptpge_get_product_envelope	For a product template: which variables apply, which are required for an identity, which values are allowed.
ptpge_validate_config	Check a configuration (bindings on vocabulary URIs) against its envelope: membership, cardinality, scope, numeric bands, cross-variable rules.
ptpge_resolve_color_notation	4/4, 4/1, 1/0 … → ink counts per face in vocabulary terms.
ptpge_fingerprint	Canonicalise a validated configuration and compute its ptpge-cfs/1 fingerprint (spec and offer).
ptpge_expand_fingerprint	A fingerprint back to its configuration, from the register at ptpge.org/f/.

Responses are plain JSON. The /playground page lets you watch an agent run the loop from a free-text order to a fingerprint, every tool call in the transcript.

Endpoints

Path	Purpose
POST /mcp	MCP over Streamable HTTP (also GET for the event stream, DELETE to end a session)
GET /health, /healthz	Liveness + dataset version
GET /playground	The Playground
GET /sse	Retired — answers 410 with a pointer to /mcp

Run it yourself

python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python -m ptpge_mcp.server          # http://0.0.0.0:8000/mcp

Test with the MCP Inspector: npx @modelcontextprotocol/inspector, transport Streamable HTTP, URL http://localhost:8000/mcp.

pytest -q

Configuration

Variable	Default	Purpose
PTPGE_API_BASE	https://api.ptpge.org/v1	Where the vocabulary is fetched from
PTPGE_REFRESH_SECONDS	900	How often to check version.json for a new dataset
PTPGE_LOG_LEVEL	INFO	Python logging level
PTPGE_MCP_AUTH_USERS	—	Optional Basic Auth on the server, comma-separated user:pass pairs. Leave unset for an open server.
PTPGE_MCP_HTPASSWD	—	Optional path to an Apache htpasswd file used instead of the variable above
PTPGE_MCP_TOKENS / _TOKENS_FILE	—	Optional per-recipient tokens (?t=), same purpose

The public server at mcp.ptpge.org runs with none of the auth variables set.

Layout

ptpge_mcp/
├── server.py           # tools, handlers, Streamable HTTP, Playground route
├── data.py             # fetch, cache, index, search
├── config.py           # environment-based runtime config
├── cfs_resolution.py   # canonicalisation + ptpge-cfs/1
├── fingerprint.py, fingermark.py   # hash and mark
├── completeness.py     # required variables / unspecified axes
├── colornotation.py    # 4/4-style notation → terms
├── semantic.py         # embedding search (term_embeddings.npz)
├── registerclient.py   # ptpge.org/f/ register client
├── playground.py, learningpage.py, missreport.py
└── _frame.py           # ptpge.org site frame (generated; do not edit)
tests/
passenger_wsgi.py       # cPanel/Passenger entry point for the hosted instance
.cpanel.yml             # deploy script for the hosted instance
CHANGELOG.md            # semver; one entry per release

Versioning

Semver for the server; the dataset has its own date version (ptpge_get_version). The fingerprint algorithm is a separate contract, ptpge-cfs/1, and does not change with server releases.

Licence

Code: Apache License 2.0. Vocabulary and data: CC BY 4.0, held by PTPGE, a non-profit association (being formed). See ptpge.org/governance.

Registry

Listed in the official MCP Registry as org.ptpge/mcp-server (server.json in this repository; published with mcp-publisher, namespace verified by a DNS record on ptpge.org).