feat(deployments): add ocis-mcp-server to the ocis_full example

changelog/unreleased/enhancement-add-ocis-mcp-server-to-full.md

@@ -0,0 +1,10 @@
+Enhancement: Add oCIS MCP Server to the ocis_full deployment example
+
+Added the oCIS MCP Server (https://github.com/owncloud/ocis-mcp-server) as an optional
+service to the ocis_full deployment example. It exposes oCIS as a set of AI-accessible
+tools over the Model Context Protocol, so AI assistants such as Claude can manage users,
+spaces, files and shares through natural language without the user having to build and
+run the MCP server locally. It is disabled by default and can be enabled by uncommenting
+`OCIS_MCP=:mcp.yml` in `.env`.
+
+https://github.com/owncloud/ocis/pull/12603

deployments/examples/ocis_full/.env

@@ -297,8 +297,32 @@ MAIL_SERVER_DOCKER_TAG=v1.29.3
 #MONITORING_COLLABORATION_OO=m_collaboration-oo.yml
 
 
+### oCIS MCP Server Settings ###
+# Exposes ownCloud Infinite Scale as a set of AI-accessible tools via the Model Context
+# Protocol (MCP), so AI assistants (e.g. Claude) can manage users, spaces, files and shares
+# through natural language, without installing the MCP server locally.
+# See: https://github.com/owncloud/ocis-mcp-server
+# Note: the leading colon is required to enable the service.
+#OCIS_MCP=:mcp.yml
+# Set the desired docker image tag or digest.
+# Defaults to "latest"
+OCIS_MCP_DOCKER_TAG=latest
+# Domain of the MCP server, where MCP clients connect over HTTPS.
+# Defaults to "mcp.owncloud.test"
+OCIS_MCP_DOMAIN=
+# Shared secret MCP clients must send as "Authorization: Bearer <secret>".
+# REQUIRED when OCIS_MCP is enabled: the container refuses to start without it, since the
+# HTTP endpoint executes every tool with the app token's privileges.
+# Generate one with: openssl rand -hex 32
+OCIS_MCP_HTTP_SECRET=
+# oCIS app token the MCP server uses to call the oCIS APIs. Create one with:
+#   docker-compose exec ocis ocis auth-app create --user-name="admin" --expiration="8760h"
+OCIS_MCP_APP_TOKEN_USER=
+OCIS_MCP_APP_TOKEN_VALUE=
+
+
 ## IMPORTANT ##
 # This MUST be the last line as it assembles the supplemental compose files to be used.
 # ALL supplemental configs must be added here, whether commented or not.
 # Each var must either be empty or contain :path/file.yml
-COMPOSE_FILE=docker-compose.yml${OCIS:-}${TIKA:-}${S3NG:-}${S3NG_MINIO:-}${COLLABORA:-}${IMPORTER:-}${CLAMAV:-}${ONLYOFFICE:-}${EXTENSIONS:-}${UNZIP:-}${DRAWIO:-}${JSONVIEWER:-}${PROGRESSBARS:-}${EXTERNALSITES:-}${PHOTOADDON:-}${ADVANCEDSEARCH:-}${MAIL_SERVER:-}${MONITORING:-}${KEYCLOAK:-}${VAULT_STORAGE:-}
+COMPOSE_FILE=docker-compose.yml${OCIS:-}${TIKA:-}${S3NG:-}${S3NG_MINIO:-}${COLLABORA:-}${IMPORTER:-}${CLAMAV:-}${ONLYOFFICE:-}${EXTENSIONS:-}${UNZIP:-}${DRAWIO:-}${JSONVIEWER:-}${PROGRESSBARS:-}${EXTERNALSITES:-}${PHOTOADDON:-}${ADVANCEDSEARCH:-}${MAIL_SERVER:-}${MONITORING:-}${KEYCLOAK:-}${VAULT_STORAGE:-}${OCIS_MCP:-}

deployments/examples/ocis_full/README.md

@@ -23,3 +23,13 @@ Keycloak can be optionally enabled by uncommenting the corresponding variables i
 - `KEYCLOAK=:keycloak.yml`
 
 Note that Keycloak requires the default `ocis` Identity Provider to be disabled, which is automatically handled when the `keycloak.yml` configuration is used.
+
+### MCP Server
+
+The [oCIS MCP Server](https://github.com/owncloud/ocis-mcp-server) exposes this deployment as a set of AI-accessible tools over the Model Context Protocol (MCP), so AI assistants such as Claude can manage users, spaces, files and shares through natural language. It can be optionally enabled by uncommenting the corresponding variable in the `.env` file:
+- `OCIS_MCP=:mcp.yml`
+
+It is reachable at `https://${OCIS_MCP_DOMAIN:-mcp.owncloud.test}` once enabled. Two things must be configured in `.env` before it will start:
+- `OCIS_MCP_HTTP_SECRET` — a shared secret every MCP client must send as `Authorization: Bearer <secret>`. The container refuses to start without it.
+- `OCIS_MCP_APP_TOKEN_USER` / `OCIS_MCP_APP_TOKEN_VALUE` — an oCIS app token, created with `docker-compose exec ocis ocis auth-app create --user-name="admin" --expiration="8760h"`.
+  **Note:** the `auth-app` service is not started by default — add `auth-app` to `START_ADDITIONAL_SERVICES` in `.env` first, or the command above will silently create an empty token.

deployments/examples/ocis_full/mcp.yml

@@ -0,0 +1,29 @@
+---
+services:
+  ocis-mcp-server:
+    image: owncloud/ocis-mcp-server:${OCIS_MCP_DOCKER_TAG:-latest}
+    # release notes: https://github.com/owncloud/ocis-mcp-server/releases
+    networks:
+      ocis-net:
+    depends_on:
+      ocis:
+        condition: service_started
+    environment:
+      OCIS_MCP_OCIS_URL: https://${OCIS_DOMAIN:-ocis.owncloud.test}
+      OCIS_MCP_TLS_SKIP_VERIFY: "${INSECURE:-true}"
+      OCIS_MCP_TRANSPORT: http
+      OCIS_MCP_HTTP_ADDR: 0.0.0.0:8090
+      OCIS_MCP_HTTP_SECRET: ${OCIS_MCP_HTTP_SECRET:-}
+      OCIS_MCP_APP_TOKEN_USER: ${OCIS_MCP_APP_TOKEN_USER:-}
+      OCIS_MCP_APP_TOKEN_VALUE: ${OCIS_MCP_APP_TOKEN_VALUE:-}
+      OCIS_MCP_LOG_LEVEL: ${LOG_LEVEL:-info}
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.ocis-mcp-server.entrypoints=https"
+      - "traefik.http.routers.ocis-mcp-server.rule=Host(`${OCIS_MCP_DOMAIN:-mcp.owncloud.test}`)"
+      - "traefik.http.routers.ocis-mcp-server.tls.certresolver=http"
+      - "traefik.http.routers.ocis-mcp-server.service=ocis-mcp-server"
+      - "traefik.http.services.ocis-mcp-server.loadbalancer.server.port=8090"
+    logging:
+      driver: ${LOG_DRIVER:-local}
+    restart: always

docs/ocis/deployment/ocis_full.md

@@ -308,6 +308,31 @@ CLAMAV=:clamav.yml
 
 After enabling that service, you can add the service to the stack with `docker-compose up -d` again.
 
+### MCP Server
+
+You can add the [oCIS MCP Server](https://github.com/owncloud/ocis-mcp-server) to the stack. It exposes oCIS as a set of AI-accessible tools over the Model Context Protocol (MCP). The service is disabled by default. To enable it, uncomment the `OCIS_MCP` line in the `.env` file, then set a bearer secret and an oCIS app token:
+
+```shell {linenos=table,hl_lines=[3,4,5,6]}
+### oCIS MCP Server Settings ###
+# The leading colon is required to enable the service.
+OCIS_MCP=:mcp.yml
+OCIS_MCP_HTTP_SECRET=change-me-to-a-long-random-value
+OCIS_MCP_APP_TOKEN_USER=admin
+OCIS_MCP_APP_TOKEN_VALUE=<token printed by "ocis auth-app create">
+```
+
+{{< hint type=important >}}
+**Note:** the `auth-app` service is not started by default. Add `auth-app` to `START_ADDITIONAL_SERVICES` in `.env` before running the command below, otherwise it will silently succeed with an empty token.
+{{< /hint >}}
+
+Create the app token with:
+
+```bash
+docker-compose exec ocis ocis auth-app create --user-name="admin" --expiration="8760h"
+```
+
+If running locally, add `mcp.owncloud.test` to your hosts file alongside the other domains (see Local Setup above), then bring up the stack again with `docker-compose up -d`. Point your MCP client at `https://mcp.owncloud.test/mcp`, sending the configured secret as `Authorization: Bearer <OCIS_MCP_HTTP_SECRET>`.
+
 ### Traefik Dashboard
 
 If you want to use the Traefik dashboard, set TRAEFIK_DASHBOARD to `true` (default is `false` and therefore not active). If you activate it, you must set a domain for the Traefik dashboard in `TRAEFIK_DOMAIN=` e.g. `TRAEFIK_DOMAIN=traefik.owncloud.test`.