Merge pull request #1621 from sberyozkin/polish_secure_mcp_cmd_demo

More secure mcp cmd demo polishing

Author: geoand

samples/secure-mcp-cmd-client-server/README.md

@@ -1,18 +1,14 @@
 # Secure MCP command line client-server example using the SSE transport protocol with Keycloak and AI Gemini.
 
-This sample showcases how Quarkus MCP client can acquire OAuth2 client_credential grant tokens from Keycloak and use them to access secure Quarkus MCP server using the [SSE transport protocol](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse) protocol.
+This sample showcases how Quarkus MCP client can acquire OAuth2 client_credentials grant tokens from Keycloak and use them to access secure Quarkus MCP server using the [SSE transport protocol](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse) protocol.
 
-Quarkus MCP server gives the LLM a tool that can return a name of the logged-in user. AI Gemini uses this tool to create a poem about Java for the logged-in user.
-
-# AI Gemini API key
-
-Get [AI Gemini API key](https://aistudio.google.com/app/apikey). Use it to either set an `AI_GEMINI_API_KEY` environment property or update the `quarkus.langchain4j.ai.gemini.api-key=${ai_gemini_api_key}` property in `application.properties` by replacing `${ai_gemini_api_key}` with the API key value.
+Quarkus MCP server gives the LLM a tool that can return a name of the service account. AI Gemini uses this tool to include a service account name in a poem about Java.
 
 # Running the sample in dev mode
 
 ### MCP server
 
-Start the mcp server component in the `secure-mcp-server` directory using `mvn quarkus:dev`.
+Start the mcp server component in the `secure-mcp-cmd-server` directory using `mvn quarkus:dev`.
 
 This will start the server on port 8080 and launch a Keycloak container on port 8081. Keycloak dev service creates a `quarkus` realm with a `quarkus-mcp-server` client.
 
@@ -25,32 +21,32 @@ Keycloak `quarkus` realm configuration must be updated to support MCP server req
 Keycloak dev service has already created the `quarkus-mcp-server` client in the `quarkus` realm and is available on 8081 port. Go to `http://localhost:8081`, login as `admin:admin` and select the `quarkus` realm.
 
 Create two more clients, `quarkus-mcp-client` that will represent Quarkus MCP client, and `quarkus-mcp-service` that will represent a protected REST server that the MCP `quarkus-mcp-server` server will call to complete the tool action.
-Make sure both client only have `Client Authentication` and  `Service Accounts Roles` client capabilities enabled.
+Make sure both clients only have `Client Authentication` and  `Service Accounts Roles` client capabilities enabled.
 
 Copy the secret of the `quarkus-mcp-client`, you will need it later to run Quarkus MCP client.
 
-Create two `Optional` client scopes, `quarkus-mcp-server-scope` and `quarkus-mcp-service-scope`, and create the `Audience` mapper for each of these scopes, selecting `quarkus-mcp-server` and `quarkus-mcp-client` clients as audiences respectively.
+Create two `Optional` client scopes, `quarkus-mcp-server-scope` and `quarkus-mcp-service-scope`, and create the `Audience` mapper for each of these scopes, selecting `quarkus-mcp-server` and `quarkus-mcp-client` clients as included client audiences respectively.
 
 Add `Optional` `quarkus-mcp-server` client scope to the `quarkus-mcp-client` client and `Optional` `quarkus-mcp-service` client scope to the `quarkus-mcp-server` client.
 
 Finally, update the `quarkus-mcp-server` capabilities to support `Standard Token Exchange`. 
 
-This Keycloak configuration enables Quarkus MCP client to request an access token that can be used to access the Quarkus MCP server only but not the protected REST server. It also allows Quarkus MCP server to exchange the token targeted at it for another token that will only be valid for accessing the protected REST server. 
+This Keycloak configuration enables Quarkus MCP client to request an access token that can be used to access the Quarkus MCP server only. It also allows Quarkus MCP server to exchange the token targeted at it for another token that will only be valid for accessing the protected REST server.
 
 ### MCP Client
 
-Make sure AI Gemini API key is available to the MCP client by exporting it as an environment property:
+Make sure the MCP server is started and the Keycloak configuration is done.
+
+Get [AI Gemini API key](https://aistudio.google.com/app/apikey) and export it as an `AI_GEMINI_API_KEY` environment property:
 
 ```shell
-export ai_gemini_api_key=your_ai_gemini_api_key
+export AI_GEMINI_API_KEY=your_ai_gemini_api_key
 ```
 
-Also make sure the MCP server is started and the Keycloak configuration is done.
-
-Export the Keycloak `quarkus-mcp-client` secret that you copied when configuring Keycloak as an environment property:
+Export the Keycloak `quarkus-mcp-client` secret that you copied when configuring Keycloak as an `OIDC_CLIENT_SECRET` environment property:
 
 ```shell
-export oidc_client_secret=keycloak_quarkus_mcp_client_secret
+export OIDC_CLIENT_SECRET=keycloak_quarkus_mcp_client_secret
 ```
 
 Package the application and run it:

samples/secure-mcp-cmd-client-server/secure-mcp-cmd-client/src/main/java/io/quarkiverse/langchain4j/sample/PoemService.java

@@ -8,7 +8,8 @@
 public interface PoemService {
     @UserMessage("""
             Write a short 1 paragraph poem in {language} about a Java programming language.
-            Please use the service account name when creating the poem.""")
+            Provide a translation to English if the original poem language is not English.
+            Dedicate the poem to the service account, refer to this account by its name.""")
     @McpToolBox("service-account-name")
     String writePoem(String language);
 }

samples/secure-mcp-cmd-client-server/secure-mcp-cmd-server/src/main/resources/application.properties

@@ -1,5 +1,5 @@
 # MCP server
-quarkus.mcp.server.server-info.name=User Name Provider
+quarkus.mcp.server.server-info.name=Service Account Name Provider
 quarkus.mcp.server.traffic-logging.enabled=true
 quarkus.mcp.server.traffic-logging.text-limit=1000
 
@@ -20,7 +20,7 @@ quarkus.keycloak.devservices.container-memory-limit=1250M
 quarkus.keycloak.devservices.image-name=quay.io/keycloak/keycloak:26.3.1
 quarkus.keycloak.devservices.port=8081
 
-# MCP server tool uses REST Client to access a protected REST server to complete a user name request.
+# MCP server tool uses REST Client to access a protected REST server to complete a service account name request.
 # REST server expects tokens that contain a `quarkus-mcp-service` audience to prove they are intended for the REST server only.
 # Therefore, instead of propagating the token whose audience is this MCP `quarkus-mcp-server` server,
 # the token is exchanged to create a new token with the correct target audience set to `quarkus-mcp-service`.
@@ -39,7 +39,7 @@ quarkus.oidc-client.grant-options.exchange.subject_token_type=urn:ietf:params:oa
 # REST client which accesses a protected REST server, by propagating the exchanged token 
 io.quarkiverse.langchain4j.sample.ServiceAccountNameRestClient/mp-rest/url=http://localhost:8080/service-account-name
 
-# OIDC `user-name-service` tenant that secures a protected REST server.
+# OIDC `service-account-name-rest-server` tenant that secures a protected REST server.
 # It enforces that all tokens that reach it have a `quarkus-mcp-service` audience.
 quarkus.oidc.service-account-name-rest-server.auth-server-url=${quarkus.oidc.auth-server-url}
 quarkus.oidc.service-account-name-rest-server.token.audience=quarkus-mcp-service