threews-avatar-mcp

<p align="center"> <a href="https://three.ws"><img src="https://three.ws/three-ws-mcp-icon.svg" alt="three.ws" width="88" height="88"></a> </p> <h1 align="center">@three-ws/avatar-mcp</h1> <p align="center"><strong>一款将实时、旋转的3D头像投放到任意聊天窗口的MCP服务器，可交互、嵌入任意位置。免费，无需API密钥。</strong></p> <p align="center"> <a href="https://www.npmjs.com/package/@three-ws/avatar-mcp"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/avatar-mcp?logo=npm&color=cb3837"></a> <a href="https://www.npmjs.com/package/@three-ws/avatar-mcp"><img alt="downloads" src="https://img.shields.io/npm/dm/@three-ws/avatar-mcp?color=cb3837"></a> <img alt="license" src="https://img.shields.io/npm/l/@three-ws/avatar-mcp?color=3b82f6"> <img alt="node" src="https://img.shields.io/node/v/@three-ws/avatar-mcp?color=339933&logo=node.js"> <a href="https://modelcontextprotocol.io"><img alt="mcp" src="https://img.shields.io/badge/Model%20Context%20Protocol-✓-9945FF"></a> <a href="https://registry.modelcontextprotocol.io/?q=io.github.nirholas"><img alt="MCP Registry" src="https://img.shields.io/badge/MCP%20Registry-io.github.nirholas%2Fthreews--avatar-blue"></a> </p> <p align="center"> <a href="#安装">安装</a> · <a href="#设置">设置</a> · <a href="#快速开始">快速开始</a> · <a href="#工具">工具</a> · <a href="#需求">需求</a> · <a href="https://three.ws">three.ws</a> </p> --- > 一个薄、零配置、**只读**的 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，将 three.ws 3D 头像带入任意 MCP 客户端 — Claude Desktop、Claude Code、Cursor 或其他主机。渲染实时、旋转的头像内联，获取粘贴任意位置的嵌入 iframe，或获取头像元数据。所有工具都实时读取真实的 three.ws 端点 — 无模拟数据。公共和未列出的头像 **无需 API 密钥**。注册表名称：`io.github.nirholas/threews-avatar`。由 [three.ws](https://three.ws) 构建。 需要钱包、语音、生成或 pump.fun 权限？请查看 sibling package [`@three-ws/avatar-agent`](https://www.npmjs.com/package/@three-ws/avatar-agent)，一个完整的 3D AI 代理。 ## 安装 ```bash npm install @three-ws/avatar-mcp ``` 使用 `npx` 直接运行（无需安装）或全局安装 `avatar-mcp` CLI： ```bash npx -y @three-ws/avatar-mcp # MCP stdio server npm install -g @three-ws/avatar-mcp # 暴露 `avatar-mcp` ``` ## 设置 **Claude Code**，一行： ```bash claude mcp add threews-avatar -- npx -y @three-ws/avatar-mcp ``` **Claude Desktop / Cursor** （JSON 配置）： ```json { "mcpServers": { "threews-avatar": { "command": "npx", "args": ["-y", "@three-ws/avatar-mcp"] } } } ``` 无需环境变量。要从不同主机（例如预览部署）读取头像，请设置 `THREEWS_BASE_URL`。编辑配置后，请重启客户端。 使用 GUI 检查工具表面： ```bash npx -y @modelcontextprotocol/inspector npx -y @three-ws/avatar-mcp ``` ## 快速开始 连接后，以纯语言询问客户端： > 在聊天中渲染 @nirholas 的头像，黑暗背景，自动旋转。 `render_avatar` 返回三项，因此在每个客户端中看起来都很棒： 1. **预览图片** 在所有地方内联渲染， 2. 一个 **交互式 `text/html` 资源** — 真实的 `<model-viewer>`，您可以旋转和缩放，适用于渲染 HTML 资源的主机，以及 3. **嵌入 URL + iframe** 将实时头像投放到任意页面。 ## 工具 所有三个工具都是免费、只读的，并且注释了 (`readOnlyHint`、`idempotentHint`、`openWorldHint`)，因此主机可以在没有确认提示的情况下运行它们。没有 x402 费用。通过 **`id`** （UUID）、 **`handle`** （`nirholas` 或 `@nirholas`）或原始 **`model`** GLB URL 标识头像。 | 工具 | 选择器 | 功能 | | ------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `render_avatar` | `id` · `handle` · `model` | 在聊天中内联渲染头像。在支持 [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview) 的主机上，它显示一个 **实时、旋转的 3D 模型**；其他客户端获取预览图片 + 嵌入 URL。参数：`background` (`transparent`/`dark`/`light`)，`scene` (`portrait`/`headshot`/`upper-body`/`full-body`)，`auto_rotate`，`height` (160–1080)。 | | `avatar_embed_code` | `id` · `handle` · `model` | 返回一个可粘贴的 `<iframe>`，将实时头像嵌入任意位置 — 像 YouTube 嵌入一样简单。参数：`background`，`width` （CSS），`height` (160–1080)，`idle` （循环空闲动画），`overlay` （无 chrome 模式适用于 OBS/叠加层）。 | | `get_avatar` | `id` · `handle` | 获取头像元数据：`name`，GLB `model_url`，所有者，可见性。 | ### 聊天中的交互式 3D — 差异化因素 `render_avatar` 是一个 [MCP App](https://modelcontextprotocol.io/extensions/apps/overview) （SEP-1865）：它声明了一个 `ui://` 资源，支持的主机在沙盒 iframe 中渲染 — 真实的、可旋转和缩放的 `<model-viewer>`，不是静态图片。头像在对话中是实时的：旋转它、缩放它、观看它空闲，无需离开聊天。不支持 MCP Apps 的主机仍然可以获取渲染的预览图片和一键式实时嵌入，因此工具在所有地方都能平稳降级。 ### 示例调用 ```jsonc // render_avatar — 聊天中的实时、旋转头像 { "handle": "nirholas", "background": "dark", "auto_rotate": true } // avatar_embed_code — 粘贴到任意网站 { "id": "c3d4e5f6-a7b8-9c0d-1e2f-3a4b5c6d7e8f", "height": 560 } // get_avatar — 元数据 { "handle": "@nirholas" } ``` 每个工具还提供一个 `outputSchema`，描述其 `structuredContent`，因此类型化的客户端可以消费结果而无需重新解析文本块。 ## 提示 | 提示 | 参数 | 功能 | | ----------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `showcase-avatar` | `avatar` — id (UUID) 或 @handle | 一步展示：内联渲染实时、旋转的头像 **和** 生成嵌入 iframe，以复制粘贴摘要（名称、查看器 URL、嵌入 URL、`<iframe>` 片段）。 | ## 工作原理 每个选择器都映射到一个真实的 three.ws 端点。原始 `model` URL 必须为 `https://` （或 `http://localhost` 用于开发）；其他方案将被拒绝。 | 选择器 / 资产 | 端点 | | ---------------- | --------------------------------------------------- | | `id` | `GET https://three.ws/api/avatars/:id` | | `handle` | `GET https://three.ws/api/users/:handle/avatar` | | 预览图片 | `GET https://three.ws/api/avatar/render?avatar=:id` | | 实时嵌入 | `https://three.ws/avatar-embed.html?...` | | 查看器 | `https://three.ws/viewer?src=:glb` | ## 需求 - **Node** `>=20`。 - **无凭证**。公共和未列出的头像无需 API 密钥。 | 变量 | 必需 | 注释 | | -------------------- | -------- | ----------------------------------------------------------- | | `THREEWS_BASE_URL` | 可选 | three.ws 主机读取。默认为 `https://three.ws`。 | | `THREEWS_TIMEOUT_MS` | 可选 | 每请求网络超时。默认为 `30000`。 | ## 链接 - 首页：https://three.ws - 兄弟包：[`@three-ws/avatar-agent`](https://www.npmjs.com/package/@three-ws/avatar-agent) — 完整的 3D AI 代理（钱包、语音、pump.fun） - 更新日志：https://three.ws/changelog - 问题：https://github.com/nirholas/three.ws/issues - 许可证：Apache-2.0 — 见 [LICENSE](./LICENSE) --- <p align="center"> _{three.ws SDK 套件的一部分 — 3D AI 代理、链上身份和代理支付。<br/> <a href="https://three.ws">网站</a> · <a href="https://three.ws/changelog">更新日志</a> · <a href="https://github.com/nirholas/three.ws">GitHub</a>} </p> ## 许可证 版权所有 © 2026 nirholas。保留所有权利。 本软件是专有的 — 见 [LICENSE](./LICENSE)。未经版权所有者明确书面许可，不得授予任何权利。