mcpField
M
Maket

Maket

本地服务
ng-galien.github.io生产力204 天前更新

关于 Maket

Maket 是面向 AI 助手的 MCP 服务和可视化文档画布,适合制作品牌化、数据驱动或持续更新的文档。它将 HTML/CSS 实时预览与品牌资源、校验数据及 PDF 导出结合起来。

主要功能

  1. 01HTML/CSS 画布与实时预览
  2. 02可复用品牌样式和图片库
  3. 03经 Schema 校验的数据集合
  4. 04带版本记录的文档状态
  5. 05PDF 导出与 Gmail 草稿

适用场景

  1. 01设计品牌化传单和报告
  2. 02根据数据行生成个性化文档
  3. 03维护实时清单或状态面板
  4. 04将完成的文档导出为 PDF

MCP 相关

Maket 通过 MCP 服务向客户端提供文档创建和编辑能力,包括集合与文档状态相关工具。

配置

本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
"mcpServers": {
"ng-galien-maket": {
"command": "npx",
"args": [
"-y",
"@ng-galien/maket"
]
}
}
}
启动命令npx -y @ng-galien/maket

本地服务需要在你的电脑上安装运行环境(如 Node.js 18+)。各客户端的配置文件位置不同,请参考客户端文档。

安装包
npm@ng-galien/maket2.2.0

工具

14

收录的工具列表 · 更新于 2 周前

参数类型必填说明
bgstring否安全的背景颜色。优先级高于 charte、profile 或 tokenRefs。
fgstring否安全的前景色。优先级高于 charte、profile 或 tokenRefs。
docstring是文档名称
codestring是Mermaid 图表语法。标题单独占一行,其后为语句。例如:"graph TD\n A-->B\n B-->C"。
fontstring否安全的主字体系列。回退字体栈会规范化为第一个字体系列。优先级高于 charte、profile 或 tokenRefs。
linestring否安全的连接线颜色。优先级高于 charte、profile 或 tokenRefs。
pagenumber是页码(从 1 开始)
mutedstring否次要文本颜色。优先级高于 charte、profile 或 tokenRefs。
themeenum否可选的内置图表 profile。优先级高于自动 charte 默认值;tokenRefs 和直接设置的值优先级更高。zinc-light | zinc-dark | tokyo-night | tokyo-night-storm | tokyo-night-light | catppuccin-mocha | catppuccin-latte | nord | nord-light | dracula | github-light | github-dark | solarized-light | solarized-dark | one-dark
widthstring否包装容器的 CSS 宽度(例如 "180mm"、"100%")。默认值:auto。
accentstring否安全的箭头/强调色。覆盖 charte、profile 或 tokenRefs。
borderstring否节点和分组的边框颜色。覆盖 charte、profile 或 tokenRefs。
dataIdstring否包装元素的 data-id。默认值:自动生成(mermaid-1、mermaid-2...)
heightstring否包装元素的 CSS 高度(例如 "120mm")。默认值:auto。
paddingnumber否流程图/状态图画布的内边距,单位为 px。
surfacestring否节点表面颜色。覆盖 charte、profile 或 tokenRefs。
positionenum否相对于目标元素的插入位置。默认值:beforeend。beforebegin | afterbegin | beforeend | afterend
targetIdstring否要插入到其中的父元素的 data-id。默认值:页面根元素。
tokenRefsobject否对文档 charte 上令牌的显式引用,按图表角色指定键。例如:{"bg":"color.paper","accent":"color.primary","font":"font.body"}。
tokenRefs.bgstring否bg 的 charte 令牌引用,格式为 "group.key"。
tokenRefs.fgstring否fg 的图表 token 引用,格式为 "group.key"。
tokenRefs.fontstring否font 的图表 token 引用,格式为 "group.key"。
tokenRefs.linestring否line 的图表 token 引用,格式为 "group.key"。
tokenRefs.mutedstring否muted 的图表 token 引用,格式为 "group.key"。
tokenRefs.accentstring否accent 的图表 token 引用,格式为 "group.key"。
tokenRefs.borderstring否border 的图表 token 引用,格式为 "group.key"。
tokenRefs.paddingstring否padding 的图表 token 引用,格式为 "group.key"。
tokenRefs.surfacestring否surface 的图表 token 引用,格式为 "group.key"。
tokenRefs.nodeSpacingstring否nodeSpacing 的图表 token 引用,格式为 "group.key"。
tokenRefs.transparentstring否transparent 的图表 token 引用,格式为 "group.key"。
tokenRefs.layerSpacingstring否layerSpacing 的图表 token 引用,格式为 "group.key"。
nodeSpacingnumber否流程图/状态图中同级节点之间的水平间距,单位为 px。
transparentboolean否渲染时不添加 SVG 背景。默认值:false。
layerSpacingnumber否流程图/状态图中图层之间的垂直间距,单位为 px。

