DevStar

Quarkus Coding Agent Tooling Workgroup

Rethinking how AI coding agents interact with Quarkus at dev time

Dev UI Dev MCP Dev Shell Dev Assistant Continuous Testing

Dev UI — The Foundation

Extensions expose functionality via JsonRPC services. Dev UI renders them in the browser.

Dev UI

Browser

WebSocket

Dev UI Runtime

JsonRPCRouter

→

JsonRPCService (runtime)

BuildTimeAction (deployment)

Every extension can contribute pages, actions, and data to Dev UI

Dev MCP — Adding AI Agents

AI agents connect to the same JsonRPC backend via streamable HTTP — same tools, new consumer.

Dev UI

Browser

WebSocket

AI Agent

Claude, Copilot, ...

Streamable HTTP

Dev UI Runtime + Dev MCP

JsonRPCRouter

→

JsonRPCService

BuildTimeAction

All running inside the Quarkus process

Two Tracks of Work

The DevStar workgroup is tackling this from two directions

🔧 Quarkus 4 — Dev UI refactor Break Dev UI into smaller components so the JsonRPC backend can be reused independently. Dev MCP and Dev Shell can run without Dev UI.

Breaking for extensions Not yet started

🚀 Agent MCP — standalone server A separate MCP server that runs outside the Quarkus process. Manages lifecycle, skills, docs, and proxies to Dev MCP.

Nearly ready Quarkus 3.35+

Current State

Everything lives inside the running Quarkus process — tightly coupled to Dev UI Runtime

Dev UI

Browser

AI Agent

Claude, Copilot

WebSocket

Streamable HTTP

Quarkus Process

All components tightly coupled to Dev UI Runtime

Dev UI Runtime

Dev MCP

JsonRPCRouter

Dev Shell

Dev Assistant

Quarkus Docs

Extension JsonRPCService

Extension BuildTimeAction

⚠ App not running = no tools, no docs, no shell

Quarkus 4 — Planned Refactor

Break apart into independent runtimes, each with its own transport — connected via CDI

Dev UI

Browser

AI Agent

Claude, Copilot

Dev Shell

Terminal

Agent MCP

stdio

WebSocket

Streamable HTTP

CDI

stdio

Dev UI
Runtime

WebSocket

Dev MCP
Runtime

Streamable HTTP

Dev Shell
Runtime

CDI

Dev JsonRPC Runtime

JsonRPCRouter

Extension Services

Quarkus Docs

Quarkus Agent MCP

AI-Powered Quarkus Development

An MCP server that lets AI coding agents create, manage, and develop Quarkus applications

Claude Code GitHub Copilot Cursor Windsurf

Dev MCP — Not Enough

Quarkus ships a Dev MCP server at /q/dev-mcp — but it has significant limitations

🚫 Only when the app is running Dev MCP lives inside the Quarkus process — no app, no tools. Can't scaffold, can't recover from crashes.

💥 Too many tools at once Exposes every Dev UI method as a tool. Agents get overwhelmed by a flat list of 50+ tools with no context.

🧠 Tools without knowledge Agents can call tools but don't know when or why. No skills, no patterns, no best practices.

📖 No documentation access Agents can't search Quarkus guides or API docs — they rely on stale training data instead.

The Solution

🧠 Purpose-built MCP server Tools, skills, and docs designed specifically for Quarkus development

🛡 Standalone process Runs separately from the app — survives crashes, manages lifecycle

🔗 Agent-agnostic Works with any MCP-compatible agent via stdio protocol

📚 Extension skills + semantic docs Teaches agents the right patterns, with version-aware documentation search

Architecture

AI Agent

Claude Code · Copilot · Cursor · Windsurf

MCP (stdio)

Quarkus Agent MCP

Standalone process — always running

Create Lifecycle Skills Docs Proxy Update

HTTP · JSON-RPC

Dev MCP

Running Quarkus app
/q/dev-mcp

JDBC · pgvector

Doc Search

pgvector container
BGE embeddings

The Tools

🏗 Scaffolding

quarkus/create scaffold & auto-start

🔄 Lifecycle

quarkus/start dev mode

quarkus/stop graceful shutdown

quarkus/restart force restart

quarkus/status instance state

quarkus/logs recent output

quarkus/list all instances

🧠 Intelligence

quarkus/skills extension patterns

quarkus/updateSkill customize skills

quarkus/searchDocs semantic doc search

🔧 Dev Integration

quarkus/searchTools discover dev tools

quarkus/callTool invoke dev tools

quarkus/update version check

Workflow — New Project

quarkus/create → Scaffolds project & auto-starts in dev mode

quarkus/skills → Load extension-specific patterns & pitfalls

