Skip to main content
Glama

Maket

Create visual documents with your AI assistant. Maket gives Claude, Codex, Gemini, and other MCP clients an HTML/CSS canvas with live preview. Compose a one-off design, bind a template to typed rows for mail merge, or attach validated document-owned state so native HTML controls and agent updates keep a living document current. Export finished output to PDF or hand it off to Gmail as a draft.

npm version npm downloads License: MIT Node MCP ng-galien/maket MCP server CI Coverage PRs welcome

Visit the Maket website →


Install Maket App

Maket App is the default way to run Maket. It includes the interface, server, runtime, and agent setup — Node.js is not required.

Platform

Installer

macOS Apple Silicon

Maket-macOS-arm64.dmg

macOS Intel

Maket-macOS-x64.dmg

Windows x64

Maket-Windows-x64-Setup.exe

Linux x64

Maket-Linux-x64.deb or Maket-Linux-x64.rpm

Download the newest snapshot to test Maket App now. Snapshot installers are unsigned, built from main, and retained for 14 days. The same unsigned installers for macOS and Windows, plus Linux packages, appear on the latest release.

Open the installer, launch Maket, then follow the first-run agent setup.

Need a headless server, CI installation, or browser-only deployment? Jump to Maket Server via npm.

Related MCP server: anno

Why Maket

Your AI assistant is good at writing. But design is about space, hierarchy, and rhythm — and that happens in layout, not prose. Maket adds a real canvas, reusable visual resources, and two distinct data models: collections produce repeated variants from ordered rows, while document state keeps one document synchronized with its own validated, revisioned data.

Features

  • Live preview — Changes appear in your browser the instant the AI writes them. Use Annotate in the detail document toolbar (or connected Reader) to select an element and save feedback for the agent; turn it off to resume navigation.

  • HTML/CSS canvas — Pages are real HTML sized in mm. No lock-in to a proprietary format.

  • Brand chartes — Define design tokens (colors, fonts, spacing, shadows) once; Maket enforces them during composition.

  • Image library — Drop images in, tag them, the AI picks the right one for the brief.

  • Data-driven collections — Define typed fields with JSON Schema, paste or edit ordered rows, bind a page to placeholders such as {{ product_name }}, preview one row or the full series, and render one output page per row.

  • Living documents — Attach a JSON Schema and state snapshot to one document, render {{ state.* }} values, edit supported fields through bound checkbox, text, select, and button controls, and retain immutable revisions for history and restore.

  • PDF export — Print-ready output via headless Chromium.

  • Gmail drafts — Compose an email document and hand it off to Gmail as a draft; you review and send yourself.

  • Paper & screen formats — A2–A8, DESKTOP/TABLET/MOBILE aspect ratios, and AUTO pages with a defined width and content-driven height.

  • Agent skills included — Three skills (maket, maket-charte, maket-review) that teach the AI assistant how to design, brand, and review documents.

What it looks like

You    — fais-moi un flyer A5 pour un concert jazz dimanche soir, ambiance feutrée

AI     — maket_doc new doc="Jazz flyer" format=A5 orientation=portrait
         maket_charte view name="Smoky Club"
         maket_html set doc="Jazz flyer" page=1 context_token=...
         → Live preview opens. Warm amber on deep navy, serif display for
           the headline, fine sans for the venue details.

You    — (clicks the date on the preview) "rends-la plus grosse"

AI     — maket_workspace list_messages → sees your note
         maket_html patch doc="Jazz flyer" ops=[...]
         → Date scales up, hierarchy re-balanced.

You    — parfait, exporte

AI     — maket_pdf doc="Jazz flyer"
         → ~/.maket/exports/jazz-flyer.pdf

Data-driven documents

Collections turn a page into a reusable template for product labels, event badges, personalized flyers, certificates, catalog pages, or any other repeated document. Each collection owns a JSON Schema and a set of ordered rows. Bind it to a page, place typed values in the HTML with {{ field_name }}, and Maket renders one variant per row.

The Collections workspace and maket_collection tool both support schema changes, row insertion/update/delete, paste-oriented tabular editing, and validation feedback. Maket validates the schema, every row, and every placeholder before rendering. In the preview you can keep the raw template visible, inspect one selected row, or display the complete generated series; print and PDF output expand the bound page across all rows.

You    — crée une série d'étiquettes produit avec le nom et le prix

AI     — maket_doc new doc="Product labels" format=A6 orientation=portrait
         maket_collection action=create name=products
           schema='{"type":"object","properties":{"product_name":{"type":"string"},"price":{"type":"string"}},"required":["product_name","price"]}'
         maket_collection action=add_row name=products
           data='{"product_name":"Earl Grey","price":"12 €"}'
         maket_collection action=add_row name=products
           data='{"product_name":"Sencha","price":"14 €"}'
         maket_collection action=bind doc="Product labels" page=1 name=products
         maket_html set doc="Product labels" page=1
           html='<article data-id="label"><h1 data-id="name">{{ product_name }}</h1><p data-id="price">{{ price }}</p></article>'
         → The preview can show the template, either product, or both generated labels.

You    — exporte toute la série

AI     — maket_pdf doc="Product labels"
         → One PDF page per collection row.

Living documents

Document state is for a single evolving artifact: a checklist, status board, form, or report whose current values belong to that document. maket_state initializes a JSON Schema and data snapshot, validates every update, requires the current revision for mutations, and records each accepted change as a complete immutable revision. Updates re-render the existing pages; they do not create mail-merge variants.

A page can use HTML, JSON Forms, or HTML embedding its current JSON Forms template at <!--maket-json-form-->. A hand-authored HTML template uses the supported Mustache subset for display and explicit data-maket-bind attributes for editing. A JSON Forms template is set with maket_page action=set_form; its optional UI schema controls layout while the document-state JSON Schema supplies fields and choices. Maket renders both formats with native controls through the same state owner. The same current values render passively in snapshots, print, and PDF output.

For sequential questions, keep the subject and answer-history Mustache list in HTML, place exactly one <!--maket-json-form--> inside a static block container outside Mustache sections, and call maket_page action=set_form for each question. Changing the form preserves the HTML and document state. The embedded form adapts to its container.

JSON Forms styling is renderer-owned: attach a charte to apply its text, background, surface, border, accent, muted, and font tokens. The UI schema controls structure and presentation options, not arbitrary CSS.

<h1 data-id="title">{{ state.title }}</h1>
<label data-id="done-label">
  <input data-id="done-input" type="checkbox" data-maket-bind="state.done">
  Done
</label>
<input data-id="owner-input" type="text" data-maket-bind="state.owner">

Use maket_state action=init to attach the initial schema and data, then get, patch or update, history, revision, and restore to manage it. Portable .maket bundles carry the current schema, data snapshot, and template format; importing one starts a fresh local history at revision 1 rather than copying prior revisions. See the document-state template contract for the exact template, schema, control, and concurrency rules.

Structured Workspaces

A Structured Workspace groups one or more named collections whose detail views are real, persistent living documents. Its data schema validates every item and may use oneOf; its representation schema gives each collection a global template and binds concrete schema paths to compact and detail template documents. Every collection has its identity, a JSON Pointer to a required string or number property of its items, /id by default when the data schema requires an id property (so a Workspace is still created from a data schema alone); the value of that property, as a string, is the item id everywhere (documents, annotations, pins, cursors, MCP calls), unique across the whole Workspace, all collections included, and Maket never generates one. Adding an item without that value, or with a value another item of the Workspace already bears, is refused naming the field or the existing item; an update cannot change it, and the generated detail form shows it read-only. Adding an item stores its data at revision 1 and gives it the next value of its collection's insertion sequence, a stored counter that only grows and is never reused. A collection may declare sortBy (a JSON Pointer into the item data, such as /place) with sortDirection ascending or descending, and its index then orders the cards of each group by that value and equal values by item id, re-sorted whenever an item or the definition changes, while a collection without it keeps insertion order. Workspaces created before declared identities were migrated once: each collection without identity gained an id property holding the former item id (or itemId when an id property held other values), so documents, annotations and pins kept resolving; a Workspace read from a bundle written before identities gets the same declaration at import.

Items are served to the index, the workspace views and the MCP answers through a data source interface (ItemSource, in packages/server/src/services/item-sources/): it lists item summaries in index order with a cursor and a total, reads one item with its revision, and writes at an expected revision. Its first implementation is Maket's own storage, where each item is one row of structured_workspace_items holding its data and revision. The source holds the data and the document holds the rendering: an item's document is created only when the item is first opened, with an id derived from the Workspace and item ids and the name given at add_item, which stays reserved for it whether or not it was opened (maket_doc and the document commands refuse it); item documents are not loaded when Maket starts but on demand, and stay loaded once opened; an export creates the documents it lacks and removes them once the bundle is written; an item document stays out of the Documents library and document search, and its state is a mirror of the row, refreshed on open and after each write. A .maket bundle carries each Workspace definition with its item rows (identity, data, revision) and the item documents it holds rendered, never item data in document states; an import rebuilds the rows, and an export reports every item whose document it leaves out. The detail form, maket_state and update_item all write through the source at the row revision, so a stale write is refused with the current data. The item history is not kept in the document state. The list is read by cursor: a query (free text over the collection searchFields, by default every text property, ignoring case and accents, filters, sort and a batch size, indexPageSize 50 by default and at most 500) answers one batch with an opaque next cursor, the total and the item count of each group, pushed down to one SQLite query; a new query restarts from the first item and there is no page number. The cursor is the sort value and the item id under a sort, the insertion sequence and the item id otherwise: no item that existed before the first batch and kept its sort value is skipped or repeated, while an item whose sort value changes during paging may move across the cursor. check and update_definition read the items by batches through the source, and update_definition reports the first breaches of a new definition. The server holds the current window of each collection, shared by every client and the agent, and re-reads it when the source changes: the index document renders that window (the first batch, then each batch loaded after it) under group headers that count the whole query, the index pane offers a search bar and a load-more control, the client keeps only the window and light workspace views (item counts and pinned items, never the item data), and maket_structured_workspace action=view answers one batch of the window with its cursor.

An agent builds a Workspace along one of three paths, documented step by step in maket_learn action=topic topic=structured-workspaces: from a data schema alone, where Maket writes the index, detail and card templates and an edit form itself; with the template HTML and form given inline in the create call, where Maket still creates and names the template documents in the Workspace category; or by naming template documents created beforehand, which binding moves out of the Documents library. create and update_definition refuse a definition with errors, one line per error with its collection, path and fix, unless allow_incomplete is set, and maket_structured_workspace action=check returns a ready or not-ready verdict with every finding, its correction and the next call, without changing anything.

The Workspace sidebar lists collection indexes and pinned items only; other items are opened from their index, and templates remain available in the Workspace actions menu. The icon-only display toggle in the general toolbar switches between a single document (Square) and list/detail (PanelLeft); there is no separate view-choice toolbar. Opening another item replaces the current detail pane; closing the item returns to its index. Both panes open in Reader with ordinary scrolling; a narrow AUTO list holds the batches loaded so far on one continuous page, and its load-more control appends the next batch. Explicit Canvas navigation enables independent wheel zoom and drag pan, and the header percentage resets the fit. A draggable, keyboard-accessible separator starts at 28/72 and adjusts the widths. On narrow windows the library opens as an overlay, preserving readable document widths and its pin preference. Item pins persist and can be removed from the sidebar. This browsing surface keeps live document forms interactive; template authoring continues on the canvas.

Reader shows the focused document with titles above each page of a multi-page document. Entering Reader from collection browsing preserves the current page; switching between its open index and item keeps their navigation context. Closing Reader restores the originating document and page and the single/split layout. Passive page visibility in either split pane remembers its own position without taking focus from the other pane. Closing all documents cancels pending explicit openings, so late server replies cannot reopen the workspace.

Template-controlled pages stay synchronized across every existing item and index document and are edited at the template. Pages added to one instance remain editable and survive template synchronization. maket_structured_workspace exposes workspace creation, revision-checked schema and template-binding changes, item creation and mutation, deletion, inspection, and explicit template synchronization through MCP.

Installation details

Pick the row that matches your machine.

Platform

Recommended

What you get

macOS (Apple Silicon or Intel)

