使用Quarkus构建首个Keycloak MCP服务器实战指南

A Keycloak示例 - 使用Quarkus构建我的第一个MCP服务器工具

最近我写了一篇关于"在Java生态系统中采用模型上下文协议"的文章。现在也是时候开始尝试自己编写MCP服务器了（也许这不是第一次）。

我当然不想错过社区展示的所有酷炫功能。我的目标是学习，并可能创建一个更实用的示例。在这篇文章中，我将选择Keycloak，并为其编写一个实验性的MCP服务器实现。这篇文章也是为了激发对这个主题的兴趣。为Keycloak开发MCP服务器会有用吗？

什么是模型上下文协议？

模型上下文协议是Anthropic于2024年11月引入的标准。MCP的目的是建立一个标准，帮助社区编写和使用工具、提示和资源。想象一下，你开始为Slack这样的工具编写工具，我也开始为Slack编写工具。看啊，我们都有自己的实现，但随后Slack也推出了自己的工具。这时我们就有个小问题：一是没有标准的方式与这些工具通信；二是如果Slack或GitHub负责为其服务创建和暴露工具，会使你我的生活更轻松。这正是我认为MCP非常有用的用例。

MCPServerClientLLMUserMCPServerClientLLMUser
您的提问（包含可用工具信息）1
分析问题并决定使用哪些工具2
指示使用选定的工具3
执行选定的工具4
工具结果5
转发工具结果6
使用工具结果制定答案7
最终响应！8

解释：
用户向LLM发送查询/问题。
LLM分析问题并决定是否需要调用工具。
LLM然后指示客户端执行工具。
客户端在MCP服务器上执行工具。
客户端将结果返回给LLM。
LLM为用户制定结果。

虽然这只是一个基本示例。现实是MCP还支持提示和资源。同样重要的是要说明，MCP通常并不真正带来新功能，而是专注于标准。自其出现以来，我们已经有多个MCP服务器和框架实现可供使用，如Quarkus、Spring AI、MCP SDK等。

MCP使我们能够通过提供例如预构建集成选择和在不同LLM之间切换的灵活性来开发代理和复杂工作流。

Stdio与SSE

在使用标准IO进行本地开发（服务器和客户端在同一台机器上）或构建CLI应用程序与使用HTTP上的服务器发送事件进行远程开发之间应该做出关键区分。后者应该被强调为在实际多应用程序使用中最实用的。另一个需要注意的重要事项是MCP服务器通过JSON-RPC进行通信。

JSON-RPC是一种无状态、轻量级的远程过程调用协议。该规范主要定义了几种数据结构及其处理规则。它在传输方面是不可知的，因为这些概念可以在同一进程内、通过套接字、通过HTTP或在许多不同的消息传递环境中使用。

逻辑分解：

StdioSSEJava AppMCP ClientMCP ServerKeycloak

Keycloak

如果您不熟悉Keycloak；它是一个开源的身份和访问管理软件。当前版本是26，已经在实际环境中广泛使用。它通过OAuth/OIDC、AD、LDAP和SAML v2提供单点登录功能。如果您不太熟悉Keycloak，我还编写了一个小型自定进度的Keycloak教程，涵盖了所有基础知识和一些高级配置。

开始吧

从quarkus cli或通过code.quarkus.io创建项目。

在我的示例中，我使用stdio。这意味着基于CLI的标准输入输出扩展。

在pom.xml中添加stdio Quarkus扩展：

<dependency>
    <groupId>io.quarkiverse.mcp</groupId>
    <artifactId>quarkus-mcp-server-stdio</artifactId>
    <version>1.0.0.Alpha5</version>
</dependency>

很棒。一个有趣的事实是Keycloak也是使用Quarkus构建的。最初它基于Wildfly，但大约2年前团队将整个项目迁移到了Quarkus。Keycloak Admin CLI，顾名思义，是用于管理Keycloak的强大工具，使用REST API。我将在这个项目中使用它。让我们也将其添加到pom.xml中：

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-keycloak-admin-rest-client</artifactId>
</dependency>

好的，这应该为开始设置好了基础。

由于我是从头开始。是时候编写第一个服务了。我将编写一个UserService，它将通过Keycloak Admin客户端调用领域内用户的CRUD操作。

什么是领域

领域是给定组或应用程序或服务的所有配置、选项的逻辑命名空间。领域保护和管理一组用户、应用程序和注册的身份代理、客户端等的安全元数据。用户可以在管理控制台内的特定领域中创建。角色（权限类型）可以在领域级别定义，您还可以设置用户角色映射以将这些权限分配给特定用户。用户属于一个领域并登录到该领域。领域彼此隔离，只能管理和验证它们控制的用户。

