内容
# TypeWriter MCP
适用于 [Typewriter](https://typewriter.gg/) Minecraft 插件的 MCP 服务器。它允许 Cursor、Claude Desktop 等 MCP 客户端读取和编辑故事线：页面、对话、事实、触发器和整个入口图。
您可以实时连接到正在运行的服务器，也可以通过 websocket 进行离线编辑页面 JSON 文件。
## 功能
Typewriter 将故事内容存储为页面和入口。网页编辑器适合手动操作，但当您需要代理创建整个分支、修复对话或连接多个入口的触发器时，速度会很慢。该服务器将这些数据公开为 MCP 工具，以便助手可以为您进行编辑。
在套接字模式下，它使用与官方网页编辑器相同的协议。更改首先进入暂存区，在面板中显示，然后可以发布到生产环境，而不会影响您在其他地方打开的工作。
## 模式
**套接字（推荐用于实时服务器）**
通过 websocket 连接到正在运行的插件。适用于生产环境和任何您希望在更改生效前在网页面板中可见的设置。
**文件（离线）**
直接编辑 `plugins/Typewriter/pages/*.json` 文件。在服务器关闭或您想要批量编辑文件并稍后重新加载时很有用。保存后在服务器上运行 `/typewriter reload`。
## 安装
```bash
git clone https://github.com/yurchik228336/TypeWriter-MCP.git
cd TypeWriter-MCP
npm install
npm run build
```
需要 Node.js 18+。
## Cursor / Claude Desktop 配置
将以下内容添加到您的 MCP 配置文件（适用于 Cursor：`~/.cursor/mcp.json`）：
```json
{
"mcpServers": {
"typewriter": {
"command": "node",
"args": ["C:/path/to/TypeWriter-MCP/dist/index.js"],
"env": {
"TYPEWRITER_MODE": "socket",
"TYPEWRITER_URL_FILE": "C:/path/to/TypeWriter-MCP/.typewriter-session-url"
}
}
}
}
```
使用此设置，服务器以套接字模式启动并等待连接 URL。 当您想要实时工作时，在游戏中运行 `/typewriter connect` 并将完整链接粘贴到聊天中。代理调用 `connect_live` 并在会话的其余时间保持套接字打开。 在该连接仍然有效时，您不需要再次粘贴链接。
如果您更喜欢在配置文件中设置固定 URL：
```json
"env": {
"TYPEWRITER_MODE": "socket",
"TYPEWRITER_URL": "http://host:8080/#/connect?host=1.2.3.4&port=9092&token=<uuid>"
}
```
注意：使用 `auth: session` 时，该令牌在生成它的玩家注销时过期。
**文件模式：**
```json
"env": {
"TYPEWRITER_MODE": "file",
"TYPEWRITER_PAGES_DIR": "C:/server/plugins/Typewriter/pages"
}
```
## Typewriter 插件设置（套接字）
1. 在 `plugins/Typewriter/config.yml` 中启用 websocket：
```yaml
enabled: true
websocket:
port: 9092
auth: session
```
编辑配置文件后重启服务器。
2. 在游戏中，运行 `/typewriter connect`。您将获得一个 URL，例如：
```
http://host:8080/#/connect?host=1.2.3.4&port=9092&token=<uuid>
```
3. 将该 URL 粘贴到您的代理或设置在 `TYPEWRITER_URL` 中。
纯 websocket URL 也有效：`ws://host:9092?token=<uuid>`
对于受信任的本地网络，您可以设置 `auth: none` 并跳过令牌。仅在您知道自己正在公开的内容时才这样做。
## 典型代理工作流程
1. 启动实时会话时粘贴连接 URL。
2. `list_pages` / `read_page` 查看已存在的内容。
3. `create_page`、`add_entry`、`connect_entries` 构建或扩展故事。
4. `validate_storyline` 捕获损坏的触发器引用。
5. `publish` 应用暂存更改（仅限套接字模式）。
如果会话断开或令牌过期，请发送新的连接 URL。
## 示例提示
将这些粘贴到 Cursor 或 Claude Desktop 中，当 Typewriter MCP 连接时。对于实时工作，请在第一个消息中包含您的连接 URL。
**连接和检查**
```
这是我的 Typewriter 连接 URL：http://host:8080/#/connect?host=1.2.3.4&port=9092&token=...
连接到服务器并列出所有页面。告诉我已经存在哪些故事线。
```
```
读取名为“chapter1”的页面，并总结每个对话条目以及触发器如何连接。
```
**创建新故事线**
```
使用此 URL 连接：...
创建一个名为“village_npcs”的静态页面，其中包含一个名为 Mira 的村民的 simple_speaker 条目。
然后创建一个名为“village_intro”的序列页面，其中包含 Mira 的 spoken_dialogue。
使用 connect_entries 连接对话流程，并在完成后运行 validate_storyline。
发布更改。
```
```
在页面“chapter2”中添加一个新的 option_dialogue，包含两个选项：
1）“我会帮助你”-> 设置永久_fact “agreed_to_help”
2）“现在不行”-> 结束对话
将选项链接到正确的后续条目。
```
**编辑现有内容**
```
搜索所有页面中的文本“旧任务名称”，并将所有匹配的对话行更新为“新任务名称”。
不要更改条目 ID 或触发器链接。
```
```
在页面“main_quest”上，找到黑smith 发言的条目，并将他的台词更改为：
“我们需要矿山的铁。给我十个锭，我会给你丰厚的奖励。”
```
**调试和验证**
```
在整个项目上运行 validate_storyline 并修复任何可以解决的损坏的触发器引用，而无需猜测缺少的条目。
显示您所做的更改。
```
```
搜索引用 fact id “abc123”的条目并列出使用它的页面。
```
**文件模式（离线）**
```
使用文件模式，读取 plugins/Typewriter/pages 下的所有内容。
创建一个名为“side_quest_rat”的新序列页面，其中包含三个 spoken_dialogue 条目：start、middle、reward。
保存文件。我将在服务器上运行 /typewriter reload。
```
## 工具
| 工具 | 描述 |
|------|-------------|
| `connection_status` | 当前模式、连接状态、保存的 URL |
| `connect_live` | 使用 `/typewriter connect` URL 连接 |
| `list_pages` | 列出页面（ID、名称、类型、条目数量） |
| `read_page` | 按名称或 ID 读取整个页面 |
| `create_page` | 创建页面（`sequence`、`static`、`cinematic`、`manifest`） |
| `rename_page` | 重命名页面 |
| `delete_page` | 删除页面及其所有条目 |
| `add_entry` | 添加条目（对话、演讲者、事实等） |
| `update_entry` | 更新一个字段通过点路径（`text`、`speaker`、`criteria.0.value`） |
| `replace_entry` | 替换条目，保持相同的 ID |
| `delete_entry` | 按 ID 删除条目 |
| `connect_entries` | 在两个条目之间追加触发器链接 |
| `search_entries` | 跨所有页面的全文搜索 |
| `validate_storyline` | 在触发器 / triggeredBy 中查找损坏的引用 |
| `publish` | 发布暂存到生产环境（仅限套接字模式） |
## 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `TYPEWRITER_MODE` | `socket` | `socket` 或 `file` |
| `TYPEWRITER_URL` | — | 可选的固定连接 URL |
| `TYPEWRITER_URL_FILE` | `.typewriter-session-url` in cwd | 存储最后一个连接 URL 的位置 |
| `TYPEWRITER_PAGES_DIR` | `plugins/Typewriter/pages` | 文件模式的页面目录 |
## 许可证
MIT。您可以随意使用：个人项目、服务器、分支、商业工作，无需获得许可。参见 [LICENSE](LICENSE)。
## 无关联
这是一个非官方的社区工具。Typewriter 由其自己的团队开发；这个 MCP 只是在 websocket 和文件格式方面进行通信。
