three.ws Assistant Widget

io.github.nirholasPublished by GitHub account nirholasv0.1.2Updated Nov 1, 2026

Generate a paste-ready embed for a floating 3D avatar chatbot on any website.

VerifiedSTDIODesktop onlyDeveloper ToolsMedia & Design

Overview

AI-generated overview

Generates paste-ready embed code for a floating 3D avatar chatbot widget on a website, from a described look and behavior.

What you can do
  • Build an embed: turn a config (avatar, background, mode, name, greeting, site context, accent, position, voice, badge) into a script tag, a frame URL, a JavaScript init snippet and the normalized config.
  • List options: enumerate built-in avatars, background presets, interaction modes, chat lanes and the data-* attribute reference, optionally filtered.
  • Validate settings: invalid or over-long values fall back to defaults so the output stays well-formed.
  • Use as a library: the package also exports the tool definitions and a server builder for direct calls.
When to use it
Useful when you want an assistant to draft the embed markup for a three.ws 3D avatar chatbot on a site, or to look up which avatars, backgrounds and attributes are available before hand-editing the snippet.
Requirements
Runs locally over stdio via npx from the npm package, so Node.js 20 or newer is needed. No account, API key or network access is required; the optional THREE_WS_BASE variable changes the origin baked into generated URLs.
Before you install
The generated snippet loads a remote script from the three.ws origin and the widget's chat runs on a third-party LLM chain by default, so visitor conversations go through that service. The output is only text; nothing is published or deployed for you.

Installation

In SourceWeft

  1. Open three.ws Assistant Widget in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[three.ws]

@three-ws/assistant-mcp

Generate a paste-ready three.ws assistant widget, a floating 3D avatar chatbot for any website, from any AI agent.

[npm] [license] [node] [MCP Registry] [three.ws]

A Model Context Protocol server that lets any AI assistant build a paste-ready embed for the three.ws assistant widget over stdio. Describe how you want the assistant to look and behave and build_assistant_widget returns a ready-to-paste <script> tag, a standalone frame URL for <iframe> embedding, and an equivalent ThreeAssistant.init({...}) JavaScript-API snippet, a floating 3D avatar chatbot that lives in the corner of any site. list_assistant_options enumerates every built-in avatar, background preset, interaction mode, chat lane, and data-* attribute you can set.

Both tools are pure and offline: building an embed is deterministic string logic over local validators. Every field is validated and clamped, so a bad or hostile value falls back to a safe default and the generated HTML is always well-formed. No API key, no signer, no payment, no network call. Point THREE_WS_BASE at a deployment (or leave the default) and go.

Install

bash
npm install @three-ws/assistant-mcp

Or run with npx (no install):

bash
npx -y @three-ws/assistant-mcp

Quick start

Claude Code, one line:

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

Claude Desktop / Cursor (claude_desktop_config.json or mcp.json):

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

Inspect the surface with the MCP Inspector:

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

Tools

ToolTypeWhat it does
build_assistant_widgetread-onlyA config → a paste-ready <script> embed (non-default settings as data-*), a frame URL, a ThreeAssistant.init() snippet, and the normalized config.
list_assistant_optionsread-onlyEnumerate every built-in avatar, background preset and grammar, interaction mode, chat lane, and the full data-* attribute reference.

build_assistant_widget is a pure function: the same config always yields the same embed, and it never touches the network. The generated <script> tag carries only the settings that differ from their defaults, so a minimal config yields a minimal tag. The frame_url carries every resolved value (including defaults) so the standalone frame renders deterministically when dropped into an <iframe>.

Input parameters

build_assistant_widget, all optional:

FieldType / valuesDefault
avataravatar id, /avatars/*.glb path, or GLB URLmannequin
agenta three.ws agent id (alternative to avatar)(none)
backgroundtransparent | #hex | ember/ocean/violet/forest/dusk/slate | gradient:#a,#b[,angle]transparent
modechat | speak | bothboth
namestring (≤ 60)(none)
greetingstring (≤ 200)(none)
contextstring (≤ 500), what the assistant should know about the site(none)
accent#hex#f97316
positionright | leftright
voiceboolean, start with voice on/offon
badgeboolean, show the three.ws attribution badgeon

Any value that fails validation (a bad hex, an unknown background, an over-long string) falls back to its default rather than being rejected, so you always get a working embed.

list_assistant_options, filter (optional: avatars | backgrounds | modes | chat_lanes | attributes). Omit to get everything.

Example

jsonc
// 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."}

Paste the snippet before </body> on any page, or drop the frame_url into an <iframe>. Design it visually first at three.ws/assistant.

Requirements

  • Node.js >= 20.
  • No network access needed. THREE_WS_BASE only sets the origin baked into the generated URLs.

Environment variables

VariableRequiredDefault
THREE_WS_BASEnohttps://three.ws

Programmatic use

The package entry point exports TOOLS (every tool definition: name, title, description, inputSchema, annotations, handler) and buildServer(), which returns a fully-registered McpServer with no transport attached. Both tools are pure and offline, so you can call them directly as a widget-builder library with no MCP client involved.

js
// run from a checkout: node this-file.mjsimport { 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();
html
<script src="https://three.ws/assistant/v1.js" async data-avatar="/avatars/michelle.glb" data-bg="dusk"></script>

Links

Part of the three.ws SDK suite, 3D AI agents, on-chain identity, and agent payments.
Website · Changelog · GitHub

Source: packages/assistant-mcp/README.md at commit c8f2cde

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v0.1.2LatestOct 10, 2026
  2. v0.1.1Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts