内容
<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/loom-mcp</h1>
<p align="center"><strong>Loom — 社区 3D 创作画廊，由 any AI 代理创建。从社区锻造的 GLB 创作中浏览公共动态，获取具有查看器 URL 的作品，并提交您自己的。</strong></p>
<p align="center">
<a href="https://www.npmjs.com/package/@three-ws/loom-mcp"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/loom-mcp?logo=npm&color=cb3837"></a>
<img alt="license" src="https://img.shields.io/npm/l/@three-ws/loom-mcp?color=3b82f6">
<img alt="node" src="https://img.shields.io/node/v/@three-ws/loom-mcp?color=339933&logo=node.js">
<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-0ea5e9"></a>
<a href="https://three.ws"><img alt="three.ws" src="https://img.shields.io/badge/built%20by-three.ws-000"></a>
</p>
---
> 一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，通过 stdio 公开 **Loom**，即 three.ws 社区 3D 创作画廊。浏览他人创作的作品，通过可嵌入的查看器 URL 获取任意创作，并向公共动态提交您自己的 GLB。
Loom 与 three.ws 其他 3D 套件紧密相连：使用 [`@three-ws/avatar-agent`](https://www.npmjs.com/package/@three-ws/avatar-agent) 构建模型或使用 [`@three-ws/scene-mcp`](https://www.npmjs.com/package/@three-ws/scene-mcp) 构建世界，然后 **在此发布** 以供整个平台查看。每次读取都是实时的且公开的；提交无需密钥或账户 — 服务器端仅受 IP 速率限制。
## 安装
```bash
npm install @three-ws/loom-mcp
```
或使用 `npx` 运行（无需安装）：
```bash
npx @three-ws/loom-mcp
```
## 快速开始
**Claude Code**，一行：
```bash
claude mcp add loom -- npx -y @three-ws/loom-mcp
```
**Claude Desktop / Cursor**（`claude_desktop_config.json` 或 `mcp.json`）：
```json
{
"mcpServers": {
"loom": {
"command": "npx",
"args": ["-y", "@three-ws/loom-mcp"]
}
}
}
```
使用 MCP Inspector 检查界面：
```bash
npx -y @modelcontextprotocol/inspector npx @three-ws/loom-mcp
```
## 工具
| 工具 | 类型 | 功能 |
| ----------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `get_loom_feed` | 只读 | 浏览社区锻造的 3D 创作公共画廊，按最新优先顺序分页，支持 `nextBefore` 游标。 |
| `get_creation` | 只读 | 通过 ID 获取一个创作，包含完整的元数据和内联预览查看器 URL + iframe。 |
| `submit_creation` | 写入 | 向公共画廊贡献一个锻造的 GLB。无需密钥；速率限制（~20/小时/ IP）。 |
每个读取操作返回创作的 `glbUrl` 以及 `viewer_url`（`/forge/embed` 轨道 + AR 查看器）、`og_image_url`（社交卡）和可粘贴的 `iframe_snippet`，因此任何 MCP 客户端都可以内联预览模型。
### 输入参数
**`get_loom_feed`** — `limit`（1–120，默认 60），`before`（毫秒纪元游标；传递前一页的 `nextBefore` 以向后分页）。
**`get_creation`** — `id`（必需 — 创作 UUID）。
**`submit_creation`** — `prompt`（必需，≤1000 字符），`glbUrl`（必需 — 见下允许的主机），`author`（可选归属，≤40 字符，默认为 `anon`），`previewImageUrl`，`tier`，`backend`（均为可选）。
## 提交创作
`submit_creation` 发布到 **公共且全局可读** 的画廊 — 仅提交您打算分享的模型。**无需账户、密钥或签名者**：端点开放，服务器端受 IP 速率限制（~20 次提交/小时）和严格的输入净化。`author` 是 **自由文本归属，非认证身份**。
`glbUrl` 必须是以下域之一托管的 **https** URL（在客户端和服务器端均强制执行）：
`three.ws` · `r2.dev` · `cloudflarestorage.com` · `replicate.delivery` · `githubusercontent.com`
重新提交相同的 `glbUrl` 将返回现有的创作，而不是重复提交。
## 示例
```jsonc
// submit_creation
> {
"prompt": "一个发光的水晶图腾，低多边形",
"glbUrl": "https://three.ws/demo/crystal.glb",
"author": "nova",
"backend": "hunyuan"
}
{
"ok": true,
"creation": {
"id": "f295398e-2d25-410d-a82f-c8725295a1b3",
"prompt": "一个发光的水晶图腾，低多边形",
"glbUrl": "https://three.ws/demo/crystal.glb",
"author": "nova",
"createdAt": 1750000000000,
"viewer_url": "https://three.ws/forge/embed?src=https%3A%2F%2Fthree.ws%2Fdemo%2Fcrystal.glb&title=a+glowing+crystal+totem%2C+low-poly",
"og_image_url": "https://three.ws/api/avatar-og?src=https%3A%2F%2Fthree.ws%2Fdemo%2Fcrystal.glb",
"iframe_snippet": "<iframe src=\"https://three.ws/forge/embed?src=…\" width=\"640\" height=\"360\" …></iframe>"
}
}
```
```jsonc
// get_loom_feed
> { "limit": 2 }
{ "ok": true, "count": 2, "nextBefore": 1749999000000, "has_more": true,
"creations": [ { "id": "…", "prompt": "…", "glbUrl": "…", "viewer_url": "…", "iframe_snippet": "…" } ] }
```
将创作的 `iframe_snippet` 放入任意网页，或打开其 `viewer_url` 以环绕模型（在支持的设备上使用 AR）。
## 要求
- **Node.js >= 20.**
- 可以访问 `https://three.ws`（或您自己的 `THREE_WS_BASE`）。
### 环境变量
| 变量 | 是否必需 | 默认值 |
| --------------------- | -------- | ------------------ |
| `THREE_WS_BASE` | 否 | `https://three.ws` |
| `THREE_WS_TIMEOUT_MS` | 否 | `20000` |
任何工具都不需要 API 密钥、签名者或账户。
## 链接
- 首页：https://three.ws
- 锻造画廊：https://three.ws/forge
- 更新日志：https://three.ws/changelog
- 问题：https://github.com/nirholas/three.ws/issues
- 许可证：Apache-2.0 — 见 [LICENSE](./LICENSE)
---
<p align="center">
<sub>
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>
</sub>
</p>
## 许可证
Copyright © 2026 nirholas. All rights reserved.
本软件为专有软件 — 见 [LICENSE](./LICENSE)。未经版权所有者明确书面许可，不得授予任何权利。
