Metadata-Version: 2.5
Name: modio-mcp
Version: 1.0.0
Summary: Read-only mod.io REST API server for the Model Context Protocol
Requires-Python: >=3.11
Requires-Dist: httpx<1,>=0.28
Requires-Dist: mcp<2,>=1.28
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: typing-extensions<5,>=4.12
Description-Content-Type: text/markdown

# mod.io MCP - mod.io REST API MCP 服务器

<div align="center">

[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://www.python.org/) [![MCP 1.x](https://img.shields.io/badge/MCP-1.x-green.svg)](https://modelcontextprotocol.io/)

**按游戏、标签和平台查 Mod，查看团队与前置，下载指定版本。**

</div>

---

## ✨ 项目简介

这个非官方本地 stdio 服务使用 mod.io REST API。每次查询 Mod 都带上所属游戏的 `game_id`，可取得项目主页、介绍、媒体、提交者、团队及可访问的文件。仓库名为 `mod.io-mcp`，Python 包的安装名和启动命令均为 `modio-mcp`。

## ⚡ 快速开始

### 前置条件

- Python 3.11 或更高版本，以及 [uv](https://docs.astral.sh/uv/)。
- 从 [mod.io API Access](https://mod.io/me/access) 或游戏管理面板取得 API path，并准备同一环境的 API Key 或访问令牌。

### 安装与更新

在 `mod.io-mcp` 仓库根目录执行：

```sh
uv sync --python 3.11
```

更新仓库源码后，重新执行上面的命令并重启客户端中的服务。若使用已有的 Python 虚拟环境，也可以用 `python -m pip install --upgrade .` 安装或更新，启动命令为 `modio-mcp`。

### 配置客户端

在仓库根目录的 `.env` 中填写面板给出的完整 HTTPS `/v1` 地址。下面以游戏级地址为例；用户级地址可形如 `https://u-12345.modapi.io/v1`。

```dotenv
MODIO_API_BASE_URL=https://g-12345.modapi.io/v1
MODIO_API_KEY='替换为你的 API Key'
# 可选；默认目录为 ~/Downloads/mod.io
# MODIO_DOWNLOAD_DIR=E:/Downloads/mod.io
```

使用 OAuth 或个人访问令牌时，改设 `MODIO_ACCESS_TOKEN`。两种凭据都存在时，服务使用访问令牌。

将以下条目加入使用 `mcpServers` 格式的客户端，把 `--directory` 后的示例路径替换为本仓库的绝对路径。使用 VS Code 的 `.vscode/mcp.json` 时，顶层键使用 `servers`。

```json
{
  "mcpServers": {
    "modio-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "E:/GitHub/mcp/mod.io-mcp", "run", "--no-sync", "--env-file", ".env", "modio-mcp"]
    }
  }
}
```

### 第一次调用

先运行 `check_auth()`。返回 `authenticated: true` 后，试试「查找 SnowRunner，列出它的 Mod 标签，再选一个 Mod 查看作者团队和当前版本」。后续查询沿用 `search_games` 返回的 `id`。

## 🧰 工具列表

| 工具 | 主要参数 | 用途 |
| --- | --- | --- |
| `check_auth` | 无 | 读取受鉴权的游戏列表，检查当前 API 地址及凭据。 |
| `search_games` | 可选 `query`、`slug`、`limit`、`offset` | 列出可访问的游戏，按关键词搜索或按 `name_id` 精确筛选。 |
| `get_game` | `game_id` | 读取游戏详情。 |
| `list_game_tags` | `game_id`；可选 `platform` 和分页参数 | 取得游戏的标签分类和选项，供 Mod 筛选使用。 |
| `search_mods` | `game_id`；可选 `query`、`slug`、`tags`、`tag_match`、`platform` | 搜索游戏内的 Mod。`tag_match=all` 匹配全部标签，`any` 匹配任意标签。 |
| `get_mod` | `game_id`、`mod_id`；可选 `platform` | 取得项目资料、主页、媒体、提交者和上游提供的活跃文件。 |
| `get_mod_team` | `game_id`、`mod_id`；可选分页参数 | 列出该项目的团队成员与角色。 |
| `get_mod_dependencies` | `game_id`、`mod_id`；可选 `recursive` 和分页参数 | 默认查询直接前置，传 `recursive=true` 由站点递归展开。 |
| `list_mod_files` | `game_id`、`mod_id`；可选 `platform` 和分页参数 | 列出文件版本、大小、哈希及平台可用性。 |
| `get_mod_file` | `game_id`、`mod_id`、`file_id`；可选 `platform` | 取得指定文件的原始元数据。 |
| `get_download_url` | `game_id`、`mod_id`；可选 `file_id`、`platform` | 刷新文件元数据，返回 `binary_url` 和可用的过期时间。省略文件 ID 时选择活跃文件。 |
| `download_file` | `game_id`、`mod_id`；可选 `file_id`、`platform`、`filename` | 流式保存所选或活跃文件；可指定本地文件名，返回路径、字节数、SHA-256 和文件 ID。 |

**分页与平台。** 列表支持 `limit`（1–100，默认 20）和 `offset`；还有下一页时使用返回的 `next_offset`。`platform` 会传给站点作为 `X-Modio-Platform`，可用平台和活跃文件由游戏配置决定。

**下载与校验。** `binary_url` 可能是临时 CDN 地址，也可能是需要鉴权的同源下载端点。`download_file` 会处理同源鉴权、跨域跳转和短期链接刷新，核对可用的大小及 `filehash.md5`，并计算 SHA-256。目标目录可用 `MODIO_DOWNLOAD_DIR` 指定绝对路径，目录缺失时会创建。最终文件通过硬链接发布，因此目录所在文件系统须支持硬链接（如 NTFS）；同名时可换一个 `filename`。

## 测试

```sh
uv run --locked pytest -q
uv run --locked ruff check .
```

默认测试用模拟 API 和真实 stdio 子进程检查工具及下载。带凭据检查实站鉴权可运行 `uv run --locked --env-file .env pytest -q -k test_live_authenticated_stdio`；若还要读取特定游戏，可设置 `MODIO_TEST_GAME_ID`。

## 构建与发布到 PyPI

首次发布前，在 PyPI 为 `modio-mcp` 登记 GitHub Trusted Publisher。仓库所有者填 `GlossMod`，仓库名填 `mod.io-mcp`，工作流文件填 `publish.yml`，环境填 `pypi`。新项目可在 [PyPI Publishing](https://pypi.org/manage/account/publishing/) 预先登记。

在 `GlossMod/mod.io-mcp` 的 GitHub Releases 页面为目标提交选择新标签，点击 **Publish release**。例如，`v0.2.0` 会发布 `modio-mcp==0.2.0`，`v0.2.0rc1` 会发布候选版。GitHub Actions 从标签取版本，构建并校验 wheel 和源码包，然后发布到 PyPI。可在本地运行 `uv build` 检查开发版本的构建产物。

参考：[mod.io REST API](https://docs.mod.io/restapi/introduction) · [平台请求头](https://docs.mod.io/restapi/platforms) · [依赖查询](https://docs.mod.io/restapi/docs/get-mod-dependencies)
