Ashlar - 面向 Minecraft Paper 服务器的 AI 建造工具

工作原理

工具层完全在插件里。MCP 服务器只是一个薄适配器：启动时从插件拉取工具目录，然后转发调用——所以每个 AI 客户端和游戏内助手用的是完全相同的九个工具。

AI 客户端

Claude Desktop、Claude Code、OpenCode、Cursor——任何支持 MCP（stdio 或 HTTP）的客户端。

→

`ashlar-mcp`

由 npx -y ashlar-mcp 启动的 Node 进程，通过 WebSocket 连到插件；自身不含任何 Ashlar 逻辑。

→

Paper 插件

先完整校验每个请求，再在主线程上按每 tick 的时间预算写方块——50 万方块的建造进行中，服务器照常运行。

/ashlar 这条路径跳过前两个环节：插件自己通过出站 HTTPS 调用模型 API——不需要 Node，不需要开放入站端口。

九个工具

典型流程：mc_players → mc_survey 或 mc_render 看现场 → mc_snapshot → mc_build → mc_render/mc_inspect 检查 → 不满意就 mc_restore。

mc_status

服务器和插件状态、队列长度。

mc_players

在线玩家的位置、朝向和正在看的方块——"这里"、"我面前"、"那堵墙"。

mc_survey

地形勘查：高度图图片加精确数字（最低/最高/中位高度、地表材质构成、最大平地）。

mc_render

区域的 PNG 图：俯视、任一立面、剖面或高度图——让模型看到自己建了什么。

mc_build

批量放置：长方体填充（replace/keep/outline/hollow/walls）、单个方块、告示牌文字、流动的水。唯一会改动世界的工具。

mc_inspect

区域内精确的方块内容：统计、ASCII 剖面、逐列游程、告示牌文字。

mc_snapshot

动手之前先保存区域。

mc_restore

把区域回滚到某个快照。

mc_command

执行控制台命令并返回输出。除非服主明确开启，否则不会提供给游戏内助手。

为模型设计，不只是 API

写入时关闭物理，建到一半不会有东西掉落或脱落；建完后的连接处理让栅栏、玻璃板、墙和楼梯像手放的一样正确连接；任何缺少支撑的方块都会作为警告反馈给模型，模型要先修好再说"完成"。

处处有边界

每个请求在入队之前就完整校验：方块上限、区块上限、允许的世界、可选的建造区域。建造按 tick 预算执行，大填充花的是 tick 数而不是 TPS。快照让每次改动都可撤销。

安装

所有人都从装插件开始。之后有两种用法，可以只开一种，也可以都开。

安装插件（所有人）

把 ashlar-*.jar 放进 Paper 26.2+（Java 25）服务器的 plugins/，启动一次，它会生成 plugins/Ashlar/config.yml。

只在游戏内用：`/ashlar`

在 config.yml 里填一个模型 API key（agent.model.api-key，任何 OpenAI 兼容的 API 都行，比如 DeepSeek），重启。有 ashlar.use 权限的玩家就可以输入 /ashlar <需求>。

到此为止。不需要 Node，不需要 MCP 客户端，不需要开放端口——插件自己去调模型 API。

配合 AI 客户端（MCP）

想在 Claude Desktop、Claude Code、OpenCode、Cursor 之类的客户端里使用 Ashlar：在 config.yml 里设置 server.token 并开放 WebSocket 端口（默认 8765）；运行客户端的机器上要有 Node 22+；然后把 Ashlar 加进客户端的 MCP 配置——在下面选你的客户端。不用手动装任何东西，客户端会用 npx -y ashlar-mcp 启动 MCP 服务器。

客户端配置（只有 2b 需要）

{
  "mcpServers": {
    "ashlar": {
      "command": "/absolute/path/to/npx",
      "args": ["-y", "ashlar-mcp", "--stdio"],
      "env": {
        "MC_PLUGIN_URL": "ws://<你的服务器 IP>:8765",
        "MC_PLUGIN_TOKEN": "<config.yml 里的 token>"
      }
    }
  }
}

设置 → Developer → Edit Config。npx 要写绝对路径；连接器的工具访问选"Tools already loaded"。

