inclusio-mcp

Inclusio

让出版惠及每一个人。

面向无障碍的 LaTeX 出版引擎，以 Python CLI 形式打包。实现 PDF/UA-2 + WTPDF + PDF/A-4f 三重符合性，提供 C2PA + PAdES + SLSA 来源证明、多格式输出 （HTML5 / JATS / EPUB3）、大模型增强评审，以及用于 Agent 集成的 MCP 服务。

---

目录

• 安装 — pip、可选附加项、源码
• 快速开始 — 60 秒内生成首个带标签的 PDF
• 功能 — 引擎提供的功能
• 用法 — 常见的 Python + CLI 示例
• 工具 — MCP 工具和资源接口
• 架构 — 引擎的包结构
• 示例 — 六个可运行场景
• 文档 — 快速入门、教程、参考
• 基于外部内容树进行出版
• 开发 — 本地验证门禁
• 安全 — 已签名提交、来源证明、审计
• 许可证

---

安装

pip install inclusio                       # engine + CLI
pip install 'inclusio[mcp]'                # + FastMCP server
pip install 'inclusio[provenance]'         # + pyhanko (PAdES)
pip install 'inclusio[dev]'                # + pytest, ruff, sphinx, interrogate

要求： Python ≥ 3.11，且 PATH 中包含 LuaLaTeX 工具链。支持 Linux、 macOS 和 WSL（原生 Windows 可使用 Python 接口；LaTeX 门禁需要 WSL 或 TeX Live 安装）。

可选工具	提供功能	安装
verapdf	严格的 EAA / 无障碍审计门禁	verapdf.org/install
pandoc (≥ 3.0)	HTML5 / JATS XML / EPUB3 多格式输出	brew install pandoc · apt install pandoc
c2patool	C2PA 内容凭证	contentauth/c2patool releases
pyhanko (via [provenance])	PAdES B-T / B-LT / B-LTA 签名	由附加项安装

从源码构建

git clone https://github.com/sebastienrousseau/inclusio.git
cd inclusio
./bin/setup        # check toolchain + install dev extras
make test          # smoke suite
make coverage      # full suite (gate: 97 %)

---

快速开始

下面是一个完整的示例，可粘贴到一个空目录中：

pip install inclusio

# Grab the minimal example, build + audit + emit + judge:
git clone --depth=1 https://github.com/sebastienrousseau/inclusio
cd inclusio/examples/01-hello-world && make

这条 make 命令会生成 build/hello.pdf（符合 PDF/UA-2 + WTPDF + PDF/A-4f 三重标准），对其运行 veraPDF，并在任何一种格式验证失败时以非零状态退出。

也可以从 Python 驱动相同的接口：

# quickstart.py
import subprocess
from pathlib import Path

# 1. Render + build the bundled "hello" fixture — the CLI is the
#    canonical entry point for the LaTeX step.
subprocess.run(
    ["python", "-m", "inclusio.cli.build", "build", "--doc", "hello"],
    cwd="examples/01-hello-world",
    check=True,
)

# 2. Audit the produced PDF in-process — pure-Python, no subprocess.
from inclusio.cli import audit

pdfs = audit.collect_pdfs(
    target=Path("examples/01-hello-world/build"),
    build_dir=Path("examples/01-hello-world/build"),
    registry_stems={"hello"},
)
report = audit.audit(pdfs)
assert report["summary"]["fail"] == 0, "veraPDF reported a failure"
print(f'  PASS  {report["summary"]["pdfs"]} PDF(s), '
      f'{report["summary"]["pass"]}/{report["summary"]["total"]} checks')
# →   PASS  1 PDF(s), 3/3 checks

---

功能

