Skip to main content
Glama

wraft-mcp

npm CI license: AGPL-3.0-only

The mcp server for Wraft, the open-source document lifecycle platform. It gives Cursor, Claude Code, Claude Desktop, and any other MCP client a curated tool set for running the document lifecycle end to end:

  • Scaffold the pipeline — create themes, layouts, approval flows, and content types (variants) with their fillable fields

  • Author templates — write a document body in markdown; [Field Name] placeholders become fillable fields

  • Produce documents — fill a template with values, build the PDF, and move the document through its approval flow

  • Automate — wire adaptor steps (build document, email, HTTP, conditions) into workflow DAGs with conditional edges

One shared tool set, two ways to run it:

  • stdio (wraft-mcp) — your MCP client spawns the server locally; auth via env vars

  • Streamable HTTP (wraft-mcp-http) — a hosted, stateless service at /mcp; auth via per-request x-api-key header

Setup

Local (stdio) — recommended for individuals. Add to your MCP client config:

{
  "mcpServers": {
    "wraft": {
      "command": "npx",
      "args": ["-y", "wraft-mcp@0"],
      "env": {
        "WRAFT_BASE_URL": "https://app.your-wraft.example",
        "WRAFT_API_KEY": "wraft_..."
      }
    }
  }
}

Remote (hosted HTTP):

{
  "mcpServers": {
    "wraft": {
      "url": "https://mcp.your-domain.example/mcp",
      "headers": { "x-api-key": "wraft_..." }
    }
  }
}

Client timeouts: build_document can run up to 120 s. Raise your MCP client's tool-call timeout accordingly (Cursor: "timeout" per server entry) or builds will appear to fail while still completing server-side.

During development (before npm publish): "command": "node", "args": ["/ABS/PATH/wraft-mcp/dist/index.cjs"].

Related MCP server: fallengineer-us-mcp

Tools

Documents

Tool

What it does

list_documents / get_document

Documents in the organisation

create_document_from_template

Preferred create path: fills a template's placeholders from a field-values map and creates the document

create_document

Raw-payload create (escape hatch)

update_document

Update content (creates a version)

build_document

Generate the PDF (synchronous, up to ~2 min)

transition_document_state

Move a document through its approval flow

list_data_templates / get_data_template

Pre-authored templates with fillable fields

create_data_template