claude mcp add --scope user --transport stdio ashlar \
  -e MC_PLUGIN_URL=ws://<你的服务器 IP>:8765 \
  -e MC_PLUGIN_TOKEN=<config.yml 里的 token> \
  -- npx -y ashlar-mcp --stdio

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ashlar": {
      "type": "local",
      "command": ["npx", "-y", "ashlar-mcp", "--stdio"],
      "environment": {
        "MC_PLUGIN_URL": "ws://<你的服务器 IP>:8765",
        "MC_PLUGIN_TOKEN": "<config.yml 里的 token>"
      },
      "timeout": 120000,
      "enabled": true
    }
  }
}

写在项目的 opencode.json 或全局的 ~/.config/opencode/opencode.json。里面带着 token，项目级文件别提交进 git。

MC_PLUGIN_URL=ws://127.0.0.1:8765 \
MC_PLUGIN_TOKEN=<插件 token> \
MCP_HTTP_TOKEN=<另一个足够长的随机 token> \
npx -y ashlar-mcp --http

MCP 服务器只跑一份，比如和面板托管的 Paper 服务器放在同一台 VPS 上；客户端连 https://mcp.example.com/mcp，带 Authorization: Bearer <MCP_HTTP_TOKEN>（不能设请求头的客户端用 /mcp/<token>）。前面加一层 TLS 反向代理，Caddy 一行就够。

国内面板服请在 MC_PLUGIN_URL 里填服务器 IP 而不是域名：有些机房会按 Host 头过滤 HTTP 请求，把 WebSocket 握手拦掉。

游戏内助手——不需要 AI 客户端

给服务器上那些不用 AI 客户端的玩家和朋友。插件自己和模型 API 对话：在 config.yml 里填一个 key，/ashlar 就对所有有权限的玩家可用。

<Steve> /ashlar 在我面前盖一间带玻璃窗的小石屋，门上挂个牌子写"家"
[Ashlar] > mc_survey from=[84,-232] to=[124,-192]
[Ashlar] > mc_snapshot
[Ashlar] > mc_build
[Ashlar] > mc_render from=[98,64,-220] to=[109,71,-211] view="south"
[Ashlar] 建好了：你北边那块平地上一间 12x9 的石砖小屋，橡木门朝南，四扇玻璃窗，牌子上写着"家"。想撤销就说恢复快照 snap-20260914-101532-7c2a。
[Ashlar] (本次请求: 318.4k tokens, $0.04 | 今日: $0.04，上限 $1.00)

agent:
  mode: embedded
  model:
    base-url: https://api.deepseek.com
    api-key: "sk-..."
    model: deepseek-flash
  limits:
    max-cost-per-player-per-day: 1.00
language: zh_CN   # 或 en，或 auto

任何 OpenAI 兼容的聊天 API 都可以。按玩家的每日请求数、token、花费上限；给想赞助的玩家充预付额度；/ashlar usage 按天查看用量。助手用玩家的语言回复；插件自身的聊天文字可选中文或英文。

可撤销

助手建造前先做快照，"撤销"就能恢复。支撑警告会反馈给模型，悬空的牌子、嵌在墙里的火把会在它说"完成"之前修好。

可控制

ashlar.use 权限或允许列表、每次请求的冷却和长度限制、建造区域围栏、附加到系统提示词的"服规"，以及需要时的 /ashlar pause。

有账可查

每次模型调用都计量：每请求、每玩家、每天的 token 和花费，支持峰谷价。服主用 /ashlar usage <玩家> 查看。

Claude 通过 Ashlar 建造的带玻璃窗的石头小屋 — "一间带玻璃窗的小石屋，门上挂个牌子"——勘查、快照、建造、渲染、回复。

组件	状态
Paper 26.2	已测试
Paper 26.3	已测试（同一个 jar）
Java	25（Paper 26.x 自身的要求）
Node	客户端机器上 22 或更新（`/ashlar` 不需要）
MCP 客户端	任何 MCP SDK v2 客户端：Claude Desktop、Claude Code、OpenCode、Cursor……
不支持	Minecraft 1.21.x 及更早、Folia、基岩版

面向 Minecraft Paper 服务器的 AI 建造工具