|
| 1 | +--- |
| 2 | +applyTo:'*' |
| 3 | +description:'Quarkus and MCP Server with HTTP SSE transport development standards and instructions' |
| 4 | +--- |
| 5 | +#Quarkus MCP Server |
| 6 | + |
| 7 | +Build MCP servers with Java 21, Quarkus, and HTTP SSE transport. |
| 8 | + |
| 9 | +##Stack |
| 10 | + |
| 11 | +- Java 21 with Quarkus Framework |
| 12 | +- MCP Server Extension:`mcp-server-sse` |
| 13 | +- CDI for dependency injection |
| 14 | +- MCP Endpoint:`http://localhost:8080/mcp/sse` |
| 15 | + |
| 16 | +##Quick Start |
| 17 | + |
| 18 | +```bash |
| 19 | +quarkus create app --no-code -x rest-client-jackson,qute,mcp-server-sse your-domain-mcp-server |
| 20 | +``` |
| 21 | + |
| 22 | +##Structure |
| 23 | + |
| 24 | +- Use standard Java naming conventions (PascalCase classes, camelCase methods) |
| 25 | +- Organize in packages:`model`,`repository`,`service`,`mcp` |
| 26 | +- Use Record types for immutable data models |
| 27 | +- State management for immutable data must be managed by repository layer |
| 28 | +- Add Javadoc for public methods |
| 29 | + |
| 30 | +##MCP Tools |
| 31 | + |
| 32 | +- Must be public methods in`@ApplicationScoped` CDI beans |
| 33 | +- Use`@Tool(name="tool_name", description="clear description")` |
| 34 | +- Never return`null` - return error messages instead |
| 35 | +- Always validate parameters and handle errors gracefully |
| 36 | + |
| 37 | +##Architecture |
| 38 | + |
| 39 | +- Separate concerns: MCP tools → Service layer → Repository |
| 40 | +- Use`@Inject` for dependency injection |
| 41 | +- Make data operations thread-safe |
| 42 | +- Use`Optional<T>` to avoid null pointer exceptions |
| 43 | + |
| 44 | +##Common Issues |
| 45 | + |
| 46 | +- Don't put business logic in MCP tools (use service layer) |
| 47 | +- Don't throw exceptions from tools (return error strings) |
| 48 | +- Don't forget to validate input parameters |
| 49 | +- Test with edge cases (null, empty inputs) |