K8s MCP Operator

MCP操作员项目指南

欢迎！本仓库将引导您构建一个Kubernetes Operator，该Operator将Model Context Protocol（MCP）组件视为一等工作负载。其目标是让部署、监控和保护集群中的MCP服务器、工具和代理变得简单易行，即使您对Kubernetes Operator是新手也没关系。

______________________________________________________________________

目录

1. 为什么要在 Kubernetes 上使用 MCP？
2. 项目概述
3. 在这个仓库中你能获得什么
4. 关键概念解析
5. 先决条件
6. 快速入门：运行MVP Operator
7. 探索自定义资源
8. 控制器的工作原理
9. 自定义您的部署
10. 测试与故障排除
11. 路线图及后续步骤
12. 有用资源与术语表

______________________________________________________________________

为什么要在 Kubernetes 上使用 MCP？

模型上下文协议（MCP） 这是一个新兴的标准，它允许大型语言模型（LLM）代理以结构化的方式与外部工具、数据存储和服务进行交互。目前，团队会临时部署MCP服务器，这导致：

• 手工编写的YAML部署，模式不一致。
• 脆弱的秘密处理与身份管理。
• 稀疏可观测性和状态报告。

A. Kubernetes Operator（中文可译为“Kubernetes 操作器”或根据具体语境简化为“K8s 操作器”） 将所有这些逻辑编码化。操作员监控自定义资源，并持续地将其协调为实际的集群对象（如Deployment、Service、ConfigMap、Secret等）。这使得平台、安全和应用团队能够以声明式的方式管理MCP基础设施，就像我们管理原生Kubernetes工作负载一样。

______________________________________________________________________

项目概述

这个项目提供：

• 自定义资源定义（CRDs） 对于三个MCP构建模块：服务器、工具和代理。
• 一个最小化的Python/Kopf控制器 使（两者）和解/调和 MCPServer 将资源部署到服务中，然后报告状态。
• 示例清单和脚本 这样你就可以立即进行实验并理解操作流程。
• 一份详细的蓝图 捕获安全态势、生产路线图以及迁移到Go/Kubebuilder实现的路径。

当前的MVP（最有价值球员）专注于 MCPServer 和解。用于……的工具 MCPTool 和 MCPAgent 进行了描述并为未来的迭代提供了框架支持。

MCP Operator Architecture Diagram

______________________________________________________________________

在这个仓库中你将获得什么

• docs – 设计蓝图，阐述目标、架构、自定义资源定义（CRDs）、安全态势及路线图。
• controller/ – Python 控制器代码（controller/mcp_operator.py:1) 使用Kopf和Kubernetes Python客户端。
• config/crds/ – MCP资源的CRD YAML文件，外加一个 kustomization.yaml 如果你更喜欢 kubectl apply -k。
• config/rbac/ – 运行集群内的操作符（operator）所需的命名空间（Namespace）、服务账户（ServiceAccount）、集群角色（ClusterRole）和集群角色绑定（ClusterRoleBinding）。
• config/samples/ – 在安装自定义资源定义（CRDs）后，尝试使用最少的MCPServer、MCPTool和MCPAgent自定义资源。
• examples/dev-stack.yaml – 一个单一清单文件，用于设置密钥、配置映射以及示例MCP资源，以构建一个开箱即用的演示环境。
• requirements.txt / Makefile – 依赖项锁定以及用于安装、运行和检查控制器的辅助目标。

______________________________________________________________________

关键概念解析

______________________________________________________________________

先决条件

在开始之前：

• 一个Kubernetes集群（使用kind、minikube、k3d或托管集群均可）。
• kubectl 配置为指向该集群。
• Python 3.9+（用于控制器）。建议使用虚拟环境。
• （可选） kustomize 如果你使用独立版 kubectl apply -k。

如果你是Kubernetes的新手，先快速浏览一下 概念概述 了解部署（Deployments）、服务（Services）、Pod以及基于角色的访问控制（RBAC）。

______________________________________________________________________

快速入门：运行MVP操作符

1. 克隆仓库 并进入该目录。

   git clone https://github.com/your-org/mcp-operator.git
   cd mcp-operator

1. 创建一个独立的Python环境 并安装依赖项。

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

