diff --git "a/cn/Zadig v4.3/21.\345\274\200\345\217\221\350\200\205\344\270\255\345\277\203/04.\345\267\245\345\205\267\345\222\214\346\217\222\344\273\266/29.mcp.md" "b/cn/Zadig v4.3/21.\345\274\200\345\217\221\350\200\205\344\270\255\345\277\203/04.\345\267\245\345\205\267\345\222\214\346\217\222\344\273\266/29.mcp.md" index 4e2ff5234..81ef0414c 100644 --- "a/cn/Zadig v4.3/21.\345\274\200\345\217\221\350\200\205\344\270\255\345\277\203/04.\345\267\245\345\205\267\345\222\214\346\217\222\344\273\266/29.mcp.md" +++ "b/cn/Zadig v4.3/21.\345\274\200\345\217\221\350\200\205\344\270\255\345\277\203/04.\345\267\245\345\205\267\345\222\214\346\217\222\344\273\266/29.mcp.md" @@ -11,7 +11,7 @@ permalink: /cn/Zadig v4.3/mcp-settings/ ::: tip - MCP Server 需要 Zadig 版本为 v4.2.0 或以上方可正常使用。 - API Token 可在 Zadig 平台的“账号设置”中获取。 -- Zadig MCP 支持 `stdio` 和 `sse` 两种启动方式，可根据接入场景选择。 +- Zadig MCP 支持 `stdio`、`sse` 和 `http` 三种启动方式，可根据接入场景选择。 ::: ### stdio 启动方式 @@ -107,7 +107,7 @@ spec: spec: containers: - name: zadig-mcp - image: koderover.tencentcloudcr.com/koderover-public/zadig-mcp:0.1.4 + image: koderover.tencentcloudcr.com/koderover-public/zadig-mcp:0.1.6 imagePullPolicy: IfNotPresent args: - "-t" @@ -269,6 +269,197 @@ https://your_domain/sse?token=your_token ![飞书 Aily 接入成功示例 1](../../../_images/aily_setting_success1.png) ![飞书 Aily 接入成功示例 2](../../../_images/aily_setting_success2.png) +### Streamable HTTP 启动方式 + +::: tip +- 请将示例中的 `https://your-zadig.com`、`https://mcp.your-company.com` 以及 `your-token` 替换为实际地址和 Token。 +- 该模式适用于通过 Streamable HTTP 协议接入 Zadig MCP 服务的场景，需先单独启动或部署 MCP Server。 +- Streamable HTTP 使用单一 HTTP Endpoint 暴露 MCP 服务，示例中默认路径为 `/http`。 +::: + +#### 适用场景 + +- 客户端支持 Streamable HTTP 协议，需要通过公网或内网 URL 访问 MCP Server。 +- 希望通过标准 HTTP Endpoint 接入 MCP 服务，而不是使用 SSE 的 `/sse` 和 `/message` 两个 Endpoint。 +- 需要将 MCP Server 统一部署在测试、办公或共享环境中，供多人复用。 + +#### 一次实践：在 Zadig 中部署 Streamable HTTP 服务 + +- 该方式适用于将 Zadig MCP Server 作为服务部署在 Zadig 环境中，并通过 Ingress 以 Streamable HTTP 方式对外提供访问能力。 +- 部署前请确认 `3000` 端口未被占用。 +- 请根据实际情况修改 `ZADIG_API_HOST`、`ingressClassName`、`name`、`namespace` 以及 Ingress 域名。 +- 默认 HTTP Endpoint 为 `/http`，如需调整，请同步修改 `MCP_HTTP_ENDPOINT` 和 Ingress 路径。 + +##### 操作步骤 + +1. 在 Zadig 中创建一个 K8s 项目，例如：`mcp`。 +2. 将下面的 K8s YAML 加入到服务配置并起名为 `zadig-mcp-http`，并按实际环境修改其中的关键参数。 +3. 保存服务配置。 +4. 将该服务加入环境中。 +5. 查看 Pod 状态，确认服务是否成功启动。 + +##### 服务配置 YAML 示例 + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: zadig-mcp-http-config + labels: + app: zadig-mcp-http +data: + ZADIG_API_HOST: "https://your-zadig.com" + MCP_TRANSPORT_TYPE: "http" + MCP_LISTEN_ADDR: "0.0.0.0:3000" + MCP_HTTP_ENDPOINT: "/http" +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: zadig-mcp-http + labels: + app: zadig-mcp-http +spec: + replicas: 1 + selector: + matchLabels: + app: zadig-mcp-http + template: + metadata: + labels: + app: zadig-mcp-http + spec: + containers: + - name: zadig-mcp + image: koderover.tencentcloudcr.com/koderover-public/zadig-mcp:0.1.6 + imagePullPolicy: IfNotPresent + args: + - "-t" + - "$(MCP_TRANSPORT_TYPE)" + - "-a" + - "$(MCP_LISTEN_ADDR)" + ports: + - name: http + containerPort: 3000 + protocol: TCP + env: + - name: ZADIG_API_HOST + valueFrom: + configMapKeyRef: + name: zadig-mcp-http-config + key: ZADIG_API_HOST + - name: MCP_TRANSPORT_TYPE + valueFrom: + configMapKeyRef: + name: zadig-mcp-http-config + key: MCP_TRANSPORT_TYPE + - name: MCP_LISTEN_ADDR + valueFrom: + configMapKeyRef: + name: zadig-mcp-http-config + key: MCP_LISTEN_ADDR + - name: MCP_HTTP_ENDPOINT + valueFrom: + configMapKeyRef: + name: zadig-mcp-http-config + key: MCP_HTTP_ENDPOINT + resources: + requests: + cpu: 200m + memory: 512Mi + limits: + cpu: 400m + memory: 1024Mi + readinessProbe: + tcpSocket: + port: 3000 + initialDelaySeconds: 5 + periodSeconds: 10 + livenessProbe: + tcpSocket: + port: 3000 + initialDelaySeconds: 10 + periodSeconds: 20 +--- +apiVersion: v1 +kind: Service +metadata: + name: zadig-mcp-http + labels: + app: zadig-mcp-http +spec: + selector: + app: zadig-mcp-http + ports: + - name: http + port: 3000 + targetPort: 3000 + protocol: TCP + type: ClusterIP +--- +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: zadig-mcp-http + namespace: your_namespace + annotations: + nginx.ingress.kubernetes.io/backend-protocol: "HTTP" + nginx.ingress.kubernetes.io/service-upstream: "true" + nginx.ingress.kubernetes.io/proxy-buffering: "off" + nginx.ingress.kubernetes.io/proxy-request-buffering: "off" + nginx.ingress.kubernetes.io/proxy-read-timeout: "3600" + nginx.ingress.kubernetes.io/proxy-send-timeout: "3600" + nginx.ingress.kubernetes.io/proxy-http-version: "1.1" + nginx.ingress.kubernetes.io/ssl-redirect: "false" + nginx.ingress.kubernetes.io/force-ssl-redirect: "false" +spec: + ingressClassName: your_ingress_class_name + rules: + - host: your_domain.com + http: + paths: + - path: /http + pathType: Prefix + backend: + service: + name: zadig-mcp-http + port: + number: 3000 +``` + +#### 客户端配置（MCP Client 侧） + +基于 `Header` 鉴权方式，在支持 Streamable HTTP 的 MCP Client 中配置 HTTP Endpoint： + +```json +{ + "mcpServers": { + "zadig-mcp-http": { + "url": "https://your_domain.com/http", + "headers": { + "Authorization": "Bearer your-token" + } + } + } +} +``` +##### 飞书 Aily 配置 + +基于 `token` URL 传参的鉴权方式，在飞书 Aily 中添加如下 URL： + +```text +https://your_domain/http?token=your_token +``` + +下面以飞书 Aily 为例，说明如何通过远程 URL 接入 Zadig MCP Server： + +1. 在飞书 Aily 中新增 MCP 服务。 +2. 填写上面的 SSE 地址。 +3. 保存配置后，验证连接是否成功。 + +![飞书 Aily 配置示例](../../../_images/aily_setting1.png) +![飞书 Aily 接入成功示例 1](../../../_images/aily_setting_success1.png) +![飞书 Aily 接入成功示例 2](../../../_images/aily_setting_success2.png) ## 升级或卸载 ```bash