RealmUsersGroupsRolesClients

Keycloak的UserService

让我们开始编写一个服务类来访问Keycloak。

@ApplicationScoped // [1]
public class UserService {
    
    @Inject 
    Keycloak keycloak; // [2]

}

服务在应用程序启动时启动@ApplicationScoped。我还注入了import org.keycloak.admin.client.Keycloak客户端来调用Keycloak上的管理API。

以下getUsers方法将领域作为输入。这意味着我强制用户指定一个领域。因为在keycloak安装中可能有多个领域。一旦接收到realm参数，我就可以调用user().list()来获取领域中的所有用户。

public List<UserRepresentation> getUsers(String realm) {
    return keycloak.realm(realm).users().list();
}

对于addUser方法，我需要用户创建参数和领域。这样，当进行工具调用时，我想确保上下文是领域。例如，用户可能要求从两个领域获取用户，然后将用户添加到其中一个。

public String addUser(String realm, String username, String firstName, String lastName, String email, String password) {
    UserRepresentation user = new UserRepresentation(); // 设置用户字段 [1]
    user.setFirstName(firstName);
    user.setLastName(lastName);
    user.setUsername(username);
    user.setEnabled(true);
    user.setEmail(email);

    CredentialRepresentation credential = new CredentialRepresentation(); // 添加密码 [2]
    credential.setType(CredentialRepresentation.PASSWORD);
    credential.setValue(password);
    credential.setTemporary(false);
    user.setCredentials(List.of(credential));
    
    Response response = keycloak.realm(realm).users().create(user); // 发送创建请求 [3]
    if (response.getStatus() == Response.Status.CREATED.getStatusCode()) {
        return "Successfully created user: " + username;
    } else {
        Log.error("Failed to create user. Status: " + response.getStatus());
        response.close();
        return "Error creating user: "+" "+username;
    }
}

1 - UserRepresentation类是Admin REST API的一部分，用于在Keycloak领域内管理用户的上下文中表示用户。该类封装了与用户相关的各种属性和属性，允许管理员以编程方式创建、更新和检索用户信息。

2 - CredentialRepresentation类用于表示与用户帐户关联的凭据。该类是Keycloak Admin REST API的一部分，对于管理用户身份验证方法（如密码、OTP和其他凭据类型）至关重要。

3 - 最后，我向Keycloak发送创建用户请求。此部分下面还有一些错误处理，以确保调用工具时，我可以返回正确的状态。

类似地，我还实现了以下两个函数，用于删除用户和按用户名获取用户。

public String deleteUser(String realm, String username)
public UserRepresentation getUserByUsername(String realm, String username)

UserService的完整代码列表可在github上找到。

为了使上述内容成功运行，我还需要做两个操作性的工作。

在属性文件中添加以下行。这意味着我在端口8081上运行我们的本地keycloak实例。

quarkus.keycloak.admin-client.server-url=http://localhost:8081

通过docker-compose的Keycloak开发模式

还有一个用于keycloak的docker-compose.yaml文件，将在本地启动它。它所做的只是以开发模式启动keycloak，并暴露端口8081。目前我正在使用podman运行此文件。

services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    container_name: keycloak
    environment:
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=admin
    ports:
      - "8081:8080"
    command: >
      start-dev
    volumes:
      - keycloak_data:/opt/keycloak/data
    restart: unless-stopped

volumes:
  keycloak_data:

要运行上述文件：docker-compose up

创建UserTool

工具是一个组件，通过使LLM能够执行特定操作并与外部系统交互来增强其能力。这可能是API、数据库、内部系统等。这正是我在这里要做的，为keycloak构建工具。我们创建以下流程，其中UserTool将调用UserService，后者又调用Keycloak进行操作。我已经创建了UserService。现在是创建UserTool的时候了。

KeycloakUserServiceUserToolKeycloakUserServiceUserTool
调用UserService（例如，用户/领域/客户端）1
调用Keycloak（获取用户/领域/客户端）2
返回结果（UserRepresentation, RealmRepresentation, ClientRepresentation）3
从UserService返回转换结果为String4

在以下UserTool类中，我注入UserService和ObjectMapper。我使用com.fasterxml.jackson.databind.ObjectMapper将一些结果转换为String，例如List。

public class UserTool {

    @Inject
    UserService userService;

    @Inject
    ObjectMapper mapper;
}

接下来，让我们创建一个MCP服务器可以暴露的工具。

