Vellum

Ein MCP-Server, der generierte Dokumente (.docx, .pdf) prüft, bevor sie den Benutzer erreichen – und dabei harte, messbare Fakten über Struktur, Typografie, Abstände und Sprachkorrektheit extrahiert, damit ein KI-Assistent seine eigenen Formatierungsfehler erkennen kann, statt sie auszuliefern.

Entwickelt gegen die 2026-07-28 MCP-Spezifikation. Siehe docs/architecture.md für die vollständige Begründung des Designs.

Warum

Fähigkeiten zur Dokumentgenerierung erzeugen .docx/.pptx/.pdf-Ausgaben, aber nichts überprüft automatisch, ob das Ergebnis wohlgeformt ist: Überschriftenebenen können übersprungen werden, Schriftarten können inkonsistent sein, Abstände können abweichen, Grammatikfehler gehen stillschweigend durch. Vellum ist eine Verifikationsschicht, kein Generator.

Related MCP server: mcp-server-docx

Kernprinzip

Der Server extrahiert Fakten. Das Modell trifft Urteile.

Vellum sagt nie „Das ist falsch.“ Es sagt: „Hier ist, was tatsächlich wahr ist, und hier ist, was im Vergleich zum Rest des Dokuments statistisch auffällig ist.“ Zu entscheiden, ob ein bestimmter Wert für die Rolle einer Zeile im Dokument angemessen ist (Titel vs. Bildunterschrift vs. Fließtext), ist ein semantisches Urteil, das beim aufrufenden Modell verbleibt, das den vollständigen Kontext des Dokuments besitzt – der Server hat ihn nicht und sollte es auch nicht versuchen.

Werkzeuge

Jedes Werkzeug liefert strukturierte Fakten plus Anomalie-Flags – niemals ein Urteil.

Jedes Werkzeug akzeptiert das Dokument entweder als Dateisystem-path oder als Inline-content_base64 (wobei filename zwingend mit angegeben werden muss) – nützlich, wenn ein Dokument nur im Gespräch existiert (z. B. direkt in einer Chat-Oberfläche hochgeladen) und nicht zuerst auf der Festplatte gespeichert wurde. Es muss genau eine der beiden Eingabeformen angegeben werden.

Status

Alle sechs Werkzeuge (check_docx_structure, check_docx_typography, check_pdf_layout, check_language, check_filename_consistency, full_report) sind vollständig implementiert, unit-getestet und gegen einen goldenen Satz von Testdateien mit bekannten absichtlich eingebauten Fehlern validiert. Die vollständige MCP-Oberfläche – Ressourcen, Prompts, Elicitation, Cache-Hinweise, OAuth-2.1-Ressourcenserver-Authentifizierung für den HTTP-Transport und korrekte Fehlersemantik – ist gebaut und getestet (163+ Tests bestehen). Siehe docs/architecture.md und PROGRESS.md für die detaillierte Build-Historie und aktuelle offene Punkte. Paketierung/Veröffentlichung (Phase 7) ist in Arbeit – noch nicht auf PyPI veröffentlicht.

Installation

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

Erfordert eine lokale LanguageTool-Instanz für check_language – siehe docs/architecture.md für die Einrichtung.

Verwendung (Claude Desktop / beliebiger MCP-stdio-Client)

Fügen Sie Ihrer MCP-Client-Konfiguration Folgendes hinzu (siehe examples/claude_desktop_config.json):

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

Entwicklung

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

Golden-Set-Testdateien (Beispiel-.docx/.pdf-Dateien mit absichtlich eingebauten Fehlern) befinden sich in golden_set/. Alle Prüfungen werden gegen diese validiert, bevor sie als vertrauenswürdig gelten – siehe docs/architecture.md für die Vorgehensweise.

Gegen MCP Inspector validiert (mcp dev src/vellum_mcp/server.py) und gegen zwei echte MCP-Clients getestet: Claude Desktop (examples/claude_desktop_config.json) und Cursor (~/.cursor/mcp.json, gleiche {"mcpServers": {"vellum": {"command": "vellum-mcp"}}}-Struktur).

Spezifikationskonformität

• Alle Primitive: Werkzeuge, Ressourcen, Prompts (nicht nur Werkzeuge)

• Zustandsloser Kern – keine Abhängigkeit von Mcp-Session-Id

• Elicitation über MRTR (InputRequiredResult / inputRequests / inputResponses)

• OAuth-2.1-Ressourcenserver-Ausrichtung für den HTTP-Transport (RFC 9728, RFC 8707, RFC 9207; CIMD über veraltetes DCR)

• Tasks-Erweiterung (io.modelcontextprotocol/tasks) für langlaufende Analysen

• Korrekte Fehlercodes (-32602 für nicht gefunden, -32020 für Header-bezogene Verstöße)

• Keine Verwendung der veralteten roots/sampling/logging-Primitive

Lizenz

MIT – siehe LICENSE.