ShapeWords MCP

ShapeWords MCP

ShapeWords を使ってワードクラウドを生成する、汎用 MCP サーバーです。

Model Context Protocol を介して ShapeWords のレンダリングツールを提供するため、MCP 対応のクライアントなら、テキスト、ワークショップのメモ、プロンプト、調査の抜粋、エージェントの出力から、SVG、JSON、PNG のワードクラウドを作成できます。デフォルトではホスト型の ShapeWords Render API を使用します。engine: "skia" を指定すると、共有レイアウトコアと CanvasKit/Skia を使用して、MCP サーバー内でローカルにレンダリングします。

ツール

すべてのツールで 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 に渡す描画/UI ロケールです。
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 は、サーバー側の Chromium を使わず、ローカルの MCP 共有コアと CanvasKit レンダラーを使用します。
returnLayout	boolean	false	true/false	対応している場合、レイアウトメタデータを含めます。
shapeType	string	cloud	1-80 文字	形状 ID です。組み込みの ID を使用するか、customShapeDefinition とともに custom を使用します。
customShapeDefinition	object	省略	下記参照	カスタム SVG パス形状です。shapeType が custom の場合は必須です。
maxWords	integer	700	1-1000	配置する単語の最大数です。
seed	integer	0	0-4294967295	再現可能なブラウザーレス描画のための符号なし 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 色	16 進カラーコード：#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 のデフォルト設定（円形、1024x640、SQ 品質、最大 120 単語）が必要な場合に限り、renderProfile: "api" を使用してください。

テキスト入力

MCP サーバーは、生の text、明示的な words、またはその両方を送信できます。

• 単語を繰り返すと頻度が上がります。例：cloud cloud cloud render render API
• words[] を使用すると、呼び出し元が指定した重みが維持され、トークン化、ストップワード、またはレンマ化の違いを回避できます。
• text と words[] の両方が指定されている場合、ShapeWords は words[] からレンダリングし、text はソースコンテキストとして保持します。
• 段落、会議メモ、ワークショップのメモ、プロンプト、調査の抜粋、キーワードリストを使用できます。
• CSV、Excel、Google Sheets などのファイルは、この MCP サーバー経由ではアップロードされません。先にテキスト内容を貼り付けるか生成してください。

重み付きテキストの例：

{
  "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 が存在しないため、render_word_cloud は format: "png" または format: "svg" のインライン MCP 画像コンテンツを常に返します。

create_word_cloud_job は、完了を待たずにジョブの作成直後に同じメタデータを返します。

get_word_cloud_job は、最新のジョブステータスとアーティファクト URL を返します。

ShapeWords Render API はレンダリングジョブをメモリ内に保存するため、生成されたアーティファクト URL の有効期間は短くなっています。

形式とエンジンに関する注意事項

• 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 で直接描画されます。
• seed はブラウザーレス／共有コアのレンダリングで適用されます。再現可能な API／MCP 出力には、engine: "auto" または engine: "browserless" を使用してください。
• engine: "browser" を強制した状態でゼロ以外の seed を指定すると、ブラウザーフォールバックでは決定論的な共有コアのシードパスが使われないため、Render API によって拒否されます。

クイックスタート

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 で必要な場合に使用する任意のベアラートークンです。
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 スキーマが公開しているのは、現在、レンダリングとスタイルのオプションのみです。高度な単語エディター、2D／3D ビューの切り替え、CSV／Excel のアップロード、Google Sheets のインポート、ライブルームの操作など、ShapeWords の UI 専用ワークフローは公開されていません。
• padding、rotationPreset、rotations、spiralType、fillMode が公開されているため、MCP の呼び出し元は ShapeWords のメインキャンバスに近い表示を実現できます。

同梱の Font Awesome およびフォントアセットに関するお知らせは、THIRD_PARTY_NOTICES.txt を参照してください。