eco-mcp-app
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)
↙
↙작동 원리
서버(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 앱 초기화 핸드셰이크를 수동으로 구현합니다:
Iframe → 호스트:
ui/initialize(요청,protocolVersion: 2026-01-26포함)호스트 → Iframe: 초기화 결과
Iframe → 호스트:
ui/notifications/initialized(알림)호스트 → 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 이미지 빌드 (
DockerfileTODO)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/재시작할 필요가 없습니다. 하네스 기능:
src/eco_mcp_app/ui/eco.html을 iframe(visibility: hidden)으로 로드합니다.iframe으로부터
ui/initialize를 수신하고 유효한McpUiInitializeResult(protocolVersion, hostInfo, hostCapabilities, hostContext)로 응답합니다.ui/notifications/initialized수신 시 iframe을 표시합니다.ui/notifications/size-changed를 수신하고 보고된{width, height}를iframe.style.height에 적용합니다. 이는 Claude Desktop이 실제로 사용하는 메커니즘입니다. claude-ai-mcp#69에서 설명하는documentElement.height읽기 방식이 아닙니다.표시 후,
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.
참고 문헌
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Tools
Latest Blog Posts
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/coilysiren/eco-mcp-app'
If you have feedback or need assistance with the MCP directory API, please join our Discord server