鸣潮 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。

命名对照

使用方法

任何支持 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 一起运行

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

与 Cherry Studio 一起运行

1. 下载 Cherry Studio
2. 设置 → 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 参数

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 的多阶段构建，提升构建速度并减小镜像体积