详细介绍

Maket

用 AI 助手创建视觉文档。 Maket 为 Claude、Codex、Gemini 和其他 MCP 客户端提供带实时预览的 HTML/CSS 画布。你可以创作一次性设计,将模板绑定到类型化行以进行邮件合并,或附加经过验证、由文档管理的状态,让原生 HTML 控件和 Agent 更新持续同步实时文档。将完成的内容导出为 PDF,或移交给 Gmail 作为草稿。

npm 版本 npm 下载量 许可证:MIT Node MCP ng-galien/maket MCP 服务 CI 覆盖率 欢迎提交 PR

访问 Maket 网站 →

Maket 演示导览

60 秒 · charte → library → data → AI 创作 → 各类文档 → 导出。


安装 Maket App

Maket App 是运行 Maket 的默认方式。它包含界面、服务、运行时和 Agent 设置,无需 Node.js。

平台安装程序
macOS Apple SiliconMaket-macOS-arm64.dmg
macOS IntelMaket-macOS-x64.dmg
Windows x64Maket-Windows-x64-Setup.exe
Linux x64Maket-Linux-x64.deb 或 Maket-Linux-x64.rpm

下载最新快照 以立即试用 Maket App。快照安装程序未经签名,基于 main 构建,并保留 14 天。相同的 macOS 和 Windows 未签名安装程序,以及 Linux 软件包,也会发布在 最新版本中。

打开安装程序,启动 Maket,然后按照首次运行时的 Agent 设置操作。

需要无头服务、CI 安装或仅限浏览器的部署?请跳转到 Maket Server via npm。

为什么选择 Maket

你的 AI 助手擅长写作。但设计关乎空间、层次和节奏,而这些体现在布局中,而非文字里。Maket 提供真实画布、可复用的视觉资源,以及两种截然不同的数据模型:集合根据有序行生成重复变体;文档状态则让单个文档与自身经过验证、带修订版本的数据保持同步。

功能

  • 实时预览 — AI 写入内容后,浏览器中会立即显示更改。使用详情文档工具栏(或已连接的 Reader)中的 批注,选择元素并保存反馈供 Agent 使用;关闭后即可继续浏览。
  • HTML/CSS 画布 — 页面采用真实的 HTML,尺寸以 mm 为单位。不会被专有格式锁定。
  • 品牌规范 — 定义一次设计令牌(颜色、字体、间距、阴影);Maket 会在排版时强制应用这些规范。
  • 图片库 — 添加图片并为其添加标签,AI 会根据需求选择合适的图片。
  • 数据驱动的集合 — 使用 JSON Schema 定义类型化字段,粘贴或编辑有序行,将页面绑定到 {{ product_name }} 等占位符,预览单行或完整系列,并为每行渲染一个输出页面。
  • 动态文档 — 为单个文档附加 JSON Schema 和状态快照,渲染 {{ state.* }} 值,通过绑定的复选框、文本、选择和按钮控件编辑受支持的字段,并保留不可变修订版本,以供查看历史记录和还原。
  • PDF 导出 — 通过无头 Chromium 生成可直接打印的输出。
  • Gmail 草稿 — 编写邮件文档并将其交给 Gmail 保存为草稿;由你审核并发送。
  • 纸张和屏幕格式 — 支持 A2–A8、DESKTOP/TABLET/MOBILE 宽高比,以及具有指定宽度和内容自适应高度的 AUTO 页面。
  • 内置 Agent 技能 — 三种技能(maket、maket-charte、maket-review),用于指导 AI 助手设计、应用品牌规范和审阅文档。

效果展示

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

数据驱动的文档

