quarkus-mcp-server-example

Quarkus MCP 服务示例

这是一个全面的示例，演示如何使用 Quarkus 构建 Model Context Protocol（MCP）服务，将 REST API 操作公开为 AI 工具。借助 Goose CLI，大模型（例如 Claude）可以通过自然语言与应用数据交互。

🎯 本示例展示的内容

本项目展示了三项强大技术的集成：

• Quarkus：用于构建现代应用的超音速、亚原子级 Java 框架
• MCP（Model Context Protocol）：用于将 AI 助手连接到数据源和工具的开放标准
• Goose CLI：可与 MCP 服务交互的 AI 驱动开发助手

📋 目录

• 什么是 MCP？
• 什么是 Quarkus？
• 什么是 Goose？
• 解决方案架构
• 前提条件
• 运行示例
• 使用示例

🔗 什么是 MCP？

Model Context Protocol（MCP） 是一项开放标准，使 AI 助手能够安全地连接并与各种数据源和工具交互。MCP 无需为每种 AI 助手构建定制集成，而是提供了一种通用协议，用于：

• 工具发现：AI 助手可以发现有哪些工具可用
• 工具执行：安全地在外部系统上执行操作
• 数据访问：从各种来源检索和操作数据
• 标准化：一套实现即可适用于任何兼容 MCP 的 AI 助手

MCP 的优势

• 互操作性：适用于任何兼容 MCP 的 AI 助手
• 安全性：受控访问外部资源
• 可扩展性：轻松添加新工具和功能
• 标准化：无需为每种 AI 助手定制集成

⚡ 什么是 Quarkus？

Quarkus 是一个面向 Kubernetes 的 Java 框架，专为现代应用开发而设计：

• 快速启动：启动时间不到一秒
• 低内存占用：针对容器化环境进行了优化
• 开发体验出色：实时重新加载、统一配置和优秀的工具支持
• 云原生：专为 Kubernetes、无服务器架构和微服务构建
• 基于标准：采用熟悉的 Java 标准（JAX-RS、CDI、JPA）

用于 MCP 的 Quarkus

Quarkus 非常适合构建 MCP 服务，因为它具备以下优势：

• 快速开发：借助实时重新加载，实现快速反馈循环
• 轻量级：工具服务的资源占用极低
• 原生编译：借助 GraalVM 实现超快启动
• 丰富的生态系统：提供大量数据库、REST 客户端等扩展

🦆 什么是 Goose？

Goose 是一个 AI 驱动的开发助手 CLI，可通过以下方式帮助开发者：

• 自然语言界面：使用通俗的英语与开发环境交互
• MCP 集成：连接 MCP 服务以访问外部工具和数据
• 上下文感知：理解项目结构和代码库
• 工具执行：可以执行命令、修改文件并与 API 交互
• 多模型支持：支持包括 Claude、GPT 等在内的各种大模型

Goose 与 MCP 配合使用

结合 MCP 服务后，Goose 可以：

• 通过自然语言查询数据库
• 与 REST API 交互，无需手动运行 curl 命令
• 通过组合多个工具执行复杂操作
• 根据应用数据提供智能洞察

🏗️ 解决方案架构

┌─────────────────────────────────────────────────────────────────────────────┐
│                           MCP Integration Flow                               │
└─────────────────────────────────────────────────────────────────────────────┘

    ┌─────────────┐    MCP Protocol     ┌─────────────────┐    REST API    ┌──────────────┐
    │             │   (JSON-RPC over    │                 │   (HTTP/JSON)  │              │
    │    Goose    │◄───────────────────►│   Quarkus MCP   │◄──────────────►│   Quarkus    │
    │     CLI     │     STDIO/SSE)      │     Server      │                │ Applications │
    │             │                     │                 │                │      MS      │
    └─────────────┘                     └─────────────────┘                └──────────────┘
           │                                      │                               │
           │                                      │                               │
    ┌──────▼──────┐                        ┌─────▼─────┐                 ┌───────▼───────┐
    │             │                        │           │                 │               │
    │   Claude    │                        │ MCP Tools │                 │  PostgreSQL   │
    │     LLM     │                        │           │                 │   Database    │
    │             │                        │ • list    │                 │               │
    └─────────────┘                        │ • get     │                 └───────────────┘
                                           │ • filter  │
                                           │ • add     │
                                           └───────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                              Data Flow                                      │
└─────────────────────────────────────────────────────────────────────────────┘

1. User asks Goose: "Show me all applications from Spain"
                    ↓
2. Goose sends MCP request to discover available tools
                    ↓
