Skip to main content
Glama
Java Project Runner MCP

Java Project Runner MCP

README.md
# Java Project Runner MCP (v1.3.1)

Single-process MCP server (stdio) that builds and manages **registered** Spring Boot + Maven projects on **macOS, Linux, and Windows**: list / inspect / build / start / stop / restart / status / logs / registry CRUD / reclaim.

Distributed via **GitHub only** (no npm publish). Prefer `npx` so clients fetch and build automatically.

**Locked behavior**

- Start runs the configured JAR via `java -jar` — not `spring-boot:run`
- Before start: Maven `package` (default) **unless** the JAR is fresher than `pom.xml` + `src/**` sources, or `skipBuild` is set; use `rebuild: true` to force package
- Prefer `./mvnw` when executable; otherwise system `mvn`
- `-DskipTests` default **on** (configurable per call / registry)
- Stop targets the **managed process tree only** (POSIX process group, or Windows `taskkill /T`) — never by port / main-class
- Maven Wrapper: `./mvnw` on Unix, `mvnw.cmd` / `mvnw.bat` on Windows; else system `mvn`
- Registry: hand-edit `~/.java-project-runner/projects.json` **or** use `project_register` / `project_update` / `project_unregister`
- **Same home** by default: multiple MCP clients (e.g. Cursor + Claude Code) may share `~/.java-project-runner`; mutating ops use per-project file locks (`locks/<id>.lock`) and return `BUSY` if contended
- Optional `JAVA_PROJECT_RUNNER_HOME` (absolute path) overrides the data root if you need an isolated home

## Requirements

- Node.js **20+** (LTS)
- macOS, Linux, or Windows
- JDK + Maven (or project Maven Wrapper) for the projects you register

## Install

### Recommended: `npx` from GitHub (no local clone)

Cursor / Claude Code `mcp.json` — first launch downloads the repo and runs `prepare` → `npm run build`:

```json
{
  "mcpServers": {
    "java-project-runner": {
      "command": "npx",
      "args": [
        "-y",
        "github:vinsmoke-sanji59/java-project-runner-mcp"
      ]
    }
  }
}
```

Requires Node.js **20+** on `PATH`. First run is slower; later runs use the npx cache.

Pin a tag/commit if you want a fixed version, e.g. `github:vinsmoke-sanji59/java-project-runner-mcp#v1.3.1`.

### Optional: clone for development

```bash
git clone https://github.com/vinsmoke-sanji59/java-project-runner-mcp.git
cd java-project-runner-mcp
nvm use 20   # if you use nvm
npm install   # also runs prepare → build
npm test
npm run dev   # TypeScript via tsx
```

Or point MCP at a local build:

```json
{
  "mcpServers": {
    "java-project-runner": {
      "command": "node",
      "args": ["/absolute/path/to/java-project-runner-mcp/dist/index.js"]
    }
  }
}
```

## Registry

Create or edit `~/.java-project-runner/projects.json` by hand, or use the register/update tools:

```json
{
  "projects": [
    {
      "id": "order-service",
      "name": "Order Service",
      "path": "/Users/you/ws/order-service",
      "jarPath": "target/order-service-0.0.1-SNAPSHOT.jar",
      "javaHome": "/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home",
      "skipTests": true,
      "defaultProfile": "local",
      "profiles": ["local", "dev"],
      "jvmArgs": ["-Xmx512m"],
      "healthCheckUrl": "http://127.0.0.1:8080/actuator/health",
      "stopTimeoutSeconds": 15,
      "enabled": true
    }
  ]
}
```

Notes:

- `id` must be a single safe path segment: 1–64 chars, start/end alphanumeric; middle may include `.` `_` `-`; no `..` or path separators.
- `path` must exist and contain `pom.xml` (enforced on register/update).
- `jarPath` may be a concrete relative path or a single-glob filename such as `target/*.jar` (exactly one non-`sources`/`javadoc` match).
- `healthCheckUrl` must be loopback (`127.0.0.1` / `localhost` / `::1`).
- State / logs / locks live under `~/.java-project-runner/state/`, `logs/<id>/`, and `locks/<id>.lock` (or under `JAVA_PROJECT_RUNNER_HOME` if set).

## MCP tools

| Tool | Purpose |
|------|---------|
| `project_list` | List registered projects |
| `project_inspect` | pom / wrapper / jar resolvability / config |
| `project_register` | Add a project to the registry |
| `project_update` | Patch an existing project (id immutable) |
| `project_unregister` | Remove a project (refuses if running/unknown) |
| `project_build` | Maven build |
| `project_start` | Smart package → `java -jar` (`rebuild` / `skipBuild` optional) |
| `project_stop` | SIGTERM → wait → SIGKILL on managed pgid |
| `project_force_stop` | Fingerprint-gated stop; requires `confirm: true`; allowed for `unknown` |
| `project_reclaim` | Re-verify PID fingerprint after MCP restart |
| `project_restart` | stop then start under one lock |
| `project_status` | One or all runtime states |
| `project_logs` | Tail stdout/stderr (max 200 lines) |

### Start build flags

| Flag | Effect |
|------|--------|
| _(none)_ | Skip Maven if resolved JAR mtime ≥ newest of `pom.xml` and `src/**` (`.java`/`.xml`/`.yml`/`.yaml`/`.properties`); else `package` |
| `rebuild: true` | Always Maven before start |
| `skipBuild: true` | Never Maven; JAR must already resolve |
| both true | `INVALID_ARGS` |

Response includes `buildSkipped` and `buildSkipReason` (`jar_fresh` | `skipBuild_flag` | `null`).

## Cursor / Claude Code config

Prefer the **Install → Recommended `npx`** block above in `~/.cursor/mcp.json` or Claude Code `.mcp.json`.

Local clone / absolute `node dist/index.js` is fine for development. For local TypeScript iteration:

```json
{
  "mcpServers": {
    "java-project-runner": {
      "command": "npx",
      "args": [
        "tsx",
        "/absolute/path/to/java-project-runner-mcp/src/index.ts"
      ],
      "cwd": "/absolute/path/to/java-project-runner-mcp"
    }
  }
}
```

## Safety

- Only `enabled` registry projects can be built/started/stopped.
- Paths are realpath-checked against the project root.
- `spawn(..., { shell: false })` only; goals / profiles / `jvmArgs` are whitelisted.
- After MCP server restart, unverified PIDs become `unknown` (pid retained for reclaim/force_stop) — the server will **not** blind-kill them.
- `project_force_stop` requires `confirm: true` and a matching `java -jar` cmdline fingerprint.
- Multiple MCP clients may share the same home; overlapping ops on one project return `BUSY` instead of corrupting state.

## License

MIT

TDQS

A3.5/5.0

Scored across 13 tools

Disambiguation4/5

Most tools target clearly distinct lifecycle operations (register/list/inspect/build/start/stop/restart/status/logs). The main possible confusion is between start and restart, and between stop and force_stop, but the descriptions make the distinctions explicit enough for an agent.

Naming Consistency5/5

Every tool follows the same project_<verb/action> snake_case convention, with predictable verb choices. There is no mixing of casing or naming styles.

Tool Count5/5

With 13 tools, the set is well-scoped for a Java project runner: registry management, build, runtime lifecycle, status, logs, and recovery operations each have a clear place. No tool appears redundant or excessive.

Completeness5/5

The surface covers the full lifecycle: register, list, inspect, update, unregister, build, start, stop, restart, status, logs, plus force-stop and PID reclaim recovery operations. No obvious operational dead ends remain for the stated purpose.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues