diff --git a/trento-docs-site/modules/api-specification/nav_api_specification.adoc b/trento-docs-site/modules/api-specification/nav_api_specification.adoc index ac67a43f..d4531ca0 100644 --- a/trento-docs-site/modules/api-specification/nav_api_specification.adoc +++ b/trento-docs-site/modules/api-specification/nav_api_specification.adoc @@ -1,9 +1,9 @@ * API specifications -** OpenApi +** OpenAPI Specifications *** https://www.trento-project.io/web/swaggerui/[Web] *** https://www.trento-project.io/wanda/swaggerui/[Wanda] ** Elixir Modules *** https://www.trento-project.io/web[Web] *** https://www.trento-project.io/wanda[Wanda] ** Go Modules -*** https://pkg.go.dev/github.com/trento-project/agent[Agent] \ No newline at end of file +*** https://pkg.go.dev/github.com/trento-project/agent[Agent] diff --git a/trento/adoc/trento-container-install.adoc b/trento/adoc/trento-container-install.adoc index 624fbba1..e13f9192 100644 --- a/trento/adoc/trento-container-install.adoc +++ b/trento/adoc/trento-container-install.adoc @@ -1,7 +1,8 @@ include::product-attributes.adoc[] +[[sec-container-deployment]] === Containerized deployment -:revdate: 2025-08-05 +:revdate: 2025-10-31 A containerized deployment of {trserver} is identical to the systemd @@ -191,3 +192,228 @@ e859c07888ca registry.suse.com/trento/trento-wanda:1.2.0 "/bin/sh -c '/app/b ---- + Both containers must run and listen on the specified ports. + +[[sec-trento-mcp-server-container]] +==== Installing {trento} MCP Server (Optional) + +The {trento} MCP Server provides AI-assisted management capabilities for your SAP landscape by exposing {trento} functionality through the Model Context Protocol (MCP). This optional component enables integration with AI tools and assistants. + +[NOTE] +==== +The {trento} MCP Server is an optional component. The core {trserver} functionality works independently without it. + +After installation, see <> for instructions on how to connect MCP-compatible AI assistants and tools to your Trento Server. +==== + +===== Requirements + +* Docker or Podman container runtime +* A running {trserver} installation (accessible via network) +* Sufficient disk space for container images and logs + +===== Configuration Overview + +The {trento} MCP Server requires minimal configuration, but needs to know how to reach your Trento Server. The key configuration parameters are: + +* `TRENTO_MCP_TRENTO_URL`: The URL where your Trento Server is accessible. This is particularly important when Trento is deployed behind NGINX or other reverse proxies. Use the externally accessible URL (e.g., `https://trento.example.com`) rather than internal service URLs. When set, the server will use this URL for OpenAPI specification autodiscovery. + +* `TRENTO_MCP_OAS_PATH`: Explicit paths to OpenAPI specification files. Use this when you want to directly specify the location of the API specifications instead of relying on autodiscovery. This is particularly useful when you want to connect to internal services (such as `localhost` or Kubernetes service names) instead of going through a reverse proxy. + +* `TRENTO_MCP_TAG_FILTER`: Filter which API operations to expose based on tags. Default is "MCP" to only expose operations specifically tagged for MCP usage. + +* `TRENTO_MCP_VERBOSITY`: Logging verbosity level (debug, info, warn, error). Default is "info". + +* `TRENTO_MCP_PORT`: Port on which the MCP Server listens. Default is 5000. + +* `TRENTO_MCP_ENABLE_HEALTH_CHECK`: Enable/disable health check HTTP server. Default is false. + +* `TRENTO_MCP_HEALTH_PORT`: Port for health check server. Default is 8080. + +===== Container Image + +The official container image is available at: + +==== +[source,text] +---- +registry.suse.com/trento/mcp-server-trento:latest +---- +==== + +===== Basic Docker Deployment + +For a basic deployment connecting to a running {trserver}: + +==== +[source,bash] +---- +docker run -d \ + --name mcp-server-trento \ + -p 5000:5000 \ + -e TRENTO_MCP_TRENTO_URL=https://trento.example.com \ + -e TRENTO_MCP_TAG_FILTER=MCP \ + -e TRENTO_MCP_VERBOSITY=info \ + --restart unless-stopped \ + registry.suse.com/trento/mcp-server-trento:latest +---- +==== + +[IMPORTANT] +==== +Replace `https://trento.example.com` with your actual {trserver} URL. +==== + +===== Advanced Docker Configuration + +For more control over the MCP Server behavior, use additional environment variables: + +==== +[source,bash] +---- +docker run -d \ + --name mcp-server-trento \ + -p 5000:5000 \ + -p 8080:8080 \ + -e TRENTO_MCP_TRENTO_URL=https://trento.example.com \ + -e TRENTO_MCP_PORT=5000 \ + -e TRENTO_MCP_TAG_FILTER=MCP \ + -e TRENTO_MCP_VERBOSITY=debug \ + -e TRENTO_MCP_ENABLE_HEALTH_CHECK=true \ + -e TRENTO_MCP_HEALTH_PORT=8080 \ + --restart unless-stopped \ + registry.suse.com/trento/mcp-server-trento:latest +---- +==== + +[NOTE] +==== +The MCP Server's health check HTTP server is primarily intended for Kubernetes environments, where liveness/readiness probes use it. For Docker deployments, you can leave health checks disabled unless you need them for monitoring. If enabled, expose the health port (default 8080) as shown above. +==== + +===== Network Integration with Trento Components + +If running {trento} components in containers on the same host, use Docker networks: + +==== +[source,bash] +---- +# Run the MCP Server connected to the trento-net network +docker run -d \ + --name mcp-server-trento \ + --network trento-net \ + -p 5000:5000 \ + -e TRENTO_MCP_OAS_PATH=http://trento-web:4000/api/all/openapi,http://trento-wanda:4000/wanda/api/all/openapi \ + -e TRENTO_MCP_TAG_FILTER=MCP \ + -e TRENTO_MCP_VERBOSITY=info \ + --restart unless-stopped \ + registry.suse.com/trento/mcp-server-trento:latest +---- +==== + +[NOTE] +==== +When using Docker networks with internal service names (e.g., `http://trento-web:4000`), ensure the MCP Server container can resolve and reach these hostnames. For external access through NGINX, use the externally accessible URL with `TRENTO_MCP_TRENTO_URL` instead. +==== + +===== Docker Compose Deployment + +For a complete deployment with Docker Compose, add the following to your `docker-compose.yml` file: + +==== +[source,yaml] +---- +services: + mcp-server-trento: + image: registry.suse.com/trento/mcp-server-trento:latest + container_name: mcp-server-trento + ports: + - "5000:5000" + - "8080:8080" + environment: + TRENTO_MCP_TRENTO_URL: https://trento.example.com + TRENTO_MCP_PORT: 5000 + TRENTO_MCP_TAG_FILTER: MCP + TRENTO_MCP_ENABLE_HEALTH_CHECK: true + TRENTO_MCP_HEALTH_PORT: 8080 + restart: unless-stopped + healthcheck: + test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/localhost/8080"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 40s +---- +==== + +Start the service: + +==== +[source,bash] +---- +docker-compose up -d mcp-server-trento +---- +==== + +===== Verifying the MCP Server Installation + +. Check that the container is running: ++ +==== +[source,bash] +---- +docker ps | grep mcp-server-trento +---- +==== ++ +Expected output should show the container in "Up" status. ++ +. Check the container logs: ++ +==== +[source,bash] +---- +docker logs mcp-server-trento +---- +==== ++ +Expected output should show successful connection to {trserver} and OpenAPI specification loading: ++ +==== +[source,bash] +---- +2025-10-31 17:31:20 INFO the MCP server has been created mcp.name=mcp-server-trento mcp.version=devel +... +2025-10-31 17:31:21 INFO the MCP server mcp-server-trento has 39 registered tools +2025-10-31 17:31:21 INFO the MCP server is listening server.address=:5000 server.transport=streamable +---- +==== ++ +. Test the MCP Server endpoint: ++ +==== +[source,bash] +---- +curl http://localhost:5000/mcp +---- +==== ++ +Expected output should show the MCP protocol handshake information. ++ +. If health checks are enabled, verify the endpoints: ++ +==== +[source,bash] +---- +# Liveness endpoint: +curl http://localhost:8080/livez + +# Example output: +# {"info":{"name":"trento-mcp-server","version":"0.1.0"},"status":"up"} + +# Readiness endpoint: +curl http://localhost:8080/readyz + +# Example output: +# {"status":"up","details":{"mcp-server":{"status":"up","timestamp":"2025-10-09T12:11:09.528898849Z"},"wanda-api":{"status":"up","timestamp":"2025-10-09T12:11:09.542078327Z"},"web-api":{"status":"up","timestamp":"2025-10-09T12:11:09.544855047Z"}}} +---- +==== diff --git a/trento/adoc/trento-guide.adoc b/trento/adoc/trento-guide.adoc index ff6fc586..ff11bab2 100644 --- a/trento/adoc/trento-guide.adoc +++ b/trento/adoc/trento-guide.adoc @@ -9,6 +9,9 @@ include::trento-lifecycle.adoc[] include::trento-requirements.adoc[] include::trento-install-server.adoc[] include::trento-install-agents.adoc[] +include::trento-mcp-install.adoc[] +include::trento-using-mcp-server.adoc[] +include::trento-mcp-config.adoc[] include::trento-user-manage.adoc[] include::trento-sso-integration.adoc[] include::trento-activity-log.adoc[] diff --git a/trento/adoc/trento-intro.adoc b/trento/adoc/trento-intro.adoc index 3c070297..33a9e078 100644 --- a/trento/adoc/trento-intro.adoc +++ b/trento/adoc/trento-intro.adoc @@ -2,21 +2,21 @@ include::product-attributes.adoc[] [[sec-trento-what]] == What is {trento}? -:revdate: 2025-06-10 +:revdate: 2025-10-31 {trento} is the official version of the Trento community project. It is a comprehensive monitoring solution consisting of two main components: the {trserver} and the {tragent}. {trento} provides the following functionality and features: * A user-friendly reactive Web interface for {sap} Basis administrators. * Automated discovery of {pace} clusters using SAPHanaSR classic or angi as well as different fencing mechanisms, including diskless SBD. -* Automated discovery of SAP systems running on ABAP or JAVA stacks and HANA databases. +* Automated discovery of {sap} systems running on ABAP or JAVA stacks and HANA databases. * Awareness of maintenance situations in a {pace} cluster at cluster, node, or resource level. * Configuration validation for {hana} Scale-Up Performance/Cost-optimized, {hana} Scale-out and ASCS/ERS clusters deployed on Azure, AWS, GCP or on-premises bare metal platforms, including KVM and Nutanix. * Useful information that offers insights about the execution of configuration checks. * Delivery of configuration checks decoupled from core functionality. * Email alerting for critical events in the monitored landscape. * Integration of saptune into the console and specific configuration checks at host and cluster levels. -* Information about relevant patches and upgradable packages for registered hosts via integration with SUSE Multi-Linux Manager. +* Information about relevant patches and upgradable packages for registered hosts via integration with {smlm}. * Monitoring of CPU and memory usage at the host level through basic integration with {prometheus}. * API-based architecture to facilitate integration with other monitoring tools. * Rotating API key to protect communication from the {tragent} to the {trserver}. @@ -36,4 +36,43 @@ See <> for additional details. [[fig-trento-architecture]] .Architectural overview -image::trento-high-level-architecture.png[width=80%] \ No newline at end of file +image::trento-high-level-architecture.png[width=80%] + +[[sec-trento-mcp-intro]] +=== AI-Assisted Operations with the {trento} MCP Server (optional) + +The {trento} MCP Server extends {trento} with AI-assisted operations by implementing the open link:https://modelcontextprotocol.io/introduction[Model Context Protocol] (MCP). It enables MCP-compatible AI assistants—such as public AI tools like link:https://code.visualstudio.com/[VS Code] with link:https://github.com/features/copilot[GitHub Copilot], link:https://claude.ai/download[Claude Desktop], or link:https://cursor.sh/[Cursor], or private AI platforms like link:https://www.suse.com/products/ai/[{suseai}]—to securely connect to {trento} and execute common monitoring and troubleshooting tasks using natural language. + +With the {trento} MCP Server, you can: + +* Ask conversational questions such as "What's the overall health of my SAP environment?" or "Show me all SAP systems with critical status." +* Retrieve cluster and host details on demand (for example, "Show configuration for cluster C1" or "List hosts running HANA"). +* Review checks and execution history to understand configuration drifts or failures. +* Surface critical alerts that need immediate attention. + +==== What is the Model Context Protocol (MCP)? + +link:https://modelcontextprotocol.io/introduction[Model Context Protocol] (MCP) is an open standard that allows AI applications to securely connect to external tools and data sources. In the context of {trento}, MCP provides a consistent, secure way for assistants to call {trserver} APIs without manual navigation of the web UI. + +==== How the MCP Server fits into {trento} + +* It runs alongside the {trserver} (as part of your deployment) and exposes a single HTTP endpoint (path `/mcp`). +* It automatically discovers the {trserver} APIs and generates MCP tools from the OpenAPI specifications exposed by {trweb} and Wanda. +* It authenticates to {trserver} using user-scoped Personal Access Tokens (API keys) and forwards requests securely. +* It's an optional component—{trento} works without it—but unlocks natural-language workflows when enabled. + +These clients can be pointed to the MCP endpoint URL and supplied with the appropriate API key header to authenticate against your {trserver}. + +==== Using the MCP Server + +To get started with the {trento} MCP Server, you need to: + +1. Ensure the MCP Server is deployed and running alongside your {trserver}. Refer to the installation guide for details. + +2. Configure your MCP-compatible AI assistant to connect to the MCP endpoint. + +3. Provide a valid Personal Access Token (API key) for authentication. + +Once connected, you can interact with {trento} using natural language commands, such as asking for system health, cluster details, or check results. + +For comprehensive instructions, including deployment options and integration with specific AI tools, see <>. diff --git a/trento/adoc/trento-kubernetes-install.adoc b/trento/adoc/trento-kubernetes-install.adoc index c46b031e..864536b0 100644 --- a/trento/adoc/trento-kubernetes-install.adoc +++ b/trento/adoc/trento-kubernetes-install.adoc @@ -2,7 +2,7 @@ include::product-attributes.adoc[] [[sec-trento-k8s-deployment]] === {k8s} deployment -:revdate: 2025-10-16 +:revdate: 2025-10-31 The subsection uses the following placeholders: @@ -265,3 +265,222 @@ For details on the required Ingress setup and configuration, refer to: https://k Additional steps are required on the Agent side. // toms 2022-09-14: which steps? + +[[sec-trento-mcp-server-k8s]] +==== Installing {trento} MCP Server (Optional) + +The {trento} MCP Server provides AI-assisted management capabilities for your SAP landscape by exposing {trento} functionality through the Model Context Protocol (MCP). This optional component enables integration with AI tools and assistants. + +[NOTE] +==== +The {trento} MCP Server is an optional component. The core {trserver} functionality works independently without it. + +After installation, see <> for instructions on how to connect MCP-compatible AI assistants and tools to your Trento Server. +==== + +===== Prerequisites + +Before installing the {trento} MCP Server, ensure you have: + +* A running {trserver} installation (Web and Wanda components). ++ +The Trento Server consists of multiple components: ++ +** *Web component*: Provides the user interface and API endpoints for managing SAP systems +** *Wanda component*: Handles automated checks and compliance validation for SAP landscapes ++ +Both components must be running and accessible for the MCP Server to function properly. + +* Network connectivity between the MCP Server and Trento Server components. +* Access to the Trento Server URL (especially important when deployed behind NGINX or other reverse proxies). + +===== Configuration Overview + +The {trento} MCP Server requires minimal configuration, but needs to know how to reach your Trento Server. The key configuration parameters are: + +* `TRENTO_URL`: The URL where your Trento Server is accessible. This is particularly important when Trento is deployed behind NGINX or other reverse proxies. Use the externally accessible URL (e.g., `https://trento.example.com`) rather than internal service URLs. When set, the server will use this URL for OpenAPI specification autodiscovery. + +* `OAS_PATH`: Explicit paths to OpenAPI specification files. Use this when you want to directly specify the location of the API specifications instead of relying on autodiscovery. This is particularly useful when you want to connect to internal services (such as `localhost` or Kubernetes service names) instead of going through a reverse proxy. + +===== Enabling the MCP Server + +When installing the complete {trserver} using Helm, the MCP Server is disabled by default. Enable it by passing `--set trento-mcp-server.enabled=true`: + +==== +[source,bash] +---- +helm upgrade --install trento-server oci://registry.suse.com/trento/trento-server \ + --set trento-web.trentoWebOrigin=TRENTO_SERVER_HOSTNAME \ + --set trento-web.adminUser.password=ADMIN_PASSWORD \ + --set trento-mcp-server.enabled=true +---- +==== + +[NOTE] +==== +The examples in this guide do not specify a Kubernetes namespace for simplicity. By default, Helm will install to the `default` namespace. For production deployments, create and use a dedicated namespace: + +[source,bash] +---- +kubectl create namespace trento +helm upgrade --install trento-server oci://registry.suse.com/trento/trento-server \ + --namespace trento \ + --set trento-mcp-server.enabled=true \ + ... +---- +==== + +The MCP Server will automatically connect to the {trweb} and Wanda internal services within the {k8s} cluster. + +===== MCP Server Configuration Options + +The {trento} MCP Server Helm chart supports various configuration options: + +====== Customize Ingress Path + +By default, ingress is enabled. To customize the ingress configuration: + +==== +[source,bash] +---- +helm upgrade --install trento-server oci://registry.suse.com/trento/trento-server \ + --set trento-mcp-server.enabled=true \ + --set trento-mcp-server.ingress.enabled=true \ + --set trento-mcp-server.ingress.hosts[0].host=TRENTO_SERVER_HOSTNAME \ + --set trento-mcp-server.ingress.hosts[0].paths[0].path=/mcp-server-trento \ + --set trento-mcp-server.ingress.hosts[0].paths[0].pathType=ImplementationSpecific +---- +==== + +The MCP Server endpoint will be: `https://TRENTO_SERVER_HOSTNAME/mcp-server-trento/mcp` + +====== Disabling Tag Filtering + +By default, only operations tagged with `MCP` are exposed. To expose all operations and remove tag filtering: + +==== +[source,bash] +---- +helm upgrade --install trento-server oci://registry.suse.com/trento/trento-server \ + --set trento-mcp-server.enabled=true \ + --set trento-mcp-server.mcpServer.tagFilter=[] +---- +==== + +[NOTE] +==== +You can also filter by different tags by setting `--set trento-mcp-server.mcpServer.tagFilter[0]=YourTag`. +==== + +====== Adjust Log Verbosity + +The default log level is `info`. Adjust it for debugging: + +==== +[source,bash] +---- +helm upgrade --install trento-server oci://registry.suse.com/trento/trento-server \ + --set trento-mcp-server.enabled=true \ + --set trento-mcp-server.mcpServer.verbosity=debug +---- +==== + +====== Adjust Resource Limits + +For production deployments with different resource requirements: + +==== +[source,bash] +---- +helm upgrade --install trento-server oci://registry.suse.com/trento/trento-server \ + --set trento-mcp-server.enabled=true \ + --set trento-mcp-server.resources.requests.cpu=100m \ + --set trento-mcp-server.resources.requests.memory=128Mi \ + --set trento-mcp-server.resources.limits.cpu=1000m \ + --set trento-mcp-server.resources.limits.memory=1Gi +---- +==== + +====== Disabling Health Check Probes + +Health check probes are enabled by default. To disable them if needed: + +==== +[source,bash] +---- +helm upgrade --install trento-server oci://registry.suse.com/trento/trento-server \ + --set trento-mcp-server.enabled=true \ + --set trento-mcp-server.livenessProbe.enabled=false \ + --set trento-mcp-server.readinessProbe.enabled=false +---- +==== + +====== Complete Configuration Example + +Here is a complete example that configures external access via a custom ingress path: + +==== +[source,bash] +---- +helm upgrade --install trento-server oci://registry.suse.com/trento/trento-server \ + --set trento-web.trentoWebOrigin=https://trento.example.com \ + --set trento-web.adminUser.password=SecurePassword123 \ + --set trento-mcp-server.enabled=true \ + --set trento-mcp-server.mcpServer.trentoURL=https://trento.example.com \ + --set trento-mcp-server.ingress.hosts[0].host=trento.example.com \ + --set trento-mcp-server.ingress.hosts[0].paths[0].path=/mcp-server-trento \ + --set trento-mcp-server.ingress.hosts[0].paths[0].pathType=ImplementationSpecific +---- +==== + +===== Verifying the MCP Server Installation + +. Check that the MCP Server pod is running: ++ +==== +[source,bash] +---- +kubectl get pods -l app.kubernetes.io/name=mcp-server +---- +==== ++ +Expected output: ++ +==== +[source,bash] +---- +NAME READY STATUS RESTARTS AGE +trento-server-mcp-server-xxxxxxxxxx-xxxxx 1/1 Running 0 2m +---- +==== ++ +. Check the logs: ++ +==== +[source,bash] +---- +kubectl logs -l app.kubernetes.io/name=mcp-server +---- +==== ++ +. If health checks are enabled, verify the health endpoints: ++ +==== +[source,bash] +---- +# Expose the health check port from the Pod, as it is not exposed as a Kubernetes Service. +kubectl port-forward --namespace default $(kubectl get pods --namespace default -l app.kubernetes.io/name=mcp-server -o jsonpath="{.items[0].metadata.name}") 8080:8080 + +# Liveness endpoint: +curl http://localhost:8080/livez + +# Example output: +# {"info":{"name":"trento-mcp-server","version":"0.1.0"},"status":"up"} + +# Readiness endpoint: +curl http://localhost:8080/readyz + +# Example output: +# {"status":"up","details":{"mcp-server":{"status":"up","timestamp":"2025-10-09T12:11:09.528898849Z"},"wanda-api":{"status":"up","timestamp":"2025-10-09T12:11:09.544855047Z"},"web-api":{"status":"up","timestamp":"2025-10-09T12:11:09.544855047Z"}}} +---- +==== diff --git a/trento/adoc/trento-lifecycle.adoc b/trento/adoc/trento-lifecycle.adoc index 2ec0e4af..801c8314 100644 --- a/trento/adoc/trento-lifecycle.adoc +++ b/trento/adoc/trento-lifecycle.adoc @@ -22,7 +22,7 @@ Delivery mechanisms::: A set of container images from the {suse} public registry {k8s} deployment::: The {trserver} runs on any current Cloud Native Computing Foundation (CNCF)-certified {k8s} distribution based on a x86_64 architecture. Depending on your scenario and needs, {suse} supports several usage scenarios: * If you already use a CNCF-certified {k8s} cluster, you can run the {trserver} in it. -* If you don't have a {k8s} cluster, and need enterprise support, {suse} recommends {suse} {rke} (RKE) version 1 or 2. +* If you don't have a {k8s} cluster, and need enterprise support, {suse} recommends {rke} version 1 or 2. * If you do not have a {k8s} enterprise solution but you want to try {trento}, {suse} Rancher's K3s provides you with an easy way to get started. But keep in mind that K3s default installation process deploys a single node {k8s} cluster, which is not a recommended setup for a stable Trento production instance. systemd and containerized deployments::: Supported in {sles4sap} 15 SP3 and newer. diff --git a/trento/adoc/trento-mcp-config.adoc b/trento/adoc/trento-mcp-config.adoc new file mode 100644 index 00000000..efc4fc0a --- /dev/null +++ b/trento/adoc/trento-mcp-config.adoc @@ -0,0 +1,409 @@ +include::product-attributes.adoc[] + +[[sec-trento-mcp-config]] +== {trento} MCP Server Configuration Options +:revdate: 2025-10-31 + +This section provides an overview of how to configure the {trento} MCP Server using command-line parameters, configuration files, and environment variables. + +[[sec-trento-mcp-config-sources]] +=== Configuration Sources + +The {trento} MCP Server supports multiple configuration sources with the following priority order (highest to lowest): + +1. **Command-line flags** - Override all other settings. +2. **Environment variables** - Useful for containerized deployments. +3. **Configuration file** - YAML file for persistent settings. +4. **Built-in defaults** - Fallback values. + +[[sec-trento-mcp-config-file]] +=== Configuration File + +You can create a {trento} MCP Server configuration file in the working directory or specify a custom path using the `--config` flag. + +The {trento} MCP Server searches for configuration files in the following order: + +1. System-wide directory (`/etc/trento/mcp-server-trento` or `/usr/etc/trento/mcp-server-trento`). +2. Custom path specified with the `--config` flag. + +[source,env] +---- +## Custom paths for API autodiscovery endpoints (comma-separated), used when OAS_PATH is empty and TRENTO_URL is set. +AUTODISCOVERY_PATHS=/api/all/openapi,/wanda/api/all/openapi + +## Enable the health check server. +ENABLE_HEALTH_CHECK=false + +## The HTTP header name used to pass the Trento API key for authentication with the Trento server. +HEADER_NAME=Authorization + +## The API path used for health checks on target servers. +HEALTH_API_PATH=/api/healthz + +## The port on which the health check server listens for incoming connections. +HEALTH_PORT=8080 + +## Comma-separated list of paths to OpenAPI specification files (local or remote URLs). +## If not provided, the server will attempt autodiscovery using the Trento URL and autodiscovery paths. +OAS_PATH=http://localhost:4000/api/all/openapi,http://localhost:4001/wanda/api/all/openapi + +## The port on which the MCP Server listens for incoming connections. +PORT=5000 + +## Comma-separated list of OpenAPI tags to filter which operations are exposed as MCP tools. Only operations with at least one matching tag will be available. +TAG_FILTER=MCP + +## The transport protocol to use for MCP communication. Options: 'streamable' (default) or 'sse'. +TRANSPORT=streamable + +## Target Trento server URL, useful when targeting remote Trento servers. Empty by default. +TRENTO_URL= + +## The logging verbosity level. Options: 'debug', 'info', 'warning', 'error'. +VERBOSITY=info +---- + +==== System-Wide Configuration + +For system-wide configuration, place the config file in `/etc/trento/mcp-server-trento`: + +[source,console] +---- +sudo mkdir -p /etc/trento +sudo tee /etc/trento/mcp-server-trento > /dev/null <> for correct configuration patterns +. Check the {trento} server logs for API authentication and access issues diff --git a/trento/adoc/trento-mcp-install.adoc b/trento/adoc/trento-mcp-install.adoc new file mode 100644 index 00000000..cd324338 --- /dev/null +++ b/trento/adoc/trento-mcp-install.adoc @@ -0,0 +1,45 @@ +include::product-attributes.adoc[] + +[[sec-trento-mcp-install]] +:revdate: 2025-10-31 +== Installing the {trento} MCP Server + +The {trento} MCP Server can be deployed in several ways depending on your infrastructure and requirements. This guide covers three main deployment methods: Kubernetes (using Helm charts), systemd (using RPM packages), and containerized deployment (using Docker/Podman). + +=== Prerequisites + +Before installing the {trento} MCP Server, ensure you have: + +* A running {trserver} installation (Web and Wanda components). ++ +The {trserver} consists of multiple components: ++ +** *Web component*: Provides the user interface and API endpoints for managing SAP systems +** *Wanda component*: Handles automated checks and compliance validation for SAP landscapes ++ +Both components must be running and accessible for the MCP Server to function properly. + +* Network connectivity between the MCP Server and {trserver} components. +* Access to the {trserver} URL (especially important when deployed behind NGINX or other reverse proxies). + +=== Configuration Overview + +The {trento} MCP Server requires minimal configuration, but needs to know how to reach your {trserver}. The key configuration parameters are: + +* `TRENTO_URL`: The URL where your {trserver} is accessible. This is particularly important when {trento} is deployed behind NGINX or other reverse proxies. Use the externally accessible URL (e.g., `https://trento.example.com`) rather than internal service URLs. When set, the server will use this URL for OpenAPI specification autodiscovery. + +* `OAS_PATH`: Explicit paths to OpenAPI specification files. Use this when you want to directly specify the location of the API specifications instead of relying on autodiscovery. This is particularly useful when you want to connect to internal services (such as `localhost` or Kubernetes service names) instead of going through a reverse proxy. + +The {trento} MCP Server can be installed as part of the {trserver} deployment or as a separate component. Refer to the specific deployment method sections above for installation instructions: + +* <> - Kubernetes deployment with Helm +* <> - systemd deployment with RPM packages +* <> - Container deployment with Docker/Podman + +=== Configuration Reference + +For detailed configuration options, including command-line parameters, environment variables, configuration file examples, and advanced settings, see <>. + +=== Troubleshooting + +For troubleshooting common issues, see <>. diff --git a/trento/adoc/trento-mcp-others.adoc b/trento/adoc/trento-mcp-others.adoc new file mode 100644 index 00000000..7c1309e9 --- /dev/null +++ b/trento/adoc/trento-mcp-others.adoc @@ -0,0 +1,178 @@ +:revdate: 2025-10-31 + +The {trento} MCP Server can be integrated with any client application that supports the Model Context Protocol (MCP). This allows you to interact with the {trento} API and execute tools defined in the OpenAPI specification through your preferred AI assistant or development tool. + +This guide uses Visual Studio Code with GitHub Copilot as the primary example, but the configuration patterns apply to any MCP-compatible host. + +==== Prerequisites + +Before configuring your MCP Host, ensure you have: + +. *A running {trserver} installation* with the {trento} MCP Server component enabled: +** Follow the <> to deploy {trserver} and enable the {trento} MCP Server. +** Note the {trento} MCP Server endpoint URL (e.g., `https://trento.example.com/mcp-server-trento/mcp`). + +. *A {trento} API token (Personal Access Token)*: +** Log in to your {trento} web interface with your username and password. +** Click on your username in the top-right corner and select *Profile*. +** Scroll down to the *Personal Access Tokens* section. +** Click the *Generate Token* button. +** Enter a descriptive name for the token (e.g., "VS Code MCP Client"). +** Optionally configure an expiration date for the token, or select *Never Expires*. +** Click the *Generate Token*. +** *Important:* Copy the generated token immediately and store it securely - it will not be shown again. + +.Generate a Personal Access Token in {trento} +image::generate-pat.png[Generate a Personal Access Token in {trento},width=800] + +==== Configuring Your MCP Host + +Once you have your {trento} installation ready with the {trento} MCP Server URL and API token, you can configure your MCP Host. The examples below show JSON configuration format, which is used by most MCP Hosts, including VS Code, Claude Desktop, and others. + +===== Option 1: Configuration with Prompted Input (Recommended) + +This configuration prompts you for your API key when the Host starts, keeping credentials secure and out of configuration files. The `password: true` setting ensures your API key input is masked when you type it. + +[NOTE] +==== +This option is supported by most MCP Hosts, including VS Code. Check your MCP Host's documentation if the prompt feature is not available. +==== + +[source,json] +---- +{ + "servers": { + "trento": { + "type": "http", + "url": "https://trento.example.com/mcp-server-trento/mcp", + "headers": { + "Authorization": "${input:trento-pat}" + } + } + }, + "inputs": [ + { + "type": "promptString", + "id": "trento-pat", + "description": "Trento Personal Access Token", + "password": true + } + ] +} +---- + +===== Option 2: Direct Header Configuration + +For MCP Hosts that don't support prompted input, or for testing purposes, you can set your {trento} API key directly in the configuration file. + +[WARNING] +==== +When using this option, ensure your configuration file has appropriate permissions and is not committed to version control systems. +==== + +[source,json] +---- +{ + "servers": { + "trento": { + "type": "http", + "url": "https://trento.example.com/mcp-server-trento/mcp", + "headers": { + "Authorization": "your-trento-pat" + } + } + } +} +---- + +[NOTE] +==== +Replace `https://trento.example.com/mcp-server-trento/mcp` with your actual {trento} MCP Server endpoint URL from your installation. +==== + +===== Client-Specific Notes + +* *VS Code*: Configuration is typically stored in `.vscode/settings.json` or in your user settings. The client will remember your API key for the session. +* *Claude Desktop*: Configuration is usually in `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). +* *Other MCP Hosts*: Refer to your client's documentation for the configuration file location. For examples of how other tools integrate with MCP, see the link:https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/README.md[GitHub MCP Server installation guides]. + +===== General Configuration Notes + +* Replace `https://trento.example.com/mcp-server-trento/mcp` with the actual URL where your {trento} MCP Server is accessible: + ** For Kubernetes deployments with ingress, use the ingress URL (e.g., `https://trento.example.com/mcp-server-trento/mcp`). + ** For local or development setups, use `http://localhost:5000/mcp` (adjust the port as needed). + ** If using Server-Sent Events (SSE) transport instead of the default streamable transport, change the path from `/mcp` to `/sse` - The transport type is configured on the {trento} MCP Server using the `TRANSPORT` configuration key or `--transport` flag (see <>). + +* Replace `your-trento-pat` with the API token you generated from your {trento} instance. +* If you configured a custom header name (using `HEADER_NAME` or `--header-name`), update `Authorization` accordingly. + +===== Troubleshooting + +If you encounter issues connecting your MCP Host to the {trento} MCP Server: + +. *Connection Errors*: +** Verify that the {trento} MCP Server URL is correct and accessible from your machine. +** Check if the {trento} MCP Server is running by reviewing logs from your {trento} installation. +** Ensure network connectivity and that any required firewall rules are in place. + +. *Authentication Errors*: +** Verify that your API token is valid by testing it directly against your {trento} Server API. +** Check that the header name matches your server configuration (default: `Authorization`). +** Ensure the token has the necessary permissions in {trento}. + +. *General Issues*: +** Check your MCP Host's developer console or logs for detailed error messages: +*** VS Code: Help → Toggle Developer Tools. +*** Claude Desktop: Check application logs. +*** Other clients: Refer to your client's documentation for log locations. +** Review the {trento} MCP Server logs for connection attempts and errors. +** Refer to the <> for additional help. + +==== Using the {trento} MCP Server + +How you use the {trento} MCP Server depends on the specific MCP Host application you're working with. The MCP ecosystem is rapidly evolving, with new hosts and improved user experiences being introduced regularly. + +===== Enable the Server and Expose Tools in Your MCP Host + +[arabic] +. Ensure the {trento} MCP Server is configured in your host (see the configuration examples above). +. Enable the server in your host's MCP settings, if required by the client: +.. Many hosts provide a *Servers*, *External Tools*, or *MCP* section where you can toggle/enable the server you added. +. Select or attach the MCP server to your assistant/model/workspace, if your host requires it: +.. Some hosts let you choose which MCP servers are available per model or project - Make sure the *{trento} MCP Server* is enabled for the target model/session. +. Start a new chat or session with your assistant and verify that tools are available: +.. Try a simple action, such as: "List SAP systems", "Show HANA clusters", "What is the health status of my SAP landscape?", or "Are there any critical alerts I need to address?". + +For detailed guidance on leveraging MCP capabilities in different tools, refer to the following official documentation: + +* link:https://code.visualstudio.com/docs/copilot/customization/mcp-servers[Visual Studio Code with GitHub Copilot - MCP Server Configuration]. +* link:https://docs.claude.com/en/docs/mcp[Claude Desktop - Model Context Protocol Integration]. +* link:https://cursor.com/[Cursor] - AI-powered code editor with MCP support. +* link:https://cloud.google.com/gemini/docs/codeassist/use-agentic-chat-pair-programmer[Google Cloud Gemini Code Assist - Agentic Chat]. +* link:https://docs.windsurf.com/windsurf/cascade/mcp[Windsurf - Cascade MCP Support]. + +===== Demo + +To see the {trento} MCP Server in action, watch link:https://www.youtube.com/watch?v=7kDVc3YUR-U[this demonstration video]. + +Find below a few example screenshots from different MCP Hosts using the {trento} MCP Server: + +====== Example: Claude Desktop + +The Claude Desktop app can attach the {trento} MCP Server and expose its tools directly in conversations. After configuring your server in Claude's MCP settings, start a new chat and look for the available tools. + +.Claude Desktop using {trento} MCP Server +image::example-claude.png[Claude Desktop using {trento} MCP Server,width=900] + +====== Example: Visual Studio Code with GitHub Copilot + +VS Code lets you register external MCP servers and make their tools available to Copilot Chat. Once configured, start a chat and pick the {trento} MCP Server tools to run common operations. + +.Visual Studio Code with GitHub Copilot using {trento} MCP Server +image::example-copilot.png[VS Code Copilot using {trento} MCP Server,width=900] + +==== Additional Resources + +* <> - For deploying and configuring the MCP Server. +* <> - For detailed MCP Server configuration reference. +* https://modelcontextprotocol.io[Model Context Protocol Documentation] - For general MCP information and client compatibility. diff --git a/trento/adoc/trento-mcp-sles.adoc b/trento/adoc/trento-mcp-sles.adoc new file mode 100644 index 00000000..b042ca0c --- /dev/null +++ b/trento/adoc/trento-mcp-sles.adoc @@ -0,0 +1,179 @@ +:revdate: 2025-10-31 + +This guide explains how to connect the {trento} MCP Server to {sles} 16 (SLES 16) using MCPHost, a lightweight CLI tool for the Model Context Protocol (MCP). + +SLES 16 is designed for modern, AI-powered workloads and agentic applications. If you run SAP landscapes, {sles4sap} 16 builds on SLES 16 and pairs naturally with {trento} for intelligent, stable operations. + +As the MCP ecosystem expands, more MCP hosts and integrations will be available for SLES and SLES for SAP, installable and updatable with `zypper`. This guide focuses on MCPHost for its simplicity and compatibility with remote MCP servers like {trento}. + +==== Prerequisites + +Before configuring your MCP Host, ensure you have: + +* A SLES 16 system with network access +* An LLM provider and credentials: +** Public hosted options, such as Google Gemini, OpenAI, etc. +** Private/on-premises option, such as {suseai} Platform - See the guide on <>. + +* *A running {trserver} installation* with the {trento} MCP Server component enabled: +** Follow the <> to deploy {trserver} and enable the {trento} MCP Server. +** Note the {trento} MCP Server endpoint URL (e.g., `https://trento.example.com/mcp-server-trento/mcp`). + +* *A {trento} API token (Personal Access Token)*: +** Log in to your {trento} web interface with your username and password +** Click on your username in the top-right corner and select *Profile*. +** Scroll down to the *Personal Access Tokens* section. +** Click the *Generate Token* button. +** Enter a descriptive name for the token (e.g., "VS Code MCP Client"). +** Optionally configure an expiration date for the token, or select *Never Expires*. +** Click *Generate Token*. +** *Important:* Copy the generated token immediately and store it securely - it will not be shown again. + +.Generate a Personal Access Token in {trento} +image::generate-pat.png[Generate a Personal Access Token in {trento},width=800] + +==== Install MCPHost on SLES 16 + +MCPHost is available as a package on SLES 16 and can be installed using the standard SUSE package manager. This ensures you get a version tested for your platform, with automatic updates and dependency management. + +To install MCPHost, open a terminal and run: + +[source,console] +---- +sudo zypper refresh +sudo zypper install mcphost +---- + +This will download and install the latest available version of MCPHost and any required dependencies. + +After installation, verify that MCPHost is available and working by checking its version: + +[source,console] +---- +mcphost --version +---- + +If you see the version and copyright, MCPHost is installed correctly and ready for configuration. + +==== Configure MCPHost + +Refer to the official https://github.com/mark3labs/mcphost#installation[MCPHost documentation] for comprehensive configuration details. This section focuses on adding the {trento} MCP Server to your system. + +MCPHost reads its configuration from several locations; one common location is `~/.mcphost.yml`. Create `~/.mcphost.yml` with the following content: + +[source,yaml] +---- +mcpServers: + trento-mcp-server: + type: "remote" + url: https://trento.example.com/mcp-server-trento/mcp + headers: + - "Authorization: Bearer ${env://TRENTO_PAT}" +---- + +[NOTE] +==== +**Security best practice:** Keep secrets out of configuration files. Store your keys in environment variables instead of hardcoding them. + +Export your keys in the shell before running MCPHost: + +[source,console] +---- +export GOOGLE_API_KEY= +export TRENTO_PAT= +---- +==== + +* Replace `https://trento.example.com/mcp-server-trento/mcp` with the actual URL where your {trento} MCP Server is accessible: + ** For Kubernetes deployments with ingress, use the ingress URL (e.g., `https://trento.example.com/mcp-server-trento/mcp`). + ** For local or development setups, use `http://localhost:5000/mcp` (adjust the port as needed). + ** If using Server-Sent Events (SSE) transport instead of the default streamable transport, change the path from `/mcp` to `/sse` - The transport type is configured on the {trento} MCP Server using the `TRANSPORT` configuration key or `--transport` flag (see <>). + +* Replace `` with the API token you generated from your {trento} instance. +* If you configured a custom header name (using `HEADER_NAME` or `--header-name`), update `Authorization` accordingly. + +[TIP] +==== +You can also configure remote LLM models directly in your MCPHost configuration. For example, to use Google Gemini as your model provider: + +[source,yaml] +---- +model: "google:gemini-2.5-pro" +provider-url: "https://generativelanguage.googleapis.com/v1beta/openai/" +provider-api-key: "${env://GOOGLE_API_KEY}" +---- + +This configuration uses the `GOOGLE_API_KEY` environment variable you exported earlier. +==== + +==== Run MCPHost and use {trento} Tools + +[arabic] +. Start MCPHost: ++ +[source,console] +---- +mcphost +---- ++ +[TIP] +==== +If no servers appear on startup, confirm your configuration file exists at `~/.mcphost.yml` (or another supported location listed in the MCPHost docs) and that your environment variables are exported in the same shell session. +==== +. Verify the connection to {trento} and basic status: ++ +[source,console] +---- +/servers +---- ++ +.MCPHost initial screen with the {trento} MCP Server connected +image::mcphost-initial.png[MCPHost initial screen, width=900] ++ +. Ask the model to invoke {trento} tools using natural language prompts, such as: ++ +* "List all {sap} systems managed". +* "Show my HANA clusters". +* "Are my {sap} systems compliant?" +* "What is the health status of my {sap} landscape?" +* "Show me all hosts running {sap} applications". +* "Are there any critical alerts I need to address?" +* "Get details about the latest check execution results". +* "Which {sap} systems are currently running?" ++ +.Example MCPHost session querying {trento} about SAP systems +image::example-mcphost.png[Example MCPHost session with {trento},width=900] + +==== Troubleshooting + +If you encounter issues connecting MCPHost to the {trento} MCP Server: + +. *Connection Errors* +** Verify that the {trento} MCP Server URL in `~/.mcphost.yml` is correct and accessible from your SLES 16 system. +** Check if the {trento} MCP Server is running by reviewing logs from your {trento} installation. +** Ensure network connectivity and that any required firewall rules are in place. +** Test basic connectivity: `curl -I https://trento.example.com/mcp-server-trento/mcp`. + +. *Authentication Errors* +** Verify that your API token is valid by testing it directly against your {trento} Server API. +** Ensure `TRENTO_PAT` is exported in the same shell session before running `mcphost`. +** Check that the header name matches your server configuration (default: `Authorization`). +** Ensure the token has the necessary permissions in {trento}. + +. *LLM Provider Errors* +** Verify that `GOOGLE_API_KEY` (or your provider's API key) is exported correctly. +** Check the `provider-url` and `model` configuration in your `~/.mcphost.yml`. +** Confirm that your API key has sufficient quota and permissions with your provider. + +. *General Issues* +** Check the MCPHost terminal output for detailed error messages during startup or operation. +** Review the {trento} MCP Server logs for connection attempts and errors. +** Verify that your configuration file exists at `~/.mcphost.yml` and has correct YAML syntax. +** Refer to the <> for additional help. + +==== Additional Resources + +* https://github.com/mark3labs/mcphost#configuration-file-support[MCPHost Configuration Documentation] - For comprehensive MCPHost configuration details. +* <> - For deploying and configuring the MCP Server. +* <> - For detailed {trento} MCP Server configuration reference. +* https://modelcontextprotocol.io[Model Context Protocol Documentation] - For general MCP information and client compatibility. diff --git a/trento/adoc/trento-mcp-suse-ai.adoc b/trento/adoc/trento-mcp-suse-ai.adoc new file mode 100644 index 00000000..7132b147 --- /dev/null +++ b/trento/adoc/trento-mcp-suse-ai.adoc @@ -0,0 +1,200 @@ +:revdate: 2025-10-31 + +This guide explains how to integrate the {trento} MCP Server with {suseai}, including configuration and deployment instructions. + +==== Getting Started with {suseai} + +{suseai} is a platform that allows you to deploy and manage AI models and applications in a {kube} environment. It provides tools for model management, deployment, and integration with various AI frameworks. + +Refer to the official https://documentation.suse.com/suse-ai/1.0/[{suseai} documentation] for detailed information. This guide focuses on deploying the {trento} MCP Server with {suseai}, specifically using Ollama and Open Web UI. Always refer to the latest instructions in the https://documentation.suse.com/suse-ai/1.0/html/AI-deployment-intro/index.html[{suseai} deployment guide] for the most accurate and up-to-date information. + +==== Prerequisites + +This guide assumes: + +* A {kube} cluster set up and running (with an ingress controller and cert-manager installed). +* Access to the {suse} Application Collection. + +When running Ollama models, this guide assumes you have one of the following: + +* A {kube} cluster with sufficient resources (GPU, memory, etc.). +* A cloud provider and enough permissions to deploy Ollama models remotely. + +==== Limitations + +Deploying the entire {suseai} stack requires significant resources, especially for running Ollama models. Alternatively, you can deploy only Open Web UI and connect it to an Ollama instance running elsewhere. This guide uses this approach: on-premises Open Web UI with Ollama running on a remote server (e.g., Google Cloud). + +==== Getting the Artifacts from SUSE Application Collection + +You need access to the SUSE Application Collection and proper entitlements to download the required artifacts. Always refer to the https://docs.apps.rancher.io/get-started/authentication/[SUSE Application Collection documentation] for the latest instructions on authentication and access. This guide assumes you have the necessary credentials and permissions. + +[NOTE] +==== +To run the entire stack, you can also use the https://github.com/SUSE/suse-ai-deployer[{suseai} Deployer Helm Chart]. +==== + +[arabic] +. Log in to the {suse} Application Collection: ++ +[source,console] +---- +# Replace placeholders with your actual credentials +helm registry login dp.apps.rancher.io/charts -u -p +---- + +. Create a namespace for {suseai}: ++ +[source,console] +---- +kubectl create namespace suse-ai +---- + +. Create a {kube} Pull Secret (`application-collection`) for the {suse} Application Collection: + ++ +[source,console] +---- +# Replace placeholders with your actual credentials +kubectl create -n suse-ai secret docker-registry application-collection \ + --docker-server=dp.apps.rancher.io \ + --docker-username= \ + --docker-password= +---- + +==== Install Open Web UI + +This section describes how to install the Open Web UI, which provides a user-friendly interface for interacting with AI models. + +[arabic] +. Create a link:https://github.com/trento-project/mcp-server/blob/main/docs/examples/values.openwebui.yaml[values.openwebui.yaml] file with the values for Open Web UI. + +[arabic] +. Install Open Web UI using Helm with the values file (`values.openwebui.yaml`) created above: ++ +[NOTE] +==== +You must have `cert-manager` properly installed, and an ingress controller is required. If you don't have an ingress controller, you may need to adjust the {kube} services configuration. +==== ++ + +[source,console] +---- +helm -n suse-ai upgrade --install open-webui oci://dp.apps.rancher.io/charts/open-webui -f values.openwebui.yaml +---- + +==== Deploying a Model with Ollama Remotely + +If your infrastructure does not have sufficient resources to run Ollama models, you can deploy them on a remote server, such as Google Cloud Run. + +This section describes how to deploy the https://ollama.com/library/qwen3:8b[`Qwen3:8b`] model using Ollama on Google Cloud Run. This guide assumes you have a Google Cloud account and the necessary permissions to deploy applications on Google Cloud Run. + +[NOTE] +==== +Always refer to the https://cloud.google.com/run/docs/tutorials/gpu-gemma-with-ollama[official Google Cloud documentation] for the most accurate and up-to-date information. +==== + +[arabic] +. Create a link:https://github.com/trento-project/mcp-server/blob/main/docs/examples/Dockerfile[Dockerfile] for the Ollama model. + +[arabic] +. In the same directory as the `Dockerfile`, run the following command to build the Docker image: + +[source,console] +---- +gcloud run deploy qwen3-8b --source . --concurrency 4 --cpu 8 --set-env-vars OLLAMA_NUM_PARALLEL=4 --gpu 1 --gpu-type nvidia-l4 --max-instances 1 --memory 32Gi --no-allow-unauthenticated --no-cpu-throttling --no-gpu-zonal-redundancy --timeout=600 +---- + ++ +[NOTE] +==== +To make requests, you need to either allow unauthenticated requests or use a service account with the necessary permissions. Refer to the https://cloud.google.com/run/docs/authenticating/service-to-service[Google Cloud Run documentation] for information on setting up service accounts and permissions. +==== ++ +After deployment, you will have a Google Cloud Run service running the `Qwen3:8b` model, accessible via a URL provided by Google Cloud Run (e.g., `https://qwen3-8b-..run.app`). + +==== Adding the Remote Model to Open Web UI + +Once you have the Ollama model running on Google Cloud Run, you can add it to Open Web UI for easy access. + +[arabic] +. Navigate to the Open Web UI settings page (e.g., `suse-ai.example.com/admin/settings`) and go to the *Connections* section. +. Add a new Ollama connection with the URL of your deployed model (e.g., `https://qwen3-8b-..run.app`). +. Navigate to the *Models* section, click *Manage Models*, select the Ollama connection you just created, and pull the `Qwen3:8b` model. + +==== Deploying the {trento} MCP Server + +To deploy the {trento} MCP Server in your {suseai} cluster, install it via the {trento} Server Helm chart. Follow the step-by-step instructions in <>. The {trento} MCP Server is packaged as a sub-chart and can be enabled during the {trento} Server installation. + +For chart sources and values, see the link:https://github.com/trento-project/helm-charts[{trento} helm-charts repository]. + +Once {trento} is installed, ensure you have created a *{trento} API token (Personal Access Token)*: + +** Log in to your {trento} web interface with your username and password. +** Click on your username in the top-right corner and select *Profile*. +** Scroll down to the *Personal Access Tokens* section. +** Click the *Generate Token* button. +** Enter a descriptive name for the token (e.g., "MCP Client"). +** Optionally configure an expiration date for the token, or select *Never Expires*. +** Click *Generate Token*. +** *Important:* Copy the generated token immediately and store it securely - it will not be shown again. + +.Generate a Personal Access Token in {trento} +image::generate-pat.png[Generate a Personal Access Token in {trento},width=800] + +==== Adding the {trento} MCP Server to Open Web UI + +Open Web UI includes native support for the Model Context Protocol (MCP). With this integration, Open Web UI connects to MCP servers from the backend, allowing you to safely use an internal {kube} Service DNS name without exposing the service publicly. + +Refer to the official Open Web UI MCP feature guide for screenshots and advanced options: https://docs.openwebui.com/features/mcp[Open Web UI with MCP]. + +==== Add the {trento} MCP Server in Open Web UI + +[arabic] +. Open *Admin Settings* and go to *External Tools*. +. Click *Add Server*. +. Set *Type* to `MCP (Streamable HTTP)`. +. Enter your Server URL and authentication details: +.. *Server URL* (example): `http://trento-server-mcp-server.suse-ai.svc.cluster.local:5000/mcp` +.. *Auth*: `` (the token you generated in the {trento} console) +. Click *Save*. + +.Open Web UI - Add the {trento} MCP Server as a tool +image::owui-add-tool.png[Add the {trento} MCP Server as a tool,width=600] + +==== Enable the {trento} MCP Server for a Model + +[arabic] +. Go to *Models*, select *Manage Models*, and open your target model (e.g., `Qwen3:8b`). +. In the *Tools* or *MCP Servers* section, enable/select `{trento} MCP Server` for this model. This makes the {trento} tools available to any user of that model in Open Web UI. +. Verify the integration: +.. Start a new chat with the enabled model +.. Confirm that tools from `{trento} MCP Server` are available and can be invoked (for example, try listing SAP systems) + +.Open Web UI - Enable {trento} MCP Server for a model +image::owui-add-model.png[Enable {trento} MCP Server for model,width=600] + +==== Using the {trento} MCP Server + +Once the {trento} MCP Server is configured and enabled for your model, you can start using it to interact with your SAP systems through natural language conversations. + +[arabic] +. Navigate to the Open Web UI main screen and select your configured model (e.g., `Qwen3:8b`) from the model selector. +. Start a new chat session with the model. +. Ask questions about your SAP landscape using natural language: +.. "List all {sap} systems in my environment" +.. "Show me the health status of my HANA clusters" +.. "Are there any critical alerts I need to address?" +.. "What {sap} systems are currently running?" +.. "Show me all hosts running {sap} applications" +.. "Get details about the latest check execution results" + +The AI model will use the {trento} MCP Server tools to query your {trento} installation and provide detailed, contextual responses about your SAP infrastructure. + +.Open Web UI - Using {trento} MCP Server in conversations +image::example-suseai.png[Using {trento} MCP Server in Open Web UI,width=900] + +==== Additional Resources + +* <> - For deploying and configuring the MCP Server. +* <> - For detailed MCP Server configuration reference. +* https://modelcontextprotocol.io[Model Context Protocol Documentation] - For general MCP information and client compatibility. diff --git a/trento/adoc/trento-requirements.adoc b/trento/adoc/trento-requirements.adoc index dd3e2bfb..3edc2c42 100644 --- a/trento/adoc/trento-requirements.adoc +++ b/trento/adoc/trento-requirements.adoc @@ -2,7 +2,7 @@ include::product-attributes.adoc[] [[sec-trento-requirements]] == Requirements -:revdate: 2025-08-06 +:revdate: 2025-10-31 This section describes requirements for the {trserver} and its {tragent}s. @@ -45,6 +45,12 @@ The hosts must have unique machine identifiers (ids) in order to be registered i Similarly, the clusters must have unique authkeys in order to be registered in {trento}. +=== {trento} MCP Server requirements (optional) + +The {trento} MCP Server is an optional component that enables AI-assisted operations via the link:https://modelcontextprotocol.io/introduction[Model Context Protocol] (MCP). It exposes a single HTTP endpoint that MCP-compatible assistants can use to interact with {trento}. + +The MCP Server is lightweight and stateless. No persistent storage required; allocate space for logs as per your logging policy. + [[sec-trento-network-requirements]] === Network requirements @@ -53,8 +59,24 @@ Similarly, the clusters must have unique authkeys in order to be registered in { * The Prometheus component of the {trserver} must be able to reach the Node Exporter in the {tragent} hosts (port TCP/9100). * The {sap} Basis administrator must access to the Web component of the {trserver} via HTTP (port TCP/80) or via HTTPS (port TCP/443) if SSL is enabled. +==== MCP Server network requirements (optional) + +Inbound to the MCP Server: + +* TCP/5000 for the MCP endpoint (default, adjustable via `PORT`). The API is exposed under the path `/mcp` + ** In {k8s}, expose via Ingress host/path as configured in the Helm chart + ** On systemd/container deployments, ensure the firewall allows access on the chosen port +* Optional: TCP/8080 for health checks when enabled (`ENABLE_HEALTH_CHECK=true`; port adjustable via `HEALTH_PORT`) + +Outbound from the MCP Server to {trserver}: + +* If using `TRENTO_URL` (recommended): HTTPS to the externally reachable {trserver} URL (for example, behind NGINX) +* If using `OAS_PATH` (direct internal access): HTTP(S) to the Web and Wanda API endpoints (for example, `http://localhost:4000/api/all/openapi`, `http://localhost:4001/wanda/api/all/openapi`, or the corresponding service names in {k8s}/container networks) + + [[sec-trento-installation-prerequisites]] === Installation prerequisites * *{trserver}* For a {k8s}-based deployment, you must have access to {suse} public registry for the deployment of {trserver} containers. For a systemd deployment, you must have a registered {sles4sap} 15 (SP3 or higher) distribution. The same applies to a containerized deployment. * *{tragent}s* A registered {sles4sap} 15 (SP3 or higher) distribution. +* *{trento} MCP Server* (optional): a running {trserver} (Web and Wanda components) reachable from the MCP Server, network connectivity from the MCP Server to the {trserver} API endpoints and a Personal Access Token (user-scoped) created in {trweb} to authenticate requests from MCP clients. diff --git a/trento/adoc/trento-systemd-install.adoc b/trento/adoc/trento-systemd-install.adoc index b4992147..88ea67de 100644 --- a/trento/adoc/trento-systemd-install.adoc +++ b/trento/adoc/trento-systemd-install.adoc @@ -2,12 +2,12 @@ include::product-attributes.adoc[] [[sec-systemd-deployment]] === systemd deployment -:revdate: 2025-08-05 +:revdate: 2025-10-31 A systemd installation of {trento} Server, based on RPM packages, can be done -manually using the latest available version of SUSE Linux Enterprise Server for -SAP Applications. For installations on Service Packs other than the current one, +manually using the latest available version of {sles} for +{sap} Applications. For installations on Service Packs other than the current one, update the repository address as indicated in the respective notes provided throughout this guide. @@ -40,7 +40,7 @@ If you choose not to install Prometheus, set `+CHARTS_ENABLED+` to `+false+` in the {trento} web RPM configuration file stored in `+/etc/trento/trento-web+`, or when it is provided to the {trento} web container. To use an existing Prometheus installation, set `+CHARTS_ENABLED+` to -`+true+` +`+true+` ==== [[prometheus-existing-installation, Use existing installation]] @@ -422,7 +422,7 @@ journalctl -fu trento-web ---- [[validate-the-health-status-of-trento-web-and-wanda]] -==== Check the health status of trento web and wanda +==== Check the health status of {trweb} and wanda You can check if {trento} web and wanda services function correctly by accessing accessing the `+healthz+` and `+readyz+` API. @@ -668,3 +668,195 @@ details on how to renew certificates. Pin the browser to `+https://trento.example.com+`. You should be able to login using the credentials specified in the `+ADMIN_USER+` and `+ADMIN_PASSWORD+` environment variables. + +[[sec-trento-mcp-server-systemd]] +==== Installing {trento} MCP Server (Optional) + +The {trento} MCP Server provides AI-assisted management capabilities for your SAP landscape by exposing {trento} functionality through the Model Context Protocol (MCP). This optional component enables integration with AI tools and assistants. + +[NOTE] +==== +The {trento} MCP Server is an optional component. The core {trserver} functionality works independently without it. + +After installation, see <> for instructions on how to connect MCP-compatible AI assistants and tools to your Trento Server. +==== + +===== Requirements + +* {sles4sap} 15 SP3 or later. +* A running {trserver} installation (accessible via network). +* Root or sudo access for installation. + +===== Configuration Overview + +The {trento} MCP Server requires minimal configuration, but needs to know how to reach your Trento Server. The key configuration parameters are: + +* `TRENTO_URL`: The URL where your Trento Server is accessible. This is particularly important when Trento is deployed behind NGINX or other reverse proxies. Use the externally accessible URL (e.g., `https://trento.example.com`) rather than internal service URLs. When set, the server will use this URL for OpenAPI specification autodiscovery. + +* `OAS_PATH`: Explicit paths to OpenAPI specification files. Use this when you want to directly specify the location of the API specifications instead of relying on autodiscovery. This is particularly useful when you want to connect to internal services (such as `localhost` or Kubernetes service names) instead of going through a reverse proxy. + +===== Installation Steps + +. Install the MCP Server package: ++ +==== +[source,bash] +---- +zypper install mcp-server-trento +---- +==== ++ +. Create the configuration file at `/etc/trento/mcp-server-trento`: ++ +==== +[source,bash] +---- +cp /etc/trento/mcp-server-trento.example /etc/trento/mcp-server-trento +---- +==== ++ +. Edit the configuration file to point to your {trserver}: ++ +==== +[source,bash] +---- +nano /etc/trento/mcp-server-trento +---- +==== ++ +Configure the connection to your {trserver}. There are two approaches: ++ +==== +.TRENTO_URL approach (Recommended for most deployments) +[source,env] +---- +## Set this to your Trento Server's external/public URL +## Use this when Trento is behind a reverse proxy (like NGINX) or when accessing from outside the local network +TRENTO_URL=https://trento.example.com +PORT=5000 +---- + +.OAS_PATH approach (For direct internal connections) +[source,env] +---- +## Use this when connecting directly to Trento components without going through a reverse proxy +## Useful when MCP Server runs on the same network as Trento components +OAS_PATH=http://localhost:4000/api/all/openapi,http://localhost:4001/wanda/api/all/openapi +PORT=5000 +---- +==== ++ +[NOTE] +==== +**When to use TRENTO_URL:** +* Trento Server is deployed behind a reverse proxy (NGINX, etc.). +* MCP Server runs on a different host/network than Trento. +* You want to use external/public URLs. + +**When to use OAS_PATH:** +* MCP Server runs on the same host as Trento components. +* You want to connect directly to internal services. +* You need to bypass reverse proxy configurations. + +The TRENTO_URL approach is recommended for most production deployments. +==== ++ +[NOTE] +==== +The MCP Server's health check HTTP server is primarily intended for Kubernetes environments, where liveness/readiness probes use it. Outside Kubernetes, you can leave it disabled. If you choose to enable it, set `ENABLE_HEALTH_CHECK=true` and `HEALTH_PORT=8080` (or your preferred port) and ensure the port is accessible (see the Firewall Configuration section below). +==== ++ +. Enable and start the MCP Server service: ++ +==== +[source,bash] +---- +systemctl enable --now mcp-server-trento +systemctl start mcp-server-trento +---- +==== ++ +. Verify the service is running: ++ +==== +[source,bash] +---- +systemctl status mcp-server-trento +---- +==== ++ +Expected output: ++ +==== +[source,bash] +---- +● mcp-server-trento.service - Trento MCP Server service + Loaded: loaded (/usr/lib/systemd/system/mcp-server-trento.service; enabled) + Active: active (running) since ... +---- +==== ++ +. Check the service logs: ++ +==== +[source,bash] +---- +journalctl -u mcp-server-trento -f +---- +==== ++ +. The Trento MCP Server should be listening at `http://localhost:5000/mcp` (or `http://localhost:/mcp` if you changed the `PORT` setting). If you need remote access, ensure this port is open in your firewall; see <>. ++ +. If you enabled health checks, verify the endpoints locally: + +==== +[source,bash] +---- +# Note: Replace localhost with the server's IP/hostname if running these commands from a remote machine, and ensure the health port is allowed by your firewall. + +# Liveness endpoint: +curl http://localhost:8080/livez + +# Example output: +# {"info":{"name":"trento-mcp-server","version":"0.1.0"},"status":"up"} + +# Readiness endpoint: +curl http://localhost:8080/readyz + +# Example output: +# {"status":"up","details":{"mcp-server":{"status":"up","timestamp":"2025-10-09T12:11:09.528898849Z"},"wanda-api":{"status":"up","timestamp":"2025-10-09T12:11:09.542078327Z"},"web-api":{"status":"up","timestamp":"2025-10-09T12:11:09.544855047Z"}}} +---- +==== + +[[sec-mcp-systemd-firewall]] +===== Firewall Configuration + +If firewalld is running, allow incoming connections to the MCP Server port: + +==== +[source,bash] +---- +firewall-cmd --zone=public --add-port=5000/tcp --permanent +firewall-cmd --reload +---- +==== + +If health checks are enabled, and you want them to be exposed, also allow the health check port: + +==== +[source,bash] +---- +firewall-cmd --zone=public --add-port=8080/tcp --permanent +firewall-cmd --reload +---- +==== + +[NOTE] +==== +Use the ports you configured. Replace the example values `5000` and `8080` with your actual settings: + +- `PORT`: MCP Server listening port (default: 5000). +- `HEALTH_PORT`: Health check server port (default: 8080). + +Adjust all commands and firewall rules accordingly. +==== diff --git a/trento/adoc/trento-using-mcp-server.adoc b/trento/adoc/trento-using-mcp-server.adoc new file mode 100644 index 00000000..3aae8eb0 --- /dev/null +++ b/trento/adoc/trento-using-mcp-server.adoc @@ -0,0 +1,26 @@ +include::product-attributes.adoc[] + +[[sec-trento-using-mcp-server]] +:revdate: 2025-10-31 +== Using the {trento} MCP Server + +The {trento} MCP Server enables AI-assisted operations by implementing the link:https://modelcontextprotocol.io/introduction[Model Context Protocol] (MCP). This allows MCP-compatible assistants to connect to {trento} and perform monitoring and troubleshooting tasks using natural language. + +This section provides comprehensive documentation for deploying and using the {trento} MCP Server: + +* <> - Complete installation guide covering all deployment methods +* <> - Detailed configuration options and examples + +Integration guides for different MCP hosts and environments: + +[[sec-trento-mcp-sles]] +=== Integrating the {trento} MCP Server with SLES 16 +include::trento-mcp-sles.adoc[] + +[[sec-trento-mcp-suse-ai]] +=== Integrating the {trento} MCP Server with {suseai} +include::trento-mcp-suse-ai.adoc[] + +[[sec-trento-mcp-others]] +=== Integrating the {trento} MCP Server with other MCP Hosts +include::trento-mcp-others.adoc[] diff --git a/trento/images/src/png/example-claude.png b/trento/images/src/png/example-claude.png new file mode 100644 index 00000000..ad14f8f7 Binary files /dev/null and b/trento/images/src/png/example-claude.png differ diff --git a/trento/images/src/png/example-copilot.png b/trento/images/src/png/example-copilot.png new file mode 100644 index 00000000..52da3ebb Binary files /dev/null and b/trento/images/src/png/example-copilot.png differ diff --git a/trento/images/src/png/example-mcphost.png b/trento/images/src/png/example-mcphost.png new file mode 100644 index 00000000..86001d00 Binary files /dev/null and b/trento/images/src/png/example-mcphost.png differ diff --git a/trento/images/src/png/example-suseai.png b/trento/images/src/png/example-suseai.png new file mode 100644 index 00000000..6eaa0df5 Binary files /dev/null and b/trento/images/src/png/example-suseai.png differ diff --git a/trento/images/src/png/generate-pat.png b/trento/images/src/png/generate-pat.png new file mode 100644 index 00000000..659da9db Binary files /dev/null and b/trento/images/src/png/generate-pat.png differ diff --git a/trento/images/src/png/mcphost-initial.png b/trento/images/src/png/mcphost-initial.png new file mode 100644 index 00000000..bd086155 Binary files /dev/null and b/trento/images/src/png/mcphost-initial.png differ diff --git a/trento/images/src/png/owui-add-model.png b/trento/images/src/png/owui-add-model.png new file mode 100644 index 00000000..e6ed1a44 Binary files /dev/null and b/trento/images/src/png/owui-add-model.png differ diff --git a/trento/images/src/png/owui-add-tool.png b/trento/images/src/png/owui-add-tool.png new file mode 100644 index 00000000..16499992 Binary files /dev/null and b/trento/images/src/png/owui-add-tool.png differ diff --git a/trento/images/src/png/trento-high-level-architecture.png b/trento/images/src/png/trento-high-level-architecture.png index d05d2092..1a30b615 100644 Binary files a/trento/images/src/png/trento-high-level-architecture.png and b/trento/images/src/png/trento-high-level-architecture.png differ