使用说明

项目简介

Quarkus MCP Server是 Model Context Protocol (MCP) 的一个实现，它基于流行的Java云原生框架Quarkus构建。该项目旨在为开发者提供一个易于使用、高效且可扩展的平台，用于构建MCP服务器，从而帮助LLM应用更好地管理和利用外部上下文信息和功能。通过使用Quarkus MCP Server，开发者可以专注于业务逻辑的实现，而无需过多关注底层协议和框架的细节。

主要功能点

资源 (Resources) 管理: 允许开发者托管和管理各种类型的数据资源，并通过标准化的URI进行访问，为LLM应用提供结构化或非结构化数据。
工具 (Tools) 注册与执行: 支持将外部功能注册为工具，并允许LLM客户端通过MCP协议远程调用这些工具，扩展LLM的能力边界，例如调用API、执行计算或访问特定服务。
Prompt 模板 (Prompts) 定义与渲染: 提供Prompt模板的定义和管理功能，支持参数化Prompt，使得LLM交互更加灵活和可定制，可以根据不同的上下文和需求生成不同的Prompt。
基于注解的API: 采用声明式的注解 ('@Tool', '@Prompt', '@Resource' 等) 简化服务器端点的开发，开发者只需在CDI Bean的方法上添加注解即可快速发布MCP功能。
多种传输协议支持: 默认支持HTTP/SSE协议，同时通过依赖项切换，也支持STDIO协议，满足不同应用场景的需求。
JSON-RPC通信: 遵循MCP协议规范，使用JSON-RPC协议与客户端进行通信，保证了互操作性和标准化。
会话管理和能力声明: 服务器端负责管理客户端会话，并在初始化时向客户端声明自身提供的能力，方便客户端了解服务器的功能。

安装步骤

添加Maven依赖: 在您的Quarkus项目的 'pom.xml' 文件中，添加Quarkus MCP Server扩展的依赖。您可以根据需要选择SSE或STDIO传输方式：

SSE (Server-Sent Events) 传输 (推荐用于Web应用)

<dependency>
    <groupId>io.quarkiverse.mcp</groupId>
    <artifactId>quarkus-mcp-server-sse</artifactId>
    <version>${quarkus.platform.version}</version>
</dependency>

STDIO 传输 (适用于命令行工具或本地集成)

<dependency>
    <groupId>io.quarkiverse.mcp</groupId>
    <artifactId>quarkus-mcp-server-stdio</artifactId>
    <version>${quarkus.platform.version}</version>
</dependency>

注意: '${quarkus.platform.version}' 需要替换为您实际使用的Quarkus平台版本。建议使用最新版本以获得最佳体验。

创建服务器功能类: 创建一个Java类（例如 'ServerFeatures.java'），并将其注册为CDI Bean ('@Singleton')。在该类中，使用'@Tool', '@Prompt', '@Resource' 等注解来声明您的MCP服务器功能。参考示例代码：

import jakarta.inject.Inject;
import jakarta.inject.Singleton;
import io.quarkiverse.mcp.server.BlobResourceContents;
import io.quarkiverse.mcp.server.Prompt;
import io.quarkiverse.mcp.server.PromptArg;
import io.quarkiverse.mcp.server.PromptMessage;
import io.quarkiverse.mcp.server.Tool;
import io.quarkiverse.mcp.server.Resource;
import io.quarkiverse.mcp.server.RequestUri;
import io.quarkiverse.mcp.server.TextContent;

@Singleton
public class ServerFeatures {

    @Inject
    CodeService codeService; // 假设您有一个CodeService

    @Tool(description = "将字符串值转换为小写")
    String toLowerCase(String value) {
        return value.toLowerCase();
    }

    @Prompt(name = "code_assist")
    PromptMessage codeAssist(@PromptArg(name = "lang") String language) {
        return PromptMessage.withUserRole(new TextContent(codeService.assist(language)));
    }

    @Resource(uri = "file:///project/alpha")
    BlobResourceContents alpha(RequestUri uri) throws IOException{
        // 实际读取文件内容逻辑
        byte[] content = "dummy content".getBytes(); // 替换为实际文件读取
        return BlobResourceContents.create(uri.value(), content);
    }
}

注意: 示例代码中的 'CodeService' 仅为演示目的，您需要根据实际业务逻辑实现相应的服务。 '@Resource' 注解中的 'file:///project/alpha' URI 和文件读取部分也需要根据您的实际资源进行调整。

运行Quarkus应用: 使用Quarkus CLI 或 Maven 命令运行您的应用。

./mvnw quarkus:dev   # 开发模式
./mvnw package -Dnative  # 构建本地可执行程序
java -jar ./target/quarkus-app/quarkus-run.jar  # 运行打包后的程序

服务器配置

MCP客户端需要配置服务器的启动命令和参数才能连接。以下是Quarkus MCP Server的典型配置信息 (JSON 格式)，请根据您选择的传输协议和实际部署情况进行调整。

SSE 传输配置示例 (用于MCP客户端配置)

{
  "serverName": "Quarkus-MCP-SSE-Server",  //  服务器名称，可自定义
  "command": "java",   //  运行命令，通常为java
  "args": [
    "-jar",
    "./target/quarkus-app/quarkus-run.jar" //  Quarkus应用JAR包路径，根据实际打包路径调整
  ],
  "transport": "sse",   //  指定传输协议为SSE
  "baseUrl": "http://localhost:8080"  //  服务器基础URL，Quarkus默认端口为8080，可根据实际情况调整
}

STDIO 传输配置示例 (用于MCP客户端配置)

{
  "serverName": "Quarkus-MCP-STDIO-Server",  // 服务器名称，可自定义
  "command": "java",   // 运行命令，通常为java
  "args": [
    "-jar",
    "./target/quarkus-app/quarkus-run.jar"  // Quarkus应用JAR包路径，根据实际打包路径调整
  ],
  "transport": "stdio"   // 指定传输协议为STDIO
}

注意:

'serverName' 字段用于标识您的MCP服务器，可以自定义。

'command' 和 'args' 字段指定了启动Quarkus MCP Server的命令。请根据您的打包方式 (JAR 或 Native Image) 和实际路径进行调整。

'transport' 字段指定了MCP客户端与服务器通信的传输协议 ('sse' 或 'stdio')，需要与您在 'pom.xml' 中添加的依赖项以及服务器实际运行配置保持一致。

SSE 配置示例中，'baseUrl' 指定了服务器的根URL。请确保端口与您的Quarkus应用配置一致 (默认 8080)。 STDIO 传输不需要 'baseUrl'。

基本使用方法

定义MCP功能: 通过在CDI Bean的方法上添加 '@Tool', '@Prompt', '@Resource', '@ResourceTemplate' 和相关的参数注解 ('@ToolArg', '@PromptArg', '@ResourceTemplateArg') 来声明服务器提供的工具、Prompt模板和资源。
实现业务逻辑: 在注解方法中编写具体的业务逻辑代码，例如数据查询、外部API调用、Prompt生成等。
运行服务器: 启动您的Quarkus MCP Server应用。
配置MCP客户端: 在您的MCP客户端应用中，配置上面生成的服务器连接信息 (JSON)。
客户端调用: 使用MCP客户端API，根据MCP协议规范，向Quarkus MCP Server发送请求 (例如调用工具、获取Prompt、读取资源)，并处理服务器返回的响应。

详细的API和功能使用方法，请参考项目提供的完整文档： https://quarkiverse.github.io/quarkiverse-docs/quarkus-mcp-server/dev/index.html.

关键词