eco-mcp-app

Встроенный виджет Claude Desktop для игрового сервера Eco via Sirens [1]. Спросите Claude: «что происходит на сервере Eco?», и вы получите живую карточку: обратный отсчет до метеорита, количество игроков (онлайн/всего), растения и животные, размер мира, законы, экономика, призыв к действию в Discord. Никаких скриншотов, никакого переключения вкладок.

Это также техническая демонстрация — минимальная, написанная вручную реализация MCP Apps [2] без сборщика или React, поэтому весь iframe представляет собой один HTML-файл на 300 строк. Полезно в качестве справочного материала для всех, кто создает MCP-приложение на Python, а не на стандартном стеке TypeScript/ext-apps [3].

Что он отображает

┌─ 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 (публичная конечная точка /info, которую серверы Eco [4] предоставляют по умолчанию), скрывает имена игроков и возвращает два блока контента: markdown-резервную копию для текстовых клиентов и JSON-полезную нагрузку для iframe. _meta.ui.resourceUri инструмента указывает на ui://eco/status.html, который является HTML-файлом iframe, зарегистрированным как ресурс.

Iframe (src/eco_mcp_app/ui/eco.html) — это простой HTML/CSS/JS — без этапа сборки, без сборщика, без React. Он вручную выполняет рукопожатие инициализации MCP Apps согласно спецификации [5]:

1. Iframe → хост: ui/initialize (запрос с protocolVersion: 2026-01-26)

2. Хост → iframe: результат инициализации

3. Iframe → хост: ui/notifications/initialized (уведомление)

4. Хост → iframe: ui/notifications/tool-result при каждом срабатывании соответствующего инструмента

Рукопожатие занимает около 30 строк. SDK ext-apps [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 [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) и перезапустите его. В новом чате:

Используй eco-mcp-app, чтобы показать мне статус сервера Eco.

Вы должны увидеть карточку метеорита прямо в чате.

Развертывание (homelab)

Долгосрочная цель — eco-mcp.coilysiren.me в том же кластере k3s, который уже размещает eco-agent. Шаблон не изменился по сравнению с infrastructure [9]:

• Сборка образа Docker (Dockerfile TODO)

• Манифесты в deploy/ (Deployment, Service, Ingress, TLS через cert-manager, ClusterIssuer уже в репозитории инфраструктуры)

• Секреты не нужны — конечная точка /info публична; сервер работает без переменных окружения

MCP-over-HTTP имеет свои подводные камни спецификации (разделение session-id и область регистрации ресурсов, отслеживается выше по потоку в ext-apps#481), поэтому первоначальное развертывание, вероятно, будет тем же stdio-бинарником, обернутым как Streamable-HTTP сервер через транспорт HTTP SDK mcp — это проблема следующего цикла.

Дымовое тестирование

Весь поток MCP → iframe → рендеринг можно протестировать через stdio без Claude:

inv smoke

Ищите: _meta.ui.resourceUri в обеих формах на id=2, HTML-ресурс реального размера на id=3, и JSON-полезную нагрузку с "view":"eco_status" на id=4.

Инструмент разработки (итерация iframe без перезапуска Claude)

dev/harness.html — это минимальная HTML-страница, имитирующая хост MCP Apps в Claude Desktop, чтобы iframe можно было разрабатывать в обычном браузере — без цикла ⌘Q / перезапуска при каждом изменении. Инструмент:

1. Загружает src/eco_mcp_app/ui/eco.html как iframe (visibility: hidden).

2. Ожидает ui/initialize от iframe и отвечает валидным McpUiInitializeResult (protocolVersion, hostInfo, hostCapabilities, hostContext).

3. По ui/notifications/initialized делает iframe видимым.

4. Ожидает ui/notifications/size-changed и применяет полученные {width, height} к iframe.style.height. Это механизм, который на самом деле использует Claude Desktop — не чтение documentElement.height, которое описывает claude-ai-mcp#69.

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 Code через запись eco-harness в .claude/launch.json.

MCP Apps — неочевидные вещи, которые я узнал при создании этого

• _meta.ui.resourceUri должен быть установлен в обеих формах: вложенной (ui.resourceUri) и плоской (ui/resourceUri) — некоторые хосты поддерживают только одну [15].

• MIME-тип должен быть точно text/html;profile=mcp-app; обычный text/html не запускает рендеринг MCP Apps.

• Без клиентского JS, выполняющего рукопожатие, Claude Desktop корректно оставляет контейнер iframe в состоянии visibility: hidden. Это означает, что тестовый HTML без скриптов не является валидной изоляцией — он будет выглядеть идентично сломанному приложению [16].

• Песочница iframe в Claude Desktop применяет жестко закодированный CSP, который игнорирует расширения _meta.ui.csp [17]. Внешние источники изображений блокируются. Если вам нужны миниатюры, встраивайте их на стороне сервера как URI data:image/...;base64,... — они всегда разрешены.

• Только чат-интерфейс Claude Desktop (clientInfo.name = "claude-ai") объявляет возможность расширения io.modelcontextprotocol/ui. Инструмент агента Claude Code Desktop (clientInfo.name = "local-agent-mode-*") этого не делает, поэтому iframe там никогда не рендерятся — используйте его панель предварительного просмотра (вызываемую вызовом инструмента Write или Edit для локального HTML-файла) в качестве резервного пути для встроенной визуализации.

Лицензия

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