Skip to main content
Glama

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

Available Tools

1 tool
get_eco_server_statusEco via Sirens — server statusA

Show the current state of the 'Eco via Sirens' game server inline: online players, meteor countdown, world stats, economy, version. Renders as a visual widget in Claude Desktop chat UI via the MCP Apps spec; falls back to a plain-text summary in hosts that don't render the iframe.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool, there is no possibility of ambiguity or overlap between tools. The tool's purpose is clearly defined and distinct by default.

    Naming Consistency5/5

    The single tool follows a clear verb_noun naming pattern (get_eco_server_status), and with no other tools to compare, consistency is inherently perfect.

    Tool Count2/5

    One tool is too few for a server named 'eco-mcp-app', which suggests a broader scope for managing an 'Eco via Sirens' game server. A single status-check tool feels thin and incomplete for such a domain.

    Completeness2/5

    The tool surface is severely incomplete for the inferred domain of game server management. It only provides status information, with no tools for actions like starting/stopping the server, managing players, configuring settings, or other CRUD operations expected in this context.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A demonstration MCP server for local development and testing with Claude Desktop on WSL. Provides basic utility tools including greeting messages, echo functionality, and server information retrieval.
      3
      MIT
    • F
      license
      B
      quality
      D
      maintenance
      A basic MCP server adapted from the official quickstart guide that provides weather data functionality and works with OpenAI chat completions API. Demonstrates MCP server setup with configuration examples for Claude Desktop and development tools.
      2
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server built with the mcp-framework for developing and managing custom tools. It provides a structured foundation for building and integrating modular components like data processors and API clients into Claude Desktop.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A simple MCP server in Python, configurable via environment variables and database, designed for integration with Claude Desktop.
      -