mcp-apps-arcade

🚀 示例：街机服务器

这是一个 MCP Apps 服务器，可让你在支持 MCP 的主机中直接浏览并游玩来自 archive.org 的经典街机游戏。

🚀 快速开始

npm install
npm run dev

服务器默认在 http://localhost:3002/mcp 启动。你可以通过设置 PORT 环境变量来更改端口。

MCP 客户端配置

{
  "mcpServers": {
    "arcade": {
      "url": "http://localhost:3002/mcp"
    }
  }
}

✨ 主要特性

• 可在 MCP 主机中直接浏览和游玩来自 archive.org 的经典街机游戏。
• 采用严格的游戏版权验证系统，仅允许加载有合法分发权的游戏。
• 利用服务器端处理绕过浏览器安全限制，确保游戏正常加载。

📦 安装指南

npm install
npm run dev

💻 使用示例

基础用法

启动服务器：

npm install
npm run dev

高级用法

若要更改服务器端口，可设置 PORT 环境变量：

PORT=3003 npm run dev

📚 详细文档

法律声明

这是一个技术演示，并非分发平台。

• 游戏在运行时直接从 archive.org 的嵌入系统获取。
• 我们不托管、分发或存储游戏内容。
• 仅允许加载具有合法分发权的游戏。
• 无合法分发权的游戏将被阻止。

版权验证机制

服务器采用严格的验证系统：

1. 精选白名单：allowlist.ts 中的游戏具有外部记录的分发权，包含来源 URL（发行商公告、官方网站），每个条目都有法律依据。
2. 元数据验证：对于不在白名单中的游戏，我们会检查 archive.org 的元数据，以确定是否有明确的版权指标（共享软件、免费软件、公共领域、知识共享许可）。

只有具有合法版权的游戏才被允许加载，未知或受限的游戏将被阻止。

可用游戏类型

• 共享软件：明确免费发布的第一集/演示版游戏（如《毁灭战士》《毁灭公爵》《指挥官基恩》《德军总部 3D》等）。
• 免费软件：由发行商正式免费发布的游戏（如《泰瑞安 2000》《丛林女孩吉尔》）。
• 公共领域：版权已过期或被放弃的游戏。

完整的游戏列表及法律文档请见 allowlist.ts。

模拟器运行时

archive.org 使用 Emularity 系统在浏览器中运行游戏，包括： | 模拟器 | 许可证 | 适用游戏 | | ---- | ---- | ---- | | DOSBox | GPL - 2.0+ | DOS 游戏 | | EM - DOSBox | GPL - 2.0+ | 通过 Emscripten 编译为 JavaScript 的 DOSBox | | MAME | BSD - 3 - Clause / GPL - 2.0+ | 街机游戏 |

我们与这些模拟器的关系：

• 我们不分发、捆绑或修改任何模拟器代码。
• 模拟器在运行时直接从 archive.org 获取。
• 我们仅代理 archive.org 的嵌入系统，该系统托管了这些模拟器的副本。
• 临时内存缓存（见下文）仅用于解决 CORS 问题。

许可证兼容性说明： MCP Apps SDK 采用 Apache - 2.0 许可证，不存在许可证冲突，原因如下：

1. 街机服务器不捆绑、包含或链接 GPL 模拟器代码。
2. 模拟器在运行时从 archive.org 获取（类似于加载任何 CDN 资源）。
3. 模拟器在用户浏览器中执行，是一个独立的执行上下文。
4. 这类似于嵌入 YouTube 视频，嵌入页面并非 YouTube 播放器的衍生作品。

如果你创建了一个修改版本并捆绑了模拟器代码到分发版本中，则必须遵守 GPL - 2.0+ 条款（版权共享、源代码可用性）。

脚本重新托管（CORS 解决方案）

服务器仅在内存中临时缓存 archive.org 的 emulation.min.js 脚本（不持久化到磁盘），以绕过沙盒 iframe 中的浏览器安全限制。这是技术上的必要操作，并非重新分发：

• 缓存使用 Cache - Control: no - store 头。
• 服务器重启时缓存将被清除。
• 首次请求时从 archive.org 重新获取脚本。
• 除了将 import() 替换为 loadScript() 以实现 iframe 兼容性外，不做其他修改。

添加新游戏

若要将游戏添加到白名单，你必须提供：

1. sourceUrl：指向记录分发权的权威来源的链接（发行商网站、新闻稿、官方公告）。
2. legalBasis：明确说明游戏合法分发的原因。
3. 验证：确认 archive.org 标识符可用。

如有疑问，请勿添加该游戏。

概述

此示例展示了将外部 HTML 内容作为 MCP App 资源进行服务。该资源是一个静态加载器，使用 MCP Apps 协议接收工具参数，然后从服务器端点获取处理后的游戏 HTML。这种模式允许同一资源根据工具输入显示不同的游戏。

关键技术：

