ptpge

PTPGE MCP 服务

一个只读的 Model Context Protocol 服务，向 AI Agent 提供 PTPGE 规范——印刷行业的开放词汇表。

该词汇表（含永久 URI 的术语、产品模板、变量、架构和注册表）以 CC BY 4.0 许可发布在 https://api.ptpge.org/v1/。此服务会加载词汇表并将其保存在内存中，在数据集版本变化时重新加载，并通过一小组 MCP 工具提供给 Agent： 搜索术语、读取术语、读取产品封套、验证配置、解析色彩标记，以及计算和展开配置指纹（ptpge-cfs/1）。

在线、开放、无需密钥：https://mcp.ptpge.org/mcp（Streamable HTTP）。open.mcp.ptpge.org 是其别名。

将其添加到你的助手

• Claude（网页版或桌面版）：Settings → Connectors → Add custom connector → https://mcp.ptpge.org/mcp
• ChatGPT：Settings → Connectors → Add（developer mode）→ 同一 URL
• Claude Code：claude mcp add ptpge --transport http https://mcp.ptpge.org/mcp

然后用任意语言提问：「什么是卷折？」或「为一份 A4 三折宣传册生成指纹，170 g 铜版纸，4/4」。

工具

工具	功能
ptpge_search_terms	在词汇表中进行自由文本搜索，不受分词方式和语言影响。命中项包含 URI、标签、层级、组、kind（term · supplier · vendor · schema）和评分。除非特别要求，否则跳过已弃用术语。
ptpge_get_term	完整读取一个术语：定义、关系（broader / narrower / related）、映射、属性、标记法。接受完整 URI 或相对路径。
ptpge_get_version	数据集版本、术语数量、许可证、方案 URL、服务版本。
ptpge_browse	从一个节点开始遍历层级结构。
ptpge_get_product_envelope	对于产品模板：适用的变量、构成身份标识所需的变量，以及允许的值。
ptpge_validate_config	根据配置封套检查配置（绑定到词汇表 URI 的值）：成员资格、基数、范围、数值区间、跨变量规则。
ptpge_resolve_color_notation	4/4、4/1、1/0 等 → 以词汇表术语表示的各面油墨数量。
ptpge_fingerprint	将经过验证的配置规范化，并计算其 ptpge-cfs/1 指纹（规格和报价）。
ptpge_expand_fingerprint	从 ptpge.org/f/ 注册表中，将指纹还原为配置。

响应均为纯 JSON。/playground 页面可让你查看 Agent 如何从自由文本订单到指纹完成整个流程，以及每次工具调用的记录。

端点

路径	用途
POST /mcp	通过 Streamable HTTP 使用 MCP（也支持用 GET 获取事件流，用 DELETE 结束会话）
GET /health、/healthz	存活状态 + 数据集版本
GET /playground	Playground
GET /sse	已停用——返回 410，并指向 /mcp

自行运行

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

使用 MCP Inspector 测试：npx @modelcontextprotocol/inspector，传输方式选择 Streamable HTTP，URL 为 http://localhost:8000/mcp。

pytest -q

配置

变量	默认值	用途
PTPGE_API_BASE	https://api.ptpge.org/v1	获取词汇表的地址
PTPGE_REFRESH_SECONDS	900	检查 version.json 是否有新数据集的频率
PTPGE_LOG_LEVEL	INFO	Python 日志级别
PTPGE_MCP_AUTH_USERS	—	服务的可选 Basic Auth，使用逗号分隔的 user:pass 对。留空则服务开放访问。
PTPGE_MCP_HTPASSWD	—	可选的 Apache htpasswd 文件路径，用于替代上述变量
PTPGE_MCP_TOKENS / _TOKENS_FILE	—	可选的按接收方区分的令牌（?t=），用途相同

mcp.ptpge.org 上的公共服务未设置任何身份验证变量。

目录结构

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

版本控制

服务采用 Semver；数据集使用独立的日期版本（ptpge_get_version）。指纹算法是一项独立约定 ptpge-cfs/1，不会随服务版本发布而改变。

许可证

代码：Apache License 2.0。词汇和数据：CC BY 4.0， 由非营利协会 PTPGE（正在筹建）持有。请参阅 ptpge.org/governance。

注册信息

已在官方 MCP Registry 中登记为 org.ptpge/mcp-server（本仓库中的 server.json；使用 mcp-publisher 发布，命名空间通过 ptpge.org 上的 DNS 记录验证）。