jhipster-mcp

A Model Context Protocol (MCP) server that lets AI agents — Claude Code, Claude Desktop, Cursor, or any MCP-compatible host — drive the JHipster CLI to scaffold and evolve applications using JDL (JHipster Domain Language).

You describe the app or change you want; the agent translates it to JDL, validates it, and runs JHipster — while this server keeps every run non-interactive, sandboxed to a directory you name, and safe to preview before it writes.

📖 Documentation

Full user guide → docs/. If you know JHipster but are new to MCP, start there and read in order:

1. Introduction — what an MCP server is, and the tools / resources / prompts model.
2. Installation — connect it to your host.
3. Getting started — your first guided session.
4. Tools reference · 5. Resources · 6. Prompts
5. How the server manages context
6. Advanced usage & customization
7. How it works (engine)

Roadmap: docs/ROADMAP.md.

Quick start

Prerequisites: Node.js 20+ and a working global jhipster CLI on your PATH (npm install -g generator-jhipster). The server spawns your existing jhipster binary — it does not bundle the generator. Full details in Installation.

Claude Code

claude mcp add jhipster -- npx -y jhipster-mcp

Claude Desktop / Cursor / other hosts

Add this to your host’s MCP config (e.g. claude_desktop_config.json), then restart:

{
  "mcpServers": {
    "jhipster": {
      "command": "npx",
      "args": ["-y", "jhipster-mcp"]
    }
  }
}

Then ask your host something like “Create a JHipster monolith in /tmp/demo with a Product entity.” See Getting started for a full walkthrough and more examples.

What’s inside (at a glance)

• 13 tools — validate_jdl, create_app_from_jdl, import_jdl, add_entity, add_relationship, set_option, info, project_commands, upgrade_advisor, preview_upgrade, generate_ci_cd, generate_deployment, run_jhipster. (reference)
• Resources — the JDL grammar plus live project state (yo-rc, entities, exported jdl). (reference)
• Prompts — scaffold_crud_monolith, add_audit_fields, monolith_to_microservices. (reference)
• Safe by design — directory scoping, empty-dir guard, no shell, JDL-injection guards, and isolated preview/dryRun. (details)

Development

npm run dev         # tsup --watch
npm run typecheck   # tsc --noEmit
npm run build       # tsup → dist/index.js
npm test            # node --test + tsx
npm run test:watch  # tests in watch mode

CI runs typecheck, build, and tests on every push/PR to main via .github/workflows/ci.yml across Node 20/22/24 on Ubuntu and macOS. Architecture and conventions for contributors live in CLAUDE.md; the engine is also documented for users in docs/09-how-it-works.md.

Quick smoke test (lists tools over stdio):

(cat <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF
) | node dist/index.js

Releasing

The GitHub Release tag is the single source of truth for the version. Everything derives from it:

• The release workflow (.github/workflows/release.yml) reads the tag (e.g. v0.0.3), strips the v, and sets package.json to that version before building and publishing.
• The MCP server reports pkg.version at runtime (src/index.ts imports package.json, inlined at build) — so the published npm version, the tag, and the runtime version are always identical.

To cut a release:

1. On GitHub, go to Releases → Draft a new release.
2. Create a new tag named vX.Y.Z (semver, v-prefixed) targeting main, fill in the notes, and Publish release.

Publishing the release fires the release: published event, which triggers the workflow to:

1. check out the release tag and set package.json to X.Y.Z,
2. run build + test,
3. publish to npm via Trusted Publishing (OIDC) — no NPM_TOKEN secret; provenance is generated automatically (requires the Trusted Publisher to be configured on npmjs.com for this repo + workflow, and npm ≥ 11.5.1, which the workflow installs).

You don’t need to bump package.json in a commit beforehand — the workflow forces it to match the tag. (Optionally keep main’s package.json in step with npm version --no-git-tag-version X.Y.Z so local dev reports the right version, but it isn’t required for publishing.)

License

Licensed under the Apache License, Version 2.0.