Maket App — .dmg

Native window, embedded server, agent setup on first launch

Windows x64

Maket App — .exe installer

Same

Linux x64

Maket App — .deb or .rpm

Native window and embedded server; manual updates

Option A — Maket App

Download the installer from the latest release, using the filename for your platform:

  • macOS Apple Silicon — Maket-macOS-arm64.dmg

  • macOS Intel — Maket-macOS-x64.dmg

  • Windows x64 — Maket-Windows-x64-Setup.exe

  • Linux x64 — Maket-Linux-x64.deb or Maket-Linux-x64.rpm

On macOS, open the .dmg and drag Maket onto Applications. On Windows, run the installer; it sets up the Start menu entry and a desktop shortcut. The macOS and Windows installers are currently unsigned. On macOS, if Gatekeeper blocks the first launch, Control-click Maket, choose Open, then confirm once. Windows may show a SmartScreen warning that must be confirmed manually. On Linux, install the package with your distribution's package manager; updates are downloaded manually. For a version not yet released, use the Linux snapshot artifact from the matching main commit. See Linux installation and sandbox diagnostics.

Maket App carries its own runtime — you do not need Node.js installed. On first launch it offers to wire the AI clients it finds on your machine (Claude Code, Codex, Gemini) to its embedded server, and it can install the bundled connector for Claude Desktop. The embedded server listens on 127.0.0.1:24843.

If a Maket server is already running from a previous npm install, the application says so and offers to stop it and take over — nothing is killed without your confirmation.

The window is not the only way in: the Maket menu has Ouvrir dans le navigateur, which serves the same workspace at http://127.0.0.1:24843 in any browser on that machine. Only that machine — the server never binds a public interface, so nothing is exposed to your network.

Updates are checked automatically and installed on your confirmation. The Candidate channel in Settings opts you into validation builds.

Option B — Maket Server via npm (advanced)

# Install Maket and its compatible headless Chromium
npm install -g --allow-scripts=puppeteer @ng-galien/maket

# Wire Maket into your AI client (drop --apply for a dry run)
maket install claude --apply
maket install codex  --apply
maket install gemini --apply

# Start the local server and open the preview
maket start
maket open

In Chrome, Edge, or another supporting browser, use Install Maket in the browser UI or in Maket Settings to keep the workspace in its own application window. This PWA uses the same local server: it does not start, stop, or update the native process, so maket start, maket stop, and maket update remain explicit terminal commands.

The explicit --allow-scripts=puppeteer is required by npm 11+'s dependency script policy. It lets Puppeteer download the exact headless Chromium build declared by the installed Maket release; no browser version is hard-coded by Maket itself. Run maket doctor after installation to prove that Chromium can actually launch, the data directory is writable, and the MCP server responds.

The CLI registers the absolute local Node runtime and installed Maket entry in an mcpServers.maket entry in ~/.claude.json (or runs claude mcp add if the Claude Code CLI is installed), a [mcp_servers.maket] section in ~/.codex/config.toml, or an mcpServers.maket entry in ~/.gemini/settings.json. This standard command-plus-arguments form does not depend on the GUI application's shell PATH. Re-run maket install <client> --apply after moving the Node or Maket installation. Without arguments, the Maket entry runs as a stdio MCP bridge — that's the form Claude Desktop, Codex, Gemini, and other MCP clients invoke automatically.

Daemon controls: maket status, maket logs [--bridge], maket stop, maket restart. Diagnostics: maket doctor, maket config. Upgrade: maket update [--check]. Undo install: maket uninstall <claude|codex|gemini> --apply. Use --scope=project on install claude to write <cwd>/.mcp.json instead of the user-scope file. Global flags --data-dir, --port, --host override the matching MAKET_* env var on any command.

Option C — Clone and hack on it

git clone https://github.com/ng-galien/maket.git
cd maket
npm install
npm run dev

Starts the development server on :24844 and Vite HMR on :5173. The included .mcp.json points an MCP client opened in the project at http://localhost:24844/mcp. Port :24843 is reserved for the installed desktop application.

Code quality and architecture rules

Maket uses code-moniker for structural rules and code-smell review. The versioned rule source is .code-moniker.toml; run npm run smell:rules to inspect the default rules and npm run smell:review to review the repository. The quality gate runs this review through npm run quality.

Do not add enforceable architecture or boundary rules to AGENTS.md, and do not add ad-hoc checker scripts in parallel with code-moniker. AGENTS.md is operator guidance for agents working in the repository; it is not the project's rule engine. If a boundary rule cannot be expressed with code-moniker yet, document that as a code-moniker evolution instead of creating another local rule system.

Exceptions are local and explicit. If a rule is intentionally not applicable, keep the rule enabled and add a targeted suppression comment in the file being checked, for example // code-moniker: ignore[maket-hygiene-limits-callable-size], with a nearby explanation of the design reason.

Option D — Package as a desktop extension (.mcpb)

npm install -g @anthropic-ai/mcpb
npm run build:client
node scripts/pack-mcpb.ts
# → dist/maket.mcpb

Drag dist/maket.mcpb into a desktop MCP host (e.g. Claude Desktop → Settings → Extensions).

Requirements: an MCP-compatible client (Claude Code, Claude Desktop, Codex, Gemini, or similar). Maket App bundles everything else; the npm, clone and .mcpb routes additionally need Node.js ≥22.

CLI reference

maket [command] [--data-dir <path>] [--port <n>] [--host <h>]

  bridge                Run the MCP v2 stdio gateway (default for MCP clients)
  start                 Start the Maket HTTP server in the background
  stop                  Stop a server started by 'maket start'
  restart               Stop (if running) then start
  status                Show whether the server is reachable
  open                  Open the Maket UI in your browser
  logs [--bridge]       Tail server (or bridge) logs
  config                Print the resolved runtime config
  doctor                One-shot diagnostic (node, port, data dir, Chromium, Gmail, npm)
  update [<version>]    Upgrade the CLI (or pin to <version>); --check for a no-op compare
  install <client>      Wire Maket into an MCP client  (claude | codex | gemini)
  uninstall <client>    Remove Maket from an MCP client (claude | codex | gemini)
                          install/uninstall flags: --apply, --scope=user|project
  gmail <sub>           Manage Gmail OAuth state       (status | reset [--force])
  help, version

