media-forge

MCP Media Forge

テキスト DSL から図、グラフ、HTML ページ、スライドデッキを生成する MCP サーバーです。AI コーディングエージェントが Markdown に埋め込めるよう設計されています。

LLM エージェントは、テキスト入力で render_mermaid、render_html_page、render_slides などのツールを呼び出すと、ドキュメントに埋め込めるアセットのファイルパスを受け取ります。

出力ギャラリー

Mermaid フローチャート

Mermaid シーケンス図

D2 アーキテクチャ図

Graphviz 依存関係グラフ

Vega-Lite 棒グラフ

ツール

図・グラフのレンダラー（Docker）

ツール	入力	形式	用途
render_mermaid	Mermaid コード	SVG、PNG	フローチャート、シーケンス図、ER 図、状態図、ガント図、Git グラフ
render_d2	D2 コード	SVG、PNG	コンテナとアイコンを含むアーキテクチャ図
render_graphviz	DOT コード	SVG、PNG	依存関係グラフ、ネットワーク図
render_chart	Vega-Lite JSON	SVG、PNG	棒グラフ、折れ線グラフ、散布図、面グラフ、ヒートマップ

HTML ジェネレーター（Docker 不要）

ツール	入力	出力	用途
render_html_page	HTML 本文 + テーマ	自己完結型 HTML	技術ドキュメント、レポート、ダッシュボード
render_slides	JSON スライド配列 + テーマ	HTML スライドデッキ	プレゼンテーション、状況報告、ウォークスルー

ユーティリティ

ツール	説明
get_tool_guide	ツールごとの使用例、アンチパターン、複雑さの上限
list_assets	出力ディレクトリ内に生成されたすべてのファイルを一覧表示

クイックスタート

1. レンダリングコンテナを起動する（図ツール用）

cd docker
docker compose up -d

HTML ページとスライドのツールは Docker なしで動作します。

2. MCP サーバーをインストールする

オプション A -- npx（インストール不要）

npx mcp-media-forge

オプション B -- クローンしてビルド

git clone https://github.com/PavelGuzenfeld/mcp-media-forge.git
cd mcp-media-forge
npm install
npm run build

3. MCP クライアントに登録する

MCP 互換のクライアント（Claude Code、Cursor、VS Code + Copilot、Cline など）であれば、このサーバーを利用できます。標準の設定は次のとおりです。