3. MCP Server exposes tools: list_applications, get_applications_by_country, etc.
                    ↓
4. Goose calls get_applications_by_country("Spain") tool
                    ↓
5. MCP Server makes REST call to Applications MS
                    ↓
6. Applications MS queries PostgreSQL database
                    ↓
7. Results flow back through the chain to Goose
                    ↓
8. Goose presents results to user in natural language

组件职责

组件	用途	技术
Goose CLI	AI 助手界面、自然语言处理	Go、大模型集成
Quarkus MCP Server	协议桥接、工具定义	Quarkus、MCP 协议
Quarkus Applications MS	业务逻辑、数据操作	Quarkus、JAX-RS、Hibernate
PostgreSQL	数据持久化	关系型数据库

前置条件

运行此示例前，请确保已安装以下内容：

• Java 21：Quarkus 应用所需
• Maven：Java 项目的构建工具
• Podman/Docker：PostgreSQL 数据库的容器运行时
• Goose CLI：AI 助手工具（安装指南）

安装 Goose

# Using Go (requires Go 1.21+)
go install github.com/square/goose@latest

# Or download binary from releases
# https://github.com/square/goose/releases

🚀 运行示例

步骤 1：构建项目

mvn clean package

步骤 2：启动 PostgreSQL 数据库

podman run -d --name db-server \
  -e POSTGRES_USER=test \
  -e POSTGRES_PASSWORD=test \
  -e POSTGRES_DB=applications \
  -p 5432:5432 \
  postgres:16

步骤 3：启动 Applications 微服务

cd quarkus-applications-ms && mvn quarkus:dev

Applications 服务将在 http://localhost:8080 启动

步骤 4：（可选）添加示例数据

curl -i -X POST \
  -F "name=Angel" \
  -F "surname=Miralles" \
  -F "personalId=12345R" \
  -F "country=Spain" \
  http://localhost:8080/application.html

curl -i -X POST \
  -F "name=Juan" \
  -F "surname=Garcia" \
  -F "personalId=31234R" \
  -F "country=Spain" \
  http://localhost:8080/application.html
  
curl -i -X POST \
  -F "name=Pedro" \
  -F "surname=Rodriguez" \
  -F "personalId=54321R" \
  -F "country=Germany" \
  http://localhost:8080/application.html

步骤 5：启动带 MCP 服务的 Goose

goose session --with-extension="java -jar quarkus-mcp-server/target/quarkus-mcp-server-1.0.0-SNAPSHOT.jar"

💡 使用示例

启动带 MCP 服务的 Goose 后，你可以使用自然语言与应用数据交互：

基本查询

> Show me all applications in the system
> List applications from Spain
> Get application with ID 1

筛选查询

> Show me all applications from France with COMPLETED status
> List all STARTED applications
> Find applications from Germany

数据管理

> Add a new application for John Doe from USA with ID 67890
> Create an application for Maria Garcia from Mexico

可用的 MCP 工具

MCP 服务向 Goose 提供以下工具：

工具名称	描述	参数
list_applications	列出所有申请	无
get_application_by_id	获取指定申请	id: Long
get_applications_by_country	按国家筛选	countryName: String
get_applications_by_country_and_status	按国家和状态筛选	countryName: String、status: ApplicationStatus
add_application	创建新申请	application: Application

申请状态值

• STARTED
• PREPROCESSED
• PROCESSED
• COMPLETED
• CANCELED
• ERROR

🔧 开发

开发模式

# Start applications service in dev mode (hot reload)
cd quarkus-applications-ms && mvn quarkus:dev

# Package MCP server for testing
cd quarkus-mcp-server && mvn package

项目结构

quarkus-mcp-server-example/
├── quarkus-applications-ms/           # REST API microservice
│   ├── src/main/java/me/amiralles/applications/
│   │   ├── boundary/ApplicationsResource.java    # REST endpoints
│   │   ├── entity/Application.java               # JPA entity
│   │   └── control/ApplicationExceptionMapper.java
│   └── src/main/resources/application.properties
├── quarkus-mcp-server/                # MCP server
│   ├── src/main/java/me/amiralles/mcp/
│   │   ├── McpApplicationsServer.java            # MCP tools definition
│   │   ├── client/ApplicationsClient.java        # REST client
│   │   └── model/Application.java                # Data models
│   └── src/test/java/
└── deployment/docker-compose/         # Monitoring stack

🔗 参考资料

• Model Context Protocol (MCP)
• Quarkus 框架
• Quarkus MCP 扩展
• Goose CLI
• Claude AI

📄 许可证

本项目作为教育用途的示例提供。