将您自己的 MCP 服务器引入 kagent 参考实现

简介

借助自带 (BYO) Model Context Protocol (MCP) 服务器，AI 智能体可以使用现有基础设施中的标准化连接，实时查询和处理来自外部代码库的数据。

此解决方案参考实现 (SRI) 文档介绍了如何在 Solo Enterprise for kagent 上部署 Nextcloud 开源应用及其 MCP 服务器，以及 Nextcloud 智能体。此架构将 Nextcloud、kagent 和 Gemma 4 模型连接到部署在 Google Distributed Cloud 纯软件版 (GDC) 中的 Google Kubernetes Engine (GKE) 集群中。在此配置中，kagent 使用 Nextcloud 作为数据存储库，让 Gemma 4 模型通过标准化的 MCP 接口访问和处理 Nextcloud 中的文件。如需了解架构背景信息，请参阅配套的参考架构。

Nextcloud 概览

Nextcloud 是一个开源、自托管的协作和云端存储空间平台，支持本地部署。在本地部署 Nextcloud 有助于维护数据的自主权、安全性和隐私性。

Nextcloud 提供以下功能：

  • 文件同步和共享：存储文件，通过专用应用在桌面设备和移动设备之间同步文件，并使用链接与他人共享文件。
  • 效率提升工具：通过内置的日历、通讯录、任务管理和邮件客户端管理日程和沟通。
  • 协作：将办公套件（例如 Collabora Online 或 ONLYOFFICE）直接集成到 Nextcloud 中，以实时共同编辑文档、电子表格和演示文稿。
  • 可扩展性：从应用商店安装插件，以添加密码管理工具、看板或音乐播放器等功能。

解决方案架构

此解决方案需要一个 GDC 环境，其中部署了 Solo Enterprise for kagent 和采用 Gemma 4 模型的 vLLM，以及一个安装了 kubectl 和 helm 的工作站。

下图展示了连接 GDC、kagent、Nextcloud 和 vLLM 与 Gemma 4 的解决方案架构：

解决方案架构：GDC、kagent、Nextcloud 和 vLLM（搭配 Gemma 4）。

部署方法

如需部署 Nextcloud 并将其 MCP 服务器与 kagent 集成，请完成以下简要步骤：

  1. 为 Nextcloud 创建专用命名空间：使用 kubectl 创建 nextcloud 命名空间，以隔离部署。
  2. 添加并更新 Helm 代码库：使用官方 Nextcloud Helm 代码库配置工作站，并更新本地图表元数据。
  3. 配置自定义部署值：创建自定义 values.yaml 文件，以便为目标环境配置 Nextcloud。此配置会停用默认的本地 SQLite 数据库，配置 MariaDB 永久性存储，定义管理员凭据，并使用 ClusterIP 服务设置内部路由。
  4. 运行 Helm 安装：使用自定义配置文件将图表部署到目标命名空间。验证所有组件（包括 Nextcloud 应用和 MariaDB 存储 Pod）是否都达到 Running 状态。
  5. 部署 Nextcloud MCP 服务器：创建一个部署清单 (nextcloud-mcp.yaml)，其中包含用于凭据的不透明 Secret、使用 nextcloud-mcp-server:latest 映像的 Deployment，以及公开端口 8000 的 ClusterIP Service。应用此清单以允许与 Nextcloud 应用进行内部 Kubernetes DNS 通信。
  6. 在 kagent 上注册工具服务器：在 kagent 界面中使用内部服务网址 http://nextcloud-mcp-service.nextcloud.svc.cluster.local:8000/mcp 和 STREAMABLE_HTTP 协议连接服务器。

部署 Nextcloud 和 MCP 服务器

  1. 为 Nextcloud 创建命名空间：

    kubectl create namespace nextcloud

    输出类似于以下内容：

    namespace/nextcloud created

  2. 将 Nextcloud Helm 仓库添加到您的工作站，并更新本地图表元数据：

    helm repo add nextcloud https://nextcloud.github.io/helm/
helm repo update

    输出类似于以下内容：

    "nextcloud" has been added to your repositories
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "nextcloud" chart repository
Update Complete. ⎈Happy Helming!⎈

  3. 在工作站上创建自定义 values.yaml 文件，以替换 Nextcloud Helm 图表的默认配置参数：

    # 0. Nextcloud administrator configuration
nextcloud:
  # Use the internal CoreDNS record
  host: "nextcloud.nextcloud.svc.cluster.local"  # Application access through CoreDNS rather than external DNS
  username: "admin"  # Application Login Credentials
  password: "SuperSecretPassword123"