{
  "mcpServers": {
    "media-forge": {
      "command": "node",
      "args": ["/path/to/mcp-media-forge/dist/index.js"],
      "env": {
        "PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

設定を追加する場所はクライアントによって異なります。

• Claude Code：~/.claude/settings.json
• Cursor：MCP 設定パネル
• VS Code (Copilot)：.vscode/mcp.json
• Cline：MCP サーバー設定

4. 使用する

AI アシスタントに図、ページ、プレゼンテーションの生成を依頼します。

「OAuth2 のフローを示すシーケンス図を作成して、README に埋め込んでください」

「KPI カードを使って API アーキテクチャをまとめた HTML ページを生成してください」

「Q1 の指標とアーキテクチャの概要をまとめたスライドデッキを作成してください」

エージェントは適切なツールを呼び出してファイルパスを取得し、Markdown に埋め込みます。

仕組み

AI Agent (any MCP client)
    |
    | MCP Protocol (JSON-RPC over stdio)
    v
MCP Media Forge (Node.js on host)
    |
    |--- Diagrams: docker exec (sandboxed, no network)
    |       |
    |       v
    |   Rendering Container
    |     ├── mmdc       (Mermaid CLI + Chromium)
    |     ├── d2         (D2 diagrams)
    |     ├── dot/neato  (Graphviz)
    |     └── vl2svg     (Vega-Lite via vl-convert)
    |
    |--- HTML/Slides: template engine (no Docker)
    |       |
    |       v
    |   CSS Design System (4 themes, depth tiers, components)
    |
    v
docs/generated/
  mermaid-a1b2c3.svg
  d2-7f8e9a.svg
  html_page-d4e5f6.html
  slides-8b9c0d.html

主な設計上の決定事項：

• テキストを入力し、ファイルパスを出力 -- 相対パスを返し、base64 の塊は返しません
• コンテンツハッシュによる命名 -- 同じ入力なら同じファイルになり、キャッシュを無料で利用でき、Git にも適しています
• SVG を優先 -- ベクター形式でファイルサイズが小さく、Git の差分も見やすくなります
• Docker 内で実行 -- 図のレンダラーは network_mode: none のサンドボックス化されたコンテナ内で動作します
• 自己完結型 HTML -- ページとスライドには外部依存関係がなく（CSS／JS をインライン化）、単独で動作します
• 入力の事前検証 -- Docker との往復処理の前に、よくある間違いを検出します
• 構造化エラー -- エラーレスポンスに error_type、error_message、suggestion を含め、LLM が自己修正できるようにします

ツールリファレンス

get_tool_guide

レンダリングする前に、任意のツールの使用ガイドを取得します。使用例、避けるべきアンチパターン、複雑さの制限、ヒントを返します。

{ "tool_name": "mermaid" }

利用可能なガイド：mermaid、d2、graphviz、vegalite、html_page、slides、または概要を取得する場合は all。

render_mermaid

{
  "code": "flowchart TD\n    A[Start] --> B{Decision}\n    B -->|Yes| C[Done]",
  "format": "svg",
  "theme": "default"
}

パラメーター	型	デフォルト	説明
code	string	必須	Mermaid 図のコード（図の種類で始める必要があります）
format	svg | png	svg	出力形式
theme	default | dark | forest | neutral	default	Mermaid のテーマ

事前検証で検出される項目： 図の種類の指定漏れ、セミコロン、ラベル内の HTML、ノード数が 25 を超える場合。

render_d2

{
  "code": "client -> server -> database",
  "format": "svg",
  "layout": "dagre"
}

パラメーター	型	デフォルト	説明
code	string	必須	D2 図のコード
format	svg | png	svg	出力形式
theme	number	--	テーマ ID（0=デフォルト、1=ニュートラルグレー、3=ターミナル）
layout	dagre | elk | tala	dagre	レイアウトエンジン

事前検証で検出される項目： Mermaid と D2 の構文の混同、波括弧の不一致、ネストの深さが 3 を超える場合。

render_graphviz

{
  "dot_source": "digraph G { A -> B -> C }",
  "engine": "dot",
  "format": "svg"
}

パラメーター	型	デフォルト	説明
dot_source	string	必須	Graphviz DOT のソースコード
engine	dot | neato | fdp | sfdp | twopi | circo	dot	レイアウトエンジン
format	svg | png	svg	出力形式

事前検証で検出される項目： グラフのラッパーの欠落、無向グラフ内の ->、波括弧の不一致。

render_chart

{
  "spec_json": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{\"values\":[{\"x\":1,\"y\":10}]},\"mark\":\"bar\",\"encoding\":{\"x\":{\"field\":\"x\"},\"y\":{\"field\":\"y\"}}}",
  "format": "svg"
}

パラメーター	型	デフォルト	説明
spec_json	string	必須	Vega-Lite の JSON 仕様
format	svg | png	svg	出力形式
scale	number	1	PNG 出力のスケール係数

事前検証で検出される項目： 無効な JSON、$schema／data／mark の欠落、インラインデータの行数が 500 を超える場合。

render_html_page

テーマ付きの自己完結型 HTML ページを生成します。Docker は不要です。

{
  "title": "System Overview",
  "body_html": "<section id=\"metrics\"><h2>Metrics</h2><div class=\"mf-grid mf-grid-3\">...</div></section>",
  "theme": "swiss",
  "description": "Q1 architecture overview",
  "nav_sections": ["Metrics", "Architecture", "Roadmap"]
}

パラメーター	型	デフォルト	説明
title	string	必須	ページのタイトル
body_html	string	必須	HTML の本文コンテンツ（内側のコンテンツのみ。<html>／<head>／<body> は含めません）
theme	swiss | midnight | warm | terminal	swiss	ビジュアルテーマ
description	string	--	ページの説明（メタタグとヘッダー）
nav_sections	string[]	--	フローティング IntersectionObserver ナビゲーション用のセクション名

デザインシステムの CSS クラス：

クラス	用途
mf-hero	主な強調セクション（大きなシャドウ）
mf-elevated	副次的な強調（中程度のシャドウ）
mf-card	枠線付きコンテンツカード
mf-recessed	強調を抑えたコンテンツ
mf-grid mf-grid-2	レスポンシブな 2 列グリッド
mf-grid mf-grid-3	レスポンシブな 3 列グリッド
mf-split	均等な 2 列
mf-kpi + mf-kpi-value + mf-kpi-label	主要指標の表示
mf-badge-success/warning/error/info	ステータスバッジ

テーマ：

テーマ	スタイル	最適な用途
swiss	白、幾何学的、青のアクセント	技術ドキュメント
midnight	濃紺、セリフ体、金のアクセント	プレゼンテーション
warm	クリーム色の紙、太字のサンセリフ体、テラコッタ	レポート
terminal	ダーク、等幅フォント、シアンのアクセント	開発者向けコンテンツ

render_slides

キーボードやタッチで操作できる、自己完結型の HTML スライドデッキを生成します。Docker は不要です。

{
  "title": "Q1 Review",
  "slides": "[{\"title\":\"Q1 Review\",\"content\":\"Engineering update\",\"type\":\"title\"},{\"title\":\"Metrics\",\"content\":\"<ul><li>99.9% uptime</li></ul>\",\"type\":\"content\"}]",
  "theme": "midnight",
  "author": "Engineering Team"
}

パラメーター	型	デフォルト	説明
title	string	必須	プレゼンテーションのタイトル
slides	string	必須	スライドオブジェクトの JSON 配列
theme	swiss | midnight | warm | terminal	swiss	ビジュアルテーマ
author	string	--	作成者（タイトルスライドに表示）

スライドの種類：

種類	レイアウト	最適な用途
title	中央揃えの大きなテキスト＋サブタイトル	オープニング／クロージングスライド
section	中央揃えの見出し＋説明	トピックの区切り
content	見出し＋本文（箇条書き、テキスト）	大半のコンテンツ
split	見出し＋2列	前後の比較、比較
code	見出し＋コードブロック	コードの解説
quote	大きな引用＋帰属表示	お客様の声、重要な引用
kpi	見出し＋自動グリッドの指標	ダッシュボード、統計
image	見出し＋中央揃えの画像	スクリーンショット、図

操作方法： 矢印キー、Space、PageUp/PageDown、Home/End。タッチ操作：左右にスワイプ。ドットをクリックすると移動できます。

list_assets

{ "directory": "" }

生成されたすべてのファイルについて、名前、パス、サイズ、更新日時を含む JSON 配列を返します。

エラー処理

すべてのツールは、LLM が自力で修正するのに役立つ構造化エラーを返します。

{
  "status": "error",
  "error_type": "syntax_error",
  "error_message": "First line must declare diagram type. Got: \"A --> B\"",
  "suggestion": "Start with: flowchart TD, sequenceDiagram, erDiagram, ... See https://mermaid.js.org/syntax/"
}

エラーの種類：syntax_error、rendering_error、dependency_missing。

事前検証により、レンダラーを実行する前に、よくある LLM の誤りを検出します。

• Mermaid：図の種類がない、セミコロン、HTML タグ、旧式の graph 構文
• D2：Mermaid 構文との混同（-->、subgraph）、括弧の不整合
• Graphviz：digraph／graph ラッパーがない、無向グラフでの ->
• Vega-Lite：無効な JSON、必須フィールドがない、インラインデータが大きすぎる

環境変数

変数	デフォルト	説明
PROJECT_ROOT	cwd()	出力パスの解決に使うプロジェクトルート
OUTPUT_DIR	docs/generated	PROJECT_ROOT を基準とした出力ディレクトリ
MEDIA_FORGE_CONTAINER	media-forge-renderer	Docker コンテナ名

開発

npm install
npm run build          # Build with tsup
npm run dev            # Watch mode
npm test               # Run all tests (95 total)
npm run test:unit      # Unit tests only (no Docker needed)
npm run test:component # Integration tests (Docker tools need container)
npm run lint           # Type-check with tsc

統合テストの実行

cd docker && docker compose up -d   # Start renderer (diagram tools only)
cd .. && npm run test:component     # All integration tests

HTML ページとスライドの統合テストは、Docker なしで実行できます。

例

サンプル入力ファイルについては、examples/ を参照してください。

ファイル	ツール	説明
mermaid/flowchart.mmd	render_mermaid	意思決定フローチャート
mermaid/sequence.mmd	render_mermaid	クライアント・サーバー間のシーケンス
d2/architecture.d2	render_d2	コンテナを含むバックエンドアーキテクチャ
graphviz/dependencies.dot	render_graphviz	npm の依存関係グラフ
vegalite/bar-chart.json	render_chart	ツールのパフォーマンス比較

MCP ツール呼び出しの例と期待される応答については、examples/README.md を参照してください。

ライセンス

MIT