three.ws Assistant Widget

@three-ws/assistant-mcp

あらゆる AI エージェントから、あらゆるウェブサイトに設置できる、貼り付けるだけの three.ws アシスタントウィジェット（浮遊する 3D アバターのチャットボット）を生成します。

---

どの AI アシスタントからでも、stdio 経由で three.ws のアシスタントウィジェット用の貼り付けるだけの埋め込みコードを作成できる、Model Context Protocol サーバーです。アシスタントの見た目や動作を指定すると、build_assistant_widget がそのまま貼り付けられる <script> タグ、<iframe> 埋め込み用のスタンドアロンフレーム URL、および同等の ThreeAssistant.init({...}) JavaScript API スニペットを返します。これにより、あらゆるサイトの隅に浮かぶ 3D アバターのチャットボットを設置できます。list_assistant_options では、組み込みアバター、背景プリセット、インタラクションモード、チャットレーン、および設定可能なすべての data-* 属性を一覧表示します。

どちらのツールも純粋なオフライン処理です。埋め込みコードの生成は、ローカルのバリデーターを使った決定的な文字列処理です。すべてのフィールドが検証され、範囲内に調整されるため、不正または悪意のある値は安全なデフォルト値に置き換えられ、生成される HTML は常に整形式です。API キー、署名者、支払い、ネットワーク呼び出しは不要です。THREE_WS_BASE をデプロイ先に設定する（またはデフォルトのままにする）だけで使えます。

インストール

npm install @three-ws/assistant-mcp

または、npx で実行します（インストール不要）。

npx -y @three-ws/assistant-mcp

クイックスタート

Claude Code の場合、1 行で設定できます。

claude mcp add assistant -- npx -y @three-ws/assistant-mcp

Claude Desktop / Cursor の場合（claude_desktop_config.json または mcp.json）：

{
	"mcpServers": {
		"assistant": {
			"command": "npx",
			"args": ["-y", "@three-ws/assistant-mcp"]
		}
	}
}

MCP Inspector でインターフェースを確認します。

npx -y @modelcontextprotocol/inspector npx @three-ws/assistant-mcp

ツール

ツール	種類	機能
build_assistant_widget	読み取り専用	設定から、貼り付けるだけの <script> 埋め込みコード（デフォルト以外の設定は data-* として指定）、フレーム URL、ThreeAssistant.init() スニペット、および正規化された設定を生成します。
list_assistant_options	読み取り専用	組み込みアバター、背景プリセットと文法、インタラクションモード、チャットレーン、および data-* 属性の完全なリファレンスを一覧表示します。

build_assistant_widget は純粋関数です。同じ設定からは常に同じ埋め込みコードが生成され、ネットワークには一切アクセスしません。生成される <script> タグには、デフォルト値と異なる設定のみが含まれるため、最小限の設定からは最小限のタグが生成されます。frame_url には、デフォルト値を含む解決済みのすべての値が含まれるため、スタンドアロンフレームを <iframe> に挿入したときも決定的にレンダリングされます。

入力パラメーター

build_assistant_widget（すべて省略可能）：

