[TRNT-3946] Add MCP documentation

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]
+*** https://pkg.go.dev/github.com/trento-project/agent[Agent]

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 <<sec-trento-using-mcp-server>> 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"}}}
+----
+====

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[]

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 <<fig-trento-architecture>> for additional details.
 
 [[fig-trento-architecture]]
 .Architectural overview
-image::trento-high-level-architecture.png[width=80%]
+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 <<sec-trento-using-mcp-server>>.