Inclusio MCP README

Inclusio

Publishing that includes everyone.

Accessibility-first publishing engine for LaTeX, packaged as a Python CLI. PDF/UA-2 + WTPDF + PDF/A-4f triple-conformance, C2PA + PAdES + SLSA provenance, multi-format emission (HTML5 / JATS / EPUB3), LLM-augmented judges, and an MCP server for agent integration.

Contents

• Install — pip, optional extras, source
• Quick Start — first tagged PDF in 60 seconds
• Features — what the engine ships
• Usage — common Python + CLI recipes
• Tools — the MCP tool and resource surface
• Architecture — the engine's package layout
• Examples — six runnable scenarios
• Documentation — quickstart, tutorials, reference
• Publishing against an external content tree
• Development — local validation gate
• Security — signed commits, provenance, audit
• License

Install

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

Requires Python ≥ 3.11 and a LuaLaTeX toolchain on PATH. Linux, macOS, and WSL are supported (native Windows works for the Python surface; the LaTeX gate needs WSL or a TeX Live install).

Build from source

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 %)

Quick Start

A complete worked example you can paste into a fresh directory:

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

That single make produces build/hello.pdf (PDF/UA-2 + WTPDF + PDF/A-4f triple-conformance), runs veraPDF over it, and exits non-zero if any flavour fails.

Drive the same surface from 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

Features

• Tagged PDF, by default. Every build emits a PDF/UA-2 + WTPDF + PDF/A-4f triple-conforming artefact via the LaTeX kernel's tagpdf integration. The veraPDF audit gate is wired into CI and exits non-zero on any FAIL.
• Multi-format emission. The same LaTeX source produces HTML5 (WCAG-clean), JATS XML (1.3, JATS4R-ready), and EPUB3 via Pandoc.
• LLM-augmented judges. ATS (Workday / Greenhouse / Lever heuristic), citation grounding, and JD-to-CV fit — local llama.cpp or BYO-key cloud (Anthropic / OpenAI), with heuristic-only fallback when the LLM is unreachable.
• Content provenance. C2PA Content Credentials (via c2patool), PAdES B-T / B-LT / B-LTA signatures (via pyhanko), and SLSA L3 build attestation (via actions/attest-build-provenance).
• MCP server. inclusio-mcp exposes list_docs, audit_pdf, render, and doc_count so Claude Code, Cursor, Continue, or any other MCP client can drive the engine.
• JSON Resume importer. inclusio import-resume converts a jsonresume.org v1 document into the engine's CV YAML schema.
• Brief-driven CV tailoring. ATS-clean variants tailored against a job description with British-English cleanup and consistency lint.

Usage

Build, audit, judge a registered document

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

Score a CV against a job description

# 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']

Drive the engine over MCP

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

Wire into Claude Code via ~/.claude/claude_desktop_config.json:

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

Embed C2PA Content Credentials

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

Tools

The inclusio-mcp server exposes four MCP tools:

• list_docs — Enumerate documents registered in the content tree
• doc_count — Quick count of available documents
• render — Build a tagged, conformant PDF (and other formats) for a document
• audit_pdf — Accessibility audit of a PDF (veraPDF)

Plus three read-only resources:

• inclusio://meta — Project manifest (meta.yaml)
• inclusio://audit/latest — Latest audit report
• inclusio://version — Engine version card

Architecture

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

External consumers supply their own content tree (LaTeX sources, YAML metadata, brand assets) and point the engine at it through INCLUSIO_CONTENT_DIR or --content-dir. The repo's own src/ and data/ directories double as the public-engine self-test fixtures.

Examples

Each folder has its own Makefile (make help lists targets) and a README.md with the why + the how.

Documentation

• Quickstart — five-minute walkthrough.
• Tutorials — four end-to-end walkthroughs paired 1 : 1 with the examples.
• Architecture — public-engine vs content-repo boundary, sprint history, decision log.
• Tagged PDF — the conformance stack.
• Multi-format — HTML / JATS / EPUB.
• Judges — ATS, citations, JD-fit, LLM rerank contract.
• Provenance — C2PA, PAdES, SLSA.
• MCP server — tool + resource surface.

Publishing against an external content tree

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

The content repo supplies its own data/meta.yaml (document registry) and src/**.tex (LaTeX sources). The engine reads no state from outside INCLUSIO_CONTENT_DIR once it's set.

Development

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

All commits to main are squash-merged via PR. Branch protection requires Lint (ruff) + Public Engine Checks (py3.11 / 3.12 / 3.13) + the Signed-commit gate to pass. See CONTRIBUTING.md.

Security

• SSH-signed commits. Every commit on main is GitHub-verified.
• Signed tags. Release tags are ED25519-signed.
• SLSA L3 build provenance (gated on the repo being public or on a paid GitHub plan).
• PyPI Trusted Publishing wiring (pypa/gh-action-pypi-publish) in release.yml; flip vars.PYPI_TRUSTED_PUBLISHING=true once the PyPI publisher is configured.
• Cloud LLM keys are env-var only — inclusio never auto- discovers credentials from disk.

Report vulnerabilities per SECURITY.md.

Related MCP Servers

Sibling MCP servers by the same author — each targets a different agent workflow:

MCP Registry

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

Install the MCP server with pip install 'inclusio[mcp]' (the mcp extra pulls in mcp[cli]>=1.27.0). Run with inclusio-mcp — stdio transport, exposes accessibility-publishing tools to Claude Desktop, Cursor, and other MCP clients.

License

Licensed under either of:

• Apache License, Version 2.0
• MIT License

at your option. © 2026 Sebastien Rousseau.