内容
# 虚幻MCP网页客户端
> 一个强大的网页客户端，用于与虚幻引擎5.8模型上下文协议（MCP）服务器交互。
## 目录
- [关于项目](#关于项目)
- [需求](#需求)
- [安装](#安装)
- [如何运行](#如何运行)
- [如何停止](#如何停止)
- [虚幻集成](#虚幻集成)
- [虚幻Python API技能](#虚幻Python-API技能)
- [概念开发指南](#概念开发指南)
- [项目结构](#项目结构)
- [更新日志](#更新日志)
- [许可证](#许可证)
---
<a name="关于项目"></a>
## 关于项目
**虚幻MCP网页客户端**是一个交互式的单页应用程序（SPA），设计用于调试和消费虚幻引擎5.8的内置MCP服务器。它允许图形化检查活动工具集、参数的JSON-RPC模式、实时调用工具和通过服务器发送事件（SSE）读取渐进式响应。
**主要技术：**
- 前端：HTML5、JavaScript（ES6+ Vanilla）、CSS3（暗黑主题、Glassmorphism、HSL令牌）。
- 本地开发服务器：FastAPI、Uvicorn、HTTPX。
---
<a name="需求"></a>
## 需求
- **虚幻引擎5.8**（启用`ModelContextProtocol`插件）。
- **Python 3.x**（安装`fastapi`、`uvicorn`和`httpx`：`pip install fastapi uvicorn httpx`）。
- **Playwright**（仅在更新概念指南时需要 - 参见[概念开发指南](#概念开发指南)）：`pip install playwright && playwright install chromium`。
- 现代网页浏览器（Chrome、Edge、Firefox等）。
---
<a name="安装"></a>
## 安装
客户端很轻量，可以在本地运行：
1. 将客户端文件复制到本地目录。
2. 确保已安装Python并可在命令行访问（`python --version`）。
---
<a name="如何运行"></a>
## 如何运行
使用根目录中的脚本：
**Windows：**
```cmd
start.cmd
```
**macOS / Linux：**
```bash
chmod +x start.sh
./start.sh
```
脚本将启动本地HTTP服务器，并自动在浏览器中打开：
`http://localhost:5000`
---
<a name="如何停止"></a>
## 如何停止
要停止本地开发服务器：
**Windows：**
```cmd
stop.cmd
```
**macOS / Linux：**
```bash
chmod +x stop.sh
./stop.sh
```
---
<a name="虚幻集成"></a>
## 虚幻集成
要将此功能（包括无限运行Python脚本）复制到任何虚幻引擎5.8项目中，请参阅详细的逐步指南：
👉 **[虚幻引擎5.8 MCP服务器集成指南](./docs/UNREAL_MCP_INTEGRATION_GUIDE.md)**
本指南涵盖：
1. 在`.uproject`中激活插件。
2. 在`.Build.cs`中链接依赖项。
3. 创建从`UToolsetDefinition`派生的自定义类，并使用`UFUNCTION(meta = (AICallable))`宏公开。
4. 使用`EPythonCommandExecutionMode::ExecuteFile`执行多语句Python。
5. 配置和重用输入/输出桥（`bridge.py`），以便Claude Desktop发现和执行自定义工具。
---
<a name="虚幻Python-API技能"></a>
## 虚幻Python API技能
该项目包括 **`dbv-unreal-python-api`** 技能，它结合了两个互补工具，使AI代理（Claude Desktop或Gemini）能够为虚幻引擎5.8生成正确的Python脚本：
| 工具 | 目的 | 何时使用 |
| --- | --- | --- |
| `dbv_unreal_dev_guide` | 概念搜索 - 散文式开发指南和配方（PCG、材质、蓝图、游戏玩法、动画、UI、节点引用...） | **首先**，在编写代码之前了解逻辑流程 |
| `dbv_python_unreal_api` | 语法搜索 - 官方Python API的确切类、方法和参数签名 | **之后**，在调用`RunPython`之前验证确切语法 |
### 它做什么以及为什么使用？
它允许AI代理准确查询和获取虚幻引擎5.8的**概念设计**（如何解决虚幻中的问题）和**官方Python API类、方法和签名**，从而生成正确的Python脚本和/或复杂的自动化任务，以便在虚幻引擎中通过`RunPython`命令执行。
该技能执行以下操作：
1. **本地爬取/抓取**：下载并清理虚幻引擎5.8的官方Python API文档（超过11,000页的Python API和几乎所有的概念文档 - 参见[概念开发指南](#概念开发指南)），将其存储在本地并删除冗余元素（菜单、侧边栏、脚本）。
2. **两层搜索引擎**：索引和分割信息为块，公开基于自然语言的概念搜索（`search_guides`）和语法搜索（`search`，支持精确搜索`exact:ClassName`）。
3. **本地MCP服务器**：公开JSON-RPC端点和HTTP API，以便智能代理可以进行直接和动态的热查询。
### 如何使用？ - 2种方式，选择适合您的客户端
#### 1. Claude Code - 项目技能（推荐，零配置）
它已经包含在存储库中：`.claude/skills/dbv-unreal-python-api/SKILL.md` 是Claude Code自动发现的内容。当克隆存储库并使用Claude Code打开它时，技能已经可用 - 不需要触摸任何配置文件。Claude在需求时通过Bash/code执行（无服务器或开放端口）执行`search_engine.py`的CLI，直接从本地磁盘读取知识库：
```bash
python skills/dbv-unreal-python-api/scripts/search_engine.py search-guides "在材质实例中连接纹理"
python skills/dbv-unreal-python-api/scripts/search_engine.py search "exact:MaterialEditingLibrary"
```
> ⚠️ **手动将技能上传到Claude Desktop / claude.ai不可行。** 该UI需要小于30MB的`.zip`文件，而此捆绑包（`scripts/` + `knowledge/`）由于其17,000个引用文件而重达约118MB。此外，上传的技能在沙盒中运行，无本地磁盘访问权限，因此即使压缩得更多，搜索器也无法工作。对于Desktop/claude.ai，请使用选项2。
#### 2. MCP服务器（Claude Desktop，claude.ai或其他MCP客户端）
对于非Claude Code的任何客户端都是必要的，因为它直接从本地磁盘读取知识库，没有上传大小限制。在`claude_desktop_config.json`中注册，调整到本地克隆的绝对路径。**在Windows上**，使用`python.exe`的完整路径（Claude Desktop并不总是继承您的`PATH`），并转义反斜杠 **两次** (`\\`)：
```json
{
"mcpServers": {
"dbv-unreal-python-api": {
"command": "C:\\Program Files\\Python312\\python.exe",
"args": [
"-u",
"C:\\RUTA\\ABSOLUTA\\A\\TU\\CLON\\MCPCLiente\\skills\\dbv-unreal-python-api\\scripts\\mcp_server.py"
]
}
}
}
```
> 有关macOS/Linux（普通斜杠，无转义）和两种方法的详细说明，请参见[SKILL.md](./skills/dbv-unreal-python-api/SKILL.md)。
#### 3. 通过HTTP API使用（此存储库的自定义Web客户端）
本地FastAPI服务器（`server.py`）在常用端口上公开快速查询端点：
* **API搜索**：`GET http://localhost:5000/api/docs/search?q=your_search`
* **API状态**：`GET http://localhost:5000/api/docs/status`
* **指南搜索**：`GET http://localhost:5000/api/guides/search?q=your_search`
* **指南状态**：`GET http://localhost:5000/api/guides/status`
#### 5. 更新或重新扫描类API
要下载和更新本地虚幻API数据库（例如，用于虚幻5.8或新版本）：
* **抓取官方API（5.8）**：
```bash
python skills/dbv-unreal-python-api/scripts/scrape_ue_api.py
```
* **更新到新版本（例如5.9）**：
```bash
python skills/dbv-unreal-python-api/scripts/update_api.py --version 5.9
```
---
<a name="概念开发指南"></a>
## 概念开发指南
除了API语法参考外，该技能还包括一个概念知识库，几乎包含了整个**虚幻引擎5.8官方文档**（不仅限于PCG/材质/蓝图）：游戏玩法系统、动画、音频、UI（UMG/Slate）、Niagara、C++，以及蓝图/控制中心/数据流节点参考卡片（`node-reference`）。
### 如何下载？ - Cloudflare绕过
Epic的文档门户（`dev.epicgames.com`）是一个受Cloudflare Bot Management保护的Angular SPA：传统HTTP请求（`urllib`、`curl`）会因缺乏真实浏览器的TLS/JS指纹而收到`403 Forbidden`。爬虫脚本（`scrape_ue_guides.py`）通过 **Playwright** （Chromium）解决这个问题，为每个页面打开一个新的**浏览器上下文** - Cloudflare在第一次请求后会降低会话的信任度，因此在页面之间重用上下文会导致第二次请求出现403。
页面发现使用`table_of_content.json`端点，该端点通过单个调用公开整个文档树（数千个页面），而不是固定的URL列表。
### 主要命令
```bash
# 下载/更新所有概念文档（推荐）
python skills/dbv-unreal-python-api/scripts/scrape_ue_guides.py --category full --resume
# 只下载特定类别（可用快捷方式：pcg, materials, blueprints, editor）
python skills/dbv-unreal-python-api/scripts/scrape_ue_guides.py --category blueprints
# 指向文档树的字面子树（适用于并行化）
python skills/dbv-unreal-python-api/scripts/scrape_ue_guides.py --category "node-reference/ControlRig"
# 查看索引的当前状态
python skills/dbv-unreal-python-api/scripts/scrape_ue_guides.py --status
```
**并行化**：每个 `--category <x>` 执行写入自己的分片（`index_guides__<x>.json`），以便同时启动多个进程而无需竞争条件。完成后，使用以下命令合并所有分片：
```bash
python skills/dbv-unreal-python-api/scripts/scrape_ue_guides.py --merge
```
> ⚠️ 不要同时运行超过~5-6个进程 - Cloudflare会随着并发性的增加而持续降低速率限制，而不仅仅是在启动时。
出错的页面记录在 `.errors_guides__<category>.json` 中（不标记为已完成），因此后续的 `--resume` 会自动重试。
---
<a name="项目结构"></a>
## 项目结构
```text
/
├── docs/ # 项目文档
│ ├── UNREAL_MCP_INTEGRATION_GUIDE.md # 集成MCP到其他项目的逐步指南
│ └── templates/ # 示例toolset的.h/.cpp文件，准备好复制到Source/
├── skills/ # AI代理的技能和本地知识库
│ └── dbv-unreal-python-api/ # 搜索引擎和API参考 + 虚幻概念指南
│ ├── knowledge/classes/ # Python API类（scrape_ue_api.py）
│ ├── knowledge/guides/ # 整个UE 5.8文档的概念指南（scrape_ue_guides.py）
│ └── scripts/ # 爬虫、搜索引擎和MCP服务器
├── .well-known/ # AI代理的声明性卡片（robots.txt, api-catalog等）
├── src/
│ ├── css/
│ │ └── style.css # 视觉样式和设计（暗黑模式霓虹灯，Safari过滤器）
│ └── js/
│ └── app.js # 客户端逻辑，连接，markdown和流解码器
├── index.html # 网页客户端结构
├── auth.md # 机器人和代理访问说明
├── start.cmd / .sh # 启动脚本
├── stop.cmd / .sh # 停止脚本
├── project.config.md # 框架配置
├── CHANGELOG.md # 更新日志
└── README.md # 本指南
```
---
<a name="更新日志"></a>
## 更新日志
在 [CHANGELOG.md](./CHANGELOG.md) 文件中查看完整的更新历史和版本记录。
---
<a name="许可证"></a>
## 许可证
MIT - 请参阅 [LICENSE](./LICENSE) 文件了解详情。
Copyright (c) 2026 David Bueno Vallejo · https://github.com/davidbuenov
---
> 🛠️ 使用 **[dbv-specs-ops](https://github.com/davidbuenov/dbv-specs-ops)** 生成。
