# Run Server

> Provision and run a LOCAL Paper test server to verify the plugin actually loads. Use this when the user wants to test/run/try the plugin in a real server, spin up a local server, deploy the jar and watch it load, or confirm it enables without errors. Downloads the matching Paper build via the PaperMC API, deploys the built jar, boots the server briefly, and reads the log. Reads the stack from .mcplugin/config.yml.

- Skill: `itamarb2010-jpg/run-server` (Agent Skill)
- Install (CLI): `npx skillmds@latest add itamarb2010-jpg/run-server`
- Raw SKILL.md: https://api.skillmd.com/api/skills/itamarb2010-jpg/run-server/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: itamarb2010-jpg (https://skillmd.com/u/itamarb2010-jpg)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/itamarb2010-jpg/run-server

---


# Run a local test server

Prove the plugin loads by booting a real Paper server matching the target `mc_version`, deploying
the jar, and watching the log for the enable line. This skill takes **heavier, real-world
actions** (downloading a server jar, running a Java server, accepting a license) — get explicit
consent before doing them.

## Phase 1: Load context & confirm a jar exists

- Read `.mcplugin/config.yml` for `mc_version`, `version_scheme`, `java_version`, `platform`,
  `plugin_name`, `artifact_id`, `plugin_version`. Missing → tell the user to run `/setup-platform`.
- `Glob` for the built plugin jar (`target/<artifact_id>-<plugin_version>.jar` or
  `build/libs/*.jar`). **If none exists**, stop and tell the user to run **`/build`** first
  (offer to hand off). If `platform` is `velocity`/`bungeecord`, note this skill boots a Paper
  *server* — a proxy needs a different setup — and confirm they still want a Paper test.
- Read `../../references/api/VERSION.md` for version facts (`Glob` `**/references/api/VERSION.md`
  as fallback).

## Phase 2: Get explicit consent (REQUIRED)

Use `AskUserQuestion`. Two things need a clear yes:
1. **Download + run a server** — "I'll download a Paper {{mc_version}} server jar (~50 MB) into a
   local `run/` folder and start it briefly on this machine. OK to proceed?"
2. **EULA** — writing `eula.txt` with `eula=true` means **you are accepting Mojang's EULA**
   (https://aka.ms/MinecraftEULA). "Do you accept the Minecraft EULA?" Do **not** write the file
   or start the server until the user confirms both. If they decline the EULA, stop here.

## Phase 3: Prepare `run/`

- Create a `run/` directory in the project root and `run/plugins/`.
- Ensure `run/` is **gitignored** (it holds a big server jar, worlds, logs). If `.gitignore`
  lacks it, `Edit` in a `run/` line. Never commit the server jar or worlds.

## Phase 4: Download the matching Paper build

Use the PaperMC downloads API. **Verify the current endpoint with `WebFetch` before hardcoding**
— the 2026 year-based scheme may be served by a newer API (a v3 may exist); check
https://docs.papermc.io/misc/downloads-api (or https://papermc.io/downloads/paper) for the target.

Classic v2 flow (works for 1.21.x; confirm for 26.x):
1. Builds for the version: `WebFetch`
   `https://api.papermc.io/v2/projects/paper/versions/{{mc_version}}/builds` — take the last
   entry (highest `build`), and its `downloads.application.name` (e.g. `paper-1.21.4-131.jar`).
2. Download URL:
   `https://api.papermc.io/v2/projects/paper/versions/{{mc_version}}/builds/{build}/downloads/{name}`

Download into `run/` (choose by OS):
- bash/macOS/Linux: `curl -fsSL -o run/paper.jar "<url>"`
- Windows PowerShell: `Invoke-WebRequest -Uri "<url>" -OutFile run/paper.jar`
- (`curl` also ships on modern Windows if the user prefers one command.)

If the API returns 404 for the version, tell the user Paper has no build for that exact
`mc_version` and suggest the nearest available one.

## Phase 5: Accept EULA & deploy the jar

- After consent (Phase 2), `Write` `run/eula.txt` containing exactly:
  ```
  eula=true
  ```
- Copy the built plugin jar into `run/plugins/` (`cp` / `Copy-Item`). Verify it landed (`Glob`
  `run/plugins/*.jar`).

## Phase 6: Boot the server briefly, then stop it

Start Paper with the **Java that matches `java_version`** (a mismatch here reproduces
`UnsupportedClassVersionError`). Run it **in the background / time-boxed** — never leave a server
running. Pipe a `stop` in so it shuts down cleanly, or launch in background and stop after the
enable line appears:

- bash/macOS/Linux (from `run/`):
  `(sleep 45; echo stop) | java -Xmx2G -jar paper.jar --nogui`
- Windows PowerShell (from `run/`):
  `$p = Start-Process java -ArgumentList '-Xmx2G','-jar','paper.jar','--nogui' -PassThru -NoNewWindow; Start-Sleep 45; if(!$p.HasExited){ Stop-Process $p }`

Prefer launching with `run_in_background` and polling the log, so you can stop as soon as startup
completes rather than always waiting the full window. First boot downloads vanilla assets and
generates a world — allow up to ~60–90s.

## Phase 7: Read the log & report

Read `run/logs/latest.log` (`Grep`). Look for:
- **Success:** a line like `[... INFO]: [{{plugin_name}}] Enabling {{plugin_name}} v...` and a
  final `Done (…)! For help, type "help"` with no stack traces.
- **Failure signals:** `Could not load 'plugins/...'`, `UnsupportedClassVersionError` (Java
  mismatch — recheck `java_version`), `Invalid plugin.yml` / `main class not found` (descriptor),
  `ClassNotFoundException` (unshaded dependency). Map each back to `../../references/pitfalls.md`.

Report plainly whether the plugin **loaded and enabled**, quoting the relevant log lines. If it
failed, give the specific fix and suggest `/build` (rebuild) or `/plugin-review`. Confirm the
server was stopped. Leave `run/` in place for the next test unless the user wants it cleaned.