# Maket [Health: Active] **Category:** πŸ’» Developer Tools **Repository:** https://github.com/ng-galien/maket **GitHub Stars:** 19 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/maket ## Description Compose branded visual documents with live preview, data collections, validation, and PDF export. ## Tools Capabilities this server exposes over MCP: - **maket_doc** β€” Document lifecycle β€” new, list, delete, duplicate, rename, meta, export/import - **maket_learn** β€” Agent onboarding β€” workflow, HTML composition, chartes, collections, review, install - **maket_workspace** β€” Session actions β€” focus, state, lock, list_messages, ack_messages - **maket_page** β€” Page structure β€” add, remove, rename, reorder, list - **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_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 Mermaid diagram to SVG and inject it - **maket_pdf** β€” Export a document to PDF via headless Chromium - **maket_gmail** β€” Gmail β€” connect, search, read, draft ## Claude Desktop Quick Installation Heuristic fallback β€” verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "maket": { "command": "npx", "args": ["-y","maket"] } } ``` ## Documentation & README # 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](https://img.shields.io/npm/v/@ng-galien/maket.svg)](https://www.npmjs.com/package/@ng-galien/maket) [![npm downloads](https://img.shields.io/npm/dm/@ng-galien/maket.svg)](https://www.npmjs.com/package/@ng-galien/maket) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/) [![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-8A2BE2.svg)](https://modelcontextprotocol.io/) [![ng-galien/maket MCP server](https://glama.ai/mcp/servers/ng-galien/maket/badges/score.svg)](https://glama.ai/mcp/servers/ng-galien/maket) [![CI](https://github.com/ng-galien/maket/actions/workflows/ci.yml/badge.svg)](https://github.com/ng-galien/maket/actions/workflows/ci.yml) [![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/ng-galien/maket/main/.github/badges/coverage.json)](https://github.com/ng-galien/maket/actions/workflows/ci.yml) [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing) **[Visit the Maket website β†’](https://ng-galien.github.io/maket/)**

Maket demo walkthrough

60 seconds Β· charte β†’ library β†’ data β†’ AI composition β†’ every kind of doc β†’ export.

--- ## 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](https://github.com/ng-galien/maket/actions/workflows/desktop-snapshot.yml) to test Maket App now. Snapshot installers are unsigned, built from `main`, and retained for 14 days. Signed macOS and Windows installers, plus Linux packages, will appear on the [latest release](https://github.com/ng-galien/maket/releases/latest) once the desktop release is published. 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](#option-b--maket-server-via-npm-advanced). ## 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. ```text 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='

{{ product_name }}

{{ price }}

' β†’ 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. ```html

{{ state.title }}

``` 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](https://github.com/ng-galien/maket/blob/HEAD/docs/document-state-bindings.md) for the exact template, schema, control, and concurrency rules. ## Installation details Pick the row that matches your machine. | Platform | Recommended | What you get | |---|---|---| | **macOS** (Apple Silicon or Intel) | [Maket App](#option-a--maket-app) β€” `.dmg` | Native window, embedded server, agent setup on first launch | | **Windows** x64 | [Maket App](#option-a--maket-app) β€” `.exe` installer | Same | | **Linux** x64 | [Maket App](#option-a--maket-app) β€” `.deb` or `.rpm` | Native window and embedded server; manual updates | ### Option A β€” Maket App Download the installer from the [latest release](https://github.com/ng-galien/maket/releases/latest), 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 build is signed and notarised, the Windows build is signed, so neither should trigger a security warning. On Linux, install the package with your distribution's package manager; updates are downloaded manually from the latest release. 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) ```bash # 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 --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 --apply`. Use `--scope=project` on `install claude` to write `/.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 ```bash 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) ```bash 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 ```text maket [command] [--data-dir ] [--port ] [--host ] 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 [] Upgrade the CLI (or pin to ); --check for a no-op compare install Wire Maket into an MCP client (claude | codex | gemini) uninstall Remove Maket from an MCP client (claude | codex | gemini) install/uninstall flags: --apply, --scope=user|project gmail Manage Gmail OAuth state (status | reset [--force]) help, version ``` ## Tools Maket exposes 14 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` | Agent onboarding β€” workflow, HTML composition, chartes, collections, review, install | | `maket_workspace` | Session actions β€” focus, state, lock, list_messages, ack_messages | | `maket_page` | Page structure β€” add, remove, rename, reorder, list | | `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_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 Mermaid diagram to SVG and inject it | | `maket_pdf` | Export a document to PDF via headless Chromium | | `maket_gmail` | Gmail β€” connect, search, read, draft | **Layout & print margins guide: [docs/layout.md](https://github.com/ng-galien/maket/blob/HEAD/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](https://github.com/ng-galien/maket/blob/HEAD/docs/gmail-setup.md).** Quick CLI helpers once set up: ```bash 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: ```bash 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
How the pieces fit together ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” 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`](https://github.com/ng-galien/maket/blob/HEAD/CLAUDE.md) for the full architectural guide.
## Development ```bash 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`](https://github.com/ng-galien/maket/blob/HEAD/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](https://github.com/ng-galien/maket/issues) or start a [discussion](https://github.com/ng-galien/maket/discussions). ## Changelog See [CHANGELOG.md](https://github.com/ng-galien/maket/blob/HEAD/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](https://github.com/ng-galien/maket/blob/HEAD/LICENSE) β€” Β© Alexandre Boyer