• MCP Apps 协议握手（ui/initialize → ui/notifications/tool - input）以动态接收游戏 ID。
• 服务器端根据游戏 ID 获取和处理 HTML。
• <base href> 标签用于解析相对于 archive.org 的相对 URL。
• baseUriDomains CSP 元数据以允许使用 <base> 标签。
• 将 ES 模块 import() 重写为经典的 <script src> 加载方式（以实现 srcdoc iframe 兼容性）。
• 本地脚本端点以绕过沙盒 iframe 中的 CORS 限制。
• 版权检查：在加载游戏前验证分发权限。

关键文件

• server.ts - 带有工具和资源注册的 MCP 服务器。
• index.ts - HTTP 传输和 Express 设置。
• [game - processor.ts](game - processor.ts) - 获取和处理 archive.org 的 HTML。
• search.ts - 带有智能回退和版权过滤的 archive.org 搜索。
• [rights - checker.ts](rights - checker.ts) - 分析 archive.org 元数据以确定分发权限。
• allowlist.ts - 精选的经过验证的共享软件/免费软件游戏列表。
• types.ts - 版权管理的类型定义。

工具

| 工具 | 描述 | UI | | ---- | ---- | ---- | | search_games | 搜索经过验证的共享软件/免费软件游戏 | 否 | | get_game_by_id | 加载并游玩具有合法分发权的游戏 | 是 |

search_games 参数

| 参数 | 类型 | 默认值 | 描述 | | ---- | ---- | ---- | ---- | | searchTerm | 字符串 | - | 游戏名称或搜索词 | | maxResults | 数字 | 10 | 最大结果数（1 - 50） |

get_game_by_id 参数

| 参数 | 类型 | 默认值 | 描述 | | ---- | ---- | ---- | ---- | | gameId | 字符串 | - | 游戏的 archive.org 标识符 |

工作原理

1. 主机调用 search_games → 服务器搜索白名单和 archive.org → 仅返回经过验证的游戏。
2. 主机调用 get_game_by_id → 服务器验证版权状态。
3. 如果版权验证通过 → 工具返回成功。
4. 如果版权未验证通过 → 工具返回错误，游戏被阻止。
5. 主机读取资源 → 获取包含 MCP Apps 协议处理程序的静态加载器。
6. 视图与主机执行 ui/initialize 握手。
7. 主机发送包含 gameId 的 tool - input → 视图获取 /game - html/:gameId。
8. 服务器从 archive.org 获取嵌入 HTML 并进行处理：
   - 移除 archive.org 的 <base> 标签。
   - 插入 <base href="https://archive.org/"> 以进行 URL 解析。
   - 将 ES 模块 import() 重写为 <script src> 加载方式。
   - 获取 emulation.min.js，进行修补，并从本地端点提供服务。
   - 插入布局 CSS 以实现全视口显示。
9. 游戏运行：模拟器加载 ROM，初始化 MAME，游戏可玩。

为什么要进行处理？

archive.org 的游戏嵌入页面使用 ES 模块 import() 来加载仿真引擎。在 srcdoc iframe（由 MCP 主机使用）中，import() 会失败，因为 iframe 的源为 null。服务器通过以下方式解决此问题：

1. 服务器端获取 emulation.min.js 并将 import() 替换为 window.loadScript()。
2. 从本地 Express 端点（/scripts/emulation.js）提供修补后的脚本。
3. 使用 <script src>，它不受 CORS 限制，不像 fetch() 或 import()。

可用游戏（18 款经过验证的游戏）

所有游戏都具有经过验证的分发权。完整的法律文档请见 allowlist.ts。

id Software 共享软件

| 标识符 | 游戏名称 | 年份 | | ---- | ---- | ---- | | doom - play | 《毁灭战士》 | 1993 | | msdos_DOOM_1993 | 《毁灭战士》（MS - DOS 版） | 1993 | | wolfenstein - 3d | 《德军总部 3D》 | 1992 | | w3d - box | 《德军总部 3D》v1.4 | 1993 | | commander_keen_volume_one_131 | 《指挥官基恩：被困火星》 | 1990 | | heretic - dos | 《异教徒》 | 1994 |

Apogee / 3D Realms 共享软件

| 标识符 | 游戏名称 | 年份 | | ---- | ---- | ---- | | duke - nukem2 - sw | 《毁灭公爵 II》 | 1993 | | 3dduke13SW - altcontrols | 《毁灭公爵 3D》 | 1996 | | Bs - aog - sw1 | 《布莱克·斯通：黄金外星人》 | 1993 | | rise - of - the - triad - the - hunt - begins - version - 1.0 | 《三合会崛起》 | 1994 | | biomenace1 - sw | 《生化威胁》 | 1993 | | Crystal - cave - sw1 | 《水晶洞穴》 | 1991 | | monster - bash1 - sw | 《怪物狂欢》 | 1993 | | halloween_harry_shareware | 《万圣节哈利》 | 1993 |

Epic MegaGames 共享软件/免费软件

| 标识符 | 游戏名称 | 年份 | | ---- | ---- | ---- | | Epic - pinball - sw1 | 《史诗弹珠台》 | 1993 | | radsw20 | 《雷迪克斯：超越虚空》 | 1995 | | msdos_Tyrian_2000_1999 | 《泰瑞安 2000》（免费软件） | 1999 | | jill - of - the - jungle - 0mhz | 《丛林女孩吉尔》（免费软件） | 1992 |