Vellum

Un servidor MCP que inspecciona documentos generados (.docx, .pdf) antes de que lleguen al usuario — extrayendo hechos objetivos y medibles sobre estructura, tipografía, espaciado y corrección del lenguaje, para que un asistente de IA pueda detectar sus propios errores de formato en lugar de enviarlos.

Construido según la especificación MCP 2026-07-28. Consulta docs/architecture.md para conocer la justificación completa del diseño.

Por qué

Las habilidades de generación de documentos producen salida .docx/.pptx/.pdf, pero nada verifica automáticamente que el resultado esté bien formado: los niveles de encabezado pueden saltarse, las fuentes pueden ser inconsistentes, el espaciado puede desviarse, los errores gramaticales pasan desapercibidos. Vellum es una capa de verificación, no un generador.

Related MCP server: mcp-server-docx

Principio central

El servidor extrae hechos. El modelo emite juicios.

Vellum nunca dice "esto está mal." Dice "esto es lo que es realmente cierto, y esto es lo que es estadísticamente anómalo en relación con el resto del documento." Decidir si un valor dado es apropiado para el rol de una línea en el documento (título frente a pie de figura frente a cuerpo) es un juicio semántico que permanece en el modelo que llama, que tiene el contexto completo del documento — el servidor no lo tiene, y no debería intentar tenerlo.

Herramientas

Cada herramienta devuelve hechos estructurados más marcas de anomalías — nunca un veredicto.

Cada herramienta acepta el documento ya sea como path del sistema de archivos o como content_base64 en línea (con filename obligatorio junto a él) — útil cuando un documento solo existe en la conversación (p. ej., subido directamente en una interfaz de chat) en lugar de guardarse primero en disco. Debe proporcionarse exactamente una de las dos formas de entrada.

Estado

Las seis herramientas (check_docx_structure, check_docx_typography, check_pdf_layout, check_language, check_filename_consistency, full_report) están completamente implementadas, probadas con pruebas unitarias y validadas contra un conjunto dorado de fixtures con defectos plantados conocidos. Toda la superficie MCP — recursos, prompts, elicitación, sugerencias de caché, autenticación de servidor de recursos OAuth 2.1 para el transporte HTTP y semántica de errores correcta — está construida y probada (163+ pruebas superadas). Consulta docs/architecture.md y PROGRESS.md para el historial de construcción detallado y los elementos abiertos actuales. El empaquetado/publicación (Fase 7) está en curso — aún no se ha publicado en PyPI.

Instalación

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

Requiere una instancia local de LanguageTool para check_language — consulta docs/architecture.md para la configuración.

Uso (Claude Desktop / cualquier cliente MCP stdio)

Añádelo a la configuración de tu cliente MCP (consulta examples/claude_desktop_config.json):

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

Desarrollo

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

Los fixtures del conjunto dorado (archivos .docx/.pdf de muestra con defectos plantados deliberadamente) se encuentran en golden_set/. Todas las comprobaciones se validan contra estos antes de ser fiables — consulta docs/architecture.md para conocer la disciplina.

Validado contra MCP Inspector (mcp dev src/vellum_mcp/server.py) y probado con dos clientes MCP reales: Claude Desktop (examples/claude_desktop_config.json) y Cursor (~/.cursor/mcp.json, misma forma {"mcpServers": {"vellum": {"command": "vellum-mcp"}}}).

Conformidad con la especificación

• Todos los primitivos: herramientas, recursos, prompts (no solo herramientas)

• Núcleo sin estado — sin dependencia de Mcp-Session-Id

• Elcitación mediante MRTR (InputRequiredResult / inputRequests / inputResponses)

• Postura de servidor de recursos OAuth 2.1 para el transporte HTTP (RFC 9728, RFC 8707, RFC 9207; CIMD sobre DCR obsoleto)

• Extensión de tareas (io.modelcontextprotocol/tasks) para análisis de larga duración

• Códigos de error correctos (-32602 para no encontrado, -32020 para violaciones vinculadas a la cabecera)

• Sin uso de los primitivos obsoletos roots/sampling/logging

Licencia

MIT — consulta LICENSE.