# Vellum

> An MCP server that inspects generated documents (`.docx`, `.pdf`) **before**
> they reach the user — extracting hard, measurable facts about structure,
> typography, spacing, and language correctness, so an AI assistant can catch
> its own formatting mistakes instead of shipping them.

Built against the **2026-07-28 MCP specification**. See [`docs/architecture.md`](docs/architecture.md)
for the full design rationale.

## Why

Document-generation skills produce `.docx`/`.pptx`/`.pdf` output, but nothing
automatically verifies the result is well-formed: heading levels can be
skipped, fonts can be inconsistent, spacing can drift, grammar errors pass
through silently. Vellum is a verification layer, not a generator.

## Core principle

**The server extracts facts. The model makes judgments.**

Vellum never says "this is wrong." It says "here is what is actually true,
and here is what is statistically anomalous relative to the rest of the
document." Deciding whether a given value is *appropriate* for a line's role
in the document (title vs. caption vs. body) is semantic judgment that stays
with the calling model, which has the document's full context — the server
does not, and should not try to.

## Tools

| Tool | Purpose |
|---|---|
| `check_docx_structure` | Heading hierarchy, TOC consistency, numbering, captions |
| `check_docx_typography` | Per-paragraph resolved font/size/weight/spacing (full style-inheritance chain resolved) + outlier flags |
| `check_pdf_layout` | Per-character coordinates, baseline spacing, margin/indent consistency, font inventory, substitution detection, intra-line collision flags |
| `check_language` | LanguageTool findings with paragraph/offset anchors |
| `check_filename_consistency` | Flags filename tokens (company/role/version/date) absent from the document body |
| `full_report` | Runs all applicable checks, returns a `report://{file_id}` resource |

Every tool returns structured facts plus anomaly flags — never a verdict.

Every tool accepts the document either as a filesystem `path` **or** as
inline `content_base64` (with `filename` required alongside it) — useful
when a document only exists in the conversation (e.g. uploaded directly in
a chat interface) rather than saved to disk first. Exactly one of the two
input forms must be given.

## Status

All six tools (`check_docx_structure`, `check_docx_typography`, `check_pdf_layout`,
`check_language`, `check_filename_consistency`, `full_report`) are fully
implemented, unit-tested, and validated against a golden set of fixtures with
known planted defects. The full MCP surface — resources, prompts, elicitation,
cache hints, OAuth 2.1 resource-server auth for the HTTP transport, and correct
error semantics — is built and tested (163+ tests passing). See
[`docs/architecture.md`](docs/architecture.md) and [`PROGRESS.md`](PROGRESS.md)
for the detailed build history and current open items. Packaging/publication
(Phase 7) is in progress — not yet released to PyPI.

## Install

```bash
git clone https://github.com/Nasser9892/vellum-mcp.git
cd vellum-mcp
pip install -e ".[dev]"
```

Requires a local [LanguageTool](https://languagetool.org/dev) instance for
`check_language` — see `docs/architecture.md` for setup.

## Usage (Claude Desktop / any MCP stdio client)

Add to your MCP client config (see `examples/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "vellum": {
      "command": "vellum-mcp"
    }
  }
}
```

## Development

```bash
pip install -e ".[dev]"
pytest                          # unit + integration tests
mcp dev src/vellum_mcp/server.py  # run under MCP Inspector
```

Golden-set fixtures (sample `.docx`/`.pdf` files with deliberately planted
defects) live in `golden_set/`. All checks are validated against these
before being trusted — see `docs/architecture.md` for the discipline.

Validated against MCP Inspector (`mcp dev src/vellum_mcp/server.py`) and
tested against two real MCP clients: Claude Desktop
(`examples/claude_desktop_config.json`) and Cursor (`~/.cursor/mcp.json`,
same `{"mcpServers": {"vellum": {"command": "vellum-mcp"}}}` shape).

## Spec conformance

- All primitives: tools, resources, prompts (not tools-only)
- Stateless core — no reliance on `Mcp-Session-Id`
- Elicitation via MRTR (`InputRequiredResult` / `inputRequests` / `inputResponses`)
- OAuth 2.1 resource-server posture for the HTTP transport (RFC 9728, RFC 8707, RFC 9207; CIMD over deprecated DCR)
- Tasks extension (`io.modelcontextprotocol/tasks`) for long-running analysis
- Correct error codes (`-32602` for not-found, `-32020` for header-bound violations)
- No use of deprecated `roots`/`sampling`/`logging` primitives

## License

MIT — see [`LICENSE`](LICENSE).