内容
<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/scene-mcp</h1>
<p align="center"><strong>将三维世界变为现实 — 通过一句描述生成一个放置好的场景。</strong></p>
<p align="center">
<a href="https://www.npmjs.com/package/@three-ws/scene-mcp"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/scene-mcp?logo=npm&color=cb3837"></a>
<img alt="license" src="https://img.shields.io/npm/l/@three-ws/scene-mcp?color=3b82f6">
<img alt="node" src="https://img.shields.io/node/v/@three-ws/scene-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) 服务器，为任何 AI 助手提供 three.ws **场景** 管道，支持标准输入/输出。描述一个世界，用一句描述生成一个放置好的场景 — 情绪、调色板、地面和一组单个对象的锻造提示 — 准备好构建成一个可轨道的三维场景。使用 `get_scene` 和 `list_scenes` 浏览已保存的世界。
这是 three.ws 角色一句话的配套工具：角色为您提供一个 *角色*；场景为您提供一个 *世界*。无需 API 密钥、无需签名、无需支付 — 每次调用都直接命中公共 `/api/diorama` 端点。
## 安装
```bash
npm install @three-ws/scene-mcp
```
或使用 `npx`（无需安装）运行：
```bash
npx @three-ws/scene-mcp
```
## 快速开始
**Claude 代码**，一行：
```bash
claude mcp add scene -- npx -y @three-ws/scene-mcp
```
**Claude 桌面版 / Cursor** (`claude_desktop_config.json` 或 `mcp.json`）：
```json
{
"mcpServers": {
"scene": {
"command": "npx",
"args": ["-y", "@three-ws/scene-mcp"]
}
}
}
```
使用 MCP 检查器检查表面：
```bash
npx -y @modelcontextprotocol/inspector npx @three-ws/scene-mcp
```
## 工具
| 工具 | 类型 | 功能 |
| --------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
| `compose_scene` | 生成式 | 一句话 → 一个场景计划：标题、情绪、调色板、地面和 2–8 个放置的单个对象锻造提示。 |
| `get_scene` | 只读 | 通过 ID（带有 GLB URL）和其可轨道查看器 URL 获取已保存的世界。 |
| `list_scenes` | 只读 | 浏览最近或精选的场景画廊。 |
`compose_scene` 只返回 *计划* — 不会锻造网格，也不会保存。 通过 `/api/forge` 锻造每个对象，然后 `POST /api/diorama {action:"save"}` 以生成一个可分享的永久链接，网址为 `https://three.ws/diorama?id=…`。
### 输入参数
**`compose_scene`** — `prompt`（必填，3–1024 个字符：描述世界的句子）。
**`get_scene`** — `id`（必填：保存时返回的场景 ID）。
**`list_scenes`** — `list`（`recent` | `featured`，默认为 `recent`），`limit`（1–50，默认为 24）。
## 示例
```jsonc
// compose_scene
> { "prompt": "一个暴风雨的悬崖上的孤独灯塔，夕阳西下" }
{
"ok": true,
"diorama": {
"title": "黄昏时的灯塔",
"mood": "dusk",
"ground": "stone",
"island": "craggy",
"palette": { "sky": ["#2b2350", "#c76b4a"], "ground": "#5b5560", "fog": "#3a3550", "accent": "#ffb27a" },
"objects": [
{ "id": "obj-0", "label": "lighthouse", "prompt": "白色和红色条纹的石头灯塔", "position": [0, 0, 0], "scale": 2.2, "rotationY": 0, "status": "pending", "glbUrl": null }
]
},
"object_count": 1,
"viewer_base": "https://three.ws/diorama"
}
```
## 要求
- **Node.js >= 20.**
- 可以访问 `https://three.ws`（或您自己的 `THREE_WS_BASE`）。
### 环境变量
| 变量 | 必需 | 默认值 |
| --------------------- | -------- | ------------------ |
| `THREE_WS_BASE` | 否 | `https://three.ws` |
| `THREE_WS_TIMEOUT_MS` | 否 | `45000` |
## 链接
- 首页：https://three.ws
- 更新日志：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)。未经版权所有者明确书面许可，不得授予任何权利。
