three.ws assistant MCP server
Commit Nov 10, 2026Generates paste-ready embed codes for floating 3D avatar chatbot widgets to be used on any website.
Also known as nirholas/assistant-mcp
- Stars
- 5
- Tools
- 13
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 10, 2026
- License
- Apache-2.0
What is three.ws assistant MCP?
three.ws assistant generates paste-ready embed codes for floating 3D avatar chatbot widgets to be used on any website. It exposes 13 tools, such as build_assistant_widget, list_assistant_options, avatar.
Summary generated from the project's README
About three.ws assistant MCP server
Creating floating 3D avatar chatbot widgets for websites is what this server enables for developers using AI agents. By describing a desired appearance and behavior, users can generate ready-to-paste embed codes, including script tags, iframe URLs, and JavaScript API snippets. This allows any AI assistant to build a customized three.ws assistant widget that lives in the corner of a webpage.
The server operates locally over stdio and requires no API keys, signers, or network calls to function. It uses deterministic string logic to ensure that every generated HTML snippet is well-formed and valid. Users can configure specific details such as avatar models, background presets like ocean or forest, interaction modes, and accent colors. The build process is entirely offline, making it a private and predictable way to generate web components through tools like build_assistant_widget and list_assistant_options.
What you can do with it
- 1Generate website chatbot embedsAn AI agent can produce a complete script tag for a 3D avatar widget based on a user's visual description.
- 2Discover available widget customizationsDevelopers can ask an AI to list all supported avatars, backgrounds, and interaction modes to plan a design.
- 3Customize chatbot visual identityYou can instruct an AI to configure a chatbot with a specific name, greeting, and color scheme.
Written from the project's README. Every use case is checked against a quote from it.
three.ws assistant MCP tools 13
Detected from the READMEbuild_assistant_widgetlist_assistant_optionsavataragentbackgroundmodenamegreetingcontextaccentpositionvoice
| build_assistant_widget | — | |
| list_assistant_options | — | |
| avatar | — | |
| agent | — | |
| background | — | |
| mode | — | |
| name | — | |
| greeting | — | |
| context | — | |
| accent | — | |
| position | — | |
| voice | — |
Show all 13 toolsShow fewer tools
badge
| badge | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablenirholas/assistant-mcp is public and reachablegithub.com/nirholas/assistant-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/nirholas/assistant-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model13 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubA 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_widgetreturns a ready-to-paste<script>tag, a standalone frame URL for<iframe>embedding, and an equivalentThreeAssistant.init({...})JavaScript-API snippet, a floating 3D avatar chatbot that lives in the corner of any site.list_assistant_optionsenumerates every built-in avatar, background preset, interaction mode, chat lane, anddata-*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
npm install @three-ws/assistant-mcp
Or run with npx (no install):
npx -y @three-ws/assistant-mcp
Quick start
Claude Code, one line:
claude mcp add assistant -- npx -y @three-ws/assistant-mcp
Claude Desktop / Cursor (claude_desktop_config.json or mcp.json):
{
"mcpServers": {
"assistant": {
"command": "npx",
"args": ["-y", "@three-ws/assistant-mcp"]
}
}
}
Inspect the surface with the MCP Inspector:
npx -y @modelcontextprotocol/inspector npx @three-ws/assistant-mcp
Tools
| Tool | Type | What it does |
|---|---|---|
build_assistant_widget |
read-only | A config → a paste-ready <script> embed (non-default settings as data-*), a frame URL, a ThreeAssistant.init() snippet, and the normalized config. |
list_assistant_options |
read-only | Enumerate 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:
| Field | Type / values | Default |
|---|---|---|
avatar |
avatar id, /avatars/*.glb path, or GLB URL |
mannequin |
agent |
a three.ws agent id (alternative to avatar) |
(none) |
background |
transparent | #hex | ember/ocean/violet/forest/dusk/slate | gradient:#a,#b[,angle] |
transparent |
mode |
chat | speak | both |
both |
name |
string (≤ 60) | (none) |
greeting |
string (≤ 200) | (none) |
context |
string (≤ 500), what the assistant should know about the site | (none) |
accent |
#hex |
#f97316 |
position |
right | left |
right |
voice |
boolean, start with voice on/off | on |
badge |
boolean, show the three.ws attribution badge | on |
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
// 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_BASEonly sets the origin baked into the generated URLs.
Environment variables
| Variable | Required | Default |
|---|---|---|
THREE_WS_BASE |
no | https://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.
// 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>
Links
- Builder: https://three.ws/assistant
- Docs: https://three.ws/docs/assistant-widget
- Homepage: https://three.ws
- Changelog: https://three.ws/changelog
- Issues: https://github.com/nirholas/three.ws/issues
- License: Apache-2.0, see LICENSE
Support the project
If assistant-mcp saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.
Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit
Built for AI agents too
Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/assistant-mcp and it has the context it needs.
More from the same author
- All repositories by nirholas: the full catalog, grouped by topic
- three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
- Questions or ideas: open an issue or start a discussion
Contributors
Star history
Part of three.ws
three.ws is a platform for 3D AI agents with Solana wallets: avatars, a skill marketplace, x402 payments and more than seventy MCP servers. @three-ws/assistant-mcp is one package from it.
- Documentation site: https://nirholas.github.io/assistant-mcp/
- npm: https://www.npmjs.com/package/@three-ws/assistant-mcp
- Canonical source: https://github.com/nirholas/three.ws (this repository is a generated mirror of
packages/assistant-mcp) - Agent-readable summary: llms.txt and AGENTS.md
- Issues and ideas: https://github.com/nirholas/assistant-mcp/issues
three.ws assistant MCP questions
What tools does three.ws assistant MCP provide?
It exposes 13 tools, including build_assistant_widget, list_assistant_options, avatar, agent, background.
Does this require an API key?
No, the server is pure and offline, requiring no API key, signer, or payment to build an embed.
What kind of embed formats are provided?
It returns a ready-to-paste <script> tag, a standalone iframe URL, and a JavaScript-API snippet.
Can I customize the appearance of the assistant?
Yes, you can customize the avatar, background, name, greeting, accent color, and position.