Skip to main content
Glama

eco-mcp-app

Eco via Sirensゲームサーバー [1] 用のClaude Desktopインラインウィジェットです。Claudeに「Ecoサーバーの状況はどう?」と尋ねると、メテオのカウントダウン、オンライン/合計プレイヤー数、動植物、ワールドサイズ、法律、経済、Discordへの誘導などが記載されたライブカードが返ってきます。スクリーンショットやタブの切り替えは不要です。

これは技術デモでもあります。バンドラーやReactを使用しない、手書きの最小限のMCP Apps実装 [2] であり、iframe全体が1つの300行のHTMLファイルで構成されています。デフォルトのTypeScript/ext-apps [3] スタックではなく、Pythonで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) は1つのツール get_eco_server_status を公開します。これは http://eco.coilysiren.me:3001/info (Eco [4] サーバーがデフォルトで公開するパブリックな /info エンドポイント) にアクセスし、プレイヤー名を伏せた上で、テキストのみのホスト用のMarkdownフォールバックと、iframe用のJSONペイロードの2つのコンテンツブロックを返します。ツールの _meta.ui.resourceUri は、リソースとして登録されたiframe HTMLである ui://eco/status.html を指しています。

iframe (src/eco_mcp_app/ui/eco.html) はプレーンなHTML/CSS/JSであり、ビルドステップやバンドラー、Reactは使用していません。仕様 [5] に従って、MCP Appsの初期化ハンドシェイクを手動で行います:

  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通知、MOD同期)を実行し、eco-agent [7] は同じサーバー用の初期のFastAPIコンパニオンサービスでした。eco-mods-public [8] はゲームプレイMODが配置されている場所です。サーバーインフラは infrastructure [9] (k3s + pyinvoke + external-secrets + Traefik) で定義されています。Ecoの標準的なリファレンス:ModKit [10]、MODドキュメント [11]、Eco wikiのMODページ [12]、Discordブリッジプラグイン [13]、MODカタログ [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 TODO)

  • deploy/ 内のマニフェスト (Deployment, Service, Ingress, cert-manager経由のTLS, ClusterIssuerはインフラリポジトリに既存)

  • シークレットは不要 — /info エンドポイントはパブリックであり、サーバーは環境変数なしで実行されます

MCP-over-HTTPには独自の仕様上の落とし穴(セッションIDの分割やリソース登録のスコープなど、ext-apps#481で追跡中)があるため、最初のデプロイは、mcp SDKのHTTPトランスポートを介してStreamable-HTTPサーバーとしてラップされたstdioバイナリと同じものになる可能性が高いです。これは後のサイクルの課題です。

スモークテスト

MCP → iframe → レンダリングのフロー全体は、Claudeなしでstdioを介してテスト可能です:

inv smoke

id=2 で両方の形式の _meta.ui.resourceUri、id=3 で実際のサイズのHTMLリソース、id=4 で "view":"eco_status" を含むJSONペイロードを確認してください。

開発ハーネス (Claudeを再起動せずにiframeを反復開発)

dev/harness.html は、Claude DesktopのMCP Appsホストを模倣した最小限のHTMLページであり、通常のブラウザで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. 表示後、モックのEco /info ペイロードを含む ui/notifications/tool-result をプッシュし、render() を実行させます。

実行コマンド:

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

ハーネス上部のステータスバーには、最後に報告された size-changed 値が表示されるため、iframeがホストにリサイズを指示しているかを確認できます。「Loading…」のまま動かない場合は、ハンドシェイクが失敗したか、connect() に到達する前にiframeのスクリプトがエラーをスローしています。DevToolsコンソールを確認してください。

このハーネスは、.claude/launch.json の eco-harness エントリを介してClaude Codeのプレビューパネルからも使用可能です。

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]。

  • Claude Desktopのサンドボックスiframeは、_meta.ui.csp 拡張を無視するハードコードされた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はそこでレンダリングされません。フォールバックのインライン可視化パスとして、Launchプレビューパネル(ローカル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

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.
      -