集合可将页面变为可重复使用的模板,用于产品标签、活动胸牌、个性化传单、证书、目录页或其他重复文档。每个集合都包含一个 JSON Schema 和一组有序行。将集合绑定到页面,在 HTML 中使用 {{ field_name }} 放置类型化的值,Maket 就会为每行渲染一个版本。

Collections 工作区和 maket_collection 工具都支持更改架构、插入/更新/删除行、面向粘贴的表格编辑,以及验证反馈。Maket 会在渲染前验证架构、每一行和每个占位符。在预览中,你可以保持显示原始模板、查看选定的某一行,或显示完整生成系列;打印和 PDF 输出会将绑定页面扩展到所有行。

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.

持续更新的文档

文档状态适用于单个持续演进的内容:清单、状态面板、表单或报告,其当前值属于该文档。maket_state 会初始化 JSON Schema 和数据快照,验证每次更新,要求修改时提供当前版本,并将每次已接受的更改记录为完整且不可变的版本。更新会重新渲染现有页面,不会创建邮件合并变体。

页面可以使用 HTML、JSON Forms,或嵌入当前 JSON Forms 模板的 HTML,位置为 ``。手工编写的 HTML 模板使用受支持的 Mustache 子集来显示内容,并通过显式的 data-maket-bind 属性进行编辑。JSON Forms 模板通过 maket_page action=set_form 设置;其可选的 UI schema 用于控制布局,而文档状态 JSON Schema 提供字段和选项。Maket 会通过同一个状态所有者,用原生控件渲染这两种格式。相同的当前值也会以静态形式显示在快照、打印件和 PDF 输出中。

对于顺序提问,请在 HTML 中保留主题和答案历史 Mustache 列表,在 Mustache 区段之外的静态容器块内恰好放置一个 ``,并为每个问题调用 maket_page action=set_form。更改表单会保留 HTML 和文档状态。嵌入的表单会适配其容器。

JSON Forms 的样式由渲染器负责:附加一个 charte,以应用其文本、背景、表面、边框、强调色、弱化色和字体令牌。UI schema 控制结构和呈现选项,而不是任意 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">

使用 maket_state action=init 附加初始 schema 和数据,然后使用 get、patch 或 update、history、revision 和 restore 对其进行管理。可移植的 .maket 捆绑包包含当前 schema、数据快照和模板格式;导入时会在本地从版本 1 开始创建全新历史记录,而不会复制之前的版本。有关确切的模板、schema、控件和并发规则,请参阅文档状态模板约定。

结构化工作区

