使用说明

项目简介

本项目是一个基于 Quarkus 框架构建的 MCP (Model Context Protocol) 服务器实现，旨在创建一个简单的智能助手应用后端。它利用 LangChain4j 和 MCP 协议，集成了多种工具，为 LLM 客户端提供上下文感知和功能扩展能力。该项目展示了如何使用 Quarkus 构建高性能、可扩展的 MCP 服务器，并集成如 OpenAI、Brave Search、Google Maps 和 Slack 等外部服务，构建功能丰富的 Agentic 应用。

主要功能点

资源管理 (Resources): 虽然代码中未显式展示资源管理，但项目集成了多种外部服务（Brave Search, Google Maps, Slack），这些服务可以被视为通过 MCP 服务器提供的外部资源访问能力。
工具注册和执行 (Tools): 集成了 Brave 搜索引擎、Google Maps 地图服务、Slack 消息服务等多种工具，允许 LLM 客户端通过 MCP 服务器调用这些工具以扩展功能。
Prompt 模板 (Prompts): 通过 'Bot.java' 中的 '@SystemMessage' 注解定义了系统级 Prompt 模板，可以定制 LLM 的行为和交互模式。
WebSocket 通信: 使用 WebSocket 作为 MCP 服务器的传输协议，实现了实时的双向通信，客户端可以通过 WebSocket 与服务器进行交互。
会话管理: 使用 '@SessionScoped' 注解，表明 'Bot' 组件是会话级别的，服务器具备一定的会话管理能力。
能力声明: 通过集成的工具和服务，隐式地声明了服务器的能力，客户端可以根据服务器提供的工具列表来调用相应的功能。

安装步骤

环境准备:
- 确保已安装 JDK 17+ 和 Maven 3.8.1+。
- 建议安装 Node.js 和 npm，用于启动某些 MCP 服务（虽然本仓库本身是服务器，但 README 中提到可能需要，此处存疑，建议根据实际运行情况调整）。
- 可选：安装 Podman 或 Docker 以体验内置的遥测功能（Grafana）。

克隆仓库:

git clone https://github.com/jamesfalkner/quarkus-mcp-agentic.git
cd quarkus-mcp-agentic

API 密钥配置:

获取以下 API 密钥并记录：

在项目根目录下创建 '.env' 文件，并填入 API 密钥：

quarkus.langchain4j.mcp.bravesearch.environment.BRAVE_API_KEY=<YOUR BRAVE API KEY HERE>
quarkus.langchain4j.mcp.googlemaps.environment.GOOGLE_MAPS_API_KEY=<YOUR GMAPS API KEY HERE>
quarkus.langchain4j.mcp.slack.environment.SLACK_BOT_TOKEN=<YOUR SLACK BOT TOKEN HERE>
quarkus.langchain4j.mcp.slack.environment.SLACK_TEAM_ID=<YOUR SLACK TEAM ID HERE>
quarkus.langchain4j.openai.api-key=<YOUR OPENAI API KEY HERE>

或将密钥配置在 'application.properties' 文件中，但注意安全性，避免泄露。

创建 playground 目录 (可选):
- 如果需要使用文件系统 MCP 服务器功能（例如创建日历文件），需要在项目根目录下创建 'playground' 目录。

编译和运行服务器:

在项目根目录下执行 Maven 命令启动开发模式：

./mvnw compile quarkus:dev

或者打包并运行：

./mvnw package
java -jar target/quarkus-app/quarkus-run.jar

或者构建原生可执行文件并运行：

./mvnw package -Dnative
./target/quarkus-mcp-agentic-1.0-SNAPSHOT-runner # (可执行文件名可能略有不同)

服务器配置 (MCP 客户端配置)

以下 JSON 配置信息用于 MCP 客户端连接到此 Quarkus MCP 服务器。客户端需要根据 MCP 协议规范发送请求与服务器交互。

{
  "serverName": "quarkus-agentic-mcp-server",  // MCP 服务器名称，客户端用于标识和管理连接
  "command": "./target/quarkus-app/quarkus-run.jar", // 启动 MCP 服务器的命令 (如果打包成 jar 运行)
  "args": [], // 启动命令参数，本例中 jar 运行无需额外参数
  "protocol": "websocket", //  MCP 服务器使用的通信协议，本项目使用 WebSocket
  "address": "ws://localhost:8080/bot" // WebSocket 连接地址，客户端通过此地址与服务器建立连接
  // "baseUrl": "http://localhost:8080" // 如果服务器支持 HTTP 协议，可以配置 baseUrl
  // 其他可能的配置项，例如认证信息、超时设置等，根据 MCP 客户端和服务器的具体实现添加
}

注意:

上述 'command' 和 'args' 配置是针对打包成 'jar' 文件运行的情况。如果使用原生可执行文件，'command' 应指向原生可执行文件的路径，例如 '"./target/quarkus-mcp-agentic-1.0-SNAPSHOT-runner"', 'args' 保持为空即可。
'address' 为 WebSocket 连接地址，客户端需要通过此地址建立 WebSocket 连接。请确保服务器已成功启动并监听在 'localhost:8080' 的 '/bot' 路径。
如果 MCP 客户端支持 HTTP 协议，并且服务器也提供了 HTTP 端点（本例中可能存在，但 WebSocket 是主要的交互方式），可以配置 'baseUrl' 为 'http://localhost:8080'。

基本使用方法

启动 MCP 服务器: 按照上述安装步骤启动 Quarkus MCP 服务器。
启动 MCP 客户端: 配置 MCP 客户端，使其连接到 Quarkus MCP 服务器。客户端需要使用 JSON-RPC 协议，通过 WebSocket 或 HTTP (如果支持) 与服务器进行通信。
客户端发送请求: MCP 客户端根据 MCP 协议规范，向服务器发送 JSON-RPC 请求，例如：
- 请求读取资源
- 请求调用已注册的工具
- 请求获取 Prompt 模板
服务器处理请求并返回响应: Quarkus MCP 服务器接收客户端请求，根据请求类型进行处理，并返回 JSON-RPC 响应或发送通知给客户端。
通过 Web 界面测试 (可选): 在开发模式或运行状态下，可以通过访问 'http://localhost:8080' 打开一个简单的 Web 界面，与智能助手进行交互，测试其功能。点击页面左下角的聊天图标即可开始对话。

示例 Prompt (来自 README):

My name is John Doe. I am a member of a team of 2 myself and Daniel Jane. I like Asian food, while Daniel is on a strict gluten-free diet.

Please find one good restaurant in Atlanta, GA with the highest rating that meets
the team's dietary needs and preferences. Then, invite the team to a lunch
at 12pm next Wednesday using the slack channel "#lunchtime".
In your message, include the name and description of the restaurant, the time and
date of the lunch, and driving directions from Georgia World Congress Center.
Also create an ICS calendar file for me to use in my calendar in the
"playground/calendar" directory.

可以将类似上述的 prompt 通过 MCP 客户端发送给服务器，测试其智能助手功能和工具调用能力。

关键词