coilyco-flight-deck/eco-mcp-app

Fork 0

Inline Claude Desktop widget for any public Eco game server — live player counts, meteor countdown, world stats. A hand-rolled MCP Apps reference implementation in Python (no bundler, no React).

claude-desktop-eco-widget mcp-apps-reference-implementation

Python 81.7%
HTML 11.6%
CSS 5.8%
Makefile 0.8%

Find a file

Kai Siren a544773821 Some checks are pending build-publish / build-publish (push) Waiting to run Details TruffleHog / Scan for secrets (push) Waiting to run Details chore(pre-commit): adopt context-load-points hooks (v0.11.1) Part of the agentic-os-kai#505 load-point framework rollout. closes coilysiren/eco-mcp-app#28 Audit-log: coily://1780119172/AGPHOXXX - coily git commit		2026-05-30 10:13:05 -07:00
.agents/skills/eco-mcp-app	chore(skills): add canonical repo-pointer SKILL.md (closes #21 )	2026-05-27 02:17:26 -07:00
.claude	lockdown: sync to coily v2.45.0 [skip ci]	2026-05-28 09:28:06 +00:00
.coily	chore(catalog): scheme-less dependsOn URLs, drop providesApis	2026-05-27 21:46:57 -07:00
.gauntlet/trials	add: gauntlet trials for eco-mcp-app	2026-04-24 19:08:24 -07:00
.github/workflows	ci: drop GHA deploy job, build and publish only	2026-05-30 10:13:03 -07:00
data	feat: pre-fetch ecopedia + species caches as committed JSON	2026-04-21 13:33:58 -07:00
deploy	feat(deploy): in-Pod tailscale sidecar replaces operator ts-proxy	2026-05-20 00:47:44 -07:00
docs	chore: trim README + AGENTS + FEATURES under cap	2026-05-16 00:11:39 -07:00
investigation	investigation: log the audience=user widget-empty-placeholder bug	2026-04-27 22:13:38 -07:00
scripts	chore: adopt coilysiren/agentic-os v0.2.1 upstream-ref pre-commit suite	2026-05-15 23:30:04 -07:00
src/eco_mcp_app	climate: parse parallel-array dataset payloads (closes #34 )	2026-05-10 16:06:30 -07:00
static	chore: rename dev/ to static/, drop issue 61 reply draft	2026-04-20 19:09:37 -07:00
tests	test(map): mock Pollution.gif endpoint to fix respx drift	2026-05-30 10:13:02 -07:00
.agentic-os.toml	chore(catalog): scheme-less dependsOn URLs, drop providesApis	2026-05-27 21:46:57 -07:00
.dockerignore	feat: homelab deploy rig + HTTP transport + point at any public Eco server	2026-04-20 19:30:38 -07:00
.gitignore	Migrate pyinvoke -> Makefile + coily	2026-05-09 16:58:50 -07:00
.pre-commit-config.yaml	chore(pre-commit): adopt context-load-points hooks (v0.11.1)	2026-05-30 10:13:05 -07:00
AGENTS.md	ci: drop GHA deploy job, build and publish only	2026-05-30 10:13:03 -07:00
CLAUDE.md	Convert CLAUDE.md symlink to @AGENTS.md import	2026-04-23 13:35:39 -07:00
coily.yaml	deploy: rename config.yml to coily.yaml	2026-05-13 22:50:24 -07:00
Dockerfile	Drop requirements.txt, use uv.lock directly in Docker	2026-05-14 06:22:26 -07:00
LICENSE	feat: initial eco-mcp-app scaffold	2026-04-20 17:07:10 -07:00
Makefile	Drop requirements.txt, use uv.lock directly in Docker	2026-05-14 06:22:26 -07:00
pyproject.toml	Migrate pyinvoke -> Makefile + coily	2026-05-09 16:58:50 -07:00
README.md	chore: trim README + AGENTS + FEATURES under cap	2026-05-16 00:11:39 -07:00
uv.lock	Migrate pyinvoke -> Makefile + coily	2026-05-09 16:58:50 -07:00

README.md

_{Banner: Steam header for Eco by Strange Loop Games. Attribution use, not my artwork.}

eco-mcp-app

An inline Claude Desktop widget for any public Eco game server [1]. Point at the "Eco via Sirens" [2] server (default) or any other Eco server by IP/hostname. Ask Claude "what's the Eco server doing?" and you get a live card: meteor countdown, online/total, world size, laws, economy, Discord CTA, Steam link.

Also a tech demo - a minimal, hand-rolled MCP Apps implementation [3] without a bundler or React. Whole iframe is one 300-line HTML file. Useful as a reference for building an MCP App in Python rather than the TypeScript/ext-apps [4] stack.

_{Live at eco-mcp.coilysiren.me/preview.}

How it works

src/eco_mcp_app/server.py exposes tools that hit Eco's public /info endpoint and admin exporters, redact player names, and return content blocks: markdown fallback for text-only hosts + JSON for the iframe. The tool's _meta.ui.resourceUri points at ui://eco/status.html, registered as an MCP resource.

The iframe (src/eco_mcp_app/ui/eco.html) is plain HTML/CSS/JS - no build step. Hand-rolls the MCP Apps handshake per spec [5]:

Iframe → host: ui/initialize (with protocolVersion: 2026-01-26)
Host → iframe: initialize result
Iframe → host: ui/notifications/initialized
Host → iframe: ui/notifications/tool-result whenever a matching tool fires

The handshake is ~30 lines. The ext-apps SDK [4] does more, but for a read-only dashboard we don't need it.

Tools

See docs/FEATURES.md for the full inventory. Headliner: get_eco_server_status. Plus tools for economy, world map, milestones, species, items, crafting, fair-price, ecoregions, government, climate. All accept an optional server arg (host, host:port, full URL).

Quick start

uv sync --group dev
coily smoke      # stdio test of all tools
coily http       # HTTP transport on :4000
coily harness    # browser dev harness on :8765

Add to Claude Desktop:

coily install-desktop

Deploy

Cloned from coilysiren/backend template. Dockerfile + deploy/main.yml (k3s) + .github/workflows/build-and-publish.yml. Target: https://eco-mcp.coilysiren.me/mcp/.

License & credits

MIT. Eco is a trademark of Strange Loop Games [1]; unofficial fan tool, not affiliated.