@Tool(description = "Get all users from a keycloak realm") // [1]
String getUsers(@ToolArg(description = "A String denoting the name of the realm where the users reside") String realm) { // [2]
    try {
        return mapper.writeValueAsString(userService.getUsers(realm)); // [3]
    } catch (Exception e) {
        throw new ToolCallException("Failed to get users from realm");
    }
}

1 - @Tool(description = "Get all users from a keycloak realm")
@Tool：表示getUsers方法被LLM识别为可调用函数或工具。
description描述此工具的作用，例如获取所有用户。当请求从keycloak获取所有用户时，LLM可以调用此工具。

由于LLM可以理解自然语言，所有导致从keycloak获取用户上下文的提问应该*理论上调用此工具。还要注意，如果我添加太多与其他工具描述混淆的细节，LLM可能不会调用所需的工具并最终产生幻觉。应注意如何编写描述。我建议简洁直接，避免歧义和重叠。

2 - ToolArg向LLM指定此工具需要一个参数。在我的情况下，它必须是一个领域。因此，如果用户只说获取所有用户，LLM应该回来询问哪个领域。如上所述，请注意description参数。

3 - 最后，一旦结果从UserService返回，在这种情况下是一个List。我使用ObjectMapper将其转换为String，以便LLM可以理解响应。我也尝试过使用Jsonb，效果也不错。

@Tool(description = "Create a new user in keycloak realm with the following mandatory fields realm, username, firstName, lastName, email, password")  // [1]
String addUser(@ToolArg(description = "A String denoting the name of the realm where the user resides") String realm,  // [2]
               @ToolArg(description = "A String denoting the username of the user to be created") String username,
               @ToolArg(description = "A String denoting the first name of the user to be created") String firstName,
               @ToolArg(description = "A String denoting the last name of the user to be created") String lastName,
               @ToolArg(description = "A String denoting the email of the user to be created") String email,
               @ToolArg(description = "A String denoting the password of the user to be created") String password) {
    return userService.addUser(realm, username, firstName, lastName, email, password);  // [3]
}

1 - 由于这是创建新用户的方法。我指定了需要的确切内容。
2 - 成功执行此工具所需的所有不同参数。
3 - 最后，一旦UserService返回，我将结果传递给LLM进行进一步处理。

打包

我们应该将以下属性添加到application.properties中。

quarkus.package.jar.type=uber-jar # [1]
quarkus.log.file.enable=true # [2]
quarkus.log.file.path=kcadmin-quarkus.log # [3]

1 - 告诉Quarkus创建一个uber jar。Uberjar，也称为"fat jar"或"shadow jar"，是一种Java存档文件，包含运行Java应用程序所需的所有依赖项和资源。
2 - 我还想要一个日志文件，以便我可以了解发生了什么。
3 - 日志文件的地址和名称。

mvn clean package

应用程序的完整源代码可以在这里找到。如果您只想运行它的话 😃

使用Goose运行

一个本地的、可扩展的、开源的AI代理，可自动化工程任务。

Goose by block提供了一个CLI工具，具有添加MCP作为扩展的能力。使用goose configure添加LLM配置和API密钥。

一旦CLI配置完成，我现在可以通过将其添加为扩展来添加打包的MCP服务器。

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

以下是一些可以提问的示例：

( O)> can I create a new user in keycloak?
是的，您可以在Keycloak中创建新用户。为此，您需要提供以下用户信息：

- **领域**：用户将驻留的领域名称。
- **用户名**：新用户的用户名。
- **名字**：用户的名字。
- **姓氏**：用户的姓氏。
- **电子邮件**：用户的电子邮件地址。
- **密码**：用户帐户的密码。

您可以提供这些详细信息，我可以协助您创建用户。

-
( O)> can you delete user sshaaf from realm quarkus

好的，总结一下。希望您喜欢它，并准备好编写您的第一个MCP服务器实现。

总结

本文探讨了为Keycloak创建一个实用的模型上下文协议服务器，旨在学习并展示其在AI驱动管理方面的潜力。MCP标准化了LLM与外部工具、提示和资源的交互方式，解决了分散的自定义集成问题。文章详细介绍了使用Quarkus和Keycloak Admin REST客户端构建这个实验性Keycloak MCP服务器的过程，重点关注指定领域内的用户管理操作。它提供了UserService和MCP UserTool的代码片段，解释了如何为LLM使用定义工具及其参数。最后，文章展示了如何打包Quarkus应用程序并使用"Goose"（一个AI代理CLI）运行它，以使用自然语言查询与Keycloak交互。示例的源代码可以在这里找到。

资源

公众号二维码

公众号二维码

posted @ 2025-10-08 23:06  qife  阅读(13)  评论(0)    收藏  举报