Quarkus MCP工具

Prerequisites

• Java 21+
• Docker or Podman (for documentation search)
• One of: Quarkus CLI, Maven, or JBang (for creating new projects)

Installation

Build from source

git clone https://github.com/quarkusio/quarkus-agent-mcp.git
cd quarkus-agent-mcp
./mvnw package -DskipTests -Dquarkus.package.jar.type=uber-jar

This produces the uber-jar at target/quarkus-agent-mcp-1.0.0-SNAPSHOT-runner.jar (version may vary).

claude mcp add quarkus-agent -- java -jar /path/to/quarkus-agent-mcp/target/quarkus-agent-mcp-1.0.11-runner.jar

Verify

After registering, ask your agent something like:

"Search the Quarkus docs for how to create a REST endpoint"

If the MCP server is working, the agent will use quarkus_searchDocs and return documentation results.

Building a Native Image

For instant startup (no JVM warmup):

./mvnw package -Dnative -DskipTests -Dquarkus.package.jar.type=uber-jar

Then reference the native binary in your MCP config:

claude mcp add quarkus-agent -- ./target/quarkus-agent-mcp-*-runner

Usage

Guides

• Creating Extension Skills - A practical guide for extension developers to discover, write, and test AI skills for their extensions

Configuration

Configuration via application.properties, system properties (-D), or environment variables:

`AccessDeniedException: C:\WINDOWS\system32\config` (Windows)

java.nio.file.AccessDeniedException: C:\WINDOWS\system32\config

This is a Quarkus core issue that occurs on Windows when the MCP server is launched by an IDE with the working directory set to system32. Quarkus scans {working-dir}/config for configuration files and hits the protected Windows registry hive directory.

Workaround: Set the working directory explicitly in your MCP config, or pass -Duser.dir to override it:

{
  "servers": {
    "quarkus-agent": {
      "type": "stdio",
      "command": "java",
      "args": ["-Duser.dir=C:\\Users\\you", "-jar", "C:\\path\\to\\quarkus-agent-mcp-runner.jar"]
    }
  }
}

MCP Tools Reference

Claude Code plugin

Add the marketplace and install the plugin:

claude plugin marketplace add quarkusio/quarkus-agent-mcp
claude plugin install quarkus-agent@quarkus-tools

This installs the plugin and configures the MCP server automatically. Requires JBang.

Development workflow

The MCP server guides the agent through the optimal Quarkus development workflow:

NEW PROJECT                           EXISTING PROJECT

1. quarkus_create                     1. quarkus_start
   → scaffolds + auto-starts             → starts dev mode
   → generates CLAUDE.md + .mcp.json
                                      2. quarkus_skills
2. quarkus_skills                        → learn extension patterns
   → learn extension patterns            → query 'quarkus-update' to check version
                                      3. quarkus_searchDocs
3. quarkus_searchDocs                    → look up APIs, config
   → look up APIs, config
                                      4. Write code + tests
4. Write code + tests
                                      5. Run tests
5. Run tests                             → quarkus_callTool
   → quarkus_callTool                    → devui-testing_runTests
   → devui-testing_runTests

6. Iterate

Key points:

• Hot reload is automatic in Quarkus dev mode — triggered on the next access (HTTP request or test run), not on file save.
• Skills before code — the agent reads extension-specific skills to learn correct patterns, testing approaches, and common pitfalls before writing any code.
• Tests via subagents — if your agent supports subagents, test execution can be dispatched to one so the main conversation stays responsive.
• The MCP server survives crashes — if the app crashes due to a code error, the agent can use devui-exceptions_getLastException to get structured exception details (class, message, stack trace, user code location) and fix it. Use quarkus_logs for broader context.
• CLAUDE.md — every new project gets a CLAUDE.md with Quarkus-specific workflow instructions that guide the agent.
• .mcp.json — every new project gets a .mcp.json for automatic MCP server discovery by agents that support the convention (Claude Code, Pi/pi.dev).

Extension skills

The agent can read extension-specific coding skills using quarkus_skills. Skills contain patterns, testing guidelines, and common pitfalls for each extension — things like "always use @Transactional for write operations with Panache" or "don't create REST clients manually, let CDI inject them."

When called without a query, skills are organized by category (Web, Data, Security, Core, etc.) for easier discovery.

Skills are loaded using a three-layer chain (most specific wins):

1. Extension skills — discovered from individual extension deployment JARs (META-INF/quarkus-skill.md) in the local Maven repository, composed with extension metadata and available Dev MCP tools. This supports skills from Quarkus core, Quarkiverse, and custom extensions. For older Quarkus versions that don't ship skill files in deployment JARs, the aggregated quarkus-extension-skills JAR is used as a fallback.
2. User-level skills — from ~/.quarkus/skills/<extension-name>/SKILL.md (or a directory configured via agent-mcp.local-skills-dir). Community workflow skills (e.g. Spring-to-Quarkus migration, project update checking) can be installed here using quarkus_installSkills. Also useful for extension developers testing new or modified skills without rebuilding the aggregated JAR.
3. Project-level skills — from .agent/skills/<extension-name>/SKILL.md in the project directory. These are standalone files read as-is (no composition with base layers), so any agent can read them directly from the filesystem. Use quarkus_saveSkill to materialize a fully composed skill into this directory, then edit the file directly.

Layers 1–2 support enhance and override composition, controlled by the mode field in the SKILL.md frontmatter:

• mode: enhance (default) — appends content to the base skill. The base content is preserved and the customization is added after a separator. This is ideal for adding personal conventions or standards without losing the built-in guidance.
• mode: override — fully replaces the base skill. Use this when you need complete control over a skill's content.

Layer 3 (project) always replaces — the file content is used directly with no composition.

The agent can create or update global skill customizations using quarkus_updateSkill (writes to ~/.quarkus/skills/). For project-level customization, use quarkus_saveSkill to materialize the full composed skill into .agent/skills/, then edit the file directly.

Extension Skills

Troubleshooting