Vellum
Vellum
一个 MCP 服务器,在生成的文档(
.docx、
基于 2026-07-28 MCP 规范构建。完整的设计原理参见 docs/architecture.md。
为什么
文档生成技能会产出 .docx/.pptx/.pdf 输出,但没有任何机制自动验证结果是否格式良好:标题层级可能被跳过、字体可能不一致、间距可能漂移、语法错误会悄然通过。Vellum 是一个验证层,而不是生成器。
Related MCP server: Visual Document Forensics MCP Server
核心原则
服务器提取事实。模型做出判断。
Vellum 从不说“这是错的”。它说的是“这里是实际为真的事实,这里是相对于文档其余部分在统计上异常的内容。”判断某个值对于一行在文档中的角色(标题 vs. 题注 vs. 正文)是否合适,属于语义判断,由调用方模型负责——该模型拥有文档的完整上下文——而服务器没有,也不应尝试拥有。
工具
Tool | Purpose |
| 标题层级、目录一致性、编号、题注 |
| 逐段落解析的字体/字号/字重/间距(完整样式继承链已解析)+ 离群值标记 |
| 逐字符坐标、基线间距、边距/缩进一致性、字体清单、替换检测、行内碰撞标记 |
| LanguageTool 发现结果,带段落/偏移锚点 |
| 标记文档正文中缺失的文件名标记(公司/角色/版本/日期) |
| 运行所有适用的检查,返回 |
每个工具都返回结构化事实加上异常标记——绝不下结论。
每个工具都接受文档,既可以是文件系统 path,也可以是内联的 content_base64(同时必须提供 filename)——当文档只存在于对话中(例如直接在聊天界面中上传)而尚未先保存到磁盘时,这很有用。两种输入形式中必须且只能提供一种。
状态
全部六个工具(check_docx_structure、check_docx_typography、check_pdf_layout、check_language、check_filename_consistency、full_report)均已完整实现、经过单元测试,并针对一组带有已知植入缺陷的黄金标准夹具进行了验证。完整的 MCP 表面——资源、提示词、引导、缓存提示、HTTP 传输的 OAuth 2.1 资源服务器认证,以及正确的错误语义——均已构建并通过测试(163+ 项测试通过)。详细的构建历史和当前未决事项参见 docs/architecture.md 和 PROGRESS.md。打包/发布(第 7 阶段)正在进行中——尚未发布到 PyPI。
安装
git clone https://github.com/Nasser9892/vellum-mcp.git
cd vellum-mcp
pip install -e ".[dev]"check_language 需要本地 LanguageTool 实例——设置方法参见 docs/architecture.md。
用法(Claude Desktop / 任何 MCP stdio 客户端)
添加到你的 MCP 客户端配置中(参见 examples/claude_desktop_config.json):
{
"mcpServers": {
"vellum": {
"command": "vellum-mcp"
}
}
}开发
pip install -e ".[dev]"
pytest # unit + integration tests
mcp dev src/vellum_mcp/server.py # run under MCP Inspector黄金标准夹具(带有故意植入缺陷的示例 .docx/.pdf 文件)位于 golden_set/。所有检查在被采信之前都会针对这些夹具进行验证——相关方法论参见 docs/architecture.md。
已针对 MCP Inspector(mcp dev src/vellum_mcp/server.py)进行验证,并针对两个真实的 MCP 客户端进行了测试:Claude Desktop(examples/claude_desktop_config.json)和 Cursor(~/.cursor/mcp.json,使用相同的 {"mcpServers": {"vellum": {"command": "vellum-mcp"}}} 结构)。
规范符合性
所有原语:工具、资源、提示词(不仅仅是工具)
无状态核心——不依赖
Mcp-Session-Id通过 MRTR 进行引导(
InputRequiredResult/inputRequests/inputResponses)HTTP 传输采用 OAuth 2.1 资源服务器姿态(RFC 9728、RFC 8707、RFC 9207;CIMD 取代已弃用的 DCR)
用于长时间运行分析的任务扩展(
io.modelcontextprotocol/tasks)正确的错误码(未找到为
-32602,头部绑定违规为-32020)不使用已弃用的
roots/sampling/logging原语
许可证
MIT——参见 LICENSE。
Available Tools
6 toolscheck_docx_structureA
Extract structural facts from a .docx file: heading hierarchy, TOC consistency, header/footer consistency, page-numbering-field presence, orphaned/empty styles, list-numbering restarts, and image/table caption presence + sequencing. Returns facts and anomaly flags only — never a verdict on correctness (see the server's global instructions).
Accepts the document either as a filesystem path OR as inline
content_base64 (with filename required alongside it) —
useful when the .docx only exists in the conversation (e.g. a
file uploaded directly in chat) rather than saved to disk.
Exactly one of the two input forms must be given.
Inputs: path, filename, content_base64. Returns: Output schema for check_docx_structure (brief §4.1).
check_docx_typographyA
Per-paragraph resolved font/size/weight (full style-chain resolved, with provenance per property) plus flags for paragraphs whose resolved combination is statistically unique in the document, and for paragraphs whose runs don't all resolve to the same combination. Facts and anomaly flags only — never a verdict on what formatting should be (see the server's global instructions).
Accepts the document either as a filesystem path OR as inline
content_base64 (with filename required alongside it) — for
a .docx that only exists in the conversation rather than saved
to disk. Exactly one of the two input forms must be given.
Inputs: path, filename, content_base64. Returns: Output schema for check_docx_typography (brief §4.3).
check_filename_consistencyA
Tokenizes the filename (stripping extension, separators, common document-type stopwords, and — heuristically — the document owner's own leading First/Last name tokens), then flags any remaining proper-noun-like token that doesn't appear anywhere in the extracted document text. Facts only: presence or absence — never a verdict on whether a mismatch is intentional (brief §3, §4.4).
Accepts the document either as a filesystem path OR as inline
content_base64 (with filename required alongside it — this
is exactly the name that gets tokenized, so pass the file's
real name here, not a placeholder). Exactly one of the two
input forms must be given.
Inputs: path, filename, content_base64. Returns: Output schema for check_filename_consistency (brief §4.4).
check_languageA
Grammar/spelling/punctuation/style findings via a local
LanguageTool instance, with paragraph/offset anchors so the
model can locate and fix issues precisely. If lang isn't
given and the language can't be auto-detected with confidence,
asks the client which language it is (MRTR elicitation) rather
than guessing. Facts and LanguageTool's own suggestions only —
never a rewritten "corrected" version of the text.
Accepts exactly one of: a filesystem path, raw text, or
inline content_base64 (with filename required alongside it)
for a .docx/.pdf that only exists in the conversation rather
than saved to disk.
Inputs: lang, path, text, filename, +1 more. Returns: Output schema for check_language (brief §4.2, §5.3). `language` is a genuine th…
check_pdf_layoutA
Per-character font/size/coordinates, computed baseline spacing, margin/indent consistency, font inventory, declared-vs-embedded font substitution detection, and intra-line horizontal collision flags (tab-stop-overflow signature). Facts and anomaly flags only — never a verdict on correctness (see the server's global instructions).
Accepts the document either as a filesystem path OR as inline
content_base64 (with filename required alongside it) — for
a .pdf that only exists in the conversation rather than saved
to disk. Exactly one of the two input forms must be given.
Inputs: path, filename, content_base64. Returns: Output schema for check_pdf_layout (brief §4.3 PDF half).
full_reportA
Runs every applicable check for the document (format auto-
detected from the file extension: .docx or .pdf) and returns an
aggregated report as a report://{file_id} resource URI, plus an
inline summary. profile selects a subset: "full" (default,
every applicable check) or "typography_only" (just the format's
typography/layout check — check_docx_typography for .docx,
check_pdf_layout for .pdf). The full persisted report can be
re-read later via the returned URI without re-running analysis
(brief §5.1/§5.2). Facts and anomaly flags only, aggregated
from each check's own output — never a merged verdict (brief
§3, see the server's global instructions).
Accepts the document either as a filesystem path OR as inline
content_base64 (with filename required alongside it) — for
a file that only exists in the conversation rather than saved
to disk. Exactly one of the two input forms must be given.
Inputs: path, profile, filename, content_base64. Returns: Output schema for full_report (brief §6). This is the inline summary the tool c…
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each check targets a clearly distinct concern: DOCX structure, DOCX typography, PDF layout, language, filename consistency, and the aggregated report. The only potentially overlapping tool, full_report, is explicitly an aggregator rather than a separate analysis, so an agent can reliably select the right tool.
Five of the six tools follow a consistent check_<target>_<aspect> pattern, making the set highly predictable. The one deviation is full_report, which breaks the check_ prefix but is still descriptive and unlikely to confuse.
Six tools is a well-scoped size for a document-inspection server. Each tool covers a distinct aspect of analysis with no redundant or extraneous additions.
The tool set covers the major inspection needs for DOCX and PDF documents: structure, typography/layout, language, filename consistency, and a full aggregated report. Since the server is explicitly analysis-only and returns facts rather than edits, there are no obvious missing operations within its stated purpose.
Maintenance
Related MCP Connectors
Preflight QA for AI-agent deliverables with structured verdicts and repair guidance.
Checks finished AI work after it is done: figures, citations and quotations, with a signed record.
Free mechanical checks for AI text: unnamed counts, dangling references, bad arithmetic, misquotes.
Fact-checks generated content against your sources of truth showing what to trust, change, & verify.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to extract and analyze text content from various document formats (PDF, DOCX, PPTX, XLSX) in local knowledge bases, and create new formatted Word and Excel documents with structured data and reports.5MIT
- FlicenseNot gradedqualityDmaintenanceEnables deterministic visual and structural analysis of PDF and DOCX documents, extracting measurable evidence such as blur, OCR confidence, and image anomalies for auditable forensic workflows.1-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to generate format-stable, editable Word DOCX documents from structured content and reusable templates, with document type recognition, schema retrieval, template rendering, validation, and conservative fixes.MIT
- AlicenseAqualityBmaintenanceEnables agents to check AI-written documents against a fixed facts file for number accuracy and context, listed skills, blocked phrases, and tone warnings, returning structured reports and exposing allowed facts, skills, and blocked phrases.2Apache 2.0