结构化工作区将一个或多个具名集合组织在一起,每个集合的详情视图都是实际且持久的持续更新文档。其数据 schema 会验证每个项目,并可使用 oneOf;表示 schema 为每个集合提供全局模板,并将具体的 schema 路径绑定到精简模板文档和详情模板文档。每个集合都有自己的 identity,即指向项目必需的字符串或数字属性的 JSON Pointer;如果数据 schema 要求存在 id 属性,则默认为 /id(因此仅凭数据 schema 也能创建工作区)。该属性的值在所有位置(文档、批注、固定项、光标和 MCP 调用)均作为项目 ID,在整个工作区范围内唯一,涵盖所有集合,且 Maket 不会生成 ID。添加项目时若未提供该值,或该值已被工作区中的另一个项目使用,操作将被拒绝,并指出字段或现有项目;更新不能更改该值,生成的详情表单会将其设为只读。添加项目会以版本 1 存储其数据,并为其分配所属集合插入序列的下一个值;这是一个只增不减且不会重复使用的已存储计数器。集合可以声明 sortBy(指向项目数据的 JSON Pointer,例如 /place)以及 sortDirection ascending 或 descending;随后,其索引会按该值对各组中的卡片排序,相同值则按项目 ID 排序,并在项目或定义发生变化时重新排序;未声明该属性的集合则保持插入顺序。在声明 identity 之前创建的工作区曾进行过一次迁移:每个未声明 identity 的集合都会新增一个 id 属性,用于存放原项目 ID(如果 id 属性已存有其他值,则使用 itemId),以确保文档、批注和固定项仍可正常解析;导入身份声明之前写入的捆绑包时读取到的工作区,也会获得相同的声明。 条目通过数据源接口(ItemSource,位于 packages/server/src/services/item-sources/)提供给索引、工作区视图和 MCP 答案:该接口按索引顺序列出条目摘要,并返回游标和总数;按指定版本读取单个条目;并在预期版本上写入。它的首个实现是 Maket 自有的存储,其中每个条目对应 structured_workspace_items 中的一行,保存其数据和版本。数据由数据源保存,呈现由文档负责:只有首次打开条目时才会创建其文档,文档 ID 根据工作区和条目 ID 生成,名称则是在 add_item 时指定的;无论条目是否打开过,这个名称都会为其保留(maket_doc 和文档命令会拒绝使用该名称);Maket 启动时不会加载条目文档,而是在需要时加载,并在打开后保持加载状态;导出时会创建缺少的文档,并在写入打包文件后将其移除;条目文档不会出现在文档库和文档搜索中,其状态是该行数据的镜像,在打开时和每次写入后刷新。.maket 打包文件包含每个工作区定义及其条目行(身份、数据、版本),以及其中保存的已呈现条目文档;条目数据绝不会保存在文档状态中。导入会重建条目行,导出则会报告所有未包含文档的条目。详情表单、maket_state 和 update_item 都会在该行版本上通过数据源写入,因此过期写入会被拒绝,并返回当前数据。条目历史不会保存在文档状态中。列表按游标读取:查询可包含搜索文本(在集合的 searchFields 中搜索,默认搜索所有文本属性,忽略大小写和重音符号)、筛选条件、排序方式和批次大小;indexPageSize 默认值为 50,最大值为 500。查询会返回一个批次,并附带不透明的 next 游标、总数和每个分组的条目数,所有操作都下推到一次 SQLite 查询中;新查询会从第一条重新开始,且没有页码。游标在排序时由排序值和条目 ID 组成,否则由插入顺序和条目 ID 组成:在首批结果生成之前已存在且排序值保持不变的条目不会被跳过或重复,但在分页期间排序值发生变化的条目可能会移动到游标另一侧。check 和 update_definition 会通过数据源分批读取条目,而 update_definition 会报告新定义中的首批违规项。服务端会为每个集合保留当前窗口,并由所有客户端和 Agent 共享;数据源发生变化时会重新读取该窗口:索引文档会在分组标题下呈现该窗口(首批结果,以及之后加载的每个批次),标题显示整个查询的分组条目数;索引面板提供搜索栏和加载更多控件;客户端只保留该窗口和轻量级工作区视图(条目数和固定条目,不含条目数据);maket_structured_workspace action=view 会返回该窗口中的一个批次及其游标。

Agent 可通过三种方式构建工作区,maket_learn action=topic topic=structured-workspaces 中提供了逐步说明:仅提供数据架构,由 Maket 自行编写索引、详情和卡片模板并创建编辑表单;在 create 调用中内联提供模板 HTML 和表单,由 Maket 仍在工作区类别中创建并命名模板文档;或指定预先创建的模板文档,这种绑定方式会将模板移出文档库。定义存在错误时,create 和 update_definition 会拒绝该定义,并逐行报告每个错误、所属集合、路径和修复方法,除非设置了 allow_incomplete;maket_structured_workspace action=check 会返回就绪或未就绪的判定,并列出所有发现的问题、对应的修正方法和下一步调用,且不会更改任何内容。 Workspace 侧边栏仅列出集合索引和已固定项目;其他项目需从其索引中打开,模板仍可通过 Workspace 操作菜单使用。通用工具栏中的纯图标显示切换按钮可在单个文档(Square)和列表/详情(PanelLeft)视图之间切换;没有单独的视图选择工具栏。打开其他项目会替换当前详情窗格;关闭项目后会返回其索引。两个窗格都在 Reader 中打开,并采用常规滚动方式;窄幅 AUTO 列表会在一个连续页面上保留目前加载的批次,其加载更多控件会追加下一批。显式切换到 Canvas 后,可独立使用滚轮缩放和拖动平移,页眉中的百分比会重置为适合窗口的大小。可拖动且支持键盘操作的分隔条初始比例为 28/72,可用于调整窗格宽度。在窄窗口中,资料库会以叠加层形式打开,以保持文档宽度便于阅读,并保留固定偏好。项目固定状态会持续保存,也可从侧边栏中移除。此浏览界面会让实时文档表单保持交互状态;模板编辑仍在画布上进行。

