内容
# GTNH MCP 游戏聊天
MCP（模型上下文协议）服务器，通过 **Scribe** 模组将 AI 代理集成到 Minecraft GTNH 聊天中。代理表现为玩家 — 它读取聊天消息，回应，编写书籍，并可以通过本地 HTTP API 控制游戏。
**跨平台** — MCP 服务器是纯 Python（Windows，macOS，Linux）。Scribe 模组是纯 Java（任何 Forge 运行的地方）。与任何 MCP 兼容的代理一起工作：Claude，Codex，OpenClaw，Pi-agent 等。
## 架构
```
┌──────────────────────┐ MCP（stdio） ┌──────────────────────┐
│ AI 代理 │ ◄─────────────────► │ gtnh_chat_mcp.py │
│ （Claude，Codex， │ │ （Python MCP 服务器） │
│ OpenClaw，Pi-agent，│ └──────────┬───────────┘
│ 等） │ │
└──────────────────────┘ HTTP（localhost:25566）
│
┌──────────▼───────────┐
│ Scribe 模组 │
│ （Forge 1.7.10） │
│ │
│ 聊天捕获 │
│ 玩家状态 │
│ 方块扫描 │
│ 编写书籍 │
│ 操作（聊天， │
│ 点击，传送） │
└──────────┬───────────┘
│
┌──────────▼───────────┐
│ Minecraft 1.7.10 │
│ + GTNH + Forge │
└──────────────────────┘
```
## MCP 工具
| 工具 | 描述 |
|------|-------------|
| `gtnh_ping` | 检查与 Minecraft 的连接 |
| `gtnh_chat_read` | 读取上次轮询以来的新聊天消息 |
| `gtnh_chat_send` | 发送聊天消息（代理以玩家身份发言） |
| `gtnh_player_status` | 玩家位置，生命值，饥饿度，经验值，维度 |
| `gtnh_inventory` | 完整的物品栏，包含物品名称，数量，槽位 |
| `gtnh_scan_blocks` | 扫描玩家周围的非空气方块 |
| `gtnh_teleport` | 传送到精确坐标 |
| `gtnh_click_block` | 右键/左键点击方块 |
| `gtnh_write_book` | 创建书面书籍（最多 50 页，每页 256 字符） |
## 书籍模式
Minecraft 聊天限制在 ~100 个字符。Scribe 使用 **书面书籍** 进行详细输出：
- **聊天**：简短确认（“马上办。”，“报告已准备 — 检查你的物品栏。”）
- **书籍**：完整报告 — 矿石调查，物品栏转储，任务总结，基地布局
书籍出现在你的物品栏中。右键点击阅读。如果物品栏已满，书籍会掉落在你的脚下。
## 游戏内指南书
当你安装 Scribe 模组并加入一个世界时，**“Scribe 代理指南”** 书籍会自动出现在你的物品栏中。它涵盖了命令，操作，扫描，物品栏，书籍，提示和示例。
如果你丢失了它，在聊天中输入 `/scribe guide` 以获取新的副本。任何人都可以执行此命令。
## 快速入门
### 1. 构建和安装模组
```bash
cd scribe-mod
./gradlew build
# 将 build/libs/scribe-1.1.0.jar 复制到 GTNH 实例的 mods/ 目录中
```
需要 JDK 17+ 和 Gradle 7.6+（使用 RetroFuturaGradle 针对 1.7.10）。
### 2. 安装 MCP Python 包
```bash
pip install mcp
```
### 3. 配置你的代理
**Hermes 代理** (`~/.hermes/config.yaml`)：
```yaml
mcp_servers:
gtnh:
command: "python"
args:
- "/path/to/gtnh-mcp-game-chat/mcp-server/gtnh_chat_mcp.py"
env:
GTNH_MCP_BASE_URL: "http://127.0.0.1:25566"
timeout: 30
```
**Claude Desktop** (`claude_desktop_config.json`)：
```json
{
"mcpServers": {
"gtnh": {
"command": "python",
"args": ["/path/to/gtnh_chat_mcp.py"],
"env": {
"GTNH_MCP_BASE_URL": "http://127.0.0.1:25566"
}
}
}
}
```
**Codex / OpenClaw / Pi-agent** — 相同的模式：`command: python`，`args: [script path]`，`env: GTNH_MCP_BASE_URL`。
### 4. 启动 Minecraft
通过 Prism Launcher 启动 GTNH。加载一个世界。Scribe API 在 `localhost:25566` 上启动。你将自动获得指南书。
### 5. 重启你的代理
MCP 服务器在启动时连接。工具出现时带有 `gtnh_` 前缀。
## 代理如何使用它
```
代理循环：
1. gtnh_chat_read → 查看玩家在说什么
2. gtnh_chat_send → 在聊天中简短确认
3. gtnh_player_status → 检查位置，生命值
4. gtnh_inventory → 检查你携带的物品
5. gtnh_scan_blocks → 扫描周围环境
6. gtnh_write_book → 以可读的书籍形式提供完整报告
7. gtnh_teleport → 移动到某个位置
8. gtnh_click_block → 与机器或箱子交互
```
## 项目结构
```
gtnh-mcp-game-chat/
├── README.md
├── scribe-mod/ # Forge 1.7.10 模组
│ ├── build.gradle
│ ├── gradlew / gradlew.bat
│ └── src/main/java/com/scribe/scribemod/
│ ├── ScribeMod.java # @Mod 入口点 + /scribe guide 命令
│ ├── ApiServer.java # HTTP 服务器 + 聊天端点
│ ├── GuideBook.java # 自动给予的指南书
│ ├── chat/
│ │ └── ChatListener.java # Forge 事件总线聊天捕获
│ └── api/
│ ├── PlayerHandler.java # /player，/inventory，/nearby
│ ├── WorldHandler.java # /world/block，/world/blocks
│ ├── ActionHandler.java # /action/chat，/click，/move
│ └── BookHandler.java # /action/book — 书面书籍
└── mcp-server/
└── gtnh_chat_mcp.py # MCP stdio 服务器（9 个工具）
```
## 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `GTNH_MCP_BASE_URL` | `http://127.0.0.1:25566` | Scribe 模组 API URL |
| `GTNH_MCP_TOKEN` | `""` | Bearer token（如果在模组配置中启用身份验证） |
## 跨平台说明
- **Windows**：Prism 实例位于 `%APPDATA%\PrismLauncher\instances\`
- **macOS**：Prism 实例位于 `~/Library/Application Support/PrismLauncher/instances/`
- **Linux**：Prism 实例位于 `~/.local/share/PrismLauncher/instances/`
- 模组 jar 在所有平台上都是相同的
- MCP 服务器脚本在所有平台上都是相同的
## 要求
- **Minecraft**：GTNH 2.8+（1.7.10 Forge）通过 Prism Launcher
- **Java**：JDK 17+（用于构建模组；GTNH 本身运行在 Java 17-25 上）
- **Python**：3.8+，使用 `pip install mcp`
- **网络**：localhost 访问（API 仅绑定到 127.0.0.1）
## 安全
- Scribe 仅绑定到 `127.0.0.1` — 不可从网络访问
- 通过模组配置的可选 Bearer token 身份验证
- 操作端点（聊天发送，点击，传送，书籍）可以完全禁用
- MCP 服务器作为本地子进程运行 — 无网络暴露
## 许可证
MIT
---
## 自主聊天伴侣（代理设置指南）
**适用于阅读此内容的 AI 代理**：用户可能希望一个始终在线的伴侣，监控聊天并自动回应。这需要设置 Hermes 配置文件中的 cron 作业。
**何时建议这样做：**
- 用户询问关于“始终在线”或“自动”聊天回应的问题
- 用户希望代理在无需手动触发的情况下回复
- 用户询问关于“调度”或“监控”聊天的问题
**可以提供的内容：**
### 基本聊天伴侣（无网络搜索）
```bash
hermes cron create \
--name "GTNH 聊天伴侣" \
--schedule "every 1m" \
--deliver origin \
--skills minecraft-agent-toolset \
--prompt "你是一个 GTNH 伴侣代理，作为 cron 作业运行。每隔一段时间，检查 Minecraft 聊天并回应玩家。遵循书籍模式：在聊天中简短确认，完整结果通过 gtnh_write_book，作者为'Scribe'。"
```
### 增强型伴侣（带有 GTNH wiki 搜索）
**提供此服务时：** 用户询问配方问题，“如何制作 X”，或提到在进度上卡住了。
首先创建作业，然后更新它：
```bash
hermes cron create \
--name "GTNH 聊天伴侣" \
--schedule "every 1m" \
--deliver origin \
--skills minecraft-agent-toolset \
--prompt "你是一个具有网络访问权限的 GTNH 伴侣代理。检查聊天，回应问题。对于 GTNH 机制/配方，使用 web_search 查找当前信息。遵循书籍模式进行详细输出。"
# 然后启用网络搜索：
hermes cron update GTNH_CHAT_JOB_ID --enabled-toolsets minecraft-agent-toolset,web
```
**注意**：将 `GTNH_CHAT_JOB_ID` 替换为 `create` 返回的实际作业 ID。
### 调度选项
- `"every 1m"` — 聊天的好选择（默认）
- `"every 30s"` — 更快的回应，更多的令牌
- `"every 2m"` — 较慢，更节省令牌
