Vellum

Vellum

Provider-agnostic production structure + provenance for AI asset generation, surfaced as MCP tools. Workspace → project → sequence → shot → version. Append-only provenance. Reproduce anything.

---

Why this exists

AI asset generation never stays in one tool. A production pulls from ComfyUI, Replicate, FAL, Scenario, and bespoke agent workflows — and the moment it does, the asset graph collapses. Files spill across services, seeds get lost, model versions drift, and "which run made this frame?" turns into a half-day archaeology dig. Vellum is the neutral layer that sits between any generator and any downstream workflow: it gives a production the structure it needs — project, sequence, shot, version, immutable provenance, and lineage you can diff and reproduce — no matter which backend produced the pixels.

> "We don't just care about the final image — we care about exactly how it was made." >    — a recurring theme in every studio conversation

What it does

One Node.js process. Two transports. One coherent surface.

Vellum is an MCP server that exposes seven coarse-grained tools (under the 12-tool MCP cap), runs over both stdio and Streamable HTTP simultaneously, and ships with a Preact dashboard served from the same process. Any MCP-compatible AI agent — Claude Desktop, Claude Code, Cursor, MCP Inspector — gets the same tool surface, and can learn it cold from the self-describing vellum://capabilities and vellum://output-contract resources. A generation can flow outbound (submit and poll any configured provider — ComfyUI, Replicate, …) or inbound (any agent or provider webhook registers a finished asset by URL). Either way it auto-creates an immutable, versioned record you can diff, reproduce, or iterate from.

The seven tools

| Tool | Purpose | Actions | | ------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------- | | workspace | Top-level container (one studio, one client, one project group) | create, list, get | | project | A film, episode, spot, or campaign within a workspace | create, list, get | | sequence | A scene or shot group within a project | create, list, get | | shot | An individual shot — zero-padded version naming (v001, underscore-separated) | create, list, get | | generation | Submit/poll any provider (ComfyUI, Replicate, …); reproduce/iterate; or register an externally-produced output | submit, status, reproduce, iterate, register | | version | Read versions, full provenance, and structured diffs between any two | get, list, provenance, diff | | asset | Tag versions, attach arbitrary metadata, and query across the hierarchy | add_tag, remove_tag, set_metadata, remove_metadata, query, list_tags, list_metadata_keys |

Every response carries the full hierarchy breadcrumb (workspace > project > sequence > shot), every tool input is Zod-validated, every error is human-readable with actionable guidance.

Architecture

Four layers, each independently testable:

• MCP tools (src/tools/*-tool.ts) — thin Zod-validated entry points. Discriminated unions on action. Zero business logic.
• Engine facade (src/engine/) — pure TypeScript, zero MCP dependency. HierarchyRepo, VersionRepo, ProvenanceRepo, AssetsEngine. Architecture-purity tests enforce this boundary at the type-level on every commit.
• Provider adapters (src/providers/, src/comfyui/) — every generation backend implements one GenerationProvider interface (submit / status / download / validate). ComfyUI Cloud and Replicate ship today; adding a backend is one class + a registry entry, and the engine never changes. SSRF-safe redirect gates, host allowlists, size caps, and atomic streaming downloads throughout.
• SQLite + WAL (drizzle/) — Drizzle ORM, four hand-prefixed migrations, busy_timeout=5000. Append-only provenance is structurally enforced (the repo has no update or delete methods — there is no path to mutate the truth).

Provenance — the differentiator

Every generation captures the full provenance:

• workflow_json / prompt_json — for graph backends (ComfyUI): the submitted workflow + the resolved prompt with seeds and model paths baked in
• generation_request_json / generation_result_json — the neutral, provider-agnostic record (params, models, output hash) for URL backends (Replicate, …) and externally-registered outputs
• provider, seed, model_names, timestamp, lineage links, optional checksums + C2PA manifests

You can:

• version diff any two versions and get a structured comparison of what changed (params, seed, models, workflow shape, metadata)
• generation reproduce any version verbatim — re-submits the stored prompt_json exactly, creating a new version with lineage_type='reproduce' and a parent pointer
• generation iterate from any version with node-scoped overrides + an optional new seed, creating a new version with lineage_type='iterate' and the parent tracked

Provenance records are immutable by construction. The ProvenanceRepo exposes only insertEvent, getEventsForVersion, getLatestCompletedEvent, and getSubmitEvent. There are no setters. Prototype-assertion tests fail the build if anyone ever adds one.

Quickstart

1. Install

git clone https://github.com/alvdansen/vellum.git
cd vellum
npm install

Node 20+ required. SQLite database (vellum.db) auto-creates on first server start.

2. Configure a provider

cp .env.example .env
# ComfyUI Cloud:  COMFYUI_API_KEY      (from https://platform.comfy.org)
# Replicate:      REPLICATE_API_TOKEN
# Choose a default with DEFAULT_PROVIDER (ComfyUI wins when it's the only one set).

Vellum discovers whichever provider credentials are present and selects a default backend. The ComfyUI endpoint is locked at https://cloud.comfy.org with healthcheck path /api/system_stats — audited as the only working combination as of v1.0, with the rationale captured by the read-only probe matrix at scripts/probe-comfy-endpoint.mts. Hierarchy, provenance, and generation register (inbound) work with no provider credentials at all.

3. Smoke test (~5 seconds, no human watching)

npm run smoke

This drives the live MCP SDK client (scripts/inspector-smoke.mjs) over stdio and runs 56 wire-level assertions — full hierarchy walk, breadcrumbs at every level, error envelopes, shot-format validation, pagination, get-by-id round-trips. If this is green, the entire MCP transport + tool registration + engine wiring works end-to-end.

4. Full test suite

npm test

Expected: 760 of 763 passing (3 documented pre-existing timing flakes under full-suite load). The suite covers hierarchy CRUD, ComfyUI client SSRF guards, append-only provenance invariants, asset query/filter composition, dashboard signal store, SSE wire-shape, and three cross-cutting regression guards (architecture-purity, phase-attribution, validation-flags).

5. Live, end-to-end with the dashboard

# Terminal 1 — start the HTTP server (also serves the dashboard)
npm run start:http

# Browser
open http://localhost:3000

# Terminal 2 — drive the server with the MCP Inspector
npm run inspect

Now create a workspace → project → sequence → shot, submit a generation, and watch the active-generations panel update via SSE as the job moves submitted → running → completed. When it finishes, a new version card appears in the timeline with full provenance drill-down.

Connecting an MCP client

Claude Code

claude mcp add vellum --scope user -- bash -c "cd $(pwd) && exec npx -y tsx src/server.ts"

Then in any Claude Code session: /mcp lists the seven tools, or just ask Claude to "create a workspace called 'demo' using vellum".

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "vellum": {
      "command": "npx",
      "args": ["-y", "tsx", "/absolute/path/to/vellum/src/server.ts"]
    }
  }
}

Streamable HTTP (web agents, custom clients)

Start the HTTP transport:

npm run start:http

The MCP endpoint is POST http://127.0.0.1:3000/mcp (loopback only by default). The dashboard, REST API, and SSE feed share the same Hono app — same port, no separate dev server.

Project structure

vellum/
├── src/
│   ├── server.ts              # dual-transport entry point (stdio + Streamable HTTP)
│   ├── tools/                 # 7 MCP tools — Zod-validated, thin
│   ├── engine/                # pure-TS facade, zero MCP dependency
│   ├── comfyui/               # ComfyUI Cloud client (SSRF-safe, healthchecked)
│   ├── http/                  # Hono REST routes + SSE handler + error middleware
│   └── __tests__/             # cross-cutting invariants (purity, attribution, validation)
├── packages/
│   └── dashboard/             # Preact + Tailwind v4 + signals; built into dist/
├── drizzle/                   # SQLite migrations (4 of them, hand-prefixed)
├── scripts/
│   ├── inspector-smoke.mjs    # 56-check programmatic UAT — the canonical smoke test
│   └── probe-comfy-endpoint.mts  # read-only matrix probe for endpoint discovery
└── docs/                      # diagrams + decision records

Quality bars

This is a v1.0 audit-passed milestone, not a sprint demo.

• Audit: passed per the v1.0 milestone re-audit. 38 of 38 v1 requirements verified, 9 of 9 phases verified, 5 critical end-to-end flows green, 4 prior tech-debt categories closed by audit-driven gap-closure phases before archival.
• Cross-cutting regression guards:
• architecture-purity.test.ts — no MCP imports outside src/tools/, no engine-layer Zod, no test-only sentinel strings in production code
• phase-attribution.test.ts — every shipped phase's frontmatter requirements-completed: is a superset of the ROADMAP attribution
• validation-flags.test.ts — Nyquist Wave 0 status flags hold across every phase
• Tool budget: 7 of 12 MCP tools used at v1.0 (workspace, project, sequence, shot, generation, version, asset) — coarse-grained action parameters keep the surface lean.
• Live-smoke: ComfyUI Cloud round-trip (generation submit → generation status → completed → version provenance) green twice back-to-back as of 2026-04-24.

Roadmap

v1.0 — MVP (shipped 2026-04-28)

Hierarchy, async ComfyUI generation, append-only provenance with reproduce/iterate lineage, asset tagging and query, Preact dashboard, dual-transport MCP server.

v1.1 — Provenance Verification (C2PA) (in design)

Driven by EU AI Act Article 50 (effective Aug 2026) and California SB 942 (in effect Jan 2026). v1.0 captures private provenance; v1.1 makes it signed, portable, and regulator-verifiable.

• Signed C2PA manifests embedded in supported output formats (PNG, JPEG, MP4, WebP)
• Explicit AI disclosure (c2pa.created action assertion)
• Model fingerprinting — SHA-256 for every checkpoint, LoRA, VAE referenced (closes the model_hash: null gap at src/engine/provenance.ts:69)
• Ingredient graph — parentOf (lineage), componentOf (control/reference images), inputTo (prompt + params) assertions
• Sidecar .c2pa manifests for non-native-embed formats (OpenEXR et al.)
• Redaction action — strip sensitive values while preserving the fact of redaction
• New tool actions: version export_manifest / version verify_manifest

v2.0 — Provider-agnostic (shipped)

Decoupled from any single generation backend and rebranded from "VFX Familiar" to Vellum.

• GenerationProvider interface — every backend is an adapter (src/providers/); the engine has zero backend-specific dependency, enforced by architecture-purity tests
• Three adapters behind one seam: ComfyUI Cloud, Replicate, and FAL (all raw REST, no SDK), selected via a provider registry + multi-credential config. Security-critical URL-provider logic (recursive output extraction, SSRF-guarded streaming download) is shared, not duplicated
• Cross-provider reproduce — reproduce works for URL providers via neutral params-replay (re-submits the original request), with the capabilities resource honestly advertising per-provider reproduce support
• Neutral, provider-agnostic provenance (generation_request_json / generation_result_json) recorded at completion; cross-provider version.diff compares neutral param bags via a pure params-diff
• Inbound two ways: the generation register MCP action, and a bearer-gated POST /webhooks/:provider HTTP route — both through one SSRF-guarded ingest boundary (https + host allowlist + size cap)
• Self-describing MCP resources (vellum://manual, vellum://capabilities, vellum://output-contract) so any cold agent learns the surface + how to report outputs
• Dashboard surfaces the originating backend per version (ProviderBadge)

Future

• Multi-provider routing — the engine holds one default client today; route status/reproduce to the provider that produced each version (engine holds the registry, not a single client)
• Function-calling adapter — OpenAI-compatible REST endpoint for non-MCP agents
• Advanced operations — batch shot queuing, hierarchy export, lineage graph visualization in the dashboard

License

MIT — see [LICENSE](LICENSE).

Acknowledgments

• Alvdansen Labs — for hosting this drop and for being a place where production-grade open-source AI tooling can land
• ComfyUI — for building the most extensible generative pipeline software in the field, and for the Cloud API that makes this whole thing possible
• Anthropic and Model Context Protocol — for the open protocol that makes this server portable across clients

---

Built deliberately for production. Designed to feel inevitable.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: alvdansen
• Source: alvdansen/vellum
• License: MIT

Install and usage instructions live in the source repository linked above.