research

Quarkus Agentic MCP 演示

本项目展示了一个基于 Quarkus（超音速、亚原子 Java 框架）和 Model Context Protocol (MCP) 构建的智能 Agent 应用。它将多个 MCP 服务与 Quarkus 和 LangChain4j 集成，打造出功能强大的 AI 助手，能够执行网络搜索、位置服务、文件管理和团队协作。

🌟 为什么要使用 Java、Quarkus 和 MCP 构建 Agentic AI 应用？

Java 在企业级 AI 中的优势

Java 仍是企业应用的中坚力量，如今也为 AI 革命做好了充分准备：

• 🏢 满足企业需求：借助 Java 成熟的生态系统、久经验证的可靠性和丰富的工具，满足企业的信赖
• 🔒 类型安全与安全性：强类型可在编译时发现错误，这对生产级 AI 系统至关重要
• ⚡ 性能：Quarkus 启动时间不到 1 秒，内存占用极低，非常适合云原生 AI 部署
• 🔄 无缝集成：将 AI 功能顺畅地连接到现有 Java 微服务、数据库和企业系统
• 👥 开发者人才：借助全球最大的开发者社区（超过 900 万 Java 开发者），为 AI 项目提供支持

为什么选择 Quarkus 开发 AI 应用？

Quarkus 是面向云原生 AI 工作负载打造的现代 Java 框架：

• ⚡ 极速运行：原生模式下启动时间约为 0.1 秒，优于传统 Java 框架
• 💾 高效利用内存：内存占用比传统 Java 技术栈少 10 倍，这对经济高效地部署 AI 至关重要
• 🔥 实时编码：开发过程中可即时热重载，立即查看 AI 行为的变化
• 📊 内置可观测性：开箱即用地集成 OpenTelemetry，监控 AI Agent 的决策
• 🐳 以容器为先：针对 Kubernetes、Docker 和无服务器平台进行了优化
• 🎯 让开发更愉悦：统一配置、开发者界面和扩展让 AI 开发效率更高

MCP 的优势

Model Context Protocol (MCP) 是构建 Agentic AI 的革新性方案：

• 🔌 标准化工具集成：通过统一协议连接任意服务（Slack、Google Maps、文件系统）
• 🧩 可组合架构：像搭积木一样组合 MCP 服务，无需编写自定义集成代码
• 🔄 可复用组件：MCP 服务可用于不同的 AI 模型和框架
• 🚀 快速开发：只需配置 MCP 服务即可添加新功能，无需编写集成代码
• 🌐 持续发展的生态系统：利用社区构建的 MCP 服务完成常见任务
• 🎭 支持多 Agent：借助共享上下文和工具协调多个 AI Agent

本演示展示的内容

本应用展示了 Java、Quarkus 和 MCP 的完美协同：

✅ 生产级 AI：利用 Java 的可靠性构建满足企业需求的 Agent 系统 ✅ 云原生性能：部署能够在毫秒内启动并高效扩展的 AI Agent ✅ 快速原型开发：借助实时编码，在几分钟内将创意转化为可运行的 AI Agent ✅ 真实场景集成：将 AI 连接到实际服务（Slack、Google Maps、文件系统） ✅ 可观测、易调试：通过内置遥测全面了解 AI 的决策过程 ✅ 面向未来：基于开放标准（MCP）和现代 Java（Quarkus）构建

真实使用场景

这种架构可支持强大的企业级 AI 场景：

• 🤖 智能助手：构建能够搜索网页、访问数据库并执行操作的聊天机器人
• 📊 数据分析 Agent：创建能够读取文件、查询 API 并生成报告的 AI
• 🔄 工作流自动化：开发能够协调多个系统（CRM、电子邮件、日历）的 Agent
• 🎯 客户支持：部署能够访问知识库、创建工单并升级问题的 AI
• 📈 商业智能：构建能够从多个来源收集数据并提供洞察的 Agent