• 默认生成带标签的 PDF。 每次构建都会通过 LaTeX 内核的 tagpdf 集成，生成同时符合 PDF/UA-2、WTPDF 和 PDF/A-4f 标准的产物。veraPDF 审核关卡已接入 CI，任何 FAIL 都会以非零状态退出。
• 生成多种格式。 同一份 LaTeX 源文件可通过 Pandoc 生成 HTML5（符合 WCAG）、JATS XML（1.3，已为 JATS4R 做好准备）和 EPUB3。
• LLM 增强型评审器。 ATS（Workday / Greenhouse / Lever 启发式评估）、引用依据核验和职位描述（JD）与简历（CV）的匹配度评估——可使用本地 llama.cpp，也可使用自带密钥的云服务（Anthropic / OpenAI）；无法连接 LLM 时回退为仅启发式评估。
• 内容来源证明。 C2PA Content Credentials（通过 c2patool）、PAdES B-T / B-LT / B-LTA 签名（通过 pyhanko）以及 SLSA L3 构建证明（通过 actions/attest-build-provenance）。
• MCP 服务。 inclusio-mcp 提供 list_docs、audit_pdf、render 和 doc_count，让 Claude Code、Cursor、Continue 或任何其他 MCP 客户端都能驱动引擎。
• JSON Resume 导入器。 inclusio import-resume 可将 jsonresume.org v1 文档转换为引擎的 CV YAML 架构。
• 根据需求定制 CV。 根据职位描述定制符合 ATS 要求的版本，并进行英式英语校正和一致性检查。

用法

构建、审核并评审已注册的文档

inclusio build --doc cv --mode draft        # → build/cv.pdf
inclusio audit --strict                     # → veraPDF, non-zero on FAIL
inclusio judge --doc cv --judge ats         # → grade + findings

根据职位描述为 CV 评分

# score_cv.py — fully runnable: drop into a directory with brief.txt + cv.txt
from pathlib import Path
from inclusio.judge import jd_fit

jd_text = Path("brief.txt").read_text(encoding="utf-8")
cv_text = Path("cv.txt").read_text(encoding="utf-8")

report = jd_fit.score_jd_fit(jd_text, cv_text)
print(f"score:   {report.score}/100   grade: {report.grade}")
print(f"missing: {sorted(report.metrics['missing_required'])[:5]}")
# → score:   78/100   grade: B
# → missing: ['opentelemetry', 'rust']

通过 MCP 驱动引擎

inclusio-mcp                          # stdio (Claude Code default)
inclusio-mcp --http --port 8765       # Streamable HTTP

通过 ~/.claude/claude_desktop_config.json 接入 Claude Code：

{
  "mcpServers": {
    "inclusio": {
      "command": "inclusio-mcp",
      "env": { "INCLUSIO_CONTENT_DIR": "/absolute/path/to/content" }
    }
  }
}

嵌入 C2PA Content Credentials

inclusio provenance --doc cv \
  --cert /path/to/cert.pem \
  --key  /path/to/key.pem \
  --output build/cv.c2pa.pdf

---

工具

inclusio-mcp 服务提供四种 MCP 工具：

• list_docs — 列出内容树中注册的文档
• doc_count — 快速统计可用文档数量
• render — 为文档构建带标签且符合标准的 PDF（及其他格式）
• audit_pdf — 对 PDF 进行无障碍审核（veraPDF）

另提供三种只读资源：

• inclusio://meta — 项目清单（meta.yaml）
• inclusio://audit/latest — 最新审核报告
• inclusio://version — 引擎版本卡片

---

架构

inclusio/                  # Python package
  cli/                     # build · audit · render · tailor · judge · emit · provenance · …
  judge/                   # ats · citations · jd_fit · local_llm · cloud_llm
  emit/                    # pandoc (HTML5 / JATS XML / EPUB3)
  provenance/              # c2pa (c2patool) · pades (pyhanko)
  mcp/                     # FastMCP server
  tools/                   # fix_semantic · stamp_pdfs · overlay
core/                      # LaTeX classes (.cls) and styles (.sty)
templates/                 # Jinja2 templates for the template-driven docs
benches/                   # pytest-benchmark micro-benchmarks
examples/                  # Six self-contained runnable scenarios
docs/                      # Sphinx documentation

