鸣潮 MCP Server

一个 Model Context Protocol (MCP) 服务器，用于获取《鸣潮》游戏的角色与声骸信息，并以 Markdown 格式返回，便于大型语言模型直接消费。

📄 English Documentation | 🇨🇳 中文文档

本仓库是 jacksmith3888/wuwa-mcp-server 的二次修改版，上游停留在 v2.0.1（MIT 许可），当前版本 v2.2.0，由颗粒维护。改动要点：适配 mcp 2.x、修复攻略子页抓取失败、输出去重、移除长度截断。完整清单见文末「版本改动」。

功能特点

角色信息查询：获取角色详情，含技能、养成攻略
声骸信息查询：获取声骸套装的详细信息
角色档案查询：获取角色档案信息
LLM 友好输出：结果格式为大型语言模型优化，内容去重且不截断
双传输模式：支持 STDIO 与 Streamable HTTP

环境要求

Python ≥ 3.12
uv（包管理与运行）

安装

从 PyPI 安装（推荐）

# 装进你的项目
uv add wuwa-mcp

# 或者不安装，直接运行
uvx wuwa-mcp

从 GitHub 安装

uv add "git+https://github.com/wzkzd666/wuwa-mcp-server"

# 锁定到某个版本
uv add "git+https://github.com/wzkzd666/wuwa-mcp-server@v2.2.0"

从本地源码安装（开发用）

# 以路径依赖装进你的项目
uv add /path/to/wuwa-mcp-server

# 安装到本仓库自身环境
cd /path/to/wuwa-mcp-server
uv sync

