ShapeWords MCP

ShapeWords MCP

用于生成词云的通用 MCP 服务，使用 ShapeWords。

它通过 Model Context Protocol 提供 ShapeWords 渲染工具，因此任何支持 MCP 的客户端都可以根据文本、研讨会笔记、提示词、研究摘录或 Agent 输出创建 SVG、JSON 或 PNG 词云。默认情况下，它使用托管的 ShapeWords Render API；设置 engine: "skia" 后，则会在 MCP 服务内部使用共享布局核心和 CanvasKit/Skia 进行本地渲染。

工具

所有工具均使用 stdio MCP 传输。

render_word_cloud

创建 ShapeWords 渲染任务，轮询直至任务完成，并返回：

• 托管渲染的公开资源 URL，或 engine: "skia" 的本地内嵌资源；
• 任务元数据；
• 可选的图像内容，适用于支持图像结果的 MCP 客户端。

当调用方需要最终资源时，使用此工具进行一次性生成。

create_word_cloud_job

启动渲染任务，并返回任务、状态和资源 URL，不等待任务完成。

用于客户端稍后轮询的异步工作流。

get_word_cloud_job

按 ID 检查渲染任务。

使用 create_word_cloud_job 或 render_word_cloud 返回的 jobId 调用此工具。

输入架构

render_word_cloud 接受以下所有渲染选项。create_word_cloud_job 仅接受托管选项：engine: "skia" 仅支持本地渲染，且由 render_word_cloud 提供支持。

字段	类型	默认值	限制	描述
renderProfile	enum	canvas	canvas、api	默认选项配置。canvas 与 ShapeWords 主画布一致；api 保留较早的精简版 Render API 默认值。
text	string	可选	1-100,000 个字符	词云的源文本。除非提供了 words，否则必填。
words	object[]	可选	1-1000 项	显式指定带权重的词语。如果调用方已对文本进行分词、词形还原或评分，请使用此项。
locale	enum	en	en、ru、ar、es、fr、zh	传递给 ShapeWords 的渲染/界面区域设置。
format	enum	svg	svg、png、json	生成内容的格式。SVG 是最快的默认格式。JSON 返回布局数据。PNG 根据同一共享布局栅格化生成。
width	integer	800	240-4096	画布宽度，单位为像素。
height	integer	600	240-4096	画布高度，单位为像素。
background	enum	white	transparent、white、dark	输出背景。
quality	enum	hq	sq、hq	标准或高质量渲染。hq 与主画布导出比例一致，但速度较慢。
engine	enum	auto	auto、browser、browserless、skia	渲染引擎。skia 使用本地 MCP shared-core 和 CanvasKit 渲染器，不依赖服务器端 Chromium。
returnLayout	boolean	false	true/false	在支持时包含布局元数据。
shapeType	string	cloud	1-80 个字符	形状 ID。使用内置 ID，或将 shapeType 设为 custom 并提供 customShapeDefinition。
customShapeDefinition	object	省略	见下文	自定义 SVG 路径形状。shapeType 为 custom 时必填。
maxWords	integer	700	1-1000	最多放置的词数。
seed	integer	0	0-4294967295	用于生成可复现的 browserless 渲染结果的无符号 32 位布局种子。输入、选项和种子相同时，会生成相同的 SVG/布局。
fontFamily	string	Montserrat	1-80 个字符	ShapeWords 字体系列名称，例如 Inter、Roboto、Montserrat、Noto Sans。
minFontSize	integer	18	4-400	词语的最小字号。
maxFontSize	integer	96	8-700	词语的最大字号。
padding	integer	3	0-100	碰撞检测使用的像素间距。
rotationPreset	enum	orthogonal	见下文	与 ShapeWords 主画布一致的旋转预设。
rotations	integer[]	省略	-90 至 90，最多 64 个值	显式指定旋转角度。提供此项时，会覆盖 rotationPreset。
spiralType	enum	archimedean	archimedean、rectangular	放置螺旋算法。
fillMode	enum	fill	fill、frequency	形状填充策略。
palette	string[]	服务默认值	最多 12 种颜色	十六进制颜色：#rgb、#rrggbb 或 #rrggbbaa。
colorMode	enum	服务默认值	sequential、random、byFrequency	调色板颜色的词语分配方式。
returnImage	boolean	false	仅适用于 render_word_cloud	下载生成的 SVG/PNG 内容，并以 MCP 图像内容形式返回。
pollIntervalMs	integer	环境变量/默认值	250-10,000	render_word_cloud 的轮询间隔。
pollTimeoutMs	integer	环境变量/默认值	1,000-180,000	render_word_cloud 的最大等待时间。