外部使用者提供自己的内容树（LaTeX 源文件、YAML 元数据、品牌素材），并通过 INCLUSIO_CONTENT_DIR 或 --content-dir 指定引擎使用该目录。仓库自身的 src/ 和 data/ 目录也兼作公共引擎的自测样例。

示例

#	文件夹	示例内容
1	01-hello-world/	带审核关卡的带标签 PDF 构建
2	02-cv-from-jsonresume/	JSON Resume → CV → ATS + JD 匹配度评分
3	03-paper-with-citations/	论文 → PDF + HTML + JATS + EPUB + 引用评审
4	04-mcp-agent/	inclusio-mcp + Claude Code 技能
5	05-c2pa-sign/	C2PA Content Credentials
6	06-pades-sign/	PAdES B-T eIDAS 签名

每个文件夹都有自己的 Makefile（运行 make help 可列出目标），以及说明缘由和操作方法的 README.md。

文档

• 快速入门 — 五分钟快速浏览。
• 教程 — 四篇端到端教程，与示例一一对应。
• 架构 — 公共引擎与内容仓库的边界、迭代历史、决策日志。
• 带标签的 PDF — 符合标准的技术栈。
• 多格式 — HTML / JATS / EPUB。
• 评审器 — ATS、引用、JD 匹配度、LLM 重排约定。
• 来源证明 — C2PA、PAdES、SLSA。
• MCP 服务 — 工具与资源接口。

使用外部内容树发布

make publish CONTENT_DIR=/absolute/path/to/your-content-repo

内容仓库提供自己的 data/meta.yaml（文档注册表）和 src/**.tex（LaTeX 源文件）。设置 INCLUSIO_CONTENT_DIR 后，引擎不会读取该目录之外的任何状态。

开发

make test          # smoke (≤ 20 s)
make coverage      # full suite + 97 % gate (~3 min)
make docstrings    # 100 % interrogate gate
make benchmark     # pytest-benchmark micro-budgets
make audit-strict  # veraPDF, exits non-zero on any FAIL
make docs          # Sphinx

所有提交都会通过 PR squash 合并到 main。分支保护要求通过 Lint (ruff)、Public Engine Checks (py3.11 / 3.12 / 3.13) 和 Signed-commit gate。请参阅 CONTRIBUTING.md。

安全

• SSH 签名提交。 main 上的每次提交都经过 GitHub 验证。
• 签名标签。 发布标签使用 ED25519 签名。
• SLSA L3 构建来源证明（要求仓库为公开状态或使用付费 GitHub 计划）。
• release.yml 中配置了 PyPI Trusted Publishing（pypa/gh-action-pypi-publish）；配置好 PyPI 发布者后，将 vars.PYPI_TRUSTED_PUBLISHING=true。
• 云端 LLM 密钥仅通过环境变量提供——inclusio 不会自动从磁盘发现凭据。

请按照 SECURITY.md 报告漏洞。

相关 MCP 服务

同一作者开发的同系列 MCP 服务——每个服务针对不同的 Agent 工作流：

服务	用途
noyalib-mcp	无损解析、格式化和验证 YAML 1.2（Rust）
rlg-mcp	用于值班 / SRE Agent 工作流的 RustLogs 日志流
pain001-mcp	生成和验证 ISO 20022 pain.001 支付发起文件
bankstatementparser-mcp	解析银行对账单（BAI2、MT940/MT942、CAMT.053、OFX、CSV）
camt053-mcp	解析并对账 ISO 20022 camt.053 银行对客户对账单
acmt001-mcp	生成和验证 ISO 20022 acmt.001 账户管理消息

---

MCP 注册表

mcp-name: io.github.sebastienrousseau/inclusio-mcp

使用 pip install 'inclusio[mcp]' 安装 MCP 服务（mcp 附加组件会引入 mcp[cli]>=1.27.0）。运行 inclusio-mcp——采用 stdio 传输方式，向 Claude Desktop、Cursor 和其他 MCP 客户端提供无障碍发布工具。

---

许可证

可任选以下许可证：

• Apache License, Version 2.0
• MIT License

© 2026 Sebastien Rousseau。