quarkus-mcp-server-sse — GitHub Copilot rule for Quarkus
This rule guides development of Quarkus MCP servers, from tool methods to project structure. Use it in Java projects with a Quarkus MCP Server extension.
.github/instructions/quarkus-mcp-server-sse.instructions.mdWhat quarkus-mcp-server-sse does
The rule applies to Java source files and Quarkus settings in application.properties, application.yml, and application.yaml. It targets Java 21 and Quarkus, recommending Streamable HTTP through mcp-server-http; HTTP/SSE remains an option for existing projects. For a new server, it points to mcp-server-http rather than the legacy mcp-server-sse, which is absent from recent Quarkus platform BOMs.
Its guidance separates MCP tools, services, and repositories, and calls for constructor injection, immutable Record models, and public @Tool methods in CDI beans. Tool methods should validate inputs and return error messages instead of null. Expected business failures should use ToolCallException; business logic belongs in the service layer, not in the tool method.
This rule is intended for projects that use a Quarkus MCP Server extension. Starting a new project with mcp-server-sse can make the Quarkus CLI fall back to an older platform stream, so the recommended HTTP extension matters when choosing the setup.
What it helps with
- organize a Quarkus MCP server into tool, service, and repository layers
- define MCP tools as CDI bean methods with
@Tool - handle expected tool failures with
ToolCallException - validate tool inputs and cover edge cases
Example prompts for the agent
- Create a Java 21 Quarkus MCP server using Streamable HTTP and follow this rule.
- Move this MCP tool's business logic into the service layer, keeping the tool method focused on the call.
- Review the
@Toolmethods for input validation and expected business errors handled withToolCallException.
How to install quarkus-mcp-server-sse
Manually: put the files in place
.github/instructions/quarkus-mcp-server-sse.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.claude/rules/quarkus-mcp-server-sse.mdThe paths frontmatter field limits the files: move applyTo from the source into paths
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/quarkus-mcp-server-sse.mdcFrontmatter: description, globs, alwaysApply. Move applyTo from the source into globs, or the rule will not attach on its own
Manually: put the files in place
.devin/rules/quarkus-mcp-server-sse.mdManually: put the files in place
.clinerules/quarkus-mcp-server-sse.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about quarkus-mcp-server-sse
How do I install quarkus-mcp-server-sse in GitHub Copilot?
Add .github/instructions/quarkus-mcp-server-sse.instructions.md to your repository.
What does quarkus-mcp-server-sse do?
It sets development conventions for Quarkus MCP servers, including code structure, tool methods, and error handling.
Which transport should I use for a new Quarkus MCP server?
The rule recommends Streamable HTTP with mcp-server-http. HTTP/SSE is retained for existing projects, while mcp-server-sse is absent from recent Quarkus platform BOMs.
Source text
quarkus-mcp-server-sse.instructions.md · MIT
--- applyTo: '**/*.java, **/application*.properties, **/application*.yml, **/application*.yaml' description: 'Quarkus MCP Server development standards and instructions, with Streamable HTTP (preferred) and legacy HTTP SSE transports' --- # Quarkus MCP Server Apply these instructions only when the project uses a Quarkus MCP Server extension (`mcp-server-http`, or the legacy `mcp-server-sse`). Build MCP servers with Java 21, Quarkus, and Streamable HTTP transport (legacy HTTP SSE is also supported). ## Stack - Java 21 with Quarkus Framework - MCP Server Extension: `mcp-server-http` (`io.quarkiverse.mcp:quarkus-mcp-server-http`), which serves both transports: legacy HTTP/SSE at `http://localhost:8080/mcp/sse` and Streamable HTTP (preferred; SSE is deprecated in the MCP spec) at `http://localhost:8080/mcp` - `mcp-server-sse` is not managed by recent Quarkus platform BOMs (verified: absent from 3.40.1); the Quarkus CLI silently falls back to an older platform stream when asked for it. Use it only to keep an existing project that already depends on it. - CDI for dependency injection ## Quick Start ```bash quarkus create app --no-code -x rest-client-jackson,qute,mcp-server-http your-domain-mcp-server ``` ## Structure - Use standard Java naming conventions (PascalCase classes, camelCase methods) - Organize in packages: `model`, `repository`, `service`, `mcp` - Use Record types for immutable data models - State management for immutable data must be managed by repository layer - Add Javadoc for public methods ## MCP Tools - Must be public methods in `@ApplicationScoped` CDI beans - Use `@Tool(name="tool_name", description="clear description")` - Never return `null` - return error messages instead - Always validate parameters and handle errors gracefully ## Architecture - Separate concerns: MCP tools → Service layer → Repository - Use constructor injection (`@Inject` is optional on a single constructor) - Make data operations thread-safe - Use `Optional<T>` to avoid null pointer exceptions ## Common Issues - Don't put business logic in MCP tools (use service layer) - For expected business errors throw `io.quarkiverse.mcp.server.ToolCallException` (its message becomes a failed tool result); don't let other unhandled exceptions escape, as they are reported as generic internal errors - Don't forget to validate input parameters - Test with edge cases (null, empty inputs)
© github · MIT · github/awesome-copilot