Reader 会显示当前聚焦的文档,并在多页文档的每页上方显示标题。从集合浏览进入 Reader 时会保留当前页面;在已打开的索引和项目之间切换时,会保留各自的导航上下文。关闭 Reader 会恢复原始文档、页面以及单栏/分栏布局。分栏中任一窗格的页面被动显示时,都会记住自己的位置,而不会使另一个窗格失去焦点。关闭所有文档会取消待处理的显式打开操作,因此服务器迟到的回复不会重新打开工作区。

模板控制的页面会在所有现有项目和索引文档之间保持同步,并在模板中编辑。添加到单个实例的页面仍可编辑,并且在模板同步后仍会保留。maket_structured_workspace 通过 MCP 提供工作区创建、带修订检查的架构和模板绑定更改、项目创建与修改、删除、检查以及显式模板同步功能。

安装详情

选择与你的机器相匹配的行。

平台推荐选项提供内容
macOS(Apple Silicon 或 Intel)Maket App — .dmg原生窗口、内嵌服务、首次启动时设置 Agent
Windows x64Maket App — .exe 安装程序同上
Linux x64Maket App — .deb 或 .rpm原生窗口和内嵌服务;手动更新
选项 A — Maket App

从最新版本下载安装程序, 并选择适用于你平台的文件名:

  • 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 或 Maket-Linux-x64.rpm

在 macOS 上,打开 .dmg,然后将 Maket 拖到 Applications。在 Windows 上, 运行安装程序;它会创建开始菜单项和桌面快捷方式。macOS 和 Windows 安装程序目前尚未签名。在 macOS 上,如果 Gatekeeper 阻止首次启动,请按住 Control 键并点按 Maket,选择 打开,然后确认一次。Windows 可能会显示 SmartScreen 警告,需要手动确认。 在 Linux 上,使用发行版的包管理器安装软件包;更新需要手动下载。对于尚未发布的版本,请使用对应 main 提交的 Linux 快照构建产物。参阅 Linux 安装和沙盒诊断。

Maket App 自带运行时——无需安装 Node.js。首次启动时,它会询问是否将机器上检测到的 AI 客户端(Claude Code、Codex、Gemini)连接到其内嵌服务,并且可以安装随附的 Claude Desktop 连接器。内嵌服务监听 127.0.0.1:24843。

如果之前通过 npm 安装的 Maket 服务已经在运行,应用会告知你并询问是否停止该服务并接管——未经确认,不会终止任何进程。

进入工作区不只限于应用窗口:Maket 菜单中有 在浏览器中打开,可在这台机器上的任何 浏览器中打开同一工作区,地址为 http://127.0.0.1:24843。只有这台机器可以访问——服务绝不会绑定公共 网络接口,因此不会向你的网络公开任何内容。

系统会自动检查更新,并在你确认后安装。设置中的 Candidate 渠道可让你选择接收验证构建版本。

选项 B — 通过 npm 安装 Maket 服务(高级)
# 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

在 Chrome、Edge 或其他支持的浏览器中,使用浏览器界面或 Maket 设置中的 安装 Maket,即可在独立的应用窗口中使用工作区。 此 PWA 使用相同的本地服务:它不会启动、停止或更新原生进程,因此 maket start、maket stop 和 maket update 仍然是需要在终端中明确执行的命令。

npm 11+ 的依赖脚本策略要求显式指定 --allow-scripts=puppeteer。这样 Puppeteer 就能下载已安装 Maket 版本声明的精确无头 Chromium 构建版本;Maket 本身不会硬编码浏览器版本。安装后运行 maket doctor,以确认 Chromium 确实可以启动、数据目录可写,且 MCP 服务能够响应。

CLI 会在 ~/.claude.json 的 mcpServers.maket 项中注册本地 Node 运行时的绝对路径和已安装的 Maket 入口(如果已安装 Claude Code CLI,则运行 claude mcp add),在 ~/.codex/config.toml 中注册 [mcp_servers.maket] 部分,或在 ~/.gemini/settings.json 的 mcpServers.maket 项中注册。此标准的命令加参数形式不依赖图形应用的 shell PATH。移动 Node 或 Maket 安装位置后,请重新运行 maket install <client> --apply。不带参数时,Maket 项会以 stdio MCP 桥接程序的形式运行——Claude Desktop、Codex、Gemini 和其他 MCP 客户端会自动调用这种形式。

