Metadata-Version: 2.4
Name: wuwa-mcp
Version: 2.2.1
Summary: MCP server that fetches Wuthering Waves character and echo data from the KuroBBS wiki and returns LLM-friendly Markdown.
Keywords: mcp,model-context-protocol,wuthering-waves,game-wiki,llm
Author: jacksmith3888
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: beautifulsoup4>=4.13.4
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp[cli]>=2.0.0
Requires-Dist: uvicorn>=0.32.1
Requires-Dist: starlette>=0.41.3
Requires-Dist: ruff>=0.8.0 ; extra == 'dev'
Maintainer: 颗粒
Requires-Python: >=3.12
Project-URL: Issues, https://github.com/wzkzd666/wuwa-mcp-server/issues
Project-URL: Repository, https://github.com/wzkzd666/wuwa-mcp-server
Provides-Extra: dev
Description-Content-Type: text/markdown

# 鸣潮 MCP Server

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

**📄 [English Documentation](README_EN.md) | 🇨🇳 中文文档**

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

## 功能特点

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

## 环境要求

- Python ≥ 3.12
- [uv](https://docs.astral.sh/uv/)（包管理与运行）

## 安装

### 从 PyPI 安装（推荐）

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

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

### 从 GitHub 安装

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

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

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

```bash
# 以路径依赖装进你的项目
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 安装后，最简配置：

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

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

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

### 与 Claude Desktop 一起运行

1. 下载 [Claude Desktop](https://claude.ai/download)
2. 创建或编辑配置文件：
   - macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows：`%APPDATA%\Claude\claude_desktop_config.json`
3. 填入上面的 `mcpServers` 配置，然后重启客户端

### 与 Cherry Studio 一起运行

1. 下载 [Cherry Studio](https://github.com/CherryHQ/cherry-studio)
2. 设置 → MCP 服务器 → 添加，填入上面的 `mcpServers` 配置

## 可用工具

### 1. 角色信息工具

```python
async def get_character_info(character_name: str) -> str
```

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

**参数：**

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

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

### 2. 声骸信息工具

```python
async def get_artifact_info(artifact_name: str) -> str
```

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

**参数：**

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

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

### 3. 角色档案工具

```python
async def get_character_profile(character_name: str) -> str
```

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

**参数：**

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

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

## 开发和测试

### 本地运行

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

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

### 代码质量

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

```bash
# 安装开发依赖
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 部署

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