eco-mcp-app

一个用于 Eco via Sirens 游戏服务器的 Claude Desktop 内嵌小部件 [1]。只需问 Claude “Eco 服务器现在怎么样了？”，你就能获得一张实时卡片：包含陨石倒计时、在线/总玩家数、动植物信息、世界大小、法律、经济状况以及 Discord 加入链接。 无需截图，无需切换标签页。

这也是一个技术演示——一个极简的、手写的 MCP 应用实现 [2]，没有使用打包工具或 React，整个 iframe 仅为一个 300 行的 HTML 文件。对于那些希望使用 Python 而非默认的 TypeScript/ext-apps [3] 技术栈来构建 MCP 应用的开发者来说，这是一个很好的参考。

渲染内容

┌─ Eco via Sirens ─────────── Established · day 2 · HighCollaboration · Slow ─ ● online ─┐
│                                                                                       │
│  DAYS UNTIL METEOR ☄                                          ┌─────┐                  │
│  57 days                                                      │ 57  │  (cycle ring,   │
│  Server running for 2 days · 5% through the cycle             │ left│  fills as days  │
│                                                               └─────┘   tick down)    │
│                                                                                       │
│  ┌ Players online ┐ ┌ World       ┐ ┌ Cycle progress  ┐ ┌ Economy & culture ┐        │
│  │ 7 / 67         │ │ 0.52 km²    │ │ day 2           │ │ 473 trades,       │        │
│  │ peak 38        │ │ 96k plants  │ │ 57d until ☄     │ │   0 contracts     │        │
│  │ ░░░░█░░░░░░░░░ │ │ 0 animals   │ │ ██░░░░░░░░░░░░░ │ │ 171.0 culture     │        │
│  └────────────────┘ └─────────────┘ └─────────────────┘ └───────────────────┘        │
│                                                                                       │
│  [v 0.13.0.2] [English] [open] [admin online]         Fetched 4:12 PM · [Join Discord]│
└───────────────────────────────────────────────────────────────────────────────────────┘

          · · · .        ·     .                 . ·
     .        ·   .    *   .          ·   . (animated starfield, twinkling)
       *              .         *                 ·
                                                         ☄ (meteor, floats)
                                                       ↙
                                                     ↙

Related MCP server: MCP Quickstart Weather Server

工作原理

该服务器 (src/eco_mcp_app/server.py) 暴露了一个工具 get_eco_server_status，它会访问 http://eco.coilysiren.me:3001/info（Eco [4] 服务器默认暴露的公共 /info 端点），对玩家名称进行脱敏处理，并返回两个内容块：一个用于纯文本主机的 Markdown 回退内容，以及一个用于 iframe 的 JSON 有效载荷。该工具的 _meta.ui.resourceUri 指向 ui://eco/status.html，即作为资源注册的 iframe HTML。

该 iframe (src/eco_mcp_app/ui/eco.html) 是纯 HTML/CSS/JS——没有构建步骤，没有打包工具，也没有 React。它按照规范 [5] 手动实现了 MCP 应用的初始化握手：

1. Iframe → 主机：ui/initialize（请求，包含 protocolVersion: 2026-01-26）

2. 主机 → Iframe：初始化结果

3. Iframe → 主机：ui/notifications/initialized（通知）

4. 主机 → Iframe：每当匹配的工具触发时发送 ui/notifications/tool-result

握手过程仅约 30 行代码。ext-apps SDK [3] 功能更丰富（自动调整大小、能力协商），但对于只读仪表盘来说，我们不需要这些——而且将其写出来能让规范更易读。

另请参阅

此仓库位于一个小型的 Eco 生态系统旁边：eco-cycle-prep [6] 负责每个周期的设置（世界生成、Discord 公告、模组同步）；eco-agent [7] 是该服务器早期的 FastAPI 配套服务；eco-mods-public [8] 是存放游戏模组的地方。服务器基础设施定义在 infrastructure [9] 中（k3s + pyinvoke + external-secrets + Traefik）。Eco 标准参考资料：ModKit [10]、模组文档 [11]、Eco Wiki 模组页面 [12]、Discord 桥接插件 [13] 以及模组目录 [14]。

安装（本地，Claude Desktop）

Claude Desktop 仅在启动时加载 MCP，因此请安装并重启：

cd /Users/kai/projects/coilysiren/eco-mcp-app
uv sync
python scripts/install-desktop-config.py

然后完全退出 Claude Desktop (⌘Q) 并重新启动。在新的对话中：

Use eco-mcp-app to show me the Eco server status.

你应该能看到内嵌的陨石卡片。

部署（家庭实验室）

长期目标是部署在已经托管 eco-agent 的同一个 k3s 集群上的 eco-mcp.coilysiren.me。模式与 infrastructure [9] 保持一致：