quarkus/searchDocs → Look up APIs, config, and best practices

Write code + tests

quarkus/callTool → Run tests, reload, add extensions

Update README.md

Workflow — Existing Project

quarkus/update → Check version & suggest upgrades via subagent

quarkus/start → Start in dev mode if not running

quarkus/skills → Load extension patterns before coding

Write code + tests

quarkus/callTool → Test & reload

How Skills Work

Three-layer chain — each layer can enhance (append) or override (replace) the previous

Project-level skills

.quarkus/skills/{ext}/SKILL.md

Team conventions & project-specific patterns

ENHANCE / OVERRIDE

User-level skills

~/.quarkus/skills/{ext}/SKILL.md

Personal customizations & extension dev testing

ENHANCE / OVERRIDE

JAR skills (baseline)

quarkus-extension-skills artifact from Maven Central

Ships with Quarkus — curated by extension authors

BASELINE

Default is enhance — add project rules without losing built-in guidance. Use mode: override for full replacement.
Agents can use quarkus/updateSkill to create customizations interactively.

Skill Anatomy

Extension developers write plain Markdown. The build composes it with metadata into a full skill.

Extension developer writes

deployment/.../META-INF/quarkus-skill.md

        <!-- Just plain Markdown, no frontmatter -->

        ### REST Endpoints

        - Annotate with @Path, @GET, @POST

        - Return RestResponse<T> for type-safe responses

        ### Testing

        - Use @QuarkusTest + REST Assured

        ### Common Pitfalls

        - Resources default to @Singleton

runtime/.../quarkus-extension.yaml

          name: "REST"

          description: "Build RESTful web services..."

          metadata:

            guide: "https://quarkus.io/guides/rest"

→

aggregate
-skills

Composed output SKILL.md

META-INF/skills/quarkus-rest/SKILL.md

        ---  ← YAML frontmatter added by build

        name: "quarkus-rest"

        description: "Build RESTful web services..."

        license: "Apache-2.0"

        metadata:

          guide: "https://quarkus.io/guides/rest"

        ---

        ### REST Endpoints

        - Annotate with @Path, @GET, @POST

        - Return RestResponse<T> for type-safe responses

        ### Testing

        - Use @QuarkusTest + REST Assured

        ### Common Pitfalls

        - Resources default to @Singleton

Doc Search — Semantic Search

Query "how to add REST endpoint"

→

      BGE Embeddings
      384-dim vectors
    

→

      pgvector
      Similarity search
    

→

Results Ranked docs

📦

Pre-indexed docs — Quarkus documentation in a Docker container, ready to search

🎯

Version-aware — Matches container image to your project's Quarkus version

🔍

Synonym expansion — 28 mappings: db → datasource auth → authentication orm → hibernate

⬆

Metadata boosting — Re-ranks results by title and path relevance

Dev MCP Proxy

Agent MCP proxies to the running Quarkus app's built-in Dev MCP server

AI Agent quarkus/searchTools
quarkus/callTool

→ MCP stdio

Agent MCP Discovers & proxies
tool invocations

→ JSON-RPC

Running App /q/dev-mcp

Example Dev Tools

devui-testing_runTests devui-testing_runTest devui-extensions_add devui-config_getAll devui-exceptions_getLastException devui-logstream_forceRestart

Filter by query: testing extension config exception

Key Design Decisions

🛡

Standalone Process

Survives app crashes. Agent MCP keeps running even when the Quarkus app fails.

⏳

Lazy Initialization

pgvector container starts on first doc search. No upfront cost if not needed.

🎯

Version-First

Docs, skills, and containers are all version-aware. Matches your project exactly.

For Extension Developers

How to make your extension work great with AI agents

Build a Quarkus app using Agent MCP with your extension

Use a small model — if it works with a budget LLM, it works everywhere Haiku GPT-4o mini

Note what the agent gets wrong — wrong patterns, missed conventions, bad defaults

SKILL.md → Enhance the skill to fix those mistakes. Ask the agent to use quarkus/updateSkill — it adds your rules on top of the base skill.

Dev MCP → Check Dev MCP tools — does the agent use them? What's missing or needs changing?

PR against Quarkus — add the skill + Dev MCP changes upstream

Demo Time

Let's see it in action

Create a new Quarkus app from a natural language prompt
Watch skills guide the agent through extension-first development
See semantic doc search find relevant Quarkus guides
Run tests via Dev MCP proxy without leaving the conversation
Hot reload and iterate in real time

Thank You

Questions?

GitHub quarkusio/quarkus-agent-mcp

Working Group Quarkus DevStar

Install jbang quarkus-agent-mcp@quarkusio