# minecraft-paper-mcp

MCP server สำหรับจัดการหลังบ้าน Paper Minecraft server — รันบนเครื่องเดียวกับตัว Minecraft server
(เข้าถึงไฟล์และสั่ง process ได้ตรงๆ) ควบคู่กับคำสั่งในเกมผ่าน RCON

## ความสามารถ

- **ควบคุม process**: `server_start`, `server_stop`, `server_restart`, `server_status`
- **RCON / คำสั่งในเกม**: `rcon_command` (คำสั่งดิบใดๆ), `players_list`, `server_tps`, `server_say`,
  `player_kick`, `player_ban`, `player_pardon`, `player_op`, `player_deop`,
  `whitelist_add`, `whitelist_remove`, `give_item`, `teleport_player`,
  `set_gamerule`, `set_weather`, `set_time`
- **อ่านไฟล์**: `whitelist_list`, `ops_list`, `banned_players_list`, `banned_ips_list`,
  `server_properties_get`, `server_properties_set` (ต้อง restart ถึงจะมีผล)
- **Log**: `logs_tail` (ดู log ล่าสุด N บรรทัด), `logs_search` (grep ด้วย regex)

## ติดตั้ง

ต้องมี Node.js 18 ขึ้นไป

```bash
cd minecraft-mcp
npm install
npm run build
```

## เตรียม Paper server

1. เปิด RCON ใน `server.properties` ของ Paper server:

   ```properties
   enable-rcon=true
   rcon.port=25575
   rcon.password=ใส่รหัสผ่านที่ตั้งเอง_อย่าใช้ค่าว่าง
   ```

2. **สำคัญ**: ถ้า RCON port เปิดสู่ภายนอกได้ ต้องปิดกั้นด้วย firewall — RCON ไม่ได้เข้ารหัส
   ควรให้ฟังเฉพาะ `127.0.0.1` (ค่าเริ่มต้น) ถ้า MCP server รันเครื่องเดียวกัน

3. Restart Paper server หนึ่งครั้งให้ค่า RCON มีผล

## ตั้งค่า environment variables

มีไฟล์ `.env.example` ให้อ้างอิง — คัดลอกเป็น `.env` แล้วใส่ค่าจริง (ไฟล์ `.env` ถูกใส่ใน
`.gitignore` แล้ว จะไม่ถูก commit ขึ้น GitHub) ตัว MCP server เองไม่ได้โหลด `.env` อัตโนมัติ
(ไม่ได้ใช้ dotenv) — ตั้งค่าผ่าน `env` ใน `claude_desktop_config.json` หรือ export ตัวแปรก่อนรันจริง
`.env` มีไว้เป็นที่จดค่าให้ตัวเองเท่านั้น


| ตัวแปร | ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|
| `MC_SERVER_DIR` | current dir | path ไปยังโฟลเดอร์ของ Paper server (ที่มี `paper.jar`, `server.properties` ฯลฯ) |
| `MC_START_COMMAND` | `java -Xmx4G -Xms2G -jar paper.jar nogui` | คำสั่งสำหรับ start server (ปรับ RAM/ชื่อ jar ตามจริง) |
| `MC_RCON_HOST` | `127.0.0.1` | host ของ RCON |
| `MC_RCON_PORT` | `25575` | port ของ RCON |
| `MC_RCON_PASSWORD` | *(ว่าง)* | รหัสผ่าน RCON — ต้องตั้งให้ตรงกับ `server.properties` |
| `MC_PID_FILE` | `<MC_SERVER_DIR>/.mc-server.pid` | ไฟล์เก็บ PID ของ process ที่ start ไว้ |

## ตั้งค่าใน Claude Desktop

เพิ่มใน `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "minecraft-paper": {
      "command": "node",
      "args": ["/absolute/path/to/minecraft-mcp/build/index.js"],
      "env": {
        "MC_SERVER_DIR": "/absolute/path/to/paper-server",
        "MC_START_COMMAND": "java -Xmx6G -Xms2G -jar paper-1.21.jar nogui",
        "MC_RCON_PASSWORD": "รหัสผ่านเดียวกับใน server.properties"
      }
    }
  }
}
```

แล้ว restart Claude Desktop

## CI

มี GitHub Actions workflow (`.github/workflows/build.yml`) ที่รัน `npm install` + `npm run build`
บน Node 18.x และ 20.x ทุกครั้งที่ push หรือเปิด PR เข้า `main` เพื่อเช็คว่าโปรเจกต์ build ผ่าน
ถ้าต้องการใช้ `npm ci` แทน `npm install` ให้รัน `npm install` ในเครื่องตัวเองครั้งหนึ่งเพื่อสร้าง
`package-lock.json` แล้ว commit ไฟล์นั้นเข้า repo ก่อน

## หมายเหตุ / ข้อควรระวัง

- `server_start`/`server_restart` จะ spawn process แบบ detached แล้วเก็บ PID ไว้ใน `MC_PID_FILE`
  — ถ้าจะรันเป็น service จริงจัง (systemd) ก็ยังใช้ได้ แต่ตัว MCP จะไม่รู้จัก process ที่ systemd
  สร้างเอง ให้เลือกวิธีใดวิธีหนึ่ง (ให้ MCP นี้เป็นคน start/stop เอง หรือให้ systemd คุมแล้วใช้แค่ tool
  ที่พึ่ง RCON/ไฟล์)
- `server_stop` จะพยายามส่งคำสั่ง `stop` ผ่าน RCON ก่อน (graceful) ถ้าต่อ RCON ไม่ได้จะ fallback
  เป็น `SIGTERM`
- `server_properties_set` แก้ไฟล์ตรงๆ ต้อง restart server เองถึงจะมีผล (ไม่ auto-restart ให้)
- คำสั่ง ban/kick/whitelist ทำผ่าน RCON ไม่ได้แก้ไฟล์ json ตรงๆ — ปลอดภัยกว่าเวลา server กำลังรันอยู่