关键词

Agentic应用LLM后端工具集成上下文服务智能助手

使用说明

项目简介

本项目 'quarkus-agentic-mcp' 是一个使用 Quarkus 框架和 LangChain4j 库构建的 Model Context Protocol (MCP) 服务器实现。它旨在演示如何通过 MCP 协议为 Agentic 应用提供后端服务，特别是上下文管理和工具集成。该服务器集成了多种实用工具，例如文件系统访问、Google Maps、Slack 通知、Brave 网页搜索等，并可通过 WebSocket 与 MCP 客户端进行通信。

主要功能点

  • 资源管理 (Resources): 通过文件系统工具，服务器可以访问和操作本地文件系统中的资源（限定于 'playground' 目录）。
  • 工具注册与执行 (Tools): 内置多种工具，包括：
    • 文件系统工具: 读写 'playground' 目录下的文件。
    • Google Maps 工具: 用于地点搜索、距离计算等地图相关操作。
    • Slack 工具: 发送消息到 Slack 频道。
    • Brave 网页搜索工具: 进行网页信息检索。
    • 记忆检索工具: 模拟知识图谱的记忆检索。
  • Prompt 模板 (Prompts): 通过 'Bot.java' 中的 '@SystemMessage' 注解定义了系统级 Prompt，指导 LLM 的行为和工具使用策略。
  • WebSocket 通信: 使用 WebSocket 协议在 '/bot' 路径上与客户端进行实时通信。
  • 会话管理: 使用 '@SessionScoped' 注解，暗示支持会话级别的上下文管理。
  • 能力声明: 通过系统 Prompt 和代码结构，声明了服务器提供的工具和功能。

安装步骤

  1. 环境准备:
    • 确保已安装 JDK 17+。
    • 确保已安装 Maven。
    • 确保已安装 Node.js 和 npm (用于启动 MCP 服务)。
    • 可选：安装 Podman 或 Docker 以体验内置遥测功能 (Grafana)。
  2. 克隆仓库: 
    git clone https://github.com/danieloh30/quarkus-agentic-mcp.git
cd quarkus-agentic-mcp
  3. 创建 'playground' 目录: 在仓库根目录下创建名为 'playground' 的目录，用于文件系统工具的测试。 
    mkdir playground
  4. 配置 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>

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

MCP 客户端需要配置以下信息以连接到此 MCP 服务器。以下是 JSON 格式的配置示例，请根据实际情况修改：

{
  "serverName": "quarkus-mcp-server",
  "command": ["java", "-jar", "target/quarkus-app/quarkus-run.jar"],
  "args": [],
  "transport": "websocket",
  "baseUrl": "ws://localhost:8080/bot"
}

配置参数说明:

  • 'serverName': 服务器名称，可以自定义，用于在 MCP 客户端中标识该服务器。
  • 'command': 启动服务器的命令。这里假设您在项目根目录下执行 MCP 客户端，并且已经使用 'mvnw package' 命令打包了服务器。如果使用 native 镜像，则 command 需修改为 native 镜像的执行命令。
  • 'args': 启动服务器命令的参数，本示例中无需额外参数。
  • 'transport': 传输协议，本服务器使用 WebSocket 协议。
  • 'baseUrl': WebSocket 连接的 URL，指向服务器的 WebSocket 端点 '/bot'。请根据服务器实际运行地址和端口进行调整。

注意: MCP 客户端需要能够执行 'command' 指定的命令来启动 MCP 服务器进程，并使用 'baseUrl' 建立 WebSocket 连接。实际部署时，请确保 MCP 服务器已正确打包并可访问，并且 MCP 客户端的网络配置允许连接到服务器地址。

基本使用方法

  1. 启动服务器: 在仓库根目录下，使用 Maven 开发模式启动服务器：

    ./mvnw compile quarkus:dev

    或者，打包后运行：

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

    服务器默认运行在 'http://localhost:8080'。

  2. 使用 MCP 客户端连接服务器: 配置 MCP 客户端，使用上面提供的服务器配置信息连接到 'quarkus-mcp-server'。

  3. 通过客户端与 LLM 助手交互: 客户端连接成功后，即可向服务器发送符合 MCP 协议的请求，与集成了各种工具的 LLM 助手进行对话和任务执行。例如，可以发送文本消息进行提问，或者触发工具调用来完成特定任务（如文件操作、搜索信息、发送 Slack 消息等）。

  4. 测试示例: 访问 'http://localhost:8080' 可以打开一个简单的 Web 前端应用，用于测试助手的功能。或者，在开发模式下，访问 'http://localhost:8080/q/dev/' 进入 Quarkus Dev UI，点击 "Extensions" -> "Chat" 可以与 LLM 进行对话。

    可以尝试以下示例 Prompt：

    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.

    更多示例 Prompt 可以在 README.md 文件中找到。

信息

分类

AI与计算

访问项目