守护进程控制:maket status、maket logs [--bridge]、maket stop、maket restart。诊断:maket doctor、maket config。升级:maket update [--check]。撤销安装:maket uninstall <claude|codex|gemini> --apply。在 install claude 中使用 --scope=project,可将内容写入 <cwd>/.mcp.json,而非用户范围的文件。全局标志 --data-dir、--port、--host 可在任何命令中覆盖对应的 MAKET_* 环境变量。

选项 C — 克隆并修改
git clone https://github.com/ng-galien/maket.git
cd maket
npm install
npm run dev

在 :24844 启动开发服务器,并在 :5173 启动 Vite HMR。随附的 .mcp.json 会将项目中打开的 MCP 客户端指向 http://localhost:24844/mcp。端口 :24843 保留给已安装的桌面应用。

代码质量与架构规则

Maket 使用 code-moniker 执行结构规则检查和代码异味审查。版本化规则源文件为 .code-moniker.toml;运行 npm run smell:rules 可查看默认规则,运行 npm run smell:review 可审查代码库。质量门禁通过 npm run quality 执行此审查。

不要在 AGENTS.md 中添加可强制执行的架构或边界规则,也不要另行添加与 code-moniker 并行的临时检查脚本。AGENTS.md 是为在代码库中工作的 Agent 提供的操作指南,不是项目的规则引擎。如果某条边界规则目前无法用 code-moniker 表达,请将其记录为 code-moniker 的演进需求,而不是创建另一套本地规则系统。

例外应局部且明确。如果某条规则确实不适用,请保持该规则启用,并在受检查的文件中添加有针对性的抑制注释,例如 // code-moniker: ignore[maket-hygiene-limits-callable-size],并在附近说明设计原因。

选项 D — 打包为桌面扩展(.mcpb)
npm install -g @anthropic-ai/mcpb
npm run build:client
node scripts/pack-mcpb.ts
# → dist/maket.mcpb

将 dist/maket.mcpb 拖入桌面 MCP 主机(例如 Claude Desktop → Settings → Extensions)。

**要求:**兼容 MCP 的客户端(Claude Code、Claude Desktop、Codex、 Gemini 或类似客户端)。Maket App 已打包其他所有内容;使用 npm、克隆和 .mcpb 方式还需要 Node.js ≥22。

CLI 参考
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

工具

Maket 提供 15 个复合 MCP 工具。每个工具都会分发多个操作:

工具功能
maket_doc文档生命周期 — 新建、列出、删除、复制、重命名、元数据、导出/导入
maket_learn面向 Agent 的结构化 Markdown 文档 — 工作流、HTML、品牌规范、图表、数据、审查、安装
maket_workspace会话操作 — 聚焦、状态、锁定、列出消息、确认消息
maket_page页面结构和 JSON Forms 模板 — 添加、删除、重命名、重新排序、列出、设置表单、获取表单
maket_canvas画布设置 — 格式、方向、背景、每侧打印边距
maket_html页面内容 — set(完整替换)、patch(按 data-id 执行精确操作)、get、check(布局溢出/重叠/边距间距)
maket_charte品牌规范 — 列出、查看、设置、删除
maket_collection类型化数据集合 — 列出、查看、创建、验证/更改架构、添加/更新/删除行、绑定/解绑页面
maket_state文档自有状态 — 初始化、获取、更新或 JSON Patch、验证/更改架构、检查历史记录和修订版本、还原
maket_structured_workspace架构驱动的项目集合 — 创建(从架构生成模板或内联提供模板,并为每个集合声明标识)、检查、按游标读取项目、添加/更新/删除项目、同步模板页面
maket_image资源库 — 列出、查看、元数据、导入、删除
maket_preview打开实时预览 URL,或将页面截取为 PNG
maket_mermaid渲染持久化且适配品牌规范的 Mermaid 图表,使用语义令牌和安全的视觉控制
maket_pdf通过无头 Chromium 将文档导出为 PDF
maket_gmailGmail — 连接、搜索、读取、起草

布局与打印边距指南:docs/layout.md — 预览中的青色安全区域代表什么、适用于不同场景的边距预设,以及内容显示异常时可以向助手提出的提示词。

插件与技能

