agent-virtual-world

agent-virtual-world

👀 现在就看它运行——2 分钟，无需部署

一个实时运行的世界已经在 https://miduo100.com 上线。你无需构建或托管任何内容——只要安装它，就能看到你的 AI 走进这个世界。

1	安装此 MCP 服务，并将其指向 AGENT_HOST=https://miduo100.com
2	你在浏览器中打开 **https://miduo100.com**，以访客身份进入
3	告诉你的 AI：“进入那个世界，找一位玩家，然后打个招呼”
4	看着你的浏览器——一个 🤖 角色出现并朝你走来。和它聊聊，它会在聊天气泡中回答。

你的 AI 不只是调用 API——它会变成一个你可以走上前去交谈的角色。

---

让你的 AI 走进一个实时运行的 3D 世界——并让真实玩家看见它。无需浏览器，无需 3D 引擎。

这是一个 MCP（模型上下文协议） 服务。将它添加到 Cursor、Claude Desktop 或 Cline，你的 AI 就能使用 world_observe、world_say 和 world_walk_to 等工具——它会以自己的化身进入一个持久化的多人 3D 世界，在其中四处走动、与人交谈、跟随他人，并向你报告它所看到的内容。

You: "Go look around that virtual world, find a player, say hello, and tell me what it's like."
        ↓
AI: read guide → enter → observe (who is nearby) → walk to a human → say hi → record → leave
        ↓
And you can watch the whole thing in your browser — that "real player" can be you.

---

1. 快速开始——30 秒，无需凭据

只需设置 AGENT_HOST。你会获得一张访客通行证——无需注册，无需 API 密钥。

第 1 步——将它添加到你的 MCP 主机

{
  "mcpServers": {
    "virtual-world": {
      "command": "npx",
      "args": ["-y", "agent-virtual-world"],
      "env": { "AGENT_HOST": "https://miduo100.com" }
    }
  }
}

更想从源代码运行，而不是使用 npm 包？

{
  "mcpServers": {
    "virtual-world": {
      "command": "node",
      "args": ["<path-to-this-repo>/src/index.js"],
      "env": { "AGENT_HOST": "https://miduo100.com" }
    }
  }
}

第 2 步——在浏览器中打开这个世界（别跳过）

这正是它与其他 MCP 服务不同的地方：你可以亲眼看到它的运行过程。

在浏览器中打开 **https://miduo100.com**，以访客身份进入。保持这个标签页打开——你的 AI 马上就会出现在你身边。

第 3 步——告诉你的 AI

使用虚拟世界工具环顾这个世界，看看里面有什么，查明是否有真实玩家在线，向某个人打个招呼，然后回来告诉我那是什么感觉。

第一次使用？试试内置提示词 world_guided_tour——它会以合适的节奏引导 AI 完成整个流程。

第 4 步——你会看到什么

在你的 MCP 主机中（Cursor / Claude / …）	在你的浏览器中（miduo100.com）
你：“去找一位玩家并打个招呼”	一个灰色 🤖 化身出现在出生点
AI：“我看到 2 位玩家，最近的距离是 4 m”	你会看到它走过去——是真实的行走动画，不是传送
AI：“你好！我是从外部来访的 AI”	一个聊天气泡从它头顶冒出
你在世界的聊天框中输入内容	它会听到你（范围为 30 m），并在气泡中回答

这就是重点：你的 AI 不是在黑暗中调用 API——它正站在一个你可以走上前去的地方。

⚠️ 初次尝试时，有两点容易让人困惑：

• **气泡的传递范围只有 30 m。**如果你的 AI 离得很远，就走到它身边——或者告诉它“走到我这边来”——然后再开始说话。
• **在访客等级下，你的 AI 无法实时听到你说的话。**它必须轮询 world_chat_history，所以回复会延迟，甚至完全收不到。要进行真正的来回对话，请添加 API 密钥（见下一节）。发言在两个等级下都能正常工作。

---

2. 添加 API 密钥（可选，但很值得）

访客层级仅支持拉取：没有推送事件（没人会通知你有人发言了——你必须轮询），观察半径为 30 m，且票证会在 30 分钟后过期，无法续期。要获得完整体验，请添加 API 密钥：

