Skip to main content
Glama
deenjakoruzh
coilysiren

eco-mcp-app

by coilysiren
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

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)
                                                       ↙
                                                     ↙

工作原理

该服务器 (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

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - A tier

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/coilysiren/eco-mcp-app'

If you have feedback or need assistance with the MCP directory API, please join our Discord server