内容
# UltimaMCP
UltimaMCP 是一个仅限本地主机的 .NET 10 桥接器，用于 Ultima SDK。它通过 REST/OpenAPI 以语义化的 JSON 形式公开经典的 Ultima Online 客户端数据，并通过 MCP Streamable HTTP 以面向模型的工具形式公开。
所需的 `Ultima.dll` 包含在存储库根目录中，并在构建过程中复制到应用程序输出。UltimaMCP 验证输入并围绕 SDK 序列化访问，因为它使用可变的静态缓存和共享的读取缓冲区。
## 要求
- Windows 和 .NET 10 SDK
- 合法的本地 Ultima Online Classic 安装
图像渲染使用 `System.Drawing`，仅限于 Windows。服务器默认绑定到 `127.0.0.1:5027`，并且没有身份验证；请勿在未添加身份验证和传输安全的情况下将其公开到外部接口上。
## 配置客户端文件
在 `UltimaAPI/appsettings.json` 中设置 `Ultima:DataPath`：
```json
{
"Ultima": {
"DataPath": "C:\\Games\\Ultima Online Classic"
}
}
```
或者，保留该值为空以使用 SDK 实现的 Windows 注册表发现，或者设置环境变量：
```powershell
$env:Ultima__DataPath = 'C:\Games\Ultima Online Classic'
dotnet run --project .\UltimaAPI\UltimaAPI.csproj
```
当目录或可选扩展文件不存在时，启动将成功降级为有限功能模式。在以下地址可以检查可用性：
- `GET http://127.0.0.1:5027/api/sdk/health`
- `GET http://127.0.0.1:5027/api/sdk/diagnostics`
- `GET http://127.0.0.1:5027/api/sdk/files`
### UOP 兼容性缓存
旧版 SDK 以读写访问权限打开 UOP 容器，即使对于读取操作也是如此。`Program Files` 下的标准安装是只读的，因此 UltimaMCP 在首次使用时在 `%LOCALAPPDATA%\UltimaMCP\UopCache` 下创建了一个可写的影子副本。在源文件大小或修改时间发生变化之前，副本将被重复使用。
设置 `Ultima:UopCachePath` 以移动缓存，或设置 `Ultima:EnableWritableUopShadow` 为 `false`，前提是客户端目录已经可写。原始游戏文件永远不会被修改。
## MCP 连接
Streamable HTTP 端点是：
```text
http://127.0.0.1:5027/mcp
```
典型的 MCP 客户端配置是：
```json
{
"servers": {
"ultima": {
"type": "http",
"url": "http://127.0.0.1:5027/mcp"
}
}
}
```
配置文件名称因 Visual Studio、VS Code、LM Studio、Ollama 集成和其他 MCP 主机而异。请使用主机 Streamable HTTP 服务器配置和上述 URL。
MCP 工具返回紧凑的语义记录。PNG 和 WAV 内容通过 REST URL 在这些记录中公开，而不是作为 base64 嵌入在模型上下文中。
## REST 和 OpenAPI
在开发过程中，OpenAPI 可在 `/openapi/v1.json` 处获得，Scalar 可在 `/scalar` 处获得。
主要路由组：
| 领域 | 示例 |
| --- | --- |
| 瓦片数据 | `/api/tiles/items/{id}`，`/api/tiles/items/search`，`/api/tiles/land/{id}` |
| 地图 | `/api/maps`，`/api/maps/{mapId}/coordinates/{x}/{y}`，`/api/maps/{mapId}/regions/{x}/{y}` |
| 地图图像 | `/api/maps/{mapId}/render.png`，`/api/multimap.png`，`/api/facets/{facetId}.png` |
| 艺术和 UI | `/api/art/land/{id}.png`，`/api/art/static/{id}.png`，`/api/gumps/{id}.png` |
| 纹理和灯光 | `/api/textures/{id}.png`，`/api/lights/{id}.png` |
| 色调和雷达 | `/api/hues/{id}`，`/api/hues/search`，`/api/hues/radar/{kind}/{id}` |
| 字体 | `/api/fonts`，`/api/fonts/ascii/{fontId}/render.png` |
| 声音 | `/api/sounds/{id}`，`/api/sounds/{id}.wav`，`/api/sounds/search` |
| 动画 | `/api/animations/sets`，`/api/animations/{fileType}/{body}/{action}/{direction}` |
| 多元 | `/api/multis/{id}`，`/api/multis/{id}.png` |
| 技能 | `/api/skills`，`/api/skills/groups` |
| 本地化字符串 | `/api/strings/{language}/{number}`，`/api/strings/{language}/search` |
| 语音和补丁 | `/api/speech/search`，`/api/verdata` |
搜索、区域、渲染、文本、多组件和动画帧有效载荷由 `appsettings.json` 中的 `Ultima:Limits` 绑定。
## 只读覆盖
桥接器读取瓦片数据、地图/静态数据、艺术、图像、色调、纹理、光照掩码、雷达颜色、字体、声音、动画、动画数据、多元、技能/组、 cliloc 字符串、语音条目、多地图/面图像和 verdata 补丁元数据。
故意不公开 SDK 中允许变异、导入、替换、删除、保存或附加到实时客户端进程的方法。
## 构建和测试
```powershell
dotnet build .\UltimaMCP.slnx
dotnet test .\UltimaAPI.Tests\UltimaAPI.Tests.csproj
```
HTTP 测试使用故意缺失的临时数据路径，因此它们在不需要本地游戏资产的情况下验证降级行为和请求边界。