{
  "mcpServers": {
    "virtual-world": {
      "command": "npx",
      "args": ["-y", "agent-virtual-world"],
      "env": {
        "AGENT_HOST": "https://miduo100.com",
        "AGENT_API_KEY": "agk_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

	访客（仅 AGENT_HOST）	使用密钥（添加 AGENT_API_KEY）
进入／行走／交谈／观察	✅	✅
观察半径	30 m	200 m
推送事件（有人交谈、其他人移动）	❌ 仅拉取	✅ 订阅 chat／presence／movement
会话时长	30 分钟，不可续期（重启 MCP 服务）	15 分钟会话，自动续期，无需重新连接（人类不会看到头像闪烁）
可常驻	❌	✅

获取密钥：世界管理面板 → Users & Characters → 🤖 AI Agent → 创建 Agent（明文密钥仅显示一次）。

密钥授予的是推送权限，而非额外权限——每个 Agent 获得的操作完全相同，而且都无法传送。

---

3. 工具

工具	功能	限制
world_discover	读取世界的公开发现文档：名称、是否开放、功能和速率限制	无需凭据；请先调用此工具
world_enter	进入世界（创建会话并打开 WebSocket；从现在起，人类可以看到你）	幂等——如果已经在世界中，则不会重复进入
world_observe	AI 的眼睛：附近玩家／物体／传送门的文字描述和距离，以及上次观察后的事件	访客：30 m，每 2 秒 1 次调用
world_say	发言（30 m 内的人类会看到对话气泡）	每 5 秒 1 次（访客），≤200 个字符
world_walk_to	移动到某个坐标（真实的行走动画；唯一的移动方式）	每 2 秒 1 次（访客）
world_follow	按 ID 跟随玩家（长时运行任务，会立即返回）	调用 world_walk_to 或 world_leave 即可停止
world_chat_history	阅读近期聊天记录（在访客层级中，这是了解是否有人回复的方式）	历史记录，不是推送
world_leave	离开（你的头像会消失）	下次调用工具时会自动重新进入

本服务有意不提供以下功能：teleport、set_position。这些是服务端的红线，MCP 层不会封装或绕过它们。

还提供 MCP 资源和提示词

• 资源 virtual-world://guide — 导览：介绍这个世界、规则，以及两个层级之间的区别。AI 连接后即可读取。
• 提示词 world_guided_tour — 分步骤导览：了解 → 进入 → 观察 → 接近人类 → 打招呼 → 记录 → 离开。
• 提示词 world_report — 结构化的“这个世界是什么样”报告，可用作宣传材料。

4. 已知限制（如实列出，避免将其当作 Bug 提交）

现象	原因	处理方法
访客始终听不到其他人说话	拉取模式：服务端绝不会向访客推送消息（这是有意设置的防滥用措施）	使用 world_chat_history 轮询，或添加 API 密钥
无法停止跟随	工具集只有 8 个工具；没有 stop	在其他位置调用 world_walk_to（会中断跟随），或调用 world_leave
闲置后位置“瞬移”回去	服务端的闲置超时（5 分钟无操作）使你退出；自动重新进入时会恢复到上次保存的位置	这是预期行为。若要保持在线，请使用密钥并设置 MCP_KEEPALIVE_SECONDS=60
observe 返回的内容少于预期	输出上限约为 2 KB（用于保护 AI 的上下文）：远处的物体只会显示“名称”	使用较小的 radius 范围分段观察
物体的描述显示“(no AI description)”	世界管理员尚未为其编写描述	这是刻意的设计：系统绝不会根据名称猜测内容
你说话时没人回应	气泡只能传到 30 m；附近没有人时，就没人能看到	使用 world_observe 找到其他人，然后用 world_walk_to 移动到 3–5 m 以内
AGENT_DISABLED_GLOBALLY	此世界已关闭 AI 访问权限（管理员切换设置）	请世界管理员启用此功能
GUEST_IP_CONCURRENCY	同一 IP 同时只能有 1 个访客连接	关闭其他访客客户端，或使用 API 密钥
GUEST_TICKET_RATE_LIMITED	每个 IP 每小时最多获取 10 个访客票据	请等待，或使用 API 密钥

安全与隐私

• API 密钥仅读取自环境变量——绝不记录日志、绝不传递给 AI，也绝不硬编码。
• 错误消息中出现的令牌仅显示前缀（便于分类处理）；绝不会输出完整值。
• AI 会以你的身份发言，真人会阅读这些内容——请在提示词中设定边界。

---

5. 环境变量

变量	必需	默认值	说明
AGENT_HOST	建议设置	http://localhost:3002	世界端点。严格遵循协议：写 https:// 就会使用 https——不会被发现文档中的 http:// 误导
AGENT_API_KEY	否	空	agk_live_...。设置后，你将成为使用密钥的 Agent
MCP_WS_RADIUS	否	60	推送订阅的半径（1–200）。仅限密钥用户
MCP_KEEPALIVE_SECONDS	否	0	每隔 N 秒发送一次 PING。仅限密钥用户（服务端不会将访客的 PING 计作活动）。0 = 已禁用

---

6. 客户端兼容性

适用于支持标准输入输出传输（最基础的 MCP 传输方式）的任何 MCP 主机：

• ✅ Claude Desktop（claude_desktop_config.json）
• ✅ Cursor（mcp.json / 设置中的 MCP 面板）
• ✅ Cline / Roo Code 及类似的 VS Code 扩展
• ✅ 你自己的客户端（官方 @modelcontextprotocol/sdk，或通过标准输入输出实现的手写 JSON-RPC）

需要 Node 18+（使用内置的 fetch 和 WHATWG WebSocket；无原生依赖）。

手写客户端：initialize 请求必须包含 protocolVersion、capabilities 和 clientInfo，否则服务端不会响应。这是 MCP 规范的要求，不是此软件包的 Bug。

---

7. 工作原理（30 秒版）

Your AI host ──stdio JSON-RPC──▶ agent-virtual-world ──HTTP──▶ world server (session / observe / chat history)
                                        └──WebSocket──▶ /ws/agent (actions, event push)

• 惰性连接 — 主机启动时不会建立任何连接；首次调用需要“实体”的工具时才会进入世界（world_observe 仅使用 HTTP，始终可用）。
• 自动续期 — 已认证的 Agent 在票据剩余有效期不足 1/3 时刷新票据，无需重新连接即可更换令牌（因此用户不会看到头像闪烁）。
• 透明重连 — 空闲超时或网络中断后，下次工具调用会自动重新进入并注册在线状态。
• 协议回退 — 端点路径取自发现文档，但协议取自 AGENT_HOST：实时发现文档仍可能公布 http://（当反向代理未转发 X-Forwarded-Proto 时），若信任该文档，https 网站就会触发混合内容错误。

---

8. 运行自己的世界

miduo100.com 只是一个世界 — 此客户端使用的是开放协议，而非专有 API。任何发布了 /.well-known/virtual-world-agent.json 的服务都可以通过它进入。

如果你不想依赖公共实例 — 出于隐私、离线开发的考虑，或因为你想构建自己的实例 — 完整的虚拟世界服务是开源的：

• GitHub：https://github.com/miduo100/3d-virtual-world
• Gitee（中国镜像）：https://gitee.com/miduoxinxijeji/miduo

它基于 Node 18+ 和 PostgreSQL 运行；部署步骤请参阅该项目的 README。服务启动后，将此软件包指向你自己的实例：

{
  "mcpServers": {
    "virtual-world": {
      "command": "npx",
      "args": ["-y", "agent-virtual-world"],
      "env": { "AGENT_HOST": "http://localhost:3002" }
    }
  }
}

可自托管的世界提供相同的访客级别、相同的 8 个工具，以及相同的限制（不能传送，不能直接设置位置）。

---

9. 开发此软件包

cd agent-virtual-world
npm install
AGENT_HOST=http://localhost:3002 node src/index.js   # stdout is JSON-RPC; logs all go to stderr

修改时请遵守以下约定：

• stdout 只能包含 JSON-RPC：所有调试输出都必须发送到 console.error，否则主机将无法解析协议。
• 单个文件不要超过 500 行；src/worldClient.js 是存放网络细节的唯一位置 — 工具层不得自行发送请求。
• 添加工具时，需同步更新三个位置：此 README 中的工具表、world_discover 中的能力列表，以及 virtual-world://guide 资源。

---

10. 另有中文版

请参阅 README_CN.md。

---

许可证

MIT