Higress MCP 公共实验环境搭建指南基于 Kind 与 Helm 的一键式可复现环境【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress本文围绕 Higress 仓库中 samples/mcp/environment 目录展开系统讲解其与 MCP 协议版本无关的公共实验环境的设计思路、完整启动/检查/清理流程、可观察后端边界以及全部可覆盖参数。读者按本文操作即可在本地拉起一套包含 Higress Controller、Gateway、CRD、Console 和模拟业务后端的完整实验环境并在此基础上运行samples/mcp/protocol下的任意 MCP Demo。一、公共实验环境在 MCP Demo 体系中的定位Higress 的 MCP Demo 体系遵循公共依赖复用、版本边界明确的设计原则参见 samples/mcp/README.mdenvironment/存放与 MCP 协议版本无关的公共环境Kind 集群定义、Higress Helm 配置、通用模拟业务后端和环境控制脚本protocol/version/存放协议版本专属的内容插件构建方式、能力验证手册和对应 Demo 资源。这意味着无论你要验证哪个 MCP 协议版本的能力例如 2026-07-28 协议版本 下的无状态 HTTP、REST-to-MCP、modern-to-legacy、请求前置校验等 Demo底层实验环境只需拉起一次、全局复用。该环境的技术组成如下组件说明Kind 集群集群名为higress-mcp-demo单节点 control-planeHigress Helm Chart固定版本2.2.3安装完整的 Controller、Gateway、CRD 与 Console公共后端observable-weather一个可观察的普通 HTTP 天气服务本地端口转发Gateway、Console、后端分别映射到本机三个固定端口环境目录结构对应 samples/mcp/environmentsamples/mcp/environment/ ├── apps/observable-weather/ # 通用模拟业务后端Dockerfile deployment.yaml server.py ├── higress/values.yaml # Higress Helm values本地化、轻量化配置 ├── kind/cluster.yaml.tpl # Kind 集群模板挂载插件目录 └── scripts/ # up.sh / status.sh / down.sh / common.sh二、前置条件在启动环境前请确认本机满足以下条件见 environment/README.mdDocker 或 Podman用于构建后端镜像并承载 Kind 节点脚本会自动探测可用的容器引擎Kind创建本地 Kubernetes 集群kubectl操作集群资源Helm安装 Higresscurl健康检查与 Demo 请求jq执行各 Demo 的响应断言至少约 4 GiB 可用内存单节点 Kind 集群 Higress 全套组件需要一定资源网络可达能够访问 Higress Helm 仓库和所需镜像仓库。脚本层面对工具存在性的校验非常严格up.sh启动时会依次调用require_command检查kind、kubectl、helm、curl、sed五个命令缺失任何一个都会以退出码 2 直接报错见 scripts/up.sh 与 scripts/common.sh。三、环境整体架构与关键设计3.1 组件关系从 scripts/up.sh 的执行顺序可以还原出完整架构Kind 集群承载全部工作负载kind/cluster.yaml.tpl定义了集群模板Higress 全家桶以 Helm 方式安装在higress-system命名空间公共后端observable-weather运行在mcp-demo命名空间三者通过三个kubectl port-forward暴露到宿主机固定端口。3.2 插件目录挂载关键设计公共环境会将宿主机的.runtime/plugins目录挂载到 Kind 节点的/opt/plugins。对应的 Kind 集群模板kind/cluster.yaml.tpl如下kind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 nodes: - role: control-plane extraMounts: - hostPath: __PLUGIN_HOST_PATH__ containerPath: /opt/plugins selinuxRelabel: true__PLUGIN_HOST_PATH__是占位符up.sh在创建集群前会用sed将其替换为真实的宿主机路径$MCP_DEMO_RUNTIME/plugins。这意味着先构建、后启动启动环境前必须先在对应协议版本目录下执行plugin/build.sh构建协议插件产物落在.runtime/plugins供 Gateway 通过 WasmPlugin CRD 加载跨启动复用.runtime/plugins不会提交到 Git且清理环境时会被保留下次启动可直接复用已构建的插件产物。3.3 Higress 的本地化轻量配置Helm values 定义在 higress/values.yaml核心配置如下global: local: true # 本地化模式 volumeWasmPlugins: true # 以 volume 方式加载 Wasm 插件对应 /opt/plugins 挂载 onlyPushRouteCluster: false enableStatus: false higress-core: gateway: replicas: 1 service: type: ClusterIP # 不暴露外部 LoadBalancer依靠 port-forward 访问 resources: requests: {cpu: 100m, memory: 256Mi} limits: {cpu: 1, memory: 1Gi} controller: replicas: 1 resources: requests: {cpu: 100m, memory: 256Mi} limits: {cpu: 1, memory: 1Gi} higress-console: service: type: ClusterIP几个要点volumeWasmPlugins: true与 Kind 节点的/opt/plugins挂载配合使 MCP 协议插件能够以本地 volume 方式被 Gateway 加载Gateway 与 Console 的 Service 均为ClusterIP不依赖云环境的外部负载均衡器访问完全通过port-forward完成适合纯本地实验对 CPU 与内存做了显式 request/limit 限制配合--wait --timeout 10m的 Helm 安装参数保证资源有限的本机也能稳定拉起。四、完整启动流程4.1 启动命令从 Higress 仓库根目录执行对应 environment/README.md 的启动小节cd samples/mcp ./protocol/2026-07-28/plugin/build.sh ./environment/scripts/up.sh两步的含义plugin/build.sh按对应协议版本目录记录的 Higress 源码 commit 构建 MCP Server 插件产物写入.runtime/pluginsenvironment/scripts/up.sh拉起公共实验环境。4.2 up.sh 执行步骤详解对照 scripts/up.sh 的源码启动脚本实际完成以下工作步骤 1环境准备校验kind、kubectl、helm、curl、sed是否安装通过select_container_engine探测容器引擎优先 Docker其次 Podman若.runtime/container-engine已有记录则使用记录值Podman 会自动设置KIND_EXPERIMENTAL_PROVIDERpodman创建.runtime/plugins与.runtime目录。步骤 2创建 Kind 集群集群名默认为higress-mcp-demo见 scripts/common.sh 的默认值定义将kind/cluster.yaml.tpl渲染为.runtime/kind-cluster.yaml后执行kind create cluster节点镜像默认kindest/node:v1.32.2创建成功后立即写入集群所有权标记详见下文所有权保护机制写入失败会自动删除集群并退出。步骤 3Helm 安装 Higress添加并更新higress.ioHelm 仓库执行helm upgrade --install higress higress.io/higress固定--version 2.2.3使用--values environment/higress/values.yaml指定--namespace higress-system --create-namespace并带--wait --timeout 10m等待就绪。步骤 4构建并部署公共后端用选定的容器引擎构建localhost/mcp-demo/observable-weather:1.0.0镜像若使用 Podman需先podman save成 docker-archive 再kind load image-archive使用 Docker 则直接kind load docker-imagekubectl apply应用 apps/observable-weather/deployment.yaml包含 Namespace、Deployment、Service依次等待observable-weather、higress-gateway、higress-controller三个 Deployment 完成 rollout。步骤 5建立端口转发并健康检查三个start_port_forward分别建立Gatewayhigress-system/service/higress-gateway的80→ 宿主机18080Consolehigress-system/service/higress-console的8080→ 宿主机18081后端mcp-demo/service/observable-weather的8080→ 宿主机18082通过wait_http依次探测后端/healthz、Console/与 Gateway/全部可达后才打印就绪信息。4.3 环境地址启动完成后本机将暴露以下地址来自 environment/README.md地址用途http://127.0.0.1:18080Higress Gatewayhttp://127.0.0.1:18081Higress Consolehttp://127.0.0.1:18082可观察 HTTP 后端http://127.0.0.1:18082/__state查询后端调用记录POST http://127.0.0.1:18082/__reset清空后端调用记录端口可通过环境变量覆盖详见第六节。五、状态检查与清理5.1 检查状态./environment/scripts/status.sh对应 scripts/status.sh该命令会校验集群存在且归本 Demo 所有否则拒绝执行并报错切换到kind-cluster上下文输出higress-system与mcp-demo两个命名空间下的 Pod 列表分别探测后端/healthz、Gateway/、Console/逐项输出三个端口转发是否ready/unavailable。5.2 清理环境./environment/scripts/down.sh对应 scripts/down.sh该命令会再次执行所有权校验拒绝删除非本 Demo 创建的集群依次停止三个port-forward按 PID 文件与命令签名匹配避免误杀其他进程见 scripts/common.sh删除 Kind 集群并清理.runtime中的所有权记录保留.runtime/plugins下的插件产物便于下次启动复用。六、公共后端 observable-weather 详解6.1 设计边界协议无关公共后端observable-weather只实现普通 HTTP不理解 MCP 版本、JSON-RPC 方法或 Session见 environment/README.md 的公共后端边界小节。特定 MCP 版本的后端 fixture 由对应 Demo 提供例如 03-modern-to-legacy 的 legacy_server.py。这保证了公共环境可以跨越多个协议版本长期复用协议演进只影响protocol/version/目录下的插件与 Demo 资源。6.2 后端接口其实现位于 apps/observable-weather/server.py是一个基于 Python 标准库http.server的轻量服务对外提供四个端点方法路径说明GET/weather?locationcity返回模拟天气数据固定sunny并记录本次调用GET/healthz就绪探针返回{ok: true}GET/__state返回全部调用记录含seq、httpMethod、path、query、requestIdPOST/__reset清空调用记录与序号调用/weather时会记录事件的 HTTP 方法、路径、查询参数和X-Request-ID请求头并按顺序编号。这套可观察设计是各 Demo 做响应断言的关键通过__state可以核对网关转发的真实请求细节例如 MCP 方法是否被正确映射为 HTTP 请求。6.3 部署形态apps/observable-weather/deployment.yaml 定义了命名空间mcp-demo单副本 Deployment容器端口8080配置了基于/healthz的 readinessProbe每 2 秒探测一次ClusterIP Serviceobservable-weather端口8080→targetPort: http。镜像基于 apps/observable-weather/Dockerfile 的python:3.12-alpine构建由up.sh在本地构建并加载进 Kind 集群无需外部拉取。七、可覆盖参数全部环境变量所有环境变量默认值集中定义在 scripts/common.sh均可通过环境变量覆盖环境变量默认值作用MCP_DEMO_CLUSTERhigress-mcp-demoKind 集群名称MCP_DEMO_KIND_NODE_IMAGEkindest/node:v1.32.2Kind 节点镜像MCP_DEMO_HIGRESS_CHART_VERSION2.2.3Higress Helm Chart 版本MCP_DEMO_GATEWAY_PORT18080Gateway 本地端口MCP_DEMO_CONSOLE_PORT18081Console 本地端口MCP_DEMO_BACKEND_PORT18082公共后端本地端口原文给出的端口覆盖示例来自 environment/README.md 的可覆盖参数小节MCP_DEMO_CLUSTERmy-mcp-demo \ MCP_DEMO_GATEWAY_PORT28080 \ MCP_DEMO_CONSOLE_PORT28081 \ MCP_DEMO_BACKEND_PORT28082 \ ./environment/scripts/up.sh实际使用时建议至少保证三个端口不与本机已有服务冲突集群名称的覆盖需要与所有权记录保持一致否则会触发拒绝操作保护。八、所有权保护机制源码级解析环境脚本设计了一套集群所有权机制防止误删或误用其他工具创建的 Kind 集群是up.sh、status.sh、down.sh三者的共同安全底座。8.1 双重记录宿主机侧.runtime下写入三个文件scripts/common.shcontainer-engine记录使用的容器引擎docker/podmancluster-name记录集群名instance-id记录本次创建的实例 ID优先uuidgen失败时回退为时间戳-PID-随机数。集群侧在kube-system命名空间创建名为higress-mcp-demo-owner的 ConfigMap以instance-id字段记录相同实例 IDscripts/common.sh。8.2 校验逻辑cluster_is_owned会比对宿主机记录的 instance-id 与集群内 ConfigMap 的instance-id两者一致才判定归本 Demo 所有。基于此启动时若存在同名集群但非本 Demo 创建up.sh直接拒绝复用并退出scripts/up.sh清理时down.sh对无主集群一律拒绝删除scripts/down.sh。因此如果你本地已有一个恰好同名的 Kind 集群最稳妥的做法是通过MCP_DEMO_CLUSTER指定一个全新的名称。8.3 端口转发的可追溯停止start_port_forward/stop_port_forward会把每次转发的命令行签名写入.runtime/name.command停止时校验 PID 对应的实际命令行包含该签名避免误杀无关进程scripts/common.sh。九、启动后的下一步运行 MCP Demo环境就绪后即可进入对应协议版本的 Demo 目录按 README 逐步验证。以 01-stateless-http 为例典型流程为cd protocol/2026-07-28/01-stateless-http export GATEWAY_URLhttp://127.0.0.1:18080/mcp export MCP_HOSTstateless.mcp.demo # 部署 Demo 资源Ingress WasmPlugin kubectl apply -f resources.yaml # 以独立 HTTP 请求调用 server/discover、tools/list、tools/call curl -sS $GATEWAY_URL -H Host: $MCP_HOST -H MCP-Protocol-Version: 2026-07-28 \ -H Mcp-Method: server/discover -H X-Request-ID: demo-stateless-discover \ --data-binary requests/discover.json | jq该 Demo 无需initialize、不产生协议 Session且可通过kubectl logs -n higress-system deployment/higress-gateway检索demo-stateless关键字查看网关侧证据。十、常见问题速查现象可能原因与处理missing required command: xxx缺少对应命令行工具安装后重试见 scripts/common.shrefusing to reuse unowned Kind cluster同名集群非本 Demo 创建改用MCP_DEMO_CLUSTER指定新名称Docker or Podman with a running engine is required容器引擎未启动或未安装启动 Docker/Podman 后重试端口转发unavailable端口被占用或对应 Deployment 未就绪换端口或先执行down.sh再up.shGateway 加载不到 MCP 插件确认已先执行对应协议版本的plugin/build.sh且插件产物位于.runtime/plugins结语本文以 samples/mcp/environment 为骨架完整还原了 Higress MCP 公共实验环境的架构设计、启动/检查/清理全流程、可观察后端的接口边界以及全部可覆盖参数并结合 scripts 源码剖析了容器引擎选择、插件目录挂载和集群所有权保护等关键实现。掌握了这套环境你就可以在本地以完全可复现的方式依次验证 Higress 对各 MCP 协议版本能力的支持情况。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Higress MCP 公共实验环境搭建指南：基于 Kind 与 Helm 的一键式可复现环境
Higress MCP 公共实验环境搭建指南基于 Kind 与 Helm 的一键式可复现环境【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress本文围绕 Higress 仓库中 samples/mcp/environment 目录展开系统讲解其与 MCP 协议版本无关的公共实验环境的设计思路、完整启动/检查/清理流程、可观察后端边界以及全部可覆盖参数。读者按本文操作即可在本地拉起一套包含 Higress Controller、Gateway、CRD、Console 和模拟业务后端的完整实验环境并在此基础上运行samples/mcp/protocol下的任意 MCP Demo。一、公共实验环境在 MCP Demo 体系中的定位Higress 的 MCP Demo 体系遵循公共依赖复用、版本边界明确的设计原则参见 samples/mcp/README.mdenvironment/存放与 MCP 协议版本无关的公共环境Kind 集群定义、Higress Helm 配置、通用模拟业务后端和环境控制脚本protocol/version/存放协议版本专属的内容插件构建方式、能力验证手册和对应 Demo 资源。这意味着无论你要验证哪个 MCP 协议版本的能力例如 2026-07-28 协议版本 下的无状态 HTTP、REST-to-MCP、modern-to-legacy、请求前置校验等 Demo底层实验环境只需拉起一次、全局复用。该环境的技术组成如下组件说明Kind 集群集群名为higress-mcp-demo单节点 control-planeHigress Helm Chart固定版本2.2.3安装完整的 Controller、Gateway、CRD 与 Console公共后端observable-weather一个可观察的普通 HTTP 天气服务本地端口转发Gateway、Console、后端分别映射到本机三个固定端口环境目录结构对应 samples/mcp/environmentsamples/mcp/environment/ ├── apps/observable-weather/ # 通用模拟业务后端Dockerfile deployment.yaml server.py ├── higress/values.yaml # Higress Helm values本地化、轻量化配置 ├── kind/cluster.yaml.tpl # Kind 集群模板挂载插件目录 └── scripts/ # up.sh / status.sh / down.sh / common.sh二、前置条件在启动环境前请确认本机满足以下条件见 environment/README.mdDocker 或 Podman用于构建后端镜像并承载 Kind 节点脚本会自动探测可用的容器引擎Kind创建本地 Kubernetes 集群kubectl操作集群资源Helm安装 Higresscurl健康检查与 Demo 请求jq执行各 Demo 的响应断言至少约 4 GiB 可用内存单节点 Kind 集群 Higress 全套组件需要一定资源网络可达能够访问 Higress Helm 仓库和所需镜像仓库。脚本层面对工具存在性的校验非常严格up.sh启动时会依次调用require_command检查kind、kubectl、helm、curl、sed五个命令缺失任何一个都会以退出码 2 直接报错见 scripts/up.sh 与 scripts/common.sh。三、环境整体架构与关键设计3.1 组件关系从 scripts/up.sh 的执行顺序可以还原出完整架构Kind 集群承载全部工作负载kind/cluster.yaml.tpl定义了集群模板Higress 全家桶以 Helm 方式安装在higress-system命名空间公共后端observable-weather运行在mcp-demo命名空间三者通过三个kubectl port-forward暴露到宿主机固定端口。3.2 插件目录挂载关键设计公共环境会将宿主机的.runtime/plugins目录挂载到 Kind 节点的/opt/plugins。对应的 Kind 集群模板kind/cluster.yaml.tpl如下kind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 nodes: - role: control-plane extraMounts: - hostPath: __PLUGIN_HOST_PATH__ containerPath: /opt/plugins selinuxRelabel: true__PLUGIN_HOST_PATH__是占位符up.sh在创建集群前会用sed将其替换为真实的宿主机路径$MCP_DEMO_RUNTIME/plugins。这意味着先构建、后启动启动环境前必须先在对应协议版本目录下执行plugin/build.sh构建协议插件产物落在.runtime/plugins供 Gateway 通过 WasmPlugin CRD 加载跨启动复用.runtime/plugins不会提交到 Git且清理环境时会被保留下次启动可直接复用已构建的插件产物。3.3 Higress 的本地化轻量配置Helm values 定义在 higress/values.yaml核心配置如下global: local: true # 本地化模式 volumeWasmPlugins: true # 以 volume 方式加载 Wasm 插件对应 /opt/plugins 挂载 onlyPushRouteCluster: false enableStatus: false higress-core: gateway: replicas: 1 service: type: ClusterIP # 不暴露外部 LoadBalancer依靠 port-forward 访问 resources: requests: {cpu: 100m, memory: 256Mi} limits: {cpu: 1, memory: 1Gi} controller: replicas: 1 resources: requests: {cpu: 100m, memory: 256Mi} limits: {cpu: 1, memory: 1Gi} higress-console: service: type: ClusterIP几个要点volumeWasmPlugins: true与 Kind 节点的/opt/plugins挂载配合使 MCP 协议插件能够以本地 volume 方式被 Gateway 加载Gateway 与 Console 的 Service 均为ClusterIP不依赖云环境的外部负载均衡器访问完全通过port-forward完成适合纯本地实验对 CPU 与内存做了显式 request/limit 限制配合--wait --timeout 10m的 Helm 安装参数保证资源有限的本机也能稳定拉起。四、完整启动流程4.1 启动命令从 Higress 仓库根目录执行对应 environment/README.md 的启动小节cd samples/mcp ./protocol/2026-07-28/plugin/build.sh ./environment/scripts/up.sh两步的含义plugin/build.sh按对应协议版本目录记录的 Higress 源码 commit 构建 MCP Server 插件产物写入.runtime/pluginsenvironment/scripts/up.sh拉起公共实验环境。4.2 up.sh 执行步骤详解对照 scripts/up.sh 的源码启动脚本实际完成以下工作步骤 1环境准备校验kind、kubectl、helm、curl、sed是否安装通过select_container_engine探测容器引擎优先 Docker其次 Podman若.runtime/container-engine已有记录则使用记录值Podman 会自动设置KIND_EXPERIMENTAL_PROVIDERpodman创建.runtime/plugins与.runtime目录。步骤 2创建 Kind 集群集群名默认为higress-mcp-demo见 scripts/common.sh 的默认值定义将kind/cluster.yaml.tpl渲染为.runtime/kind-cluster.yaml后执行kind create cluster节点镜像默认kindest/node:v1.32.2创建成功后立即写入集群所有权标记详见下文所有权保护机制写入失败会自动删除集群并退出。步骤 3Helm 安装 Higress添加并更新higress.ioHelm 仓库执行helm upgrade --install higress higress.io/higress固定--version 2.2.3使用--values environment/higress/values.yaml指定--namespace higress-system --create-namespace并带--wait --timeout 10m等待就绪。步骤 4构建并部署公共后端用选定的容器引擎构建localhost/mcp-demo/observable-weather:1.0.0镜像若使用 Podman需先podman save成 docker-archive 再kind load image-archive使用 Docker 则直接kind load docker-imagekubectl apply应用 apps/observable-weather/deployment.yaml包含 Namespace、Deployment、Service依次等待observable-weather、higress-gateway、higress-controller三个 Deployment 完成 rollout。步骤 5建立端口转发并健康检查三个start_port_forward分别建立Gatewayhigress-system/service/higress-gateway的80→ 宿主机18080Consolehigress-system/service/higress-console的8080→ 宿主机18081后端mcp-demo/service/observable-weather的8080→ 宿主机18082通过wait_http依次探测后端/healthz、Console/与 Gateway/全部可达后才打印就绪信息。4.3 环境地址启动完成后本机将暴露以下地址来自 environment/README.md地址用途http://127.0.0.1:18080Higress Gatewayhttp://127.0.0.1:18081Higress Consolehttp://127.0.0.1:18082可观察 HTTP 后端http://127.0.0.1:18082/__state查询后端调用记录POST http://127.0.0.1:18082/__reset清空后端调用记录端口可通过环境变量覆盖详见第六节。五、状态检查与清理5.1 检查状态./environment/scripts/status.sh对应 scripts/status.sh该命令会校验集群存在且归本 Demo 所有否则拒绝执行并报错切换到kind-cluster上下文输出higress-system与mcp-demo两个命名空间下的 Pod 列表分别探测后端/healthz、Gateway/、Console/逐项输出三个端口转发是否ready/unavailable。5.2 清理环境./environment/scripts/down.sh对应 scripts/down.sh该命令会再次执行所有权校验拒绝删除非本 Demo 创建的集群依次停止三个port-forward按 PID 文件与命令签名匹配避免误杀其他进程见 scripts/common.sh删除 Kind 集群并清理.runtime中的所有权记录保留.runtime/plugins下的插件产物便于下次启动复用。六、公共后端 observable-weather 详解6.1 设计边界协议无关公共后端observable-weather只实现普通 HTTP不理解 MCP 版本、JSON-RPC 方法或 Session见 environment/README.md 的公共后端边界小节。特定 MCP 版本的后端 fixture 由对应 Demo 提供例如 03-modern-to-legacy 的 legacy_server.py。这保证了公共环境可以跨越多个协议版本长期复用协议演进只影响protocol/version/目录下的插件与 Demo 资源。6.2 后端接口其实现位于 apps/observable-weather/server.py是一个基于 Python 标准库http.server的轻量服务对外提供四个端点方法路径说明GET/weather?locationcity返回模拟天气数据固定sunny并记录本次调用GET/healthz就绪探针返回{ok: true}GET/__state返回全部调用记录含seq、httpMethod、path、query、requestIdPOST/__reset清空调用记录与序号调用/weather时会记录事件的 HTTP 方法、路径、查询参数和X-Request-ID请求头并按顺序编号。这套可观察设计是各 Demo 做响应断言的关键通过__state可以核对网关转发的真实请求细节例如 MCP 方法是否被正确映射为 HTTP 请求。6.3 部署形态apps/observable-weather/deployment.yaml 定义了命名空间mcp-demo单副本 Deployment容器端口8080配置了基于/healthz的 readinessProbe每 2 秒探测一次ClusterIP Serviceobservable-weather端口8080→targetPort: http。镜像基于 apps/observable-weather/Dockerfile 的python:3.12-alpine构建由up.sh在本地构建并加载进 Kind 集群无需外部拉取。七、可覆盖参数全部环境变量所有环境变量默认值集中定义在 scripts/common.sh均可通过环境变量覆盖环境变量默认值作用MCP_DEMO_CLUSTERhigress-mcp-demoKind 集群名称MCP_DEMO_KIND_NODE_IMAGEkindest/node:v1.32.2Kind 节点镜像MCP_DEMO_HIGRESS_CHART_VERSION2.2.3Higress Helm Chart 版本MCP_DEMO_GATEWAY_PORT18080Gateway 本地端口MCP_DEMO_CONSOLE_PORT18081Console 本地端口MCP_DEMO_BACKEND_PORT18082公共后端本地端口原文给出的端口覆盖示例来自 environment/README.md 的可覆盖参数小节MCP_DEMO_CLUSTERmy-mcp-demo \ MCP_DEMO_GATEWAY_PORT28080 \ MCP_DEMO_CONSOLE_PORT28081 \ MCP_DEMO_BACKEND_PORT28082 \ ./environment/scripts/up.sh实际使用时建议至少保证三个端口不与本机已有服务冲突集群名称的覆盖需要与所有权记录保持一致否则会触发拒绝操作保护。八、所有权保护机制源码级解析环境脚本设计了一套集群所有权机制防止误删或误用其他工具创建的 Kind 集群是up.sh、status.sh、down.sh三者的共同安全底座。8.1 双重记录宿主机侧.runtime下写入三个文件scripts/common.shcontainer-engine记录使用的容器引擎docker/podmancluster-name记录集群名instance-id记录本次创建的实例 ID优先uuidgen失败时回退为时间戳-PID-随机数。集群侧在kube-system命名空间创建名为higress-mcp-demo-owner的 ConfigMap以instance-id字段记录相同实例 IDscripts/common.sh。8.2 校验逻辑cluster_is_owned会比对宿主机记录的 instance-id 与集群内 ConfigMap 的instance-id两者一致才判定归本 Demo 所有。基于此启动时若存在同名集群但非本 Demo 创建up.sh直接拒绝复用并退出scripts/up.sh清理时down.sh对无主集群一律拒绝删除scripts/down.sh。因此如果你本地已有一个恰好同名的 Kind 集群最稳妥的做法是通过MCP_DEMO_CLUSTER指定一个全新的名称。8.3 端口转发的可追溯停止start_port_forward/stop_port_forward会把每次转发的命令行签名写入.runtime/name.command停止时校验 PID 对应的实际命令行包含该签名避免误杀无关进程scripts/common.sh。九、启动后的下一步运行 MCP Demo环境就绪后即可进入对应协议版本的 Demo 目录按 README 逐步验证。以 01-stateless-http 为例典型流程为cd protocol/2026-07-28/01-stateless-http export GATEWAY_URLhttp://127.0.0.1:18080/mcp export MCP_HOSTstateless.mcp.demo # 部署 Demo 资源Ingress WasmPlugin kubectl apply -f resources.yaml # 以独立 HTTP 请求调用 server/discover、tools/list、tools/call curl -sS $GATEWAY_URL -H Host: $MCP_HOST -H MCP-Protocol-Version: 2026-07-28 \ -H Mcp-Method: server/discover -H X-Request-ID: demo-stateless-discover \ --data-binary requests/discover.json | jq该 Demo 无需initialize、不产生协议 Session且可通过kubectl logs -n higress-system deployment/higress-gateway检索demo-stateless关键字查看网关侧证据。十、常见问题速查现象可能原因与处理missing required command: xxx缺少对应命令行工具安装后重试见 scripts/common.shrefusing to reuse unowned Kind cluster同名集群非本 Demo 创建改用MCP_DEMO_CLUSTER指定新名称Docker or Podman with a running engine is required容器引擎未启动或未安装启动 Docker/Podman 后重试端口转发unavailable端口被占用或对应 Deployment 未就绪换端口或先执行down.sh再up.shGateway 加载不到 MCP 插件确认已先执行对应协议版本的plugin/build.sh且插件产物位于.runtime/plugins结语本文以 samples/mcp/environment 为骨架完整还原了 Higress MCP 公共实验环境的架构设计、启动/检查/清理全流程、可观察后端的接口边界以及全部可覆盖参数并结合 scripts 源码剖析了容器引擎选择、插件目录挂载和集群所有权保护等关键实现。掌握了这套环境你就可以在本地以完全可复现的方式依次验证 Higress 对各 MCP 协议版本能力的支持情况。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考