get_word_cloud_job 接受：

字段	类型	限制	描述
jobId	string	6-64 个字符	ShapeWords 渲染任务 ID。

words 项采用以下结构：

字段	类型	默认值	限制	描述
text	string	必填	1-120 个字符	要显示的单词或表情符号。
value	integer	1	1-100,000	用于控制大小的权重／频率。
kind	enum	word	word、emoji	单词类型。渲染器会让表情符号保持水平。
sizeScale	number	省略	0.1-5	可选的额外大小乘数；ShapeWords 布局核心支持时使用。
repeat	boolean	true	true/false	布局是否可以重复此单词，以改善形状填充效果。

旋转预设：

horizontal, vertical, orthogonal, crossing, crossingVoids, dancing,
positiveSlope, negativeSlope, random, custom, mixed, angled, free

renderProfile: "canvas" 会采用与主编辑器画布相同的实用默认值：shapeType: "cloud"、width: 800、height: 600、quality: "hq"、maxWords: 700、seed: 0、fontFamily: "Montserrat"、minFontSize: 18、maxFontSize: 96、padding: 3、rotationPreset: "orthogonal"、spiralType: "archimedean" 和 fillMode: "fill"。

仅当需要较早期的紧凑型 Render API 默认值时，才使用 renderProfile: "api"：圆形、1024x640、SQ 质量，以及最多 120 个单词。

文本输入

MCP 服务可以发送原始 text、显式的 words，或两者兼有：

• 重复的单词会增加频率，例如 cloud cloud cloud render render API；
• words[] 可保留调用方提供的权重，并避免分词、停用词或词形还原方面的差异；
• 同时提供 text 和 words[] 时，ShapeWords 会根据 words[] 进行渲染，并将 text 保留为源上下文；
• 段落、会议记录、研讨会记录、提示词、研究摘录和关键词列表均可使用；
• 不会通过此 MCP 服务上传 CSV、Excel 或 Google Sheets 等文件；请先粘贴或生成文本内容。

加权文本示例：

{
  "text": "MCP MCP MCP ShapeWords ShapeWords word cloud word cloud render API agents tools",
  "shapeType": "cloud",
  "format": "svg",
  "seed": 12345
}

显式加权单词示例：

{
  "words": [
    { "text": "ShapeWords", "value": 12 },
    { "text": "MCP", "value": 9 },
    { "text": "canvas", "value": 7 },
    { "text": "layout", "value": 6 },
    { "text": "render", "value": 5 }
  ],
  "shapeType": "cloud",
  "format": "svg"
}

形状

使用 shapeType 选择词云遮罩。

生产渲染器接受的稳定内置形状 ID 包括：

rectangle, circle, heart, star, cloud, diamond, tree, triangle, arrow,
square, pentagon, hexagon, octagon, cross, plus, moon, sun, drop,
flame, leaf, flower, mountain, apple, house, book, camera, music,
chat, location, trophy, rocket, plane, car, shield, lightning, check,
infinity, tag

内置品牌形状 ID 包括：

brand-product-hunt, brand-y-combinator, brand-hacker-news,
brand-indie-hackers, brand-github, brand-figma, brand-notion,
brand-stripe, brand-vercel, brand-linear, brand-supabase,
brand-railway, brand-netlify, brand-firebase, brand-cloudflare,
brand-airtable, brand-replit, brand-anthropic

生产渲染器也可能接受其他生成的 ShapeWords ID。为确保自动化流程具有可移植性，请优先使用上述稳定 ID，或传入自定义 SVG 形状。

本地 engine: "skia" 路径目前支持 rectangle、square、circle、diamond、triangle、star、heart、cloud、自定义 SVG 形状，以及 fa-cat 等随附的 Font Awesome 形状 ID。不支持的本地形状 ID 会被拒绝，而不会静默更改所请求的形状。

自定义形状

将 shapeType 设为 custom，并提供 customShapeDefinition：

