eco-mcp-app

Ein Inline-Claude-Desktop-Widget für den Eco via Sirens-Spieleserver [1]. Frage Claude einfach: „Was macht der Eco-Server?“ und du erhältst eine Live-Karte: Meteor-Countdown, online/gesamte Spieler, Pflanzen und Tiere, Weltgröße, Gesetze, Wirtschaft, Discord-CTA. Keine Screenshots, kein Tab-Wechsel.

Es ist auch eine Tech-Demo – eine minimale, handgeschriebene MCP-Apps-Implementierung [2] ohne Bundler oder React, sodass das gesamte Iframe eine einzige 300-Zeilen-HTML-Datei ist. Nützlich als Referenz für jeden, der eine MCP-App in Python statt mit dem standardmäßigen TypeScript/ext-apps [3]-Stack baut.

Was es rendert

┌─ 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

Funktionsweise

Der Server (src/eco_mcp_app/server.py) stellt ein Tool bereit, get_eco_server_status, das http://eco.coilysiren.me:3001/info aufruft (den öffentlichen /info-Endpunkt, den Eco [4]-Server standardmäßig bereitstellen), Spielernamen schwärzt und zwei Inhaltsblöcke zurückgibt: ein Markdown-Fallback für reine Text-Hosts und ein JSON-Payload für das Iframe. Das _meta.ui.resourceUri des Tools verweist auf ui://eco/status.html, das als Ressource registrierte Iframe-HTML.

Das Iframe (src/eco_mcp_app/ui/eco.html) ist reines HTML/CSS/JS – kein Build-Schritt, kein Bundler, kein React. Es führt den MCP-Apps-Initialisierungs-Handshake gemäß der Spezifikation [5] manuell aus:

1. Iframe → Host: ui/initialize (Anfrage, mit protocolVersion: 2026-01-26)

2. Host → Iframe: Initialisierungsergebnis

3. Iframe → Host: ui/notifications/initialized (Benachrichtigung)

4. Host → Iframe: ui/notifications/tool-result wann immer ein passendes Tool ausgelöst wird

Der Handshake umfasst ca. 30 Zeilen. Das ext-apps-SDK [3] bietet mehr (automatische Größenanpassung, Fähigkeitsaushandlung), aber für ein schreibgeschütztes Dashboard benötigen wir nichts davon – und das manuelle Schreiben macht die Spezifikation lesbar.

Siehe auch

Dieses Repo befindet sich neben einem kleinen Eco-Ökosystem: eco-cycle-prep [6] führt das Setup pro Zyklus aus (Weltgenerierung, Discord-Ankündigungen, Mod-Sync); eco-agent [7] war ein früherer FastAPI-Begleitdienst für denselben Server; eco-mods-public [8] ist der Ort, an dem die Gameplay-Mods leben. Die Serverinfrastruktur ist in infrastructure [9] definiert (k3s + pyinvoke + external-secrets + Traefik). Kanonische Eco-Referenzen: ModKit [10], Modding-Dokumentation [11], Eco-Wiki-Modding-Seite [12], das Discord-Bridge-Plugin [13] und der Mod-Katalog [14].

Installation (lokal, Claude Desktop)

Claude Desktop lädt MCPs nur beim Start, daher installieren + neu starten:

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

Beende dann Claude Desktop vollständig (⌘Q) und starte es neu. In einem neuen Chat:

Verwende eco-mcp-app, um mir den Eco-Server-Status anzuzeigen.

Du solltest die Meteor-Karte inline erhalten.

Bereitstellung (Homelab)

Das langfristige Ziel ist eco-mcp.coilysiren.me auf demselben k3s-Cluster, der bereits eco-agent hostet. Das Muster ist unverändert gegenüber infrastructure [9]:

• Erstelle ein Docker-Image (Dockerfile TODO)

• Manifeste in deploy/ (Deployment, Service, Ingress, TLS via cert-manager, ClusterIssuer bereits im Infra-Repo)

• Keine Secrets erforderlich – der /info-Endpunkt ist öffentlich; der Server läuft ohne Umgebungsvariablen

