RomM MCP

romm-mcp 是一个社区维护的模型上下文协议（MCP）服务器，用于通过 RomM 的认证 API 对 RomM 进行有界管理。它与 RomM 项目无关联，未获得其认可，也非由其维护。

该服务器有意比完整的 RomM API 更窄：它为常见的库管理任务提供显式类型化的读写工具，而没有通用的 HTTP 透传或宽泛的管理后门。

状态与兼容性

• 初始发布系列：0.1.x。

• 已针对 RomM 5.1.0 API 契约进行测试。

• 需要 Python 3.12 或更高版本。

• 使用 RomM 客户端 API 令牌（rmm_...）作为 Bearer 凭据。

更高版本的 RomM 可能仍然兼容，但在验证之前不声称已测试。

能力边界

v0.1 中包含：

• 平台与 ROM 发现。

• 受限的 ROM 文本元数据更新（name、name_sort_key、summary）。

• 个人 ROM 状态/评分/完成度属性。

• ROM 笔记。

• 常规集合与集合成员关系。

• 带有显式 RomM 5.1 过滤模式的智能集合。

• 用户可见性与游玩会话读取。

v0.1 中有意排除：

• 通用 API/HTTP 透传。

• ROM 或 ROM 文件删除。

• ROM/文件上传或替换。

• 远程封面/手册获取与资源变更。

• 库扫描、后台任务与批量元数据刷新。

• 平台/系统配置变更。

• 客户端令牌管理。

• 用户、权限组或授权变更。

• 设备/同步变更。

从集合中移除 ROM 只会改变集合成员关系。删除常规集合需要 confirm=true；RomM 还会删除该集合自身托管的封面/资源目录，但此 MCP 绝不会删除 ROM 文件。

有关完整的 26 个工具接口及每个工具的副作用，请参阅 docs/tools.md。

安装

发布版本以不可变的 GitHub Release wheel 形式分发。romm-mcp 目前未发布到 PyPI。

对于 v0.1.0：

uvx --python 3.12 \
  --from https://github.com/X1pheR/romm-mcp/releases/download/v0.1.0/romm_mcp-0.1.0-py3-none-any.whl \
  romm-mcp

每个发布版本都包含 SHA256SUMS。对于固定版本或生产环境使用，请在部署前验证 wheel 摘要，并在支持的情况下，使用其 SHA-256 哈希固定工件 URL。

配置

服务器需要一个存储在文件中的专用 RomM 客户端 API 令牌。令牌值绝不会作为 MCP 工具参数被接受。

ROMM_BASE_URL=https://romm.example.com
ROMM_API_TOKEN_FILE=/path/to/romm-api-token
ROMM_TIMEOUT_SECONDS=15

ROMM_BASE_URL 必须是绝对的 http:// 或 https:// URL。ROMM_TIMEOUT_SECONDS 必须大于 0 且最多为 300 秒。

对于完整的 v0.1 工具集，预期的 RomM 权限范围集为：

me.read
platforms.read
roms.read
roms.write
roms.user.read
roms.user.write
collections.read
collections.write
users.read

users.write、任务执行、平台写入、设备写入和资源写入范围不是 v0.1 所必需的。

MCP 客户端示例

{
  "command": "uvx",
  "args": [
    "--python",
    "3.12",
    "--from",
    "https://github.com/X1pheR/romm-mcp/releases/download/v0.1.0/romm_mcp-0.1.0-py3-none-any.whl",
    "romm-mcp"
  ],
  "env": {
    "ROMM_BASE_URL": "https://romm.example.com",
    "ROMM_API_TOKEN_FILE": "/path/to/romm-api-token",
    "ROMM_TIMEOUT_SECONDS": "15"
  }
}

安全模型

RomM 客户端 API 令牌及其上游权限范围是硬性授权边界。请使用专用令牌，并且只授予你打算暴露的工具所需的权限范围。

MCP 层增加了第二道边界：

• 凭据以文件为后端，并从工具模式中省略。

• 没有通用请求工具。

• 不接受远程封面/手册 URL，从而避免通过此 MCP 进行服务器端资源获取/写入行为。

• 笔记、常规集合和智能集合的删除需要显式的 confirm=true。

• ROM/文件删除、上传、任务执行和授权管理不在工具注册表中。

有关漏洞报告和凭据处理指南，请参阅 SECURITY.md。

开发

uv.lock 是 CI 和发布验证所使用的规范精确依赖解析，而发布的包在 pyproject.toml 中保留兼容的依赖范围。

bash ./scripts/verify.sh

验证脚本创建隔离的 Python 3.12 环境，同步冻结的 uv.lock 解析，编译包，运行测试套件并构建发布 wheel。

上游与许可证

此仓库是 RomM 的独立社区集成。RomM 是一个独立的上游项目，受其自身许可证和项目政策约束。

romm-mcp 根据 MIT 许可证 授权。