MCP 服务提供 maket_learn,这是 Agent 入门引导的权威来源。技能保持精简:它们引导 Claude、Codex 或 Gemini 使用实时工具指南,而不是重复产品知识。面向人工用户的入门指南单独提供,可通过 Maket UI 中的 Help 按钮打开。

plugin/claude/ 目录包含三个 Agent 技能:

  • maket — 入门引导技能。首先使用 maket_learn,然后使用 MCP 工具开展设计工作。
  • maket-charte — 品牌识别专家。根据简报、行业或参考 URL 构建统一的设计令牌系统。
  • maket-review — QA Agent。检查 charte 合规性、图片路径和布局溢出;通过 maket_html patch 修复问题。

Claude、Codex 和 Gemini 的兼容文件位于 plugin/ 下。

配置

默认情况下,Maket 将数据存储在 ~/.maket/ 中:

  • documents.db — SQLite(文档、chartes、集合、资源元数据)
  • assets/、documents/、exports/ — 用户文件

使用环境变量进行覆盖:

变量默认值用途
MAKET_PORT24842(使用 npm run dev 时为 24844;使用 start:isolated 时为 3333)HTTP 服务端口
MAKET_DATA_DIR~/.maket/用户数据目录
MAKET_DB$MAKET_DATA_DIR/documents.dbSQLite 路径
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET—Gmail OAuth 凭据(可选)
Gmail 集成(可选,适合高级用户)

Maket 可以将已撰写的文档转换为 Gmail 草稿(附带 PDF)。它只会创建草稿,绝不会发送。你可以在 Gmail 中检查草稿并亲自点击 Send。

设置大约需要 10 分钟:你需要在 Google Cloud Console 中注册自己的 OAuth Desktop 客户端,启用 Gmail API,将自己添加为测试用户,然后把 JSON 粘贴到 Maket 的设置表单中。凭据保存在 ~/.maket/ 下,且仅所有者可访问——不会放入仓库,也不会存放在任何服务端上。

完整操作指南与故障排除:docs/gmail-setup.md。

设置完成后可使用的快速 CLI 辅助工具:

maket gmail status         # check whether credentials are in place
maket gmail reset --force  # wipe and start over
初始化下游工作区

如果你将 Maket 作为长期运行的服务,并希望其他项目连接到它:

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

会在目标目录中创建 .mcp.json、.claude/skills/ 和精简的 package.json。绝不会覆盖已有文件。

架构

各部分如何协同工作
┌──────────┐   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)  │
                                     └─────────────────┘
  • 基于 Streamable HTTP 的 MCP — 无状态,每个请求启动一个服务。
  • Awilix DI — 每个服务、工具包和 HTTP 路由都在 packages/server/src/bootstrap.ts 中注册。
  • 存储层 → 总线 → WebSocket — 每次变更都会发出带类型的事件;预览会进行协调更新。
  • packages/shared — 仅包含线协议类型(WS 消息、HTTP 信封)。领域类型按两侧分别保留。

完整架构指南请参阅 CLAUDE.md。

开发

npm run dev         # Server + Vite HMR (most common)
npm run quality     # Lint + typecheck + tests (must pass before commit)
npm run test        # vitest

提交前检查:lefthook 会运行 biome、tsc -b 和 vitest,三项都必须通过。

更多脚本:dev:watch(将客户端重新构建到 public/)、dev:server、dev:client、build:client、lint:fix、test:coverage。完整列表请参阅 package.json。

贡献

欢迎贡献。开始之前:

  1. Fork 仓库并创建功能分支。
  2. 运行 npm install && npm run dev 来设置开发环境。
  3. 进行修改;保持改动范围明确(修复 bug 无需顺带清理周边代码)。
  4. 运行 npm run quality,并确保通过。
  5. 提交 PR,并清楚说明改动内容及其动机。

发现 bug、有新想法,或想在动手开发前讨论某些内容?请提交 issue 或发起 discussion。

更新日志

请参阅 CHANGELOG.md,了解每个版本面向用户的变更。使用 npm run changelog:draft 起草下一个 [Unreleased] 部分(按 Conventional Commits 类型归类自上一个标签以来的提交)。

README 配图 Agent 日志 — 参与 Maket 开发的 Agent 的实地笔记。

许可证

MIT — © Alexandre Boyer

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。