1. 安装CRDs（自定义资源定义） 这样，Kubernetes 就能理解新的资源类型。

   kubectl apply -k config/crds

确认他们已注册：

   kubectl get crd | grep mcp.operator

1. 安装RBAC资产 (命名空间，服务账户，集群角色，绑定)。

   kubectl apply -k config/rbac

1. 在本地运行操作符 （这会使用您的 kubeconfig 文件与集群进行通信）。

   make run

你应该看到Kopf的日志输出，表明操作员正在监控 MCPServer 资源。

1. 应用样本资源 在另一个终端中。

   kubectl apply -k config/samples
   # or use the richer example:
   kubectl apply -f examples/dev-stack.yaml

1. 检查状态。

   kubectl get mcpservers -n mcp-system
   kubectl describe mcpserver demo-server -n mcp-system
   kubectl get pods -n mcp-system

就是这样——你正在运行MVP操作符！示例MCPServer现在会持续地在内部被调整为Deployment和Service mcp-system 命名空间。

______________________________________________________________________

探索自定义资源

MCPServer（config/crds/mcpservers.yaml:1）

您可以设置的关键字段：

• spec.imageMCP服务器的容器镜像（必需）。
• spec.replicas期望的副本数量（默认为1）。
• spec.portMCP服务器暴露的容器端口。
• spec.env环境变量，包括可选的 valueFrom 秘密参考。
• spec.config要么是内联JSON（会为您转换为ConfigMap），要么是现有ConfigMap的引用。
• spec.secretRefs要挂载的密钥名称；控制器将每个密钥映射到一个卷。
• spec.podSecurity像这样的属性 serviceAccountName， runAsNonRoot，以及 seccompProfile。
• spec.resources标准的 Kubernetes 请求/限制字典。

状态字段（status.phase， status.conditions， status.endpoint) 由控制器进行更新，以便您能够与GitOps或仪表板集成。

MCPTool（config/crds/mcptools.yaml:1）

尽管控制器目前还不能对工具进行操作，但CRD允许团队注册元数据：

• spec.type工具类别（http， postgres等）。
• spec.endpoint工具所在的位置。
• spec.auth.secretRef包含凭据的秘密。
• spec.schema内联规范或参考说明，描述预期的输入/输出。

MCPAgent（config/crds/mcpagents.yaml:1）

设计用于在代理自动化实现后进行未来的对账：

• spec.serverRef指示代理应使用的MCPServer。
• spec.tools工具引用的数组（默认情况下处于同一命名空间）。
• spec.scaling基本的自动扩展提示（最小/最大副本数，CPU目标）。
• spec.rollout策略旋钮映射部署策略。
• spec.runtime额外的环境变量和资源预算。

即使在合并工具存在之前，这些定义也为平台团队提供了一种一致的方式来在Git中捕捉意图。

______________________________________________________________________

控制器的工作原理

核心逻辑存在于 controller/mcp_operator.py:1以下是高级流程概述：

1. 配置加载 – 控制器尝试加载集群内的配置，若从笔记本电脑运行则回退到本地kubeconfig文件。
2. “Kopf handlers”可以翻译为“头部操作员”或“头部处理人员”，具体取决于上下文和行业术语的习惯用法。在某些领域，如机械维修、制造业或特定的工业流程中，这个术语可能指的是负责处理或操作头部部件的工作人员。 – 装饰器（@kopf.on.create， @kopf.on.update， @kopf.timer为MCPServer事件和定期状态检查注册回调函数。
3. 期望状态合成 – 当一个新的MCPServer出现时，控制器会构建：

- 一个用于MCP服务器容器的部署（包含环境变量、密钥、配置卷、安全上下文）。 - 一个在请求的端口上暴露部署的服务。 - 如果你提供，就是一个内联的ConfigMap spec.config.inline。

1. 申请或更新 – 控制器创建资源，如果资源已存在，则对其进行修补。
2. 状态报告 – 每30秒，它会检查部署的就绪状态，并更新MCPServer的状态，包括阶段、条件以及一个内部终端URL。

因为控制器总是会调整以符合期望的规格，所以您可以放心地修改MCPServer的YAML文件，操作符将会滚动更新Deployment以使其匹配。

______________________________________________________________________

自定义您的部署