Tools

Maket exposes 15 compound MCP tools. Each one dispatches multiple actions:

Tool

What it does

maket_doc

Document lifecycle — new, list, delete, duplicate, rename, meta, export/import

maket_learn

Structured Markdown documentation for agents — workflow, HTML, chartes, diagrams, data, review, install

maket_workspace

Session actions — focus, state, lock, list_messages, ack_messages

maket_page

Page structure and JSON Forms templates — add, remove, rename, reorder, list, set_form, get_form

maket_canvas

Canvas setup — format, orientation, background, per-side print margins

maket_html

Page content — set (full replace), patch (surgical ops by data-id), get, check (layout overflow / overlap / margin clearance)

maket_charte

Brand chartes — list, view, set, delete

maket_collection

Typed data collections — list, view, create, validate/change schema, add/update/delete rows, bind/unbind a page

maket_state

Document-owned state — initialize, get, update or JSON Patch, validate/change schema, inspect history and revisions, restore

maket_structured_workspace

Schema-driven item collections — create (templates generated from the schema or given inline, identity declared per collection), check, read items by cursor, add/update/delete items, synchronize template pages

maket_image

Asset library — list, view, meta, import, delete

maket_preview

Open the live preview URL or snapshot a page to PNG

maket_mermaid

Render a durable, charte-aware Mermaid diagram with semantic tokens and safe visual controls

maket_pdf

Export a document to PDF via headless Chromium

maket_gmail

Gmail — connect, search, read, draft

Layout & print margins guide: docs/layout.md — what the cyan safe-zone in the preview means, margin presets per use case, and prompts to ask the assistant when something looks off.

Plugin & skills

The MCP server exposes maket_learn, the source of truth for agent onboarding. Skills stay thin: they orient Claude, Codex, or Gemini toward the live tool guidance instead of duplicating product knowledge. Human onboarding is separate and opens from the Help button in the Maket UI.

The plugin/claude/ directory ships three agent skills:

  • maket — Orientation skill. Starts with maket_learn, then uses the MCP tools for design work.

  • maket-charte — Brand-identity expert. Builds coherent design-token systems from a brief, an industry, or a reference URL.

  • maket-review — QA agent. Audits charte compliance, image paths, layout overflow; fixes issues via maket_html patch.

Claude, Codex, and Gemini compatibility files live under plugin/.

Configuration

By default Maket stores data in ~/.maket/:

  • documents.db — SQLite (documents, chartes, collections, assets metadata)

  • assets/, documents/, exports/ — user files

Override with environment variables:

Variable

Default

Purpose

MAKET_PORT

24842 (24844 with npm run dev; 3333 with start:isolated)

HTTP server port

MAKET_DATA_DIR

~/.maket/

User data directory

MAKET_DB

$MAKET_DATA_DIR/documents.db

SQLite path

GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET

—

Gmail OAuth credentials (optional)

Gmail integration (optional, power-user)

Maket can turn a composed document into a Gmail draft (with PDF attachments). It only creates drafts — never sends. You review the draft in Gmail and click Send yourself.

Setup takes about 10 minutes: you register your own OAuth Desktop client in Google Cloud Console, enable the Gmail API, add yourself as a test user, and paste the JSON into Maket's setup form. Credentials live under ~/.maket/ with owner-only permissions — nothing in the repo, nothing on any server.

Full walkthrough + troubleshooting: docs/gmail-setup.md.

Quick CLI helpers once set up:

maket gmail status         # check whether credentials are in place
maket gmail reset --force  # wipe and start over

Bootstrap a downstream workspace

If you run Maket as a long-lived server and want other projects to connect to it:

make bootstrap DIR=/path/to/my-project PORT=3335

Creates .mcp.json, .claude/skills/, and a minimal package.json in the target directory. Never overwrites existing files.

Architecture

