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