归根结底：如果你正在为企业构建 AI 应用，Java + Quarkus + MCP 能让你兼具 Python 框架的性能与 Java 的可靠性和生态系统。

---

📋 目录

• 概述
• 先决条件
• 安装与设置
• 运行应用
• 测试应用
• 打包与部署
• 故障排除
• 其他资源

🎯 概述

此应用展示了：

• 使用 OpenAI 的 GPT 模型进行 AI 驱动的 Agent 推理
• 多个 MCP 服务集成：Brave Search、Google Maps、Slack、文件系统、memory 和 time
• 通过 WebSocket 提供的 实时聊天界面
• 基于 OpenTelemetry、Grafana 和 LGTM stack 的 内置可观测性
• 使用 Quarkus Dev Mode 进行 实时编码

⚙️ 先决条件

运行此应用前，请确保已安装以下软件：

必需软件

1. Java 21 或更高版本

   • 检查版本：java -version
   • 建议使用 SDKMAN! 管理 Java 版本
   • 此项目使用 Java 21（参见 .sdkmanrc）

   # Install SDKMAN (if not already installed)
   curl -s "https://get.sdkman.io" | bash
   
   # Install Java 21
   sdk install java 21.0.2-tem
   sdk use java 21.0.2-tem
   

2. Maven 3.9+

   • 检查版本：./mvnw --version
   • 项目中包含 Maven wrapper（mvnw）

3. Node.js 和 npm

   • MCP 服务进程需要使用
   • 检查版本：node --version 和 npm --version
   • 建议使用 Node.js 18+ 和 npm 9+
   • 从 nodejs.org 安装，或使用 nvm

   # Using nvm (recommended)
   nvm install --lts
   nvm use --lts
   

4. Python 3.8+（用于 time MCP 服务）

   • 检查版本：python3 --version
   • 安装 MCP time 服务：

   pip3 install mcp-server-time
   

5. 容器运行时（可选，但建议安装）

   • Docker Desktop、Podman 或类似工具
   • 内置遥测/可观测性功能（Grafana、LGTM stack）需要此运行时
   • 如果无法使用，请参阅禁用遥测

API 密钥

你需要以下服务的 API 密钥：

服务	用途	获取 API 密钥
OpenAI	LLM 聊天模型（GPT-4o-mini）	platform.openai.com
Brave Search	网页搜索功能	brave.com/search/api
Google Maps	位置和路线	Google Maps API
Slack	团队消息集成	Slack MCP 设置

Slack 注意事项：你需要 Bot User OAuth Token（以 xoxb- 开头）和 Team ID。请按照设置说明创建 Slack 应用并获取这些凭据。

🚀 安装与设置

1. 克隆仓库

git clone <repository-url>
cd quarkus-agentic-mcp

2. 创建 Playground 目录

文件系统 MCP 服务需要一个 playground 目录：

mkdir -p playground

你也可以创建一个示例团队文件：

mkdir -p playground/calendar
echo "Daniel Oh - Likes Italian food" > playground/team.txt
echo "Colleague - Gluten-free diet" >> playground/team.txt

3. 配置 API 密钥

在项目根目录中创建一个 .env 文件（此文件已添加到 .gitignore 中）：

touch .env

将 API 密钥添加到 .env 文件中：

# OpenAI Configuration
quarkus.langchain4j.openai.api-key=sk-proj-xxxxxxxxxxxxxxxxxxxxx

# Brave Search API Key
quarkus.langchain4j.mcp.bravesearch.environment.BRAVE_API_KEY=BSAxxxxxxxxxxxxxxxxxxxxx

# Google Maps API Key
quarkus.langchain4j.mcp.googlemaps.environment.GOOGLE_MAPS_API_KEY=AIzaxxxxxxxxxxxxxxxxxxxxx