MCP-over-HTTP bringt seine eigenen Spezifikations-Fallstricke mit sich (Session-ID-Splits und Registrierungsumfang für Ressourcen, verfolgt in ext-apps#481), daher wird die erste Bereitstellung wahrscheinlich das gleiche stdio-Binärprogramm sein, das als Streamable-HTTP- Server über den HTTP-Transport des MCP-SDKs verpackt ist – das ist ein Problem für einen späteren Zyklus.

Rauchtest

Der gesamte MCP → Iframe → Render-Ablauf ist über stdio ohne Claude testbar:

inv smoke

Suche nach: _meta.ui.resourceUri in beiden Formen bei id=2, einer HTML-Ressource mit tatsächlicher Größe bei id=3 und einem JSON-Payload mit "view":"eco_status" bei id=4.

Entwicklungs-Harness (Iterieren am Iframe ohne Claude-Neustart)

dev/harness.html ist eine minimale HTML-Seite, die den MCP-Apps-Host von Claude Desktop nachahmt, sodass das Iframe in einem normalen Browser entwickelt werden kann – kein ⌘Q / Neustart-Zyklus pro Änderung. Der Harness:

1. Lädt src/eco_mcp_app/ui/eco.html als Iframe (visibility: hidden).

2. Lauscht auf ui/initialize vom Iframe und antwortet mit einem gültigen McpUiInitializeResult (protocolVersion, hostInfo, hostCapabilities, hostContext).

3. Bei ui/notifications/initialized wird das Iframe sichtbar gemacht.

4. Lauscht auf ui/notifications/size-changed und wendet die gemeldeten {width, height} auf iframe.style.height an. Dies ist der Mechanismus, den Claude Desktop tatsächlich verwendet – nicht das documentElement.height-Auslesen, das claude-ai-mcp#69 beschreibt.

5. Nach dem Sichtbarmachen wird ein fertiges ui/notifications/tool-result mit einem Mock-Eco /info-Payload gepusht, damit render() ausgeführt wird.

Führe es aus mit:

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

Die Statusleiste oben im Harness zeigt den letzten size-changed-Wert an, damit du sehen kannst, ob das Iframe den Host zur Größenänderung auffordert. Wenn dort ewig „Loading…“ steht, ist entweder der Handshake fehlgeschlagen oder das Skript des Iframes hat vor dem Erreichen von connect() einen Fehler geworfen – prüfe die DevTools-Konsole.

Der Harness ist auch über das Vorschau-Panel von Claude Code über den eco-harness-Eintrag in .claude/launch.json nutzbar.

MCP-Apps – nicht offensichtliche Dinge, die ich dabei gelernt habe

• _meta.ui.resourceUri muss in beiden verschachtelten (ui.resourceUri) und flachen (ui/resourceUri) Formen gesetzt werden – einige Hosts berücksichtigen nur eine [15].

• Der MIME-Typ muss exakt text/html;profile=mcp-app sein; einfaches text/html löst das Rendern von MCP-Apps nicht aus.

• Ohne clientseitiges JS, das den Handshake ausführt, lässt Claude Desktop den Iframe-Container korrekterweise auf visibility: hidden. Das bedeutet, ein Test-HTML ohne Skript ist keine gültige Isolation – es sieht identisch aus wie eine defekte App [16].

• Das Sandbox-Iframe von Claude Desktop erzwingt eine fest codierte CSP, die _meta.ui.csp-Erweiterungen ignoriert [17]. Externe Bildursprünge werden blockiert. Wenn du Thumbnails benötigst, bette sie serverseitig als data:image/...;base64,... URIs ein – diese sind immer erlaubt.

• Nur die Claude Desktop Chat-UI (clientInfo.name = "claude-ai") bewirbt die io.modelcontextprotocol/ui-Erweiterungsfähigkeit. Der Agent-Harness von Claude Code Desktop (clientInfo.name = "local-agent-mode-*") tut dies nicht, daher rendern Iframes dort nie – verwende dessen Launch-Vorschau-Panel (ausgelöst durch einen Write- oder Edit-Tool-Aufruf auf einer lokalen HTML-Datei) als Fallback-Pfad für die Inline-Visualisierung.

Lizenz

MIT.

Referenzen

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