# Fullbleed MCP

First-party, local MCP tools for Fullbleed PDF Engine. The server lets agents discover the installed engine and create, preview, inspect, verify, and compile deterministic print documents through a small structured tool surface.

<!-- mcp-name: io.github.fullbleed-engine/fullbleed-mcp -->

## Install and run

```text
python -m pip install fullbleed-mcp
fullbleed-mcp --root .
```

Fullbleed MCP 0.1.1 requires Fullbleed 2.5.1 or newer. This includes the tool
schema correction needed by strict MCP clients. To update an existing install,
upgrade both the engine and the adapter:

```text
python -m pip install --upgrade fullbleed fullbleed-mcp
```

Naming both packages matters: upgrading only `fullbleed-mcp` can leave an older
compatible engine installed.

The initial transport is newline-delimited JSON-RPC over stdio. User-supplied document paths are confined to `--root`. The server does not require credentials, network access, a browser, system fonts, or a system PDF runtime.

The adapter delegates rendering and discovery to the installed `fullbleed` distribution. It does not maintain a second renderer or capability database. Start with `fullbleed_capabilities` or `fullbleed_agent_contract` and trust their runtime-reported values.

Use this server for structured reports, invoices, statements, letters, forms, certificates, accessible/print-ready documents, template overlays, and VDP. Use a browser tool when the requested artifact is a screenshot or interactive state of an arbitrary live website.

## Direct core entrypoint

Fullbleed also exposes the same dependency-free adapter directly. Use version
2.5.1 or newer for compatibility with strict MCP clients:

```text
fullbleed mcp --root .
```

The separate `fullbleed-mcp` distribution exists for package and MCP Registry discovery and keeps optional agent-integration installation separate from `pip install fullbleed`.

## Run with Docker

The optional repository-root `Dockerfile` packages the stdio server for container
users and MCP directories. It builds the adapter from this repository and installs
the released engine pinned in `container-requirements.txt` from hash-checked Linux wheels. It does not add
Docker or other dependencies to the Python package.

From the repository root:

```text
docker build -t fullbleed-mcp:local .
docker run --rm -i --network none --mount "type=bind,source=/absolute/path/to/documents,target=/workspace" fullbleed-mcp:local
```

Replace the source path with an existing directory. The image runs as UID/GID
`10001:10001`, and document paths are relative to `/workspace`. On Linux, add
`--user "$(id -u):$(id -g)"` before the image name to write a directory owned by
your current user. Keep `-i` and omit `-t` when connecting an MCP client over stdio.

The `MCP container` workflow builds the image and exercises initialization, tool
discovery, previews, inspection, verification, and three-record VDP output. Its
smoke run disables networking, makes the image read-only, and checks that a tool
cannot read outside its document workspace. It retains the generated PDFs and
preview, independently checks their text and page counts, and rejects a blank
preview. A second check uses the official
TypeScript MCP SDK to validate tool discovery and structured results against the
running container. To run these checks locally:

```text
python -m pip install -r requirements-test.txt
python tools/smoke_mcp_stdio.py --container-image fullbleed-mcp:local --output-dir output/mcp-smoke --json
python tools/verify_mcp_artifacts.py output/mcp-smoke
npm ci --ignore-scripts --no-audit --no-fund --prefix tools/mcp-client-smoke
node tools/mcp-client-smoke/smoke.mjs --container-image fullbleed-mcp:local
```

Choose a new `--output-dir` for each run. The smoke check refuses to overwrite
an existing directory. Omitting the option uses a temporary workspace.

`container-requirements.txt` pins the released engine used by this distribution.
Update its version and wheel hashes when intentionally moving the container to a
new engine release. `glama.json` identifies the maintainer for the Glama directory;
it does not imply that a directory has approved or scored the server.

## Registry metadata

`server.json` is generated from this package's `[tool.fullbleed-mcp.registry]` metadata:

```text
python tools/generate_mcp_server_json.py --check --json
```

Publish the PyPI distribution before submitting `server.json`; the official registry verifies the matching `mcp-name` marker above from the PyPI long description. Registry publication is prepared in `.github/workflows/publish-mcp.yml` and uses the `io.github.fullbleed-engine/fullbleed-mcp` namespace.