# Slack Configuration
quarkus.langchain4j.mcp.slack.environment.SLACK_BOT_TOKEN=xoxb-xxxxxxxxxxxxxxxxxxxxx
quarkus.langchain4j.mcp.slack.environment.SLACK_TEAM_ID=Txxxxxxxxxxxxx

⚠️ 安全警告：切勿将 .env 文件提交到版本控制系统。对于生产部署，请使用 HashiCorp Vault、Kubernetes Secrets 或云服务提供商的密钥管理器等安全的密钥管理解决方案。

4. 验证 MCP 服务依赖项

启动应用程序时，它会通过 npm 自动下载 MCP 服务软件包。若要验证 npm 是否可以访问这些软件包：

# Test npm access
npm view @modelcontextprotocol/server-filesystem version
npm view @modelcontextprotocol/server-memory version
npm view @modelcontextprotocol/server-brave-search version
npm view @modelcontextprotocol/server-google-maps version
npm view @modelcontextprotocol/server-slack version

5. 禁用遥测（可选）

如果没有可用的容器运行时，请注释掉 src/main/resources/application.properties 中的以下几行，以禁用遥测：

# Comment out these lines if no container runtime is available:
# %dev.quarkus.otel.exporter.otlp.traces.endpoint=http://localhost:4317
# %dev.quarkus.otel.exporter.otlp.traces.headers=authorization=Bearer my_secret
# %dev.quarkus.datasource.jdbc.telemetry=true
# %dev.quarkus.otel.logs.enabled=true
# %dev.quarkus.otel.traces.enabled=true

或者在 .env 文件中设置此项：

quarkus.observability.enabled=false

🏃 运行应用程序

开发模式（推荐）

以开发模式启动应用程序并启用实时重新加载：

./mvnw compile quarkus:dev

启动期间会发生什么：

• Maven 编译 Java 代码
• Quarkus 在端口 8080 上启动应用程序
• 通过 npm/python 自动启动 MCP 服务
• Dev Services（如 LGTM stack）在容器中启动（如果可用）
• 启用实时重新加载，以便即时应用代码更改

访问入口：

• 主应用程序：http://localhost:8080
• Dev UI：http://localhost:8080/q/dev/
• Grafana（启用遥测时）：可通过 Dev UI → Observability 访问

首次启动

首次运行可能需要更长时间，因为它会：

1. 下载 Maven 依赖项
2. 下载 MCP 服务的 npm 软件包
3. 启动 Dev Services 容器
4. 编译应用程序

之后启动会快得多。

验证应用程序是否正在运行

你应该会看到类似以下内容的输出：