Author a template from markdown — [Field Name] placeholders become fillable holder fields (must match the content type's fields)

Scaffolding

Tool

What it does

list_content_types

Content types (document variants) with their fields

create_content_type

Create a variant with fields, wired to a layout, flow, and theme

list_field_types

Field types (String, Text, Date, …) for create_content_type fields

list_flows / get_flow / list_flow_states

Approval flows and their states

create_flow

Create a flow (default Draft → Publish states; custom states/approvers need the Wraft UI)

list_themes / create_theme

Themes: font + colors (font-file assets must pre-exist; pass ids)

list_layouts / list_engines / create_layout

Layouts: engine, page-template slug (pletter / contract / gantt_chart), dimensions (no letterhead upload via MCP)

list_assets

Uploaded assets by type (theme fonts, layout letterheads) — source of ids for create_theme

list_workflows / get_workflow

Automation workflows (DAGs of adaptor steps) and their full structure

create_workflow

Create a workflow: steps (adaptor + config, referenced by key) connected by edges; triggers need the Wraft UI

execute_workflow

Run a workflow with trigger data and get per-step results (synchronous)

list_workflow_runs / get_workflow_run

Run history and per-step results of a run

whoami

Verify the key: user, email, organisation, roles

Notes for agents

  • Pagination: list_* tools accept page and return page_number / total_pages / total_entries — paginate before concluding something doesn't exist. Exceptions: list_flow_states and list_field_types return plain arrays.

  • Field machine names: create_document_from_template takes fields keyed by machine name — the field's name lowercased, apostrophes stripped, spaces → _, other characters removed ("Client Name" → client_name). Get field names from get_data_template (under content_type.fields).

  • Writes are not idempotent: a timed-out create_* or build_document call may still have completed. List or fetch before retrying — a blind retry creates a duplicate.

  • No update/delete for scaffolding: themes, layouts, flows, content types, and workflows can be created but not modified or removed via MCP — clean up mistakes in the Wraft web UI. Workflow triggers also need the UI (execution is available via execute_workflow).

API keys

  • Keys are unscoped. A Wraft API key carries its owner's full role permissions — the curated tool list limits what the agent can reach, not what the credential could do elsewhere. Create a dedicated least-privilege user for MCP keys.

  • IP-whitelisted keys don't work via the hosted server. Wraft sees the MCP server's IP, not yours, so whitelisted keys get 403 ip_not_whitelisted. Use a key without an IP whitelist for hosted access, or run stdio from an allowed machine. Do not whitelist the MCP server's egress IP — that nullifies the control for everyone behind the proxy.

  • Keys are never logged by this server; redaction of x-api-key / authorization must also be configured in any logging/APM middleware added around it.

Hosted deployment

See deploy/README.md — Docker image, env reference, ready-made compose + nginx edge, and the hosting checklist.

Development

npm install
npm test          # unit tests
npm run typecheck
npm run build     # dist/index.cjs (stdio) + dist/http.cjs (HTTP)

# live smoke against a running Wraft (runs whoami by default; exits non-zero on tool errors):
WRAFT_BASE_URL=http://localhost:4000 WRAFT_API_KEY=wraft_... npm run smoke
# or pass tool calls:
node scripts/smoke.mjs dist/index.cjs '{"name":"list_flows","arguments":{}}'

# optional pre-push gate (typecheck + tests + build before every push):
git config core.hooksPath .githooks

License

AGPL-3.0-only — see LICENSE.md.

Available Tools

15 tools
build_documentA

Generate the document's PDF. Runs synchronously and can take up to two minutes — do not retry a timed-out build without checking get_document first (the build may have completed; retrying creates another build version). Fails with 422 if the document is locked (approval flow complete).

Inputs: id (required), naration.

create_data_templateA

Author a new data template for a content type from markdown. Write [Field Name] placeholders in the body and title_template — they become fillable holder fields, and MUST match the content type's field names (see list_content_types). Supported markdown: #-###### headings, paragraphs, - bullets, 1. numbered lists, > quotes, ---, bold, italic. The result reports any placeholders that didn't match a field (left as plain text) — fix and recreate if needed. NOT idempotent.

Inputs: title (required), body_markdown (required), content_type_id (required), title_template.

create_documentA

Create a document from a raw payload (escape hatch — prefer create_document_from_template). serialized must be an object: {title, body (markdown), serialized (JSON-encoded ProseMirror doc), fields (JSON-encoded field-values map)}. NOT idempotent: if the call times out, the document may still have been created — list_documents before retrying.

Inputs: raw (required), serialized (required), content_type_id (required), meta, +1 more.

create_document_from_templateA

PREFERRED way to create a document: fills a data template's placeholder fields and creates the document in one step. Get field machine names from get_data_template (content_type.fields → lowercase name, spaces to underscores, e.g. "Client Name" → client_name). NOT idempotent: if the call times out, the document may still have been created — list_documents before retrying.

Inputs: fields (required), data_template_id (required), meta, title.

get_data_templateA

Get one data template with its content type and fields. The content_type.fields list gives each field's name; the machine name for create_document_from_template is the lowercased name with spaces as underscores and other characters stripped (e.g. "Client Name" → client_name).

Inputs: id (required).

get_documentA

Get one document with its content, content type, state, versions, and approval systems.

Inputs: id (required).

get_flowC

Get one flow with its states.

Inputs: id (required).

list_content_typesA

List Wraft content types (document variants such as NDA, Offer Letter). Each includes its fields (name, type, required) — field names determine the machine names used by create_document_from_template. Paginated.

Inputs: name, page, sort.

list_data_templatesA

List Wraft data templates (pre-authored document bodies with fillable placeholder fields). Use a template id with get_data_template or create_document_from_template. Paginated.

Inputs: page, title.

list_documentsA

List documents (content instances) in the organisation. Paginated — check total_pages and paginate before concluding a document doesn't exist.

Inputs: page, sort, state, instance_id, +2 more.

list_flowsA

List Wraft approval flows. Paginated.

Inputs: name, page, sort.

list_flow_statesA

List the states of a flow in order (returns a plain array, not paginated). Use a state's id with transition_document_state. Note: states can carry approver requirements — a transition may be rejected if the API key's user is not an eligible approver.

Inputs: flow_id (required).

transition_document_stateA

Move a document to another state in its flow. Get valid state ids from list_flow_states (the document's flow is on its content type). Transitions may be rejected if the flow requires an approver the API key's user is not.

Inputs: id (required), state_id (required).

update_documentA

Update a document's content. serialized has the same object shape as create_document. Fails if the document is no longer editable (approval flow complete). Metadata is NOT updated here. NOT idempotent: if the call times out, the document may still have been created — list_documents before retrying.

Inputs: id (required), raw (required), serialized (required), naration, +1 more.

whoamiA

Get the current user for the configured API key (name, email, organisation, roles). Use to verify connectivity and see which organisation the key operates on.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 15 tools

    Disambiguation4/5

    Most tools target distinct resources and actions (documents, templates, flows, content types), with clear verb-prefixed names. The main potential confusion is between create_document_from_template and create_document, and between get_flow and list_flow_states, but the descriptions clarify their respective purposes well.

    Naming Consistency4/5

    The majority follow a consistent verb_noun pattern: get_, list_, create_, update_, build_, transition_. The only outlier is 'whoami', a common utility convention, so it doesn't disrupt overall readability.

    Tool Count5/5

    With 15 tools, the server sits at the upper end of the ideal range but every tool serves a distinct necessary function for document management, template authoring, and approval flows. No redundant or superfluous tools are present.

    Completeness4/5

    Core document lifecycle is covered: create (two ways), read, update, build PDF, and transition states. Missing delete operations for documents/templates and an update for data templates are minor gaps that agents can work around, but they don't prevent primary workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP server for MDMA (Markdown Document with Mounted Applications) — interactive Markdown with forms, approval gates, tables, and more. Exposes the MDMA spec, authoring prompts, package metadata, and live docs to AI assistants so agents can author and integrate MDMA correctly.
      8
      86 npm
      75
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A sovereign, MIT-licensed MCP server for professional-service workflow tools that runs on your infrastructure with Ed25519 signing, enabling autonomous agents to discover and invoke tools securely.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      MCP server that dynamically exposes each enabled ComfyUI workflow as a tool with JSON Schema, supports job submission with wait and idempotency, file uploads, and resource metadata, with both stdio and authenticated Streamable HTTP transports.
      3
      6
      MIT
    • F
      license
      A
      quality
      C
      maintenance
      Experimental MCP server for the wflow.com public API, enabling natural language operations on documents, registers, users, roles, and teams across one or many organizations.
      26
      6 npm
      -