eco-mcp-app

Eco via Sirens 게임 서버 [1]를 위한 인라인 Claude Desktop 위젯입니다. Claude에게 "Eco 서버 상태가 어때?"라고 물어보면 운석 카운트다운, 온라인/전체 플레이어 수, 동식물 정보, 세계 크기, 법률, 경제, Discord CTA 등이 포함된 실시간 카드를 받을 수 있습니다. 스크린샷을 찍거나 탭을 전환할 필요가 없습니다.

이 프로젝트는 기술 데모이기도 합니다. 번들러나 React 없이 수작업으로 구현한 최소한의 MCP 앱 [2]으로, 전체 iframe이 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)는 get_eco_server_status라는 하나의 도구를 노출합니다. 이 도구는 http://eco.coilysiren.me:3001/info(Eco [4] 서버가 기본적으로 노출하는 공개 /info 엔드포인트)에 접속하여 플레이어 이름을 가리고, 텍스트 전용 호스트를 위한 마크다운 폴백과 iframe을 위한 JSON 페이로드라는 두 가지 콘텐츠 블록을 반환합니다. 도구의 _meta.ui.resourceUri는 리소스로 등록된 iframe HTML인 ui://eco/status.html을 가리킵니다.

iframe(src/eco_mcp_app/ui/eco.html)은 순수 HTML/CSS/JS로 작성되었으며, 빌드 단계나 번들러, React가 필요 없습니다. 사양 [5]에 따라 MCP 앱 초기화 핸드셰이크를 수동으로 구현합니다:

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 공지, 모드 동기화)을 실행하고, 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)하고 다시 실행하세요. 새로운 채팅에서:

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, infra 저장소에 이미 있는 ClusterIssuer)

• 비밀 정보 불필요 — /info 엔드포인트는 공개되어 있으며, 서버는 환경 변수 없이 실행됩니다.

HTTP 기반 MCP는 고유한 사양 문제(세션 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 앱 호스트를 모방하는 최소한의 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. 표시 후, render()가 실행되도록 모의 Eco /info 페이로드가 포함된 ui/notifications/tool-result를 푸시합니다.

다음 명령으로 실행하세요:

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

하네스 상단의 상태 표시줄은 마지막 size-changed 값을 보여주므로 iframe이 호스트에 크기 조정을 요청하고 있는지 확인할 수 있습니다. 계속 "Loading…"이라고 표시된다면 핸드셰이크가 실패했거나 connect()에 도달하기 전에 iframe 스크립트에서 오류가 발생한 것이므로 DevTools 콘솔을 확인하세요.

이 하네스는 .claude/launch.json의 eco-harness 항목을 통해 Claude Code의 Preview 패널에서도 사용할 수 있습니다.

MCP 앱 — 개발하며 배운 비직관적인 사실들

• _meta.ui.resourceUri는 중첩된(ui.resourceUri) 형식과 평면(ui/resourceUri) 형식 모두에 설정되어야 합니다. 일부 호스트는 하나만 인식합니다 [15].

• MIME 타입은 정확히 text/html;profile=mcp-app이어야 합니다. 일반 text/html은 MCP 앱 렌더링을 트리거하지 않습니다.

• 클라이언트 측 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이 거기서는 렌더링되지 않습니다. 로컬 HTML 파일에 대한 Write 또는 Edit 도구 호출로 트리거되는 Launch 미리보기 패널을 대체 인라인 시각화 경로로 사용하세요.

라이선스

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