一旦快速入门成功运行，请根据您的需求调整YAML文件：

• 交换 spec.image 用于您自己的MCP服务器构建。
• 添加在（此处）引用的机密信息 spec.secretRefs 注入API密钥或TLS证书。
• 使用 spec.config.configMapRef 链接到外部管理的配置。
• 调整 spec.podSecurity.serviceAccountName 用于IAM角色（在EKS上的IRSA，GKE上的Workload Identity等）。
• 修改示例 config/samples/mcptool.yaml:1 并且 config/samples/mcpagent.yaml:1 以反映真实的工具/代理。即使没有协调器，这些自定义资源（CRs）也可以记录依赖关系。
• 将这些资源整合到Git仓库中，以便GitOps工具（如ArgoCD、Flux）能够自动应用它们。

______________________________________________________________________

测试与故障排除

• 运行控制器并启用详细日志：

  KOPF_LOGLEVEL=DEBUG make run

• 检查事件 由操作员发出：

  kubectl get events --sort-by=.metadata.creationTimestamp -n mcp-system

• 检查生成的Deployment/Service 验证标签和数量：

  kubectl get deploy demo-server -n mcp-system -o yaml
  kubectl get svc demo-server-svc -n mcp-system -o yaml

• 常见问题：

- *镜像拉取错误*确保镜像可访问，并在需要时配置镜像拉取密钥（imagePullSecrets）。 - *秘密未找到*在应用MCPServer之前，请先创建引用的密钥。 - *状态卡在“待处理”*跑 kubectl describe deployment 查看为何Pod未就绪（探测失败、配置缺失等）。 - *权限被拒绝*确保你已经申请了 config/rbac/operator-rbac.yaml:1 并且操作员进程正在使用 mcp-operator 服务账户。

在受限环境中进行Python字节码编译时，请使用：

PYTHONPYCACHEPREFIX=.pycache python3 -m py_compile controller/mcp_operator.py

______________________________________________________________________

路线图及后续步骤

长期愿景（概述于 docs:1）包括：

1. 全面重写为Go/Kubebuilder – 获取准入webhooks、类型化客户端、领导者选举以及更强大的测试功能。
2. MCPTool 和 MCPAgent 一致性检查器 – 自动连接工具和代理，应用网络策略，并传播凭据。
3. 操作强化 – 水平Pod自动扩缩器、Pod干扰预算、Prometheus指标、结构化日志。
4. 渐进式交付 – 金丝雀发布和蓝绿部署策略，Argo Rollouts集成，以及使用Gatekeeper/Kyverno进行策略强制执行。
5. 多租户（架构） – 工作区隔离、团队级基于角色的访问控制（RBAC）框架、资源配额。
6. 联合会 – 使用GitOps覆盖层或Cluster API管理跨集群的MCP部署。

欢迎社区贡献——请查看问题列表或提出与蓝图相符的增强建议。

______________________________________________________________________

有用资源及术语表

• Kubernetes Operator 基础知识 – 操作符模式介绍.
• Kopf 文档 – 框架使用指南.
• 模型上下文协议 – OpenAI的公告和MCP（模型上下文协议）规范（搜索“Model Context Protocol OpenAI”以获取最新参考）。
• 术语表：

- *CRD（Customer Relationship Development，客户关系发展）* – CustomResourceDefinition，一种模式扩展，使Kubernetes能够接受自定义对象。 - *“Reconciler”可以翻译为“协调者”或“和解者”，具体取决于上下文和语境。在金融或会计领域，它可能指的是负责核对账目、确保账目一致的人或系统；在更广泛的语境中，它可以指任何负责协调、调解或解决冲突的人* – 运算符内部的循环，用于将实际状态驱动至期望状态。 - *服务账户* – Pods用于与Kubernetes API或云提供商通信的身份。 - *内联配置* – 配置直接嵌入到MCPServer规范中，由控制器转换为ConfigMap。

______________________________________________________________________

按照本README文件的指导，您应该能够：

1. 了解MCP操作员的职责。
2. 安装并观察MVP控制器。
3. 尝试MCPServer的规范，并为未来版本中更丰富的工具做好准备。

祝建设顺利，欢迎根据所收录的设计指南对操作符进行迭代改进 docs。