┌──────────┐   MCP Streamable HTTP   ┌────────────────────────┐
│ AI agent │ ──────────────────────► │  Express @ :3333       │
│  (any    │                         │  ├─ /mcp  (MCP server) │
│  MCP     │                         │  ├─ /assets, /export   │
│  client) │                         │  └─ WS /ws (preview)   │
└──────────┘                         └────────┬───────────────┘
                                              │
                                     ┌────────┴────────┐
                                     │  SQLite         │
                                     │  ~/.maket/*.db  │
                                     └─────────────────┘
                                              │
                                              ▼ WS broadcast
                                     ┌─────────────────┐
                                     │ React preview   │
                                     │  (Vite, :5173)  │
                                     └─────────────────┘
  • MCP over Streamable HTTP — stateless, one server per request.

  • Awilix DI — every service, tool pack, and HTTP route is registered in packages/server/src/bootstrap.ts.

  • Store → bus → WebSocket — every mutation emits a typed event; the preview reconciles.

  • packages/shared — wire-contract types only (WS messages, HTTP envelopes). Domain types stay per-side.

See CLAUDE.md for the full architectural guide.

Development

npm run dev         # Server + Vite HMR (most common)
npm run quality     # Lint + architecture + typecheck + Vitest coverage + versions
npm run test        # Vitest only
npm run verify:release # Both CI test jobs and their builds, including all browser tests

Pre-commit: lefthook runs biome, tsc -b, and vitest — all three must pass.

Local checks and CI

quality and the commit hook do not run Playwright. Targeted browser tests are useful during iteration, but do not replace the full delivery check:

Command

Scope

CI job

npm run verify:quality

MCP reader build, quality, client build, Pages build

Quality & Coverage

npm run test:e2e:coverage

All Chromium workflows, PDF checks, client and server coverage reports

End-to-end (Chromium)

npm run verify:release

Both commands above, with CI=1

Both jobs, sequentially locally

Before delivery, run npm run verify:release from the repository root. It stops on failure, rejects focused tests, starts isolated test servers instead of reusing one, and uses the CI retry/report settings. Review retries in the Playwright report; a successful retry is not proof that a failure was harmless. Tests use .e2e-maket or temporary directories, never development or installed-app data.

Match the CI prerequisites: Node 26, dependencies installed with npm install --no-audit --loglevel=error, Code Moniker 0.8.0 on PATH (or CODE_MONIKER_BIN), the Chromium revision installed by npx playwright install chromium, and Poppler (pdfinfo and pdftoppm; brew install poppler on macOS, poppler-utils on Ubuntu). Linux also needs Playwright system dependencies (npx playwright install --with-deps chromium). The authoritative job setup is ci.yml.

These are the same test suites and settings, not identical operating systems: CI runs on Ubuntu. Desktop packaging uses Node 22 from .desktop-node-version and native macOS, Windows and Linux runners. The release workflow also runs npm run test:package and builds the distributable installers; verify:release does not claim to validate other operating systems or a real installed-app upgrade. Coverage badges and uploaded reports are CI publication steps, not additional tests.

Client property-based tests use fast-check inside Vitest, so quality and CI run them too. They generate HTML/CSS delimiter and DOM attribute variations, then check structure, resource URLs and namespace preservation. Failures print a reduced counterexample, seed and shrink path. Replay one failing property with FAST_CHECK_SEED=<seed> FAST_CHECK_PATH='<path>' npm run test -- <test-file> -t '<test-name>'. Keep a browser regression for the reported interaction alongside these generated cases.

More scripts: dev:watch (rebuilds client into public/), dev:server, dev:client, build:client, lint:fix, test:coverage. See package.json for the full list.

Contributing

Contributions are welcome. To get started:

  1. Fork the repo and create a feature branch.

  2. Run npm install && npm run dev to set up your environment.

  3. Make your changes; keep them scoped (a bug fix doesn't need surrounding cleanup).

  4. Run npm run verify:release — both CI test suites must pass.

  5. Open a PR with a clear description of the change and motivation.

Found a bug, have an idea, or want to discuss something before building it? Open an issue or start a discussion.

Changelog

See CHANGELOG.md for user-visible changes per release. Draft the next [Unreleased] section with npm run changelog:draft (groups commits since the last tag by conventional-commit type).

Agent journal — Field notes from the agents working on Maket.

License

MIT — © Alexandre Boyer

Available Tools

16 tools
maket_canvasA

When to use: set or update the canvas (physical frame) of a document — format, orientation, background, margins. Call this before adding content to a fresh doc, or when switching a doc between formats.

Coordinates are in mm. Paper sizes — A2=420×594, A3=297×420, A4=210×297, A5=148×210, A6=105×148, A7=74×105, A8=52×74. Screen sizes — DESKTOP=288×205 (1440×1024), TABLET=167×239 (834×1194), MOBILE=79×170 (393×852). AUTO — width in mm is required; each page height follows its content. Orientation is ignored. Use normal HTML flow rather than a fixed-height wrapper. Unspecified fields keep their current value.

Inputs: doc (required), width, format, margins, +2 more.

maket_charteA

When to use: manage brand style guides (chartes). view is a prerequisite for any charte-aware HTML edit — it returns the context_token required by maket_html set/patch.

Design tokens become CSS variables (--charte-color-primary, etc.) injected into every page. Voice and rules guide content composition. maket_mermaid automatically consumes canonical diagram tokens and documented fallbacks from color/font groups; its tokenRefs option can target any existing safe token explicitly. list — list all chartes with a short colour-palette preview. view — read one charte; returns tokens, voice, rules, and context_token. set — create or overwrite a charte. delete — remove a charte.

Inputs: action (required), name, rules, voice, +2 more.

maket_collectionA

When to use: manage data collections used by page placeholders.

Collections are typed by JSON Schema and contain ordered members. A page can be bound to one collection; rendering then produces one page per member. list — list collections. view — read one collection with fields and members. create — create an empty collection from a JSON Schema. validate_schema — check a schema against existing members without saving. change_schema — apply a schema only when existing members validate. add_row / update_row / delete_row — edit collection members. delete — remove a collection. bind / unbind — bind or clear a collection on a document page. cursor — read or move a bound page's preview cursor (doc + page required). Without mode/row it reads; with mode (template|rendered|all) and/or row (member id or 1-based number) it moves. The human's live canvas, this cursor and the exports all share this state.

Inputs: action (required), doc, row, data, +5 more.

maket_docA

When to use: every persistent document-lifecycle operation — create, clone, rename, delete, list, update metadata, or move bundles in/out. For session-level actions (open a doc/page in the preview, inspect state, lock), use maket_workspace. For per-page edits use maket_page and for content use maket_html.

doc is the doc in scope for every action except list. name only appears when you need a NEW name (duplicate, rename).

Manage design documents (the workspace unit: canvas + pages + meta). new — create a blank document at doc; sets it active. Previous unsaved work is lost. list — enumerate saved documents: pinned documents first (most recently pinned first, marked 📌, with their category), then the other documents as a hierarchy of category paths. lookup — read-only identity of doc by exact name, Workspace documents included: JSON {name, id, revision (monotonic modification token), pageCount, dataModel, stateRevision (null without state)}. It never opens the preview nor changes the active document. When absent, the error lists near matches. link — return a reading path for doc, using its stable document id and configured browser base path. Prefix it with the reachable gateway origin. delete — remove doc permanently; refused if it's the only document left. duplicate — clone doc → name (format variants, A/B copies). rename — rename doc → name. meta — update doc's metadata: designNotes, teamNotes, rating, category, charte, responsive. The responsive flag applies to every browser-reader page while canvas/PDF keep authored dimensions. Owned Workspace templates accept responsive alone; sync_template propagates it. pin — pin doc at the top of the document lists (desktop library, Reader navigation, list). The most recently pinned document comes first; pinning an already pinned doc keeps its place. Allowed on locked documents. Workspace item pins appear under their collection in the Workspace sidebar; indexes and templates cannot be pinned. unpin — remove doc's pin; free documents return to their category and Workspace items disappear from the pinned shortcuts. export — write a portable .maket bundle to EXPORTS_DIR. By default the bundle embeds referenced asset binaries (images, SVGs) so it survives transfer to another machine or a fresh datadir. Pass include_assets=false for a lighter structure-only snapshot. Include doc for a single document, docs for a list, or omit both to export every document. Referenced chartes, collections, and current document-state snapshots (with their revision retention) are embedded automatically; revision history stays local. Override the filename with output. import — load a .maket bundle from input (absolute path or EXPORTS_DIR-relative). Documents land with conflict-renamed names; chartes and collections skip names that already exist. Current document-state snapshots initialize revision 1, and assets are restored to ASSETS_DIR with the existing collision rule.

Inputs: action (required), doc, docs, name, +14 more.

maket_gmailA

When to use: connect Gmail, search/read mail, download an attachment, or create a draft from a Maket document. All actions except connect require an active OAuth session — call connect first.

connect — restore the refresh token if present, otherwise open the browser for OAuth consent. Pass with_read=true to also request inbox access (drafts are always granted). search — list subject/from/date for messages matching a Gmail query. Capped at 50. Requires with_read=true at connect time. read — fetch one message by id: headers, body (3000-char truncated), attachments listing. Requires with_read=true at connect time. fetch_attachment — download one attachment (id + attachmentId from a prior read). Images land in the Maket asset library (validated, optimized, thumbnailed, metadata row). Other files (PDF, zip, docx, …) drop into <DATA_DIR>/attachments/ untouched. Requires with_read=true at connect time. draft — compose a Gmail draft from a document page. Charte tokens resolve to literals, assets inline as base64, listed docs attach as PDFs. Maket never sends — the user reviews and sends from Gmail.

Inputs: action (required), cc, id, to, +13 more.

maket_htmlA

When to use: read and write page HTML. Pick set for the initial skeleton, patch for iterative edits, get to read, check to measure overflow without writing.

Every visible element MUST have a data-id. Use flex/grid with mm units. When a charte is loaded, prefer var(--charte-*) tokens. The compliance check is narrow: it rejects (1) hardcoded colour literals that duplicate an existing charte token value (e.g. #2563EB when primary=#2563EB), (2) any hardcoded font-family when the charte defines fonts, (3) any hardcoded box-shadow when the charte defines shadows. Fresh colours that don't duplicate a token pass untouched. Layout override: data-maket-layout="ignore" excludes exactly one marked non-interactive leaf block from overflow, overlap, clipping, and margin checks. The block must have no child elements or text; controls, links, data-maket-bind and focusable/ARIA elements are ineligible. Reserve it for intentional non-content decoration after visual review. Add it only with maket_html action=patch using attr on an existing data-id; the enabling op must be the only op in that patch request. Set, insert, replace, and content HTML cannot introduce it. For a state-backed document, Mustache is display-only. The document must author editable controls and all their CSS explicitly: data-maket-bind supports for booleans, and for strings, for string enums (or for a string whose options come from a state list with data-maket-options="state.list"), and for the single-value editor; a bound button with data-maket-value="" (optionally data-maket-action="set") writes that value on click instead. Use state.foo at the root and relative foo inside state sections; never persist data-maket-path or other runtime attributes. set — REPLACE the full page HTML. Rejects the whole payload on any violation. Requires context_token when the doc has a charte. patch — apply ops by data-id: style/content/attr/insert/replace/remove/clone/moveTo. Violating ops roll back individually, the rest still apply. get — return current HTML; pass id= for a single element, format=text to strip tags. check — measure layout against the canvas + declared canvas.margins, and report page links that target a missing page; no side effects. The page is measured as readers see it: a state-backed page hydrated with the current document state (a JSON Forms page on its rendered form), a collection page with the member its preview cursor shows (first member otherwise), a Structured Workspace collection document with its items; a list that flows onto continuation pages is measured page by page; other pages as authored. The report's first line names what was measured. set and patch measure the same way. Returns a Markdown measurement report with physical canvas and content extents, root geometry, problematic addressable blocks, parent/canvas excess per side, clipping, and overlap pairs. Status: ✓ OK, ⚠ tight (block crosses a declared margin band — tighten or move into the safe zone before shipping), ⛔ overflow (block escapes the canvas, not shippable; pairwise overlaps between [data-id] blocks are reported under this same status), or ⛔ unchecked when headless validation could not run. On tight/overflow, the next: block points to a snapshot + targeted patch; unchecked is diagnostic-only to avoid blind retry loops. Page links: (canonical, 1-based page number) or navigates to that page of the same document in Canvas, Reader and viewer, and becomes an internal link in print and PDF. In the authoring Canvas a plain click selects the link for editing; ⌘-click (Ctrl-click elsewhere) follows it. The href is a literal: set and patch refuse Mustache in a page link.

Inputs: doc (required), page (required), action (required), id, +4 more.

maket_imageA

When to use: manage the asset library (images). view → meta is a required two-step: meta refuses any write without the context_token from the latest view call — proof the image was read before metadata is attributed.

Images live on disk under the assets dir; metadata lives in the store; both move together. list — list assets grouped by category; flags items missing metadata. view — load an asset inline (text + binary image) and return its context_token. MUST be called before meta. meta — write/update metadata; rejects without a current context_token. import — copy an asset in via url, path, or register-mode (filename-only for already-present files). Auto-optimises + thumbnails. delete — remove the file, thumbnail, and metadata row.

Inputs: action (required), url, path, tags, +8 more.

maket_learnA

When to use: first call for any agent entering Maket; source of operational guidance for using Maket MCP tools correctly.

Returns structured Markdown inside MCP text content. It teaches agents how to operate Maket: workflow, HTML composition, chartes, diagram styling, collections, living document state, Structured Workspaces, review loop, and client installation. This is not the user-facing Help document opened from the Maket UI.

Actions: overview — short operating model. topics — list available topics. topic — read one topic with topic=.

Inputs: topic, action, audience.

maket_mermaidA

When to use: add a diagram to a page. Works for flowcharts, sequence, class, ER, state, and XY chart diagrams. Pick this over manual SVG or nested divs when the thing you want is conceptually a graph.

Renders Mermaid syntax to durable inline SVG and injects it into the page HTML. The answer gives the document's reading path in Maket and the rendered diagram as an inline image (at most 1600 px and 1 MB of base64; beyond a 2:1 ratio, its top or left part). The source and semantic rendering choices stay on the wrapper so charte changes can rerender the diagram. The diagram scales with its wrapper (width/height drive the frame, not the SVG itself). If dataId already exists, the diagram is replaced in place — idempotent edits. A document charte is applied automatically through canonical diagram tokens and documented color/font fallbacks. tokenRefs selects any existing charte token explicitly; direct safe values take final precedence. Density controls are supported for flowchart and state diagrams by the current renderer. Source-level Mermaid styling directives are rejected; use charte tokens or safe diagram options. Header on its own line: graph TD\n A-->B (NOT graph TD; A-->B)

Inputs: doc (required), code (required), page (required), bg, +18 more.

maket_pageA

When to use: manage page structure within a document — add, remove, rename, reorder, list. For page content, use maket_html instead.

Manage pages within a document. HTML can embed the current JSON Forms template at . add — append a page with html, json_forms, or both with one form slot; sets it active. remove — delete a page by 1-based index or name; refused if it's the last page. rename — rename a page by index or current name. reorder — move a page from one 1-based position to another; activePage adjusts. list — list pages with their template format; the active page is marked ●. set_form — replace the current form, preserving HTML with a form slot; without a slot, switch to a full-page form. get_form — read one page's JSON Forms template.

Note: charte compliance (token-literal colours, font-family, box-shadow) is enforced by maket_html set/patch, not by maket_page add. If the new page must match a charte, follow maket_page add with maket_html set to validate.

Inputs: doc (required), action (required), to, from, +4 more.

maket_pdfA

When to use: export a document to PDF for sharing or print. One call renders every page in order. For a single-page raster (PNG), use maket_preview snapshot instead.

Renders every page via headless Chromium at the canvas's true mm size, then writes to EXPORTS_DIR/.pdf. Charte CSS is inlined so fonts and tokens render identically to the live preview. The result lists, by number and name, every page whose PDF rendering differs from its preview (element boxes, fonts, colours). quality — screen (96 DPI, smallest), print (150 DPI, default), hd (300 DPI). rows — collection-bound pages: preview (default, follows the page cursor), current (cursor row only), all (one page per row), template (raw placeholders). Check the cursor first with maket_collection action=cursor.

Inputs: doc (required), rows, quality.

maket_previewA

When to use: view documents outside the agent. open flips the live preview URL into the user's browser; snapshot rasterises a single page to PNG at its true mm size; show puts pages in front of the user inside the conversation.

open — launch the live preview URL (localhost) in the default browser. No params. snapshot — render a page via headless Chromium. Returns the full-size PNG as a file path on disk, the page's reading path in Maket, and the image inline (at most 1600 px on its longest side and 1 MB of base64, downscaled when larger; beyond a 2:1 ratio, the top or left part of the page). On hosts that render MCP Apps, the Maket reader also opens on that page. show — on hosts that render MCP Apps, open the Maket reader in the conversation: doc, pages ("all", 3, "3-5" or [1,4]), layout (scroll | page), start (page to open at), zoom (fit-width | actual). The user can then switch layout, jump through the page list, zoom and open the document in Maket. Other hosts get the reading path. Returns no image: use snapshot to inspect a page yourself.

Inputs: action (required), doc, page, path, +4 more.

maket_readerB

Calls of the Maket reader view (ui://maket/page): page returns one rendered page without image data, image returns one of its images downscaled to the displayed width, write sets one value of a state document as the Maket form does. Not for agents.

Inputs: doc (required), action (required), op, file, +5 more.

maket_stateA

When to use: attach durable data and immutable snapshot history to one living document.

Document state is separate from collections and mail merge. A state-backed document renders Mustache variables, sections, inverted sections, and loops from its latest revision. Every mutation stores a complete validated schema + data snapshot. History is unbounded unless the document has a revision retention. The page interface is HTML/CSS, a JSON Forms template, or HTML embedding the current form at . Configure the form with maket_page set_form. HTML uses display-only Mustache plus explicit data-maket-bind controls. JSON Forms uses the document-state JSON Schema and data, with an optional UI schema. Both formats resolve to the same JSON Pointer patches and revisioned store. init — attach a schema and initial data to a static document (revision 1; no expected_revision). get — read the schema, the revision retention (retention, null when unbounded), and the current revision. update — append a complete state snapshot; expected_revision is required. patch — apply RFC 6902 JSON Patch operations; expected_revision is required. validate_schema — validate a proposed schema against current or supplied data without saving. change_schema — atomically replace the schema and append compatible data; expected_revision is required. history — list immutable revisions newest first. revision — read one revision. restore — append a new revision containing an older schema + data snapshot; expected_revision is required. set_retention — keep retention previous revisions besides the current one and delete older ones now and after every later write; 0 keeps only the current state, null restores unbounded history. Applies to Workspace items and collection projections too.

Inputs: doc (required), action (required), data, patch, +4 more.

maket_structured_workspaceA

HTTP read increment: create/update_definition accept data_source={kind:'http',baseUrl,collectionId,bindingId,auth?:'env:NAME',list:{path,params:{cursor,limit,sort,text?,filters?},itemsPointer,nextPointer,totalPointer?,revisionPointer?},get:{path:'items/{id}',dataPointer?,revisionPointer?}}. One collection/binding, declared identity and sortBy required; grouping unavailable. Query parameters carry text/cursor/limit verbatim, sort/filters as JSON. Item data is each list object; detail is the whole response or dataPointer. nextPointer gives a server token or null; no total unless declared. Bearer auth is resolved only in the server environment. Source records are fetched by requested batch; opening a detail rereads GET. HTTP is read-only in this increment (writes refuse read_only); revisions stay opaque. view retries an unavailable source, reopen refreshes a detail. No background poll or webhook. When to use: create and operate a Structured Workspace — a schema-driven collection of items, listed in an index and opened as Maket documents built from templates.

Method (full recipe: maket_learn action=topic topic=structured-workspaces): 1) create with a data_schema alone that has a required "id" property (string), one value per item: Maket identifies the items by "/id" — or declare another identity per collection, e.g. representation_schema={"collections":{"items":{"name":"Items","identity":"/code"}}} — and Maket writes the index, detail, card templates and the detail form itself, in the Workspace category; 2) add_item; 3) check, which must answer verdict ready. Inline template HTML (detailTemplateHtml, compactTemplateHtml, indexTemplateHtml, detailForm) or names of existing template documents are the optional second and third paths. Identity: every collection has an identity, a JSON Pointer to a required string or number property of its items (e.g. "/code"); without one, "/id" when the schema requires an id property. Its value, as a string, is the item id used everywhere (item=, documents, cursors) and is unique across the whole Workspace, all collections included; Maket never generates one. add_item refuses data without it, or a value another item of the Workspace already bears (invalid_record, naming that item); update_item refuses a change of it: delete and add the item again instead. The identity of a collection holding items cannot be changed. create and update_definition refuse a definition with errors (isError, one line per error with collection, path and fix) and keep the previous definition; allow_incomplete=true persists it anyway. add_item and update_item refuse data that breaks the schema with its path, rule and fix.

The data schema validates every item. The representation schema declares one or more collections; each collection owns its global template and binds concrete schema paths to compact and detail templates. The item source holds the item data; an item's document is created from its detail template when the item is opened or exported. Template-controlled pages are synchronized from the template; instance-owned pages remain in the same document. Reading items is a cursor query: view answers one batch of item summaries for one collection (collection, default the first) with next (an opaque cursor, absent once the listing is exhausted), total and the group counts. Pass text (searches searchFields, by default every text property, ignoring case and accents), filters ([{"field":"/status","op":"eq","value":"todo"}], op in for a list), sort ({"field":"/title","direction":"descending"}) and batch (default indexPageSize, 50; at most 500) to start a new query, which also becomes the window every client sees in the index. To read the next batch, pass cursor= with the same query arguments (the answer gives the call in more): it reads the source directly and never depends on the shared window: no item that existed before and kept its sort value is skipped or read twice, while an item whose sort value changes during paging may move across the cursor. There is no page number and no previous: a new query restarts from the first item. view with neither query nor cursor answers the first batch of the collection's own order. Optional collection grouping: groupBy is a JSON Pointer into item data (e.g. "/status"), groupOrder lists group values to place first, and pageSize (default 24) caps the compact cards per collection page. With groupBy, each item slot receives a group header followed by its cards and the collection document flows onto as many pages as needed; without it, the collection stays one page. Optional collection sort: sortBy is a JSON Pointer into item data (e.g. "/place") and sortDirection is "ascending" (default) or "descending"; cards are ordered by that value inside each group, or across the slot without groupBy, items without a value last and ties in item id order; without sortBy, insertion order stays. list — list Structured Workspaces, each prefixed with ready or incomplete. view — verdict and finding count first, then the definition, item counts, pinned items, owned documents, one batch of the collection window (see the cursor query above), and reading: the reading path of that collection's index in Maket. check — the doctor: verdict ready or not ready and every finding with severity, object, sentence, fix and next call. Never writes. create — create a workspace from a data schema, with an optional representation schema; refuses errors unless allow_incomplete=true. update_definition — validate and replace the data and/or representation contract, then update the item and index documents that exist; an erroneous definition is refused and the previous one kept unless allow_incomplete=true. add_item — validate data and write the item to its source under the id its identity property holds; its document is created when the item is opened. update_item — replace item data with optimistic revision control. delete_item — delete the item from its source, with its document when it was opened. sync_template — propagate current detail-template pages while preserving instance-owned pages. rename — rename the Workspace without regenerating owned documents. delete — atomically delete the Workspace and every document, state revision, and annotation it owns.

Inputs: action (required), data, item, sort, +16 more.

maket_workspaceA

When to use: every session-level interaction with the live workspace — open a doc/page in the preview, inspect a doc's current state, toggle its lock, and process the user-message queue. For persistent CRUD on documents (create, rename, delete, duplicate, meta, import/export) use maket_doc.

focus — open doc at page page in the live preview (sets active doc + active page). state — summarise doc's current state: canvas, pages with element counts and data-source cursors (collection · mode · row), charte, pending messages. lock — lock or unlock doc. When locked, every doc-scoped mutation refuses until it's unlocked. Pass locked=true/false, or omit to toggle. fit_view — zoom out the client to fit the whole workspace (same as the Maximize button). list_messages — return pending annotations as JSON. With doc, return only that document's messages; without it, return all document and workspace messages. Each message carries docName (or none for workspace scope), pageIndex and elementId for its anchor, text, ts; a note the person changed after sending also carries edited: true and editedAt (epoch ms) — act on the current text. ack_messages — drop the given ids from whichever bucket they live in.

Inputs: action (required), doc, ids, page, +1 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 16 tools

    Disambiguation4/5

    Tools are cleanly partitioned by resource: doc for lifecycle, page for structure, html for content, canvas for frame, collection/state/structured_workspace for data, image/charte for assets and styling. Some functional overlap exists among maket_collection, maket_state, and maket_structured_workspace (all data-backed), but descriptions explicitly draw the boundaries. maket_reader is explicitly 'Not for agents,' which is odd but distinct.

    Naming Consistency5/5

    Every tool follows the same `maket_<resource>` prefix with snake_case (maket_structured_workspace) and consistent sub-action verb naming within each tool. Predictable and readable throughout.

    Tool Count4/5

    16 tools for a large document-design platform is reasonable, with each tool covering a coherent domain rather than one micro-action. Slightly above the ideal 3-15 range but no tool feels redundant.

    Completeness4/5

    The surface spans document lifecycle, pages, HTML, canvas, style, data (collection/state/structured), assets, export/preview, diagrams, and Gmail integration—broadly complete with no obvious dead ends. Minor gaps: no dedicated search across documents, and maket_reader is an outlier not intended for agent use.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Let your AI assistant design beautiful emails & layouts — in your Temway workspace. It turns Claude, ChatGPT, Cursor and friends into a visual email & layout authoring studio.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Local-first HTML review workspace for AI coding agents, enabling direct text and formatting edits, element comments, area annotations, and slide-aware review with durable agent handoffs.
      1
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to author presentations, reports, and one-pagers as visual documents that humans can edit in a WYSIWYG editor and export to a single HTML file.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents to build and edit a local-first design board of HTML screens, flows, components, design-system pages, and plan tables, then review it in a browser with undo/restore, rendering, and export tools.
      MIT