Vellum

一个 MCP 服务器，在生成的文档（.docx、.pdf）到达用户之前对其进行检查——提取关于结构、排版、间距和语言正确性的硬性、可量化的事实，使 AI 助手能够发现自己的格式错误，而不是将其交付出去。

基于 2026-07-28 MCP 规范构建。完整的设计原理参见 docs/architecture.md。

为什么

文档生成技能会产出 .docx/.pptx/.pdf 输出，但没有任何机制自动验证结果是否格式良好：标题层级可能被跳过、字体可能不一致、间距可能漂移、语法错误会悄然通过。Vellum 是一个验证层，而不是生成器。

Related MCP server: mcp-server-docx

核心原则

服务器提取事实。模型做出判断。

Vellum 从不说“这是错的”。它说的是“这里是实际为真的事实，这里是相对于文档其余部分在统计上异常的内容。”判断某个值对于一行在文档中的角色（标题 vs. 题注 vs. 正文）是否合适，属于语义判断，由调用方模型负责——该模型拥有文档的完整上下文——而服务器没有，也不应尝试拥有。

工具

每个工具都返回结构化事实加上异常标记——绝不下结论。

每个工具都接受文档，既可以是文件系统 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。