Genshin Bwiki MCP / 原神 Bwiki MCP

A read-only Python MCP server for searching and reading the community-maintained Genshin Bwiki. It wraps the site's public MediaWiki API and requires no account or API key.

这是一个只读 Python MCP server，用于检索和读取社区维护的原神 WIKI_BWIKI。它封装站点公开的 MediaWiki API，不需要账号或 API Key。

This project is an independent API client, not an official Bilibili or HoYoverse product. Wiki content remains subject to the source site's rules and rights notices.

本项目是独立 API 客户端，并非哔哩哔哩或米哈游官方产品。Wiki 内容仍受来源站点社区规则及权利声明约束。

Tools / 工具

All tool responses are JSON strings with one of these envelopes:

{"ok": true, "data": {}}

{"ok": false, "error": "ValueError", "message": "..."}

JSON configuration / JSON 配置

Install uv, then import example.json into an MCP client that accepts the common mcpServers format. The included file points at this checkout and uses uvx --refresh --from so it can run before a PyPI release.

安装 uv，然后把 example.json 导入支持通用 mcpServers 格式的客户端。示例已经指向当前项目目录，并使用 uvx --refresh --from，因此不依赖预先发布到 PyPI。

For another machine, replace the path after --from with that machine's absolute project path. After a future PyPI release, the shorter configuration is:

换到其他机器时，请把 --from 后的路径改为项目的绝对路径。未来发布到 PyPI 后，可使用更短的配置：

{
  "mcpServers": {
    "genshin_bwiki": {
      "command": "uvx",
      "args": ["--refresh", "genshin-bwiki-mcp"]
    }
  }
}

Local development / 本地开发

uv sync
uv run pytest -q
uv run genshin-bwiki-mcp
uv build

The server uses stdio transport. Do not print debugging output to stdout while it is attached to an MCP client.

服务器使用 stdio 传输；连接 MCP 客户端时，请勿向 stdout 输出调试信息。

API behavior / API 行为

• Base endpoint / 基础端点：https://wiki.biligame.com/ys/api.php
• Requests are anonymous, read-only, time-limited, and carry an identifying user agent. / 请求匿名、只读、带超时和可识别 User-Agent。
• Output size limits reduce accidental context flooding. / 输出长度限制可避免意外占满模型上下文。
• Bwiki does not return content through the usual MediaWiki Extracts response, so get_page_summary converts action=parse HTML locally. / Bwiki 未通过常见 Extracts 响应返回正文，因此摘要工具会在本地转换 action=parse HTML。

Upstream protection / Bwiki 上游保护

The protection pipeline runs inside the MCP server process, so every client using this server automatically gets persistent connection reuse, serialized requests, duplicate-request coalescing, TTL/LRU caching, a 1.25-second minimum interval, a 12-request rolling minute budget, exponential retry with jitter, and a 45-second circuit breaker for repeated failures.

保护逻辑位于 MCP Server 进程内部，因此网页端、Claude Desktop、Cherry Studio 等 MCP 客户端都会自动获得连接复用、串行请求、并发重复请求合并、TTL/LRU 缓存、最小 1.25 秒调用间隔、每分钟 12 次滚动预算、带抖动的指数退避，以及连续失败后的 45 秒熔断。

Retryable statuses are 429, 500, 502, 503, 504, and Bwiki's non-standard 567. After retries are exhausted, tools return a structured BwikiTemporarilyUnavailable JSON error instead of exposing 567 Unknown Status directly. Defaults can be overridden with the BWIKI_* environment variables documented in webapp/.env.example.

可重试状态包括 429、500、502、503、504 和 Bwiki 的非标准 567。重试耗尽后，工具会返回结构化的 BwikiTemporarilyUnavailable JSON 错误，不再直接暴露 567 Unknown Status。默认值可以通过 webapp/.env.example 中的 BWIKI_* 环境变量覆盖。

The rolling budget is process-local. Multiple independently launched MCP server processes do not share cache or counters and should each keep conservative defaults.

滚动预算以 MCP 进程为单位；多个独立启动的 MCP Server 不共享缓存和计数器，应分别保留保守配置。