字段	类型	必填	限制	描述
path	string	是	1-100,000 个字符	用作遮罩的 SVG 路径数据。
viewBox	string	是	1-120 个字符	SVG viewBox，例如 0 0 100 100。
fillRule	enum	否	nonzero、evenodd	SVG 填充规则。省略时采用渲染器行为。
name	string	否	1-80 个字符	可选的人类可读名称。
nameEn	string	否	1-80 个字符	可选的英文名称。

自定义爱心示例：

{
  "text": "love love design care product community team support",
  "shapeType": "custom",
  "customShapeDefinition": {
    "name": "Heart",
    "path": "M 50 90 C 25 70, 0 50, 0 30 A 25 25 0 0 1 50 30 A 25 25 0 0 1 100 30 C 100 50, 75 70, 50 90 Z",
    "viewBox": "0 0 100 100",
    "fillRule": "nonzero"
  },
  "format": "svg"
}

输出

render_word_cloud 返回：

• 包含已完成作业 ID 和产物位置的文本内容；
• 包含规范化作业元数据的 structuredContent.job；
• 托管渲染的 structuredContent.artifactUrl；
• engine: "skia" 的 structuredContent.localArtifact；
• structuredContent.siteUrl；
• 当 returnImage 为 true，且 format 为 svg 或 png 时，返回可选的 MCP 图像内容。

对于 engine: "skia"，由于没有托管产物 URL，当 format 为 png 或 svg 时，render_word_cloud 始终返回内嵌的 MCP 图像内容。

create_word_cloud_job 会在创建作业后立即返回相同的元数据，不会等待作业完成。

get_word_cloud_job 会返回最新的作业状态和产物 URL。

生成的产物 URL 有效时间较短，因为 ShapeWords Render API 会将渲染作业存储在内存中。

格式和引擎说明

• svg 是推荐的自动化格式：速度快、体积小，并且适用于无浏览器的共享核心渲染器。
• json 返回来自同一共享核心布局的数据。
• png 根据同一生成的 SVG／布局进行栅格化，因此对于相同输入和选项，词语位置与 SVG／JSON 一致。
• 除非需要强制指定特定路径，否则建议使用 engine: "auto"。
• engine: "browserless" 支持 svg、json 和 png。
• engine: "browser" 支持 svg 和 png，不支持 json。
• engine: "skia" 仅支持本地使用，且仅由 render_word_cloud 支持。它不会创建可轮询的托管任务。布局由随附的 ShapeWords 共享核心生成；PNG 直接使用 CanvasKit／Skia 绘制。
• browserless／共享核心渲染会遵循 seed。如需获得可复现的 API／MCP 输出，请使用 engine: "auto" 或 engine: "browserless"。
• Render API 会拒绝强制使用 engine: "browser" 时设置的非零 seed，因为浏览器回退路径不使用确定性的共享核心种子路径。

快速开始

直接从 GitHub 运行：

npx -y github:kirrrr-2423/shapewords-mcp

或者克隆到本地：

git clone https://github.com/kirrrr-2423/shapewords-mcp.git
cd shapewords-mcp
npm install
npm start

客户端配置

在任何兼容 MCP 的客户端中使用 stdio 传输。

{
  "mcpServers": {
    "shapewords": {
      "command": "npx",
      "args": ["-y", "github:kirrrr-2423/shapewords-mcp"],
      "env": {
        "SHAPEWORDS_API_BASE_URL": "https://shapewords.fun"
      }
    }
  }
}

对于本地克隆：

{
  "mcpServers": {
    "shapewords": {
      "command": "node",
      "args": ["/absolute/path/to/shapewords-mcp/src/index.js"],
      "env": {
        "SHAPEWORDS_API_BASE_URL": "https://shapewords.fun"
      }
    }
  }
}

环境变量

变量	默认值	说明
SHAPEWORDS_API_BASE_URL	https://shapewords.fun	ShapeWords 应用 URL。
SHAPEWORDS_RENDER_API_KEY	empty	如果你的 Render API 要求提供 bearer token，可选用此变量。
SHAPEWORDS_API_KEY	empty	SHAPEWORDS_RENDER_API_KEY 的向后兼容别名。
SHAPEWORDS_POLL_INTERVAL_MS	1500	已完成渲染的轮询间隔。
SHAPEWORDS_POLL_TIMEOUT_MS	90000	渲染等待超时时间。
SHAPEWORDS_REQUEST_TIMEOUT_MS	30000	托管 API 和资源请求的单次请求超时时间。
SHAPEWORDS_MAX_IMAGE_BYTES	8388608	当 returnImage 为 true 时，下载的资源大小上限。