# 或先构建再安装产物
uv build
uv pip install dist/*.whl

⚠️ 不要安装 wuwa-mcp-server —— PyPI 上那个是上游 v2.0.1，不含 mcp 2.x 适配与去重 / 缓存修复，在 mcp 2.x 环境下启动即崩。本项目发布的包名是 wuwa-mcp，import 名与包名一致为 wuwa_mcp（import wuwa_mcp）。唯一的控制台命令也是 wuwa-mcp。

命名对照

用途	名称
PyPI 分发包名	`wuwa-mcp`
import 名	`wuwa_mcp`
控制台命令	`wuwa-mcp`（唯一）
MCP 服务器名	`wuwa-mcp`

使用方法

任何支持 MCP 的客户端（Claude Desktop、Cherry Studio、Cline 等）都可用同一份配置接入。

从 PyPI 安装后，最简配置：

{
  "mcpServers": {
    "wuwa-mcp": {
      "command": "uvx",
      "args": ["wuwa-mcp"]
    }
  }
}

从本地源码或路径运行时：

{
  "mcpServers": {
    "wuwa-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/wuwa-mcp-server", "run", "wuwa-mcp"]
    }
  }
}

与 Claude Desktop 一起运行

下载 Claude Desktop
创建或编辑配置文件：
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows：%APPDATA%\Claude\claude_desktop_config.json
填入上面的 mcpServers 配置，然后重启客户端

与 Cherry Studio 一起运行

下载 Cherry Studio
设置 → MCP 服务器 → 添加，填入上面的 mcpServers 配置

可用工具

1. 角色信息工具

async def get_character_info(character_name: str) -> str

在库街区上查询角色详细信息（含技能、养成攻略）并以 Markdown 格式返回。

参数：

character_name: 要查询的角色的中文名称

返回： 包含角色信息的 Markdown 字符串（完整原文，仅去重、不截断），或者在找不到角色或获取数据失败时返回错误消息。

2. 声骸信息工具

async def get_artifact_info(artifact_name: str) -> str

在库街区上查询声骸详细信息并以 Markdown 格式返回。

参数：

artifact_name: 要查询的声骸套装的中文名称

返回： 包含声骸信息的 Markdown 字符串，或者在找不到声骸或获取数据失败时返回错误消息。

3. 角色档案工具

async def get_character_profile(character_name: str) -> str

在库街区上查询角色档案信息并以 Markdown 格式返回。

参数：

character_name: 要查询的角色的中文名称

返回： 包含角色档案信息的 Markdown 字符串，或者在找不到角色或获取数据失败时返回错误消息。

开发和测试

本地运行

# STDIO 模式（默认）
uv run python -m wuwa_mcp.server

# HTTP 模式
TRANSPORT=http uv run python -m wuwa_mcp.server

代码质量

项目使用 ruff 进行代码格式化和静态分析。

# 安装开发依赖
uv sync --extra dev

# 格式化所有 Python 代码
uv run ruff format .

# 检查代码问题
uv run ruff check .

# 自动修复可修复的问题
uv run ruff check --fix .

Ruff 配置：行长度 120 字符，目标 Python 3.12，启用 pycodestyle / pyflakes / isort / 命名约定 / pyupgrade / bugbear / 代码简化等规则，强制单行导入。

Docker 部署

# 构建镜像
docker build -t wuwa-mcp .

# 运行容器（HTTP 模式，监听 8081）
docker run -p 8081:8081 wuwa-mcp

# 运行容器（STDIO 模式）
docker run -e TRANSPORT=stdio wuwa-mcp

详细功能

结果处理

清理并格式化库街区数据
为 LLM 消费优化格式
支持并行处理提高性能
异步操作避免阻塞

传输模式

STDIO 传输：适用于本地客户端，如 Claude Desktop
Streamable HTTP 传输：适用于云端部署和远程访问
通过环境变量 TRANSPORT 自动切换模式

贡献

本 fork 由颗粒维护（原作者 jacksmith3888）。改动以「能跑通 + 数据完整」为目标，未做大规模重构。

欢迎提出问题和拉取请求。一些可改进的方向：

增加对更多《鸣潮》游戏内容的支持
增强内容解析选项
增加对频繁访问内容的缓存层
支持更多语言的本地化

许可证

本项目采用 MIT 许可证，原始版权归 jacksmith3888 所有。

本地修改部分（v2.2.0，维护者：颗粒）同样遵循 MIT 许可证。

版本改动（维护者：颗粒）

v2.2.0

🔤 统一命名：import 包目录 wuwa_mcp_server → wuwa_mcp，与分发包名 wuwa-mcp 完全一致（PEP 503 归一化），不再需要 [tool.uv.build-backend] module-name 特殊声明。控制台命令也只保留 wuwa-mcp 一个，移除 wuwa-mcp-server 别名。这是一处破坏性变更：原 import wuwa_mcp_server 需改为 import wuwa_mcp，原 wuwa-mcp-server 命令需改为 wuwa-mcp
🐛 修复循环导入：core/__init__.py 顶层 from .container import ... 与 services 反向依赖 core 构成环，导致「先 import services.character_service」直接 ImportError（必须先 import core 才能用）。改为 PEP 562 模块级 __getattr__ 惰性导出 DIContainer / get_container / reset_container，对外 API 不变
🧹 删除死代码 542 行：经 AST 可达性分析 + 全项目引用计数双重确认，移除 26 个零引用符号——13 个重复的工厂函数（create_*，container 已直接构造）、3 个 legacy 兼容壳（LegacyMarkdownConverter、ContentParser、CharacterDevelopmentStrategy）、6 个未被引用的 protocol / ABC、2 个未用异常类、2 个未用 value object（含级联孤立的 ModuleData）
🧹 裁剪冗余再导出：builders / domain / infrastructure / infrastructure.api / parsers / services 六个 __init__.py 的急切再导出无人消费，精简为仅保留 docstring，降低耦合与导入开销
🩹 修复版本漂移：__init__.py 的 __version__ 原硬编码 2.0.1（与 pyproject.toml 不符），改为从 importlib.metadata 读取，杜绝再次漂移
🩹 修复潜在 F821：artifact_service / character_service 中 "MarkdownService" 前向引用从未导入，补 TYPE_CHECKING 导入
✅ 质量：全项目 ruff check --select F 通过；34 个模块独立进程导入测试 0 个 ImportError

v2.1.0（本仓库 fork）

相对上游 v2.0.1 的改动：

🔌 适配 mcp 2.x：FastMCP → MCPServer，修复原版在 mcp 2.x 下启动即崩的 ImportError
🩹 修复攻略子页抓取偶发失败：根因是 HTTP client not initialized（原 _fetch_strategy_content 裸用 api_client 未进 async context）
⚡ 新增 API 响应 TTL 缓存（600s），减少库街区实时请求
♻️ 输出去重：修复「整页渲染两遍」，并移除长度截断，改为始终返回完整原文
📊 表格与标题质量修复：行名缺失、首列空白、blob URL 泄漏、重复表 / 残缺表清理、空标题、数字型 tab 补 Lv. 前缀、全角％归一
🧹 清理：移除 Smithery 硬依赖，get_character_info 不再有 full 参数

文件	改动
`server.py`	`mcp.server.fastmcp.FastMCP` → `mcp.server.mcpserver.MCPServer`；移除手搓 Starlette/SSE 分支，改用 mcp 2.x 原生 `streamable_http_app()`；移除 `@smithery.server()` 分支并补 `import sys`；`get_character_info` 不再有 `full` 参数（始终返回完整内容）
`character_repository.py`	新增托管方法 `get_entry_detail(entry_id)`（内部 `async with self.api_client`），供攻略子页复用
`character_service.py`	`_fetch_strategy_content` 改调 `get_entry_detail()`（修复 `ConnectionException`）；末尾固定 `postprocess_markdown(..., max_chars=0)` —— 只去重、不截断
`kuro_api_client.py`	新增 `_TTLCache`（ttl=600s），缓存 `list:char` / `list:artifact` / `detail:{entry_id}`
`markdown_service.py`	新增模块级 `postprocess_markdown()`：先按空行分块去重相邻重复块（修「整页渲染两遍」），再按需截断（`max_chars<=0` 表示不截断）
`parsers/html_converter.py`	表格行名修复、首列空白修复、blob URL 泄漏修复、重复表与残缺表清理
`parsers/content_parser.py`	空标题清理、数字型 tab 标题补 `Lv.` 前缀、全角％归一为半角 `%`
`pyproject.toml`	`mcp[cli]>=1.8.0` → `mcp>=2.0.0`；移除 `smithery` 依赖与 `[tool.smithery]` 段；版本升 `2.1.0`

v2.0.1（上游 jacksmith3888）

🏗️ 架构重构：采用领域驱动设计（DDD）架构，清晰的分层结构
🔧 代码质量：集成 ruff 代码格式化和静态分析工具
📝 现代化语法：使用 Python 3.12+ 现代类型注解（dict/list 替代 Dict/List）
🧹 代码清理：移除旧有代码，统一代码风格和质量标准
✅ 支持 Streamable HTTP 传输
🔄 向后兼容：同时支持传统的 STDIO 和新的 HTTP 传输模式
🌐 云端部署就绪：适配 VPS、Google Cloud Run、AWS Lambda 等云环境
📦 依赖注入：使用依赖注入容器管理服务实例
🐳 Docker 优化：使用 uv 的多阶段构建，提升构建速度并减小镜像体积