# You can use a standard ClusterIP service since
# you are relying on internal routing, not an External LB.
service:
  type: ClusterIP

# 1. Configure RWO Storage for Nextcloud
persistence:
  enabled: true
  storageClass: "local-shared"
  accessMode: ReadWriteOnce
  size: 50Gi # Adjust based on your file storage needs

# 2. Explicitly disable the default local SQLite database
internalDatabase:
  enabled: false

# 3. Configure RWO Storage for the Database
mariadb:
  enabled: true
  auth:
    database: "nextcloud"
    username: "nextcloud"
    password: "NextcloudDBPassword123"
    rootPassword: "RootDBPassword123"
  primary:
    persistence:
      enabled: true
      storageClass: "local-shared"
      accessModes:
        - ReadWriteOnce
      size: 10Gi

# 4. Force Nextcloud to connect through the TCP Network
externalDatabase:
  enabled: true
  type: mysql
  host: "nextcloud-mariadb" # The internal Kubernetes service name for the DB
  database: "nextcloud"
  user: "nextcloud"
  password: "NextcloudDBPassword123" # MUST match mariadb.auth.password above

# Optional: Enable Ingress to route external traffic to Nextcloud
ingress:
  enabled: false # Set to true if you are using an Ingress Controller (like NGINX)
  className: "nginx"
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: 4G # Required to allow large file uploads

  4. 使用 Helm 部署 Nextcloud：

    helm install nextcloud nextcloud/nextcloud \
    --namespace nextcloud \
    --values values.yaml

    输出类似于以下内容：

    NAME: nextcloud
LAST DEPLOYED: Thu Jul  9 17:14:03 2026
NAMESPACE: nextcloud
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
1. Get the nextcloud URL by running:

  export POD_NAME=$(kubectl get pods --namespace nextcloud -l "app.kubernetes.io/name=nextcloud" -o jsonpath="{.items[0].metadata.name}")
  echo http://127.0.0.1:8080/
  kubectl port-forward --namespace nextcloud $POD_NAME 8080:80

2. Get your nextcloud login credentials by running:

  echo User:     admin
  echo Password: $(kubectl get secret --namespace nextcloud nextcloud -o jsonpath="{.data.nextcloud-password}" | base64 --decode)

    验证 Nextcloud Pod 是否处于 Running 状态，以及 nextcloud 命名空间中是否存在 Service：

    kubectl get pod -n nextcloud
kubectl get svc -n nextcloud

    输出类似于以下内容：

    NAME                                    READY   STATUS    RESTARTS   AGE
nextcloud-558cbccb4c-q6zqq              1/1     Running   0          25m
nextcloud-mariadb-0                     1/1     Running   0          25m

NAME                         TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
nextcloud                    ClusterIP   10.255.224.187   <none>        8080/TCP   25m
nextcloud-mariadb            ClusterIP   10.255.226.235   <none>        3306/TCP   25m
nextcloud-mariadb-headless   ClusterIP   None             <none>        3306/TCP   25m

  5. 如需在 nextcloud 命名空间中部署 Nextcloud MCP 服务器，请在工作站上创建一个名为 nextcloud-mcp.yaml 的文件：

    # Secret Creation
apiVersion: v1
kind: Secret
metadata:
  name: nextcloud-mcp-secret
  namespace: nextcloud
type: Opaque
stringData:
  # Use your dedicated App Password here, NEVER your primary administrator password
  NEXTCLOUD_USERNAME: "admin"
  NEXTCLOUD_PASSWORD: "SuperSecretPassword123"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nextcloud-mcp-server
  namespace: nextcloud
  labels:
    app: nextcloud-mcp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nextcloud-mcp
  template:
    metadata:
      labels:
        app: nextcloud-mcp
    spec:
      containers:
        - name: mcp-server
          # The official Docker image provided by the project
          image: ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
          imagePullPolicy: Always
          ports:
            - containerPort: 8000
              name: http-mcp
          env:
            - name: NEXTCLOUD_HOST
              # Since the MCP server is in the same namespace, it can securely
              # talk to Nextcloud through the internal Kubernetes DNS, completely bypassing the internet.
              value: "http://nextcloud.nextcloud.svc.cluster.local:8080"
            - name: NEXTCLOUD_USERNAME
              valueFrom:
                secretKeyRef:
                  name: nextcloud-mcp-secret
                  key: NEXTCLOUD_USERNAME
            - name: NEXTCLOUD_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: nextcloud-mcp-secret
                  key: NEXTCLOUD_PASSWORD
          resources:
            requests:
              cpu: "100m"
              memory: "128Mi"
            limits:
              cpu: "500m"
              memory: "512Mi"