提示词示例

Create a fast SVG word cloud about MCP, universal tools, word cloud generation, AI agents, and ShapeWords. Use the default ShapeWords canvas profile and return the artifact URL.

工具输入示例：

{
  "text": "MCP MCP MCP Model Context Protocol word cloud word cloud ShapeWords tools resources prompts stdio server client universal integration connector API render PNG SVG artifact agents automation context protocol schema",
  "locale": "en",
  "format": "svg",
  "width": 800,
  "height": 600,
  "background": "white",
  "quality": "hq",
  "engine": "auto",
  "returnLayout": false,
  "shapeType": "cloud",
  "seed": 12345,
  "palette": ["#7c3aed", "#ddd6fe", "#14b8a6", "#111827"],
  "returnImage": false
}

更多示例

透明 PNG

{
  "text": "launch launch startup product customers retention growth metrics roadmap",
  "format": "png",
  "engine": "auto",
  "shapeType": "rocket",
  "width": 1200,
  "height": 900,
  "background": "transparent",
  "quality": "hq",
  "returnImage": true
}

本地 Skia PNG

{
  "words": [
    { "text": "MCP", "value": 12 },
    { "text": "ShapeWords", "value": 10 },
    { "text": "Skia", "value": 8 },
    { "text": "CanvasKit", "value": 7 },
    { "text": "local", "value": 6 },
    { "text": "renderer", "value": 5 }
  ],
  "format": "png",
  "engine": "skia",
  "shapeType": "cloud",
  "width": 800,
  "height": 600,
  "quality": "sq",
  "seed": 12345
}

JSON 布局

{
  "text": "design system tokens components variants accessibility contrast typography layout",
  "format": "json",
  "engine": "browserless",
  "shapeType": "diamond",
  "returnLayout": true,
  "seed": 7,
  "maxWords": 80
}

可复现的 SVG

{
  "text": "MCP shared core browserless renderer reproducible seed deterministic layout",
  "format": "svg",
  "engine": "browserless",
  "shapeType": "cloud",
  "returnLayout": true,
  "seed": 12345
}

自定义调色板和字体

{
  "text": "research synthesis interview persona journey insight opportunity experiment",
  "format": "svg",
  "shapeType": "book",
  "fontFamily": "Roboto",
  "palette": ["#111827", "#2563eb", "#14b8a6", "#f59e0b"],
  "colorMode": "byFrequency",
  "maxWords": 160
}

开发

npm install
npm run smoke
npm run smoke:skia
npm run inspect

服务使用 stdio，并将协议消息写入 stdout。诊断信息写入 stderr。

说明

• 当 MCP 客户端支持图像内容且需要将托管渲染字节内嵌时，在 render_word_cloud 中设置 returnImage: true。本地 Skia 图像渲染会自动内嵌。
• 对于自动化程度较高的用法，优先使用 SVG 或 JSON 布局资源；仅在调用方需要栅格像素时才请求 PNG。
• 当调用方需要在多次 MCP 运行中获得可重复的 SVG／JSON／PNG 布局时，设置 seed。engine: "skia" 默认具有确定性。
• 本地 Skia PNG 输出在质量缩放后最多为 40,000,000 像素，以避免占用过多本地内存。
• 本地 Skia 字体渲染目前仅支持随附的 Montserrat 和 OpenDyslexic。托管渲染可能支持更多字体系列。
• MCP 架构目前仅公开渲染和样式选项，不公开 ShapeWords 专属 UI 工作流，例如高级词语编辑器、2D／3D 视图切换、CSV／Excel 上传、Google Sheets 导入或实时房间控制。
• 提供 padding、rotationPreset、rotations、spiralType 和 fillMode，以便 MCP 调用方更贴近地匹配 ShapeWords 主画布。

捆绑的 Font Awesome 和字体资源声明请参阅 THIRD_PARTY_NOTICES.txt。