{
  "markdown": "# Maket\n\n**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.\n\n[![npm version](https://img.shields.io/npm/v/@ng-galien/maket.svg)](https://www.npmjs.com/package/@ng-galien/maket)\n[![npm downloads](https://img.shields.io/npm/dm/@ng-galien/maket.svg)](https://www.npmjs.com/package/@ng-galien/maket)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)\n[![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-8A2BE2.svg)](https://modelcontextprotocol.io/)\n[![ng-galien/maket MCP server](https://glama.ai/mcp/servers/ng-galien/maket/badges/score.svg)](https://glama.ai/mcp/servers/ng-galien/maket)\n[![CI](https://github.com/ng-galien/maket/actions/workflows/ci.yml/badge.svg)](https://github.com/ng-galien/maket/actions/workflows/ci.yml)\n[![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)\n[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)\n\n**[Visit the Maket website →](https://ng-galien.github.io/maket/)**\n\n<p align=\"center\">\n  <img src=\"docs/demo.gif\" alt=\"Maket demo walkthrough\" width=\"800\" />\n</p>\n\n<p align=\"center\">\n  <em>60 seconds · charte → library → data → AI composition → every kind of doc → export.</em>\n</p>\n\n---\n\n## Install Maket App\n\nMaket App is the default way to run Maket. It includes the interface, server,\nruntime, and agent setup — Node.js is not required.\n\n| Platform | Installer |\n|---|---|\n| **macOS Apple Silicon** | `Maket-macOS-arm64.dmg` |\n| **macOS Intel** | `Maket-macOS-x64.dmg` |\n| **Windows x64** | `Maket-Windows-x64-Setup.exe` |\n| **Linux x64** | `Maket-Linux-x64.deb` or `Maket-Linux-x64.rpm` |\n\n[Download the newest snapshot](https://github.com/ng-galien/maket/actions/workflows/desktop-snapshot.yml)\nto test Maket App now. Snapshot installers are unsigned, built from `main`, and\nretained for 14 days. Signed macOS and Windows installers, plus Linux packages,\nwill appear on the [latest release](https://github.com/ng-galien/maket/releases/latest)\nonce the desktop release is published.\n\nOpen the installer, launch **Maket**, then follow the first-run agent setup.\n\nNeed a headless server, CI installation, or browser-only deployment? Jump to\n[Maket Server via npm](#option-b--maket-server-via-npm-advanced).\n\n## Why Maket\n\nYour 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.\n\n## Features\n\n- **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.\n- **HTML/CSS canvas** — Pages are real HTML sized in mm. No lock-in to a proprietary format.\n- **Brand chartes** — Define design tokens (colors, fonts, spacing, shadows) once; Maket enforces them during composition.\n- **Image library** — Drop images in, tag them, the AI picks the right one for the brief.\n- **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.\n- **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.\n- **PDF export** — Print-ready output via headless Chromium.\n- **Gmail drafts** — Compose an email document and hand it off to Gmail as a draft; you review and send yourself.\n- **Paper & screen formats** — A2–A8, plus DESKTOP/TABLET/MOBILE aspect ratios for digital mockups.\n- **Agent skills included** — Three skills (`maket`, `maket-charte`, `maket-review`) that teach the AI assistant how to design, brand, and review documents.\n\n## What it looks like\n\n```\nYou    — fais-moi un flyer A5 pour un concert jazz dimanche soir, ambiance feutrée\n\nAI     — maket_doc new doc=\"Jazz flyer\" format=A5 orientation=portrait\n         maket_charte view name=\"Smoky Club\"\n         maket_html set doc=\"Jazz flyer\" page=1 context_token=...\n         → Live preview opens. Warm amber on deep navy, serif display for\n           the headline, fine sans for the venue details.\n\nYou    — (clicks the date on the preview) \"rends-la plus grosse\"\n\nAI     — maket_workspace list_messages → sees your note\n         maket_html patch doc=\"Jazz flyer\" ops=[...]\n         → Date scales up, hierarchy re-balanced.\n\nYou    — parfait, exporte\n\nAI     — maket_pdf doc=\"Jazz flyer\"\n         → ~/.maket/exports/jazz-flyer.pdf\n```\n\n## Data-driven documents\n\nCollections 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.\n\nThe 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.\n\n```text\nYou    — crée une série d'étiquettes produit avec le nom et le prix\n\nAI     — maket_doc new doc=\"Product labels\" format=A6 orientation=portrait\n         maket_collection action=create name=products\n           schema='{\"type\":\"object\",\"properties\":{\"product_name\":{\"type\":\"string\"},\"price\":{\"type\":\"string\"}},\"required\":[\"product_name\",\"price\"]}'\n         maket_collection action=add_row name=products\n           data='{\"product_name\":\"Earl Grey\",\"price\":\"12 €\"}'\n         maket_collection action=add_row name=products\n           data='{\"product_name\":\"Sencha\",\"price\":\"14 €\"}'\n         maket_collection action=bind doc=\"Product labels\" page=1 name=products\n         maket_html set doc=\"Product labels\" page=1\n           html='<article data-id=\"label\"><h1 data-id=\"name\">{{ product_name }}</h1><p data-id=\"price\">{{ price }}</p></article>'\n         → The preview can show the template, either product, or both generated labels.\n\nYou    — exporte toute la série\n\nAI     — maket_pdf doc=\"Product labels\"\n         → One PDF page per collection row.\n```\n\n## Living documents\n\nDocument 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.\n\nTemplates 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.\n\n```html\n<h1 data-id=\"title\">{{ state.title }}</h1>\n<label data-id=\"done-label\">\n  <input data-id=\"done-input\" type=\"checkbox\" data-maket-bind=\"state.done\">\n  Done\n</label>\n<input data-id=\"owner-input\" type=\"text\" data-maket-bind=\"state.owner\">\n```\n\nUse `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](docs/document-state-bindings.md) for the exact template, schema, control, and concurrency rules.\n\n## Installation details\n\nPick the row that matches your machine.\n\n| Platform | Recommended | What you get |\n|---|---|---|\n| **macOS** (Apple Silicon or Intel) | [Maket App](#option-a--maket-app) — `.dmg` | Native window, embedded server, agent setup on first launch |\n| **Windows** x64 | [Maket App](#option-a--maket-app) — `.exe` installer | Same |\n| **Linux** x64 | [Maket App](#option-a--maket-app) — `.deb` or `.rpm` | Native window and embedded server; manual updates |\n\n### Option A — Maket App\n\nDownload the installer from the [latest release](https://github.com/ng-galien/maket/releases/latest),\nusing the filename for your platform:\n\n- **macOS Apple Silicon** — `Maket-macOS-arm64.dmg`\n- **macOS Intel** — `Maket-macOS-x64.dmg`\n- **Windows x64** — `Maket-Windows-x64-Setup.exe`\n- **Linux x64** — `Maket-Linux-x64.deb` or `Maket-Linux-x64.rpm`\n\nOn macOS, open the `.dmg` and drag **Maket** onto **Applications**. On Windows,\nrun the installer; it sets up the Start menu entry and a desktop shortcut. The\nmacOS build is signed and notarised, the Windows build is signed, so neither\nshould trigger a security warning. On Linux, install the package with your\ndistribution's package manager; updates are downloaded manually from the latest\nrelease.\n\nMaket App carries its own runtime — **you do not need Node.js installed**. On\nfirst launch it offers to wire the AI clients it finds on your machine (Claude\nCode, Codex, Gemini) to its embedded server, and it can install the bundled\nconnector for Claude Desktop. The embedded server listens on `127.0.0.1:24843`.\n\nIf a Maket server is already running from a previous npm install, the\napplication says so and offers to stop it and take over — nothing is killed\nwithout your confirmation.\n\nThe window is not the only way in: the **Maket** menu has *Ouvrir dans le\nnavigateur*, which serves the same workspace at `http://127.0.0.1:24843` in any\nbrowser on that machine. Only that machine — the server never binds a public\ninterface, so nothing is exposed to your network.\n\nUpdates are checked automatically and installed on your confirmation. The\n**Candidate** channel in Settings opts you into validation builds.\n\n### Option B — Maket Server via npm (advanced)\n\n```bash\n# Install Maket and its compatible headless Chromium\nnpm install -g --allow-scripts=puppeteer @ng-galien/maket\n\n# Wire Maket into your AI client (drop --apply for a dry run)\nmaket install claude --apply\nmaket install codex  --apply\nmaket install gemini --apply\n\n# Start the local server and open the preview\nmaket start\nmaket open\n```\n\nThe explicit `--allow-scripts=puppeteer` is required by npm 11+'s dependency\nscript policy. It lets Puppeteer download the exact headless Chromium build\ndeclared by the installed Maket release; no browser version is hard-coded by\nMaket itself. Run `maket doctor` after installation to prove that Chromium can\nactually launch, the data directory is writable, and the MCP server responds.\n\nThe 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.\n\nDaemon 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.\n\n### Option C — Clone and hack on it\n\n```bash\ngit clone https://github.com/ng-galien/maket.git\ncd maket\nnpm install\nnpm run dev\n```\n\nStarts 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.\n\n### Code quality and architecture rules\n\nMaket 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`.\n\nDo 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.\n\nExceptions 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.\n\n### Option D — Package as a desktop extension (.mcpb)\n\n```bash\nnpm install -g @anthropic-ai/mcpb\nnpm run build:client\nnode scripts/pack-mcpb.ts\n# → dist/maket.mcpb\n```\n\nDrag `dist/maket.mcpb` into a desktop MCP host (e.g. Claude Desktop → Settings → Extensions).\n\n**Requirements:** an MCP-compatible client (Claude Code, Claude Desktop, Codex,\nGemini, or similar). Maket App bundles everything else; the npm, clone and\n`.mcpb` routes additionally need Node.js ≥22.\n\n### CLI reference\n\n```text\nmaket [command] [--data-dir <path>] [--port <n>] [--host <h>]\n\n  bridge                Run the MCP v2 stdio gateway (default for MCP clients)\n  start                 Start the Maket HTTP server in the background\n  stop                  Stop a server started by 'maket start'\n  restart               Stop (if running) then start\n  status                Show whether the server is reachable\n  open                  Open the Maket UI in your browser\n  logs [--bridge]       Tail server (or bridge) logs\n  config                Print the resolved runtime config\n  doctor                One-shot diagnostic (node, port, data dir, Chromium, Gmail, npm)\n  update [<version>]    Upgrade the CLI (or pin to <version>); --check for a no-op compare\n  install <client>      Wire Maket into an MCP client  (claude | codex | gemini)\n  uninstall <client>    Remove Maket from an MCP client (claude | codex | gemini)\n                          install/uninstall flags: --apply, --scope=user|project\n  gmail <sub>           Manage Gmail OAuth state       (status | reset [--force])\n  help, version\n```\n\n## Tools\n\nMaket exposes 14 compound MCP tools. Each one dispatches multiple actions:\n\n| Tool | What it does |\n|------|--------------|\n| `maket_doc` | Document lifecycle — new, list, delete, duplicate, rename, meta, export/import |\n| `maket_learn` | Agent onboarding — workflow, HTML composition, chartes, collections, review, install |\n| `maket_workspace` | Session actions — focus, state, lock, list_messages, ack_messages |\n| `maket_page` | Page structure — add, remove, rename, reorder, list |\n| `maket_canvas` | Canvas setup — format, orientation, background, per-side print margins |\n| `maket_html` | Page content — `set` (full replace), `patch` (surgical ops by `data-id`), `get`, `check` (layout overflow / overlap / margin clearance) |\n| `maket_charte` | Brand chartes — list, view, set, delete |\n| `maket_collection` | Typed data collections — list, view, create, validate/change schema, add/update/delete rows, bind/unbind a page |\n| `maket_state` | Document-owned state — initialize, get, update or JSON Patch, validate/change schema, inspect history and revisions, restore |\n| `maket_image` | Asset library — list, view, meta, import, delete |\n| `maket_preview` | Open the live preview URL or snapshot a page to PNG |\n| `maket_mermaid` | Render a Mermaid diagram to SVG and inject it |\n| `maket_pdf` | Export a document to PDF via headless Chromium |\n| `maket_gmail` | Gmail — connect, search, read, draft |\n\n**Layout & print margins guide: [docs/layout.md](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.\n\n## Plugin & skills\n\nThe 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.\n\nThe `plugin/claude/` directory ships three agent skills:\n\n- **`maket`** — Orientation skill. Starts with `maket_learn`, then uses the MCP tools for design work.\n- **`maket-charte`** — Brand-identity expert. Builds coherent design-token systems from a brief, an industry, or a reference URL.\n- **`maket-review`** — QA agent. Audits charte compliance, image paths, layout overflow; fixes issues via `maket_html patch`.\n\nClaude, Codex, and Gemini compatibility files live under `plugin/`.\n\n## Configuration\n\nBy default Maket stores data in `~/.maket/`:\n\n- `documents.db` — SQLite (documents, chartes, collections, assets metadata)\n- `assets/`, `documents/`, `exports/` — user files\n\nOverride with environment variables:\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `MAKET_PORT` | `24842` (`24844` with `npm run dev`; `3333` with `start:isolated`) | HTTP server port |\n| `MAKET_DATA_DIR` | `~/.maket/` | User data directory |\n| `MAKET_DB` | `$MAKET_DATA_DIR/documents.db` | SQLite path |\n| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | — | Gmail OAuth credentials (optional) |\n\n### Gmail integration (optional, power-user)\n\nMaket 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.\n\nSetup 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.\n\n**Full walkthrough + troubleshooting: [docs/gmail-setup.md](docs/gmail-setup.md).**\n\nQuick CLI helpers once set up:\n\n```bash\nmaket gmail status         # check whether credentials are in place\nmaket gmail reset --force  # wipe and start over\n```\n\n### Bootstrap a downstream workspace\n\nIf you run Maket as a long-lived server and want other projects to connect to it:\n\n```bash\nmake bootstrap DIR=/path/to/my-project PORT=3335\n```\n\nCreates `.mcp.json`, `.claude/skills/`, and a minimal `package.json` in the target directory. Never overwrites existing files.\n\n## Architecture\n\n<details>\n<summary>How the pieces fit together</summary>\n\n```\n┌──────────┐   MCP Streamable HTTP   ┌────────────────────────┐\n│ AI agent │ ──────────────────────► │  Express @ :3333       │\n│  (any    │                         │  ├─ /mcp  (MCP server) │\n│  MCP     │                         │  ├─ /assets, /export   │\n│  client) │                         │  └─ WS /ws (preview)   │\n└──────────┘                         └────────┬───────────────┘\n                                              │\n                                     ┌────────┴────────┐\n                                     │  SQLite         │\n                                     │  ~/.maket/*.db  │\n                                     └─────────────────┘\n                                              │\n                                              ▼ WS broadcast\n                                     ┌─────────────────┐\n                                     │ React preview   │\n                                     │  (Vite, :5173)  │\n                                     └─────────────────┘\n```\n\n- **MCP over Streamable HTTP** — stateless, one server per request.\n- **Awilix DI** — every service, tool pack, and HTTP route is registered in `packages/server/src/bootstrap.ts`.\n- **Store → bus → WebSocket** — every mutation emits a typed event; the preview reconciles.\n- **`packages/shared`** — wire-contract types only (WS messages, HTTP envelopes). Domain types stay per-side.\n\nSee [`CLAUDE.md`](CLAUDE.md) for the full architectural guide.\n</details>\n\n## Development\n\n```bash\nnpm run dev         # Server + Vite HMR (most common)\nnpm run quality     # Lint + typecheck + tests (must pass before commit)\nnpm run test        # vitest\n```\n\nPre-commit: `lefthook` runs `biome`, `tsc -b`, and `vitest` — all three must pass.\n\nMore scripts: `dev:watch` (rebuilds client into `public/`), `dev:server`, `dev:client`, `build:client`, `lint:fix`, `test:coverage`. See [`package.json`](package.json) for the full list.\n\n## Contributing\n\nContributions are welcome. To get started:\n\n1. Fork the repo and create a feature branch.\n2. Run `npm install && npm run dev` to set up your environment.\n3. Make your changes; keep them scoped (a bug fix doesn't need surrounding cleanup).\n4. Run `npm run quality` — it must pass.\n5. Open a PR with a clear description of the change and motivation.\n\nFound 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).\n\n## Changelog\n\nSee [CHANGELOG.md](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).\n\n<sub><a href=\"https://ng-galien.github.io/categories/mcp-maket/\"><img src=\"docs/agent-journal.svg\" alt=\"\" width=\"14\" height=\"14\" class=\"agent-journal-icon\" /> Agent journal</a> — Field notes from the agents working on Maket.</sub>\n\n## License\n\n[MIT](LICENSE) — © Alexandre Boyer\n",
  "bytes": 22829,
  "sha": "3cc32970654f70029f981f16a442e9a060066858ebbb7987cdba2792b8568a76",
  "repo_slug": "ng-galien/maket",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ng_galien_maket_c36816b5/readme"
}