---
apiVersion: v1
kind: Service
metadata:
  name: nextcloud-mcp-service
  namespace: nextcloud
spec:
  type: ClusterIP
  ports:
    - port: 8000
      targetPort: 8000
      protocol: TCP
      name: http-mcp
  selector:
    app: nextcloud-mcp

    应用 nextcloud-mcp.yaml 清单：

    kubectl apply -f nextcloud-mcp.yaml

    输出类似于以下内容：

    secret/nextcloud-mcp-secret created
deployment.apps/nextcloud-mcp-server created
service/nextcloud-mcp-service created

    验证 Pod 和 Service 是否在 nextcloud 命名空间中运行：

    kubectl get svc -n nextcloud
kubectl get pod -n nextcloud

    输出类似于以下内容：

    NAME                         TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
nextcloud                    ClusterIP   10.255.224.187   <none>        8080/TCP   26m
nextcloud-mariadb            ClusterIP   10.255.226.235   <none>        3306/TCP   26m
nextcloud-mariadb-headless   ClusterIP   None             <none>        3306/TCP   26m
nextcloud-mcp-service        ClusterIP   10.255.226.105   <none>        8000/TCP   55s

NAME                                    READY   STATUS    RESTARTS   AGE
nextcloud-558cbccb4c-q6zqq              1/1     Running   0          29m
nextcloud-mariadb-0                     1/1     Running   0          29m
nextcloud-mcp-server-58484d5799-mfvct   1/1     Running   0          4m11s

  6. 如需通过网址集成 Nextcloud MCP 工具，请前往 kagent 界面，并使用以下值注册工具服务器：

    • 网址： http://nextcloud-mcp-service.nextcloud.svc.cluster.local:8000/mcp
    • 协议：STREAMABLE_HTTP
    • Namespace：kagent
    • 集群：您的集群名称（例如 mgmt-cluster）

    验证 RemoteMCPServer 资源在 kagent 命名空间中是否被接受：

    kubectl get remotemcpserver -n kagent

    输出类似于以下内容：

    NAME                 PROTOCOL          URL                                                                 ACCEPTED
kagent-grafana-mcp   STREAMABLE_HTTP   http://kagent-grafana-mcp.kagent:8000/mcp                           True
kagent-tool-server   STREAMABLE_HTTP   http://kagent-tools.kagent:8084/mcp                                 True
nextcloud            STREAMABLE_HTTP   http://nextcloud-mcp-service.nextcloud.svc.cluster.local:8000/mcp   True

  7. 如需从工作站访问 Nextcloud，请将本地端口 8080 转发到 nextcloud 服务（如果您配置了外部网址，请跳过此步骤）：

    kubectl port-forward -n nextcloud svc/nextcloud 8080:8080 &

    输出类似于以下内容：

    Forwarding from 127.0.0.1:8080 -> 80
Forwarding from [::1]:8080 -> 80

验证部署并配置 Nextcloud 代理

在工作站浏览器中，打开 http://localhost:8080 以查看 Nextcloud 信息中心：

Nextcloud 应用信息中心页面。

Files 视图会显示 Nextcloud 中存储的目录和文件：

Nextcloud 应用中的目录和文件界面。

在 kagent 界面中，信息中心页面会显示已连接的集群和已部署的代理：

kagent 应用信息中心。

工具服务器页面列出了通过 MCP 为 Nextcloud 应用发现的工具：

kagent 工具服务器页面，其中显示了为 Nextcloud 应用发现的工具。

工具页面会显示可供代理使用的 Nextcloud 工具集合：

Nextcloud 中提供的 kagent 工具集合。

如需在 kagent 界面中创建 nextcloud 代理，请在基本信息下输入代理名称、集群、命名空间和说明：

为 Nextcloud 创建 kagent 代理。

在行为和模型设置下，选择 Gemma 4 模型，然后输入代理的系统指令：

用于技能和模型对齐的 kagent 智能体配置。

在工具和智能体下，为智能体选择 Nextcloud MCP 工具，然后点击创建智能体：

用于选择 Nextcloud 工具的 kagent 代理配置。

代理页面会显示 nextcloud 代理，其状态为 Ready：

已将智能体添加到 kagent 应用。

您可以提示 Nextcloud 代理列出 Nextcloud 应用中的目录和文件：

Nextcloud 智能体列出目录和文件。

您还可以提示 Nextcloud 代理将文件内容从英语翻译和音译为法语：

Nextcloud 智能体将文件内容从英语翻译成法语。