Maket MCP Server

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.

Visit the Maket website →

---

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. Click any element to annotate it and send feedback back to the chat.
• 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, plus DESKTOP/TABLET/MOBILE aspect ratios for digital mockups.
• 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.

Templates use the supported Mustache subset for display and explicit data-maket-bind attributes for editing. Live mode supports boolean checkboxes, string text inputs, string-enum selects, and buttons that open a terminal-value editor. The same current values render passively in snapshots, print, and PDF output.

<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 and data snapshot; importing one starts a fresh local history at revision 1 rather than copying prior revisions. See the document-state HTML binding contract for the exact template, schema, control, and concurrency rules.

Install

Option A — npm (recommended)

# 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

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 B — Clone and hack on it

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

Starts the server on :24843 and Vite HMR on :5173. The included .mcp.json points an MCP client opened in the project at http://localhost:24843/mcp.

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[smell-long-callable], with a nearby explanation of the design reason.

Option C — 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: Node.js ≥22 and an MCP-compatible client (Claude Code, Claude Desktop, Codex, Gemini, or similar).

CLI reference

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

  bridge                Run stdio ↔ HTTP MCP proxy (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 14 compound MCP tools. Each one dispatches multiple actions:

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:

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 + typecheck + tests (must pass before commit)
npm run test        # vitest

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

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 quality — it 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).

License

MIT — © Alexandre Boyer