フィールド	型／値	デフォルト
avatar	アバター ID、/avatars/*.glb パス、または GLB URL	mannequin
agent	three.ws エージェント ID（avatar の代わりに指定）	(none)
background	transparent | #hex | ember/ocean/violet/forest/dusk/slate | gradient:#a,#b[,angle]	transparent
mode	chat | speak | both	both
name	文字列（≤ 60）	(none)
greeting	文字列（≤ 200）	(none)
context	文字列（≤ 500）、アシスタントがサイトについて把握しておくべき情報	(none)
accent	#hex	#f97316
position	right | left	right
voice	ブール値、音声をオン／オフにして起動	on
badge	ブール値、three.ws の帰属表示バッジを表示	on

検証に失敗した値（不正な hex、未定義の背景、文字数超過の文字列など）は拒否されず、デフォルト値に置き換えられるため、常に動作する埋め込みを利用できます。

list_assistant_options：filter（省略可能：avatars | backgrounds | modes | chat_lanes | attributes）。省略するとすべて取得します。

例

// build_assistant_widget
> {
    "avatar": "/avatars/selfie-girl.glb",
    "background": "ocean",
    "mode": "both",
    "name": "Aria",
    "greeting": "Hi! Ask me anything about the site.",
    "accent": "#00c2ff",
    "position": "left"
  }
{
  "ok": true,
  "snippet": "<script src=\"https://three.ws/assistant/v1.js\" async data-avatar=\"/avatars/selfie-girl.glb\" data-bg=\"ocean\" data-name=\"Aria\" data-greeting=\"Hi! Ask me anything about the site.\" data-accent=\"#00c2ff\" data-position=\"left\"></script>",
  "frame_url": "https://three.ws/assistant-frame?avatar=%2Favatars%2Fselfie-girl.glb&bg=ocean&mode=both&name=Aria&greeting=Hi%21+Ask+me+anything+about+the+site.&accent=%2300c2ff",
  "js_api": "ThreeAssistant.init({\n  \"bg\": \"ocean\",\n  \"mode\": \"both\",\n  \"accent\": \"#00c2ff\",\n  \"position\": \"left\",\n  \"avatar\": \"/avatars/selfie-girl.glb\",\n  \"name\": \"Aria\",\n  \"greeting\": \"Hi! Ask me anything about the site.\"\n});",
  "builder_url": "https://three.ws/assistant",
  "config": { "bg": "ocean", "mode": "both", "accent": "#00c2ff", "position": "left", "avatar": "/avatars/selfie-girl.glb", "name": "Aria", "greeting": "Hi! Ask me anything about the site." },
  "notes": "Chat runs on the free three.ws LLM chain by default (no key). Visitors can paste their own Groq or OpenRouter key in the widget settings for a private lane; that key stays in their browser."
}

snippet を任意のページの </body> の前に貼り付けるか、frame_url を <iframe> に指定してください。まず three.ws/assistant で見た目をデザインできます。

要件

• Node.js >= 20。
• ネットワークアクセスは不要です。THREE_WS_BASE は、生成される URL に埋め込まれるオリジンのみを設定します。

環境変数

変数	必須	デフォルト
THREE_WS_BASE	いいえ	https://three.ws

プログラムからの利用

パッケージのエントリーポイントでは、すべてのツール定義（name、title、 description、inputSchema、annotations、handler）を含む**TOOLSと、トランスポートが接続されていない、完全に登録済みの McpServer を返すbuildServer()**をエクスポートしています。どちらのツールも純粋なオフラインツールなので、MCP クライアントを介さず、ウィジェット構築ライブラリとして直接呼び出せます。

// run from a checkout: node this-file.mjs
import { TOOLS, buildServer } from '@three-ws/assistant-mcp';

const build = TOOLS.find((t) => t.name === 'build_assistant_widget');
const { snippet } = await build.handler({ avatar: '/avatars/michelle.glb', background: 'dusk' });
console.log(snippet);

// Or hand the whole registered server to your own MCP transport.
buildServer();

<script src="https://three.ws/assistant/v1.js" async data-avatar="/avatars/michelle.glb" data-bg="dusk"></script>

リンク

• ビルダー：https://three.ws/assistant
• ドキュメント：https://three.ws/docs/assistant-widget
• ホームページ：https://three.ws
• 変更履歴：https://three.ws/changelog
• イシュー：https://github.com/nirholas/three.ws/issues
• ライセンス：Apache-2.0。詳細は LICENSE をご覧ください。

---

_{three.ws の SDK スイートの一部です。3D AI エージェント、オンチェーン ID、エージェント決済を提供します。
ウェブサイト · 変更履歴 · GitHub}