使用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.mcpgroupId>
<artifactId>quarkus-mcp-server-stdioartifactId>
<version>1.0.0.Alpha5version>
dependency>
很棒。一个有趣的事实是Keycloak也是使用Quarkus构建的。最初它基于Wildfly，但大约2年前团队将整个项目迁移到了Quarkus。Keycloak Admin CLI，顾名思义，是用于管理Keycloak的强大工具，使用REST API。我将在这个项目中使用它。让我们也将其添加到pom.xml中：
<dependency>
<groupId>io.quarkusgroupId>
<artifactId>quarkus-keycloak-admin-rest-clientartifactId>
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交互。示例的源代码可以在这里找到。
资源
- Goose - https://github.com/block/goose
- MCP - https://modelcontextprotocol.io/docs/concepts/tools
- Keycloak MCP Server - 示例 https://github.com/sshaaf/keycloak-mcp-server
- MCP和调用您的REST API - https://github.com/learnj-ai/llm-jakarta/tree/workshop/step-09-mcp
- Quarkus - https://quarkus.io/blog/mcp-server/
- 使用Quarkus创建MCP服务器 - https://iocanel.com/2025/03/creating-an-mcp-server-with-quarkus-and-backstage/
更多精彩内容 请关注我的个人公众号 公众号（办公AI智能小助手）
对网络安全、黑客技术感兴趣的朋友可以关注我的安全公众号（网络安全技术点滴分享）
