three.ws Assistant Widget

@three-ws/assistant-mcp

让任何 AI Agent 都能生成可直接粘贴的 three.ws 助手小组件——一个适用于任何网站的悬浮式 3D 头像聊天机器人。

---

一个通过标准输入/输出（stdio）让任何 AI 助手都能为 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，一行命令：

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	avatar ID、/avatars/*.glb 路径或 GLB URL	mannequin
agent	three.ws agent 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

任何未通过验证的值（无效的十六进制颜色、未知背景或超长字符串）都会回退到默认值，而不会被拒绝，因此始终能获得可用的嵌入组件。

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

编程式使用

该软件包入口导出 TOOLS（每个工具定义包含：name、title、 description、inputSchema、annotations、handler）和 buildServer()，后者会返回一个 已完整注册、未附加传输的 McpServer。这两个工具均为纯函数且可离线使用，因此你 可以直接将其作为组件构建库调用，无需涉及 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 Agent、链上身份和 Agent 支付。
网站 · 更新日志 · GitHub}