• 构建 Docker 镜像（Dockerfile 待办）

• deploy/ 中的清单（Deployment, Service, Ingress, 通过 cert-manager 实现 TLS，基础设施仓库中已有 ClusterIssuer）

• 无需密钥——/info 端点是公开的；服务器运行无需环境变量

基于 HTTP 的 MCP 带来了其特有的规范陷阱（会话 ID 分割和资源注册范围，在 ext-apps#481 中跟踪），因此初始部署很可能与 stdio 二进制文件相同，通过 MCP SDK 的 HTTP 传输封装为 Streamable-HTTP 服务器——这是后续周期要解决的问题。

冒烟测试

整个 MCP → iframe → 渲染流程可以通过 stdio 在没有 Claude 的情况下进行测试：

inv smoke

检查：id=2 上两种形式的 _meta.ui.resourceUri，id=3 上实际大小的 HTML 资源，以及 id=4 上带有 "view":"eco_status" 的 JSON 有效载荷。

开发工具（无需重启 Claude 即可迭代 iframe）

dev/harness.html 是一个极简的 HTML 页面，模拟了 Claude Desktop 的 MCP 应用主机，以便在普通浏览器中开发 iframe——无需每次修改都执行 ⌘Q / 重启循环。该工具：

1. 将 src/eco_mcp_app/ui/eco.html 加载为 iframe (visibility: hidden)。

2. 监听来自 iframe 的 ui/initialize 并以有效的 McpUiInitializeResult（protocolVersion, hostInfo, hostCapabilities, hostContext）进行响应。

3. 在 ui/notifications/initialized 时显示 iframe。

4. 监听 ui/notifications/size-changed 并将报告的 {width, height} 应用于 iframe.style.height。这是 Claude Desktop 实际使用的机制——而不是 claude-ai-mcp#69 所描述的 documentElement.height 读取方式。

5. 显示后，推送一个预设的 ui/notifications/tool-result 以及模拟的 Eco /info 有效载荷，以便触发 render()。

运行命令：

inv harness
# then open http://localhost:8765/dev/harness.html

工具顶部的状态栏显示最后一次 size-changed 的值，这样你可以看到 iframe 是否在通知主机调整大小。如果它一直显示“Loading…”，要么是握手失败，要么是 iframe 的脚本在到达 connect() 之前抛出了错误——请检查 DevTools 控制台。

该工具也可以通过 .claude/launch.json 中的 eco-harness 条目在 Claude Code 的预览面板中使用。

MCP 应用——构建过程中学到的非显而易见的事项

• _meta.ui.resourceUri 必须在嵌套 (ui.resourceUri) 和扁平 (ui/resourceUri) 两种形式中都进行设置——有些主机只支持其中一种 [15]。

• MIME 类型必须严格为 text/html;profile=mcp-app；普通的 text/html 不会触发 MCP 应用渲染。

• 如果没有客户端 JS 运行握手，Claude Desktop 会正确地将 iframe 容器保持在 visibility: hidden 状态。这意味着无脚本的测试 HTML 不是有效的隔离测试——它看起来会和损坏的应用一模一样 [16]。

• Claude Desktop 的沙箱 iframe 强制执行硬编码的 CSP，该 CSP 会忽略 _meta.ui.csp 扩展 [17]。外部图像源会被阻止。如果你需要缩略图，请在服务器端将其内联为 data:image/...;base64,... URI——这些始终是被允许的。

• 只有 Claude Desktop 聊天 UI (clientInfo.name = "claude-ai") 会声明 io.modelcontextprotocol/ui 扩展能力。Claude Code Desktop 的代理工具 (clientInfo.name = "local-agent-mode-*") 不会，因此 iframe 在那里永远不会渲染——请使用其启动预览面板（通过对本地 HTML 文件调用 Write 或 Edit 工具触发）作为回退的内联可视化路径。

许可证

MIT。

参考资料

1. https://www.coilysiren.me/

2. https://modelcontextprotocol.io/docs/concepts/apps

3. https://github.com/modelcontextprotocol/ext-apps

4. https://play.eco/

5. https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx

6. https://github.com/coilysiren/eco-cycle-prep

7. https://github.com/coilysiren/eco-agent

8. https://github.com/coilysiren/eco-mods-public

9. https://github.com/coilysiren/infrastructure

10. https://github.com/StrangeLoopGames/EcoModKit

11. https://docs.play.eco/

12. https://wiki.play.eco/en/Modding

13. https://github.com/Eco-DiscordLink/EcoDiscordPlugin

14. https://mod.io/g/eco

15. https://github.com/anthropics/claude-ai-mcp/issues/71

16. https://github.com/anthropics/claude-ai-mcp/issues/61#issuecomment-4283640203

17. https://github.com/anthropics/claude-ai-mcp/issues/40