__  ____  __  _____   ___  __ ____  ______
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
INFO  [io.quarkus] (Quarkus Main Thread) research 1.0-SNAPSHOT on JVM (powered by Quarkus 3.36.0) started in 3.456s. Listening on: http://localhost:8080
INFO  [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.
INFO  [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, langchain4j-mcp, langchain4j-openai, ...]

🧪 测试应用程序

Web 界面

应用程序运行后，在浏览器中打开 http://localhost:8080。你会看到一个聊天界面，可以在其中与 AI 助手交互。

示例提示词

尝试使用以下提示词，看看 Agent 如何进行推理和使用工具：

复杂的多步骤任务

My name is Daniel Oh. I am a member of a team of 2. I like Italian food, while my colleague is on a strict gluten-free diet.

Please find one good restaurant in Boston, MA with the highest rating that meets the team's dietary needs and preferences.
Then, invite the team to a lunch at 12pm next Friday. In your message, include the name and description of the restaurant,
the time and date of the lunch, and driving directions from Back Bay, Boston.

此示例展示了：

• 从 playground/team.txt 读取团队信息（filesystem MCP）
• 搜索餐厅（Brave Search MCP）
• 查询位置和路线（Google Maps MCP）
• 计算日期和时间（Time MCP）
• 记忆对话上下文（Memory MCP）

后续任务

发送初始提示词后，尝试以下后续提示：

Send the restaurant recommendation details to the slack channel "#lunchtime".

Create an ICS calendar file for me in my calendar in the "playground/calendar" directory.

推理与反思提示词

What was the reasoning you used to arrive at that recommendation?

How did you choose the restaurant?

What actions did you take for each step and which tools did you use?

Why did you search for gluten-free restaurants?

What do you remember about each person on the team based on team.txt file?

使用 Dev UI

Quarkus Dev UI 提供了更多测试功能：

1. 访问 http://localhost:8080/q/dev/
2. 转到 Extensions → LangChain4j → Chat
3. 你会看到从 Bot.java 预先填入的系统消息
4. 开始与 AI 助手聊天

Dev UI 功能：

• 查看所有可用的 MCP 工具
• 监控请求/响应日志
• 访问 Grafana 仪表板（启用遥测时）
• 热重载代码更改
• 查看应用程序指标

可观测性

如果已启用遥测（且容器运行时可用）：

1. 转到 Dev UI → Observability
2. 点击 Grafana 链接
3. 查看跟踪记录、日志和指标
4. 查看大模型请求/响应详情
5. 监控 MCP 服务交互

📦 打包与部署

标准 JVM 软件包

构建标准 JVM 软件包：

./mvnw package

这会创建 target/quarkus-app/quarkus-run.jar，并将依赖项放在 target/quarkus-app/lib/ 中。

运行打包后的应用程序：

# Ensure API keys are set as environment variables
export OPENAI_API_KEY="your-key-here"
export BRAVE_API_KEY="your-key-here"
export GOOGLE_MAPS_API_KEY="your-key-here"
export SLACK_BOT_TOKEN="your-token-here"
export SLACK_TEAM_ID="your-team-id"

# Run the application
java -jar target/quarkus-app/quarkus-run.jar

Uber JAR 软件包

构建包含所有依赖项的单个可执行 JAR：

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

运行 uber JAR：

java -jar target/research-1.0-SNAPSHOT-runner.jar

原生可执行文件

构建原生可执行文件，以加快启动速度并减少内存占用：

选项 1：本地已安装 GraalVM

# Ensure GraalVM is installed and GRAALVM_HOME is set
./mvnw package -Dnative

选项 2：使用容器构建（推荐）

# No GraalVM installation required
./mvnw package -Dnative -Dquarkus.native.container-build=true

运行原生可执行文件：

# Set environment variables
export OPENAI_API_KEY="your-key-here"
# ... (other API keys)

# Run
./target/research-1.0-SNAPSHOT-runner

原生构建的优势：

• ⚡ 启动时间：约 0.1 秒（JVM 约为 3 秒）
• 💾 内存使用量：约 50 MB（JVM 约为 200 MB）
• 📦 单个可执行二进制文件
• 🚀 非常适合容器和无服务器环境

注意：原生构建耗时较长（5-10 分钟），但会生成高度优化的可执行文件。

容器部署

构建容器镜像：

# Using Docker
docker build -f src/main/docker/Dockerfile.jvm -t quarkus-agentic-mcp:jvm .

# Or for native
docker build -f src/main/docker/Dockerfile.native -t quarkus-agentic-mcp:native .

运行容器：

docker run -i --rm -p 8080:8080 \
  -e OPENAI_API_KEY="your-key" \
  -e BRAVE_API_KEY="your-key" \
  -e GOOGLE_MAPS_API_KEY="your-key" \
  -e SLACK_BOT_TOKEN="your-token" \
  -e SLACK_TEAM_ID="your-team-id" \
  quarkus-agentic-mcp:jvm

🔧 故障排除

常见问题

1. “Cannot find node or npm”

问题：由于找不到 Node.js/npm，MCP 服务无法启动。

解决方案：

# Verify installation
node --version
npm --version

# If not installed, install Node.js
# macOS (using Homebrew)
brew install node

# Linux (using nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

2. “Python3 not found”或 Time MCP Server 启动失败

问题：Time MCP 服务需要 Python 3。

解决方案：

# Install Python 3
# macOS
brew install python3

# Install the MCP time server
pip3 install mcp-server-time

# Verify
python3 --version
python3 -m mcp_server_time --help

3. API 密钥错误

问题：“Unauthorized”或“Invalid API key”错误。

解决方案：

• 确认 .env 文件存在且包含有效密钥
• 检查密钥中是否有多余的空格或引号
• 确保 .env 文件位于项目根目录
• 更新 .env 后重启应用程序

4. 端口 8080 已被占用

问题：另一个应用程序正在使用端口 8080。

解决方案：

# Find what's using the port
lsof -i :8080

# Kill the process or change Quarkus port
# Add to .env:
quarkus.http.port=8081

5. 容器/Docker 问题

问题：遥测功能无法启动。

解决方案：

• 确保 Docker/Podman 正在运行：docker ps
• 或禁用遥测（参见禁用遥测）

6. MCP 服务连接失败

问题：“Failed to connect to MCP server”错误。

解决方案：

# Test npm package access
npm view @modelcontextprotocol/server-filesystem

# Clear npm cache if needed
npm cache clean --force

# Verify playground directory exists
ls -la playground/

7. 内存不足错误

问题：应用程序因 OutOfMemoryError 崩溃。

解决方案：

# Increase JVM heap size
./mvnw compile quarkus:dev -Djvm.args="-Xmx2g"

调试模式

启用详细日志以便排查问题：

添加到 .env：

quarkus.log.level=DEBUG
quarkus.log.category."io.quarkiverse.langchain4j".level=DEBUG
quarkus.log.category."dev.langchain4j".level=DEBUG

获取帮助

• Quarkus 文档：https://quarkus.io/guides/
• LangChain4j Quarkus：https://docs.quarkiverse.io/quarkus-langchain4j/dev/
• MCP 文档：https://modelcontextprotocol.io/
• GitHub Issues：在代码仓库中报告错误或提问

📚 其他资源

文档

• Quarkus：https://quarkus.io/
• LangChain4j：https://docs.langchain4j.dev/
• Model Context Protocol：https://modelcontextprotocol.io/
• OpenAI API：https://platform.openai.com/docs/

关键技术

• Quarkus LangChain4j MCP Extension（指南）：MCP 客户端实现
• Quarkus LangChain4j OpenAI（指南）：OpenAI 集成
• Quarkus WebSockets：实时通信
• Quarkus OpenTelemetry：可观测性和追踪

使用的 MCP 服务

服务	用途	文档
filesystem	文件操作	npm
memory	对话记忆	npm
brave-search	网络搜索	npm
google-maps	位置服务	npm
slack	团队消息	npm
time	日期/时间操作	PyPI

项目结构

quarkus-agentic-mcp/
├── src/main/java/
│   ├── Bot.java              # AI assistant configuration
│   └── BotWebsocket.java     # WebSocket endpoint
├── src/main/resources/
│   ├── application.properties # Configuration
│   └── META-INF/resources/
│       └── index.html        # Web UI
├── playground/               # Filesystem MCP workspace
├── pom.xml                   # Maven dependencies
├── .env                      # API keys (create this)
└── README.md                 # This file

配置参考

application.properties 中的关键配置属性：

• 大模型：quarkus.langchain4j.openai.chat-model.model-name=gpt-4o-mini
• 温度：quarkus.langchain4j.openai.chat-model.temperature=0.8
• 超时：quarkus.langchain4j.openai.timeout=3m
• MCP 服务：quarkus.langchain4j.mcp.<server-name>.*

贡献

欢迎贡献！请：

1. Fork 此代码库
2. 创建功能分支
3. 进行修改
4. 提交拉取请求

许可证

[在此添加许可证信息]

---

使用 Quarkus、LangChain4j 和 Model Context Protocol 构建，倾注 ❤️