使用说明

k8s计算mcp

Kubernetes计算数学MCP服务器

Go版本许可证

概述

k8s-compute-mcp 是一个用Go编写的本地MCP（模型上下文协议）服务器，充当LLM客户端（Gemini CLI、Claude Desktop、Cursor）和Kubernetes集群之间的桥梁。它使LLM能够使用专门的运算符将繁重的数学和财务计算卸载到集群中。

主要特点

MPI作业提交 -通过Kubeflow MPI运算符提交分布式MPI工作负载（Python/C++）
蒙特卡罗模拟 -使用带有自动输出隔离的JobSet运行并行蒙特卡洛批处理
结果聚合 -提交减速器作业以聚合计算结果
状态监控 -实时查询作业/工作量状态
工件访问 -直接从共享存储读取计算结果
可观测性 -Prometheus指标、结构化日志记录、健康/准备状态探测
可靠性 -使用指数回退、输入验证和代码大小限制重试
E2E测试 -具有KIND集群生命周期的Ginkgo/Gomega框架
安全 -gosec扫描、Trivy容器分析、SBOM生成
发布 -具有多平台二进制文件和容器映像的GoReleaser

建筑

┌─────────────────────────────────────────────────────────────────────┐
│                    MCP Client (Gemini/Claude/Cursor)                 │
└────────────────────────────┬────────────────────────────────────────┘
                             │ stdio / SSE
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    k8s-compute-mcp Server                            │
│       MCP Protocol → Tool Handlers → K8s Client                      │
└────────────────────────────┬────────────────────────────────────────┘
                             │ client-go
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Kubernetes Cluster                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │   Kueue     │  │ MPI Operator│  │   JobSet    │  │  Shared PVC │ │
│  │  (Queuing)  │  │ (Kubeflow)  │  │ Controller  │  │  /mnt/data  │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────────────────────┘

目标集群要求

库贝内特斯1.28+
Kueue -工作量排队
MPI操作员（v2beta1）-分布式MPI工作负载
作业集控制器（v1alpha2）-并行作业集
共用PVC ReadWriteMany 访问模式安装在 /mnt/data

可用工具

工具	说明	K8s资源
`submit_mpi_job`	提交MPI工作负载（Python/C++）	`kubeflow.org/v2beta1 MPIJob`
`submit_monte_carlo_batch`	提交并行蒙特卡洛模拟	`jobset.x-k8s.io/v1alpha2 JobSet`
`submit_reducer`	提交结果聚合作业	`batch/v1 Job`
`check_status`	查询作业/工作量状态	各种
`read_artifact_head`	读取结果文件的前N行	PVC访问

工具示例

提交MPI作业：

{
  "tool": "submit_mpi_job",
  "arguments": {
    "code": "from mpi4py import MPI\n...",
    "language": "python",
    "nodes": 4
  }
}

提交蒙特卡洛批次：

{
  "tool": "submit_monte_carlo_batch",
  "arguments": {
    "script": "import random\n...",
    "replicas": 100
  }
}

快速开始

先决条件

转到1.25+
使用必需的运算符访问Kubernetes集群
kubectl 配置了群集访问权限

从源代码构建

git clone https://github.com/ArangoGutierrez/k8s-compute-mcp.git
cd k8s-compute-mcp
make build

跑

# Stdio mode (for MCP clients)
./bin/server

# Test with example
cat examples/submit_mpi.json | ./bin/server

配置Claude桌面

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "k8s-compute": {
      "command": "/path/to/k8s-compute-mcp/bin/server"
    }
  }
}

安装

使用Go

go install github.com/ArangoGutierrez/k8s-compute-mcp/cmd/server@latest

容器图像

docker pull ghcr.io/arangogutierrez/k8s-compute-mcp:latest

Helm 图表

helm install k8s-compute-mcp \
  oci://ghcr.io/arangogutierrez/charts/k8s-compute-mcp \
  --namespace compute-mcp --create-namespace

配置

服务器使用本地kubeconfig(~/.kube/config)用于集群访问。

环境变量	描述	默认值
`KUBECONFIG`	kubeconfig文件的路径	`~/.kube/config`
`KUBE_CONTEXT`	要使用的Kubernetes上下文	当前上下文
`MCP_LOG_LEVEL`	日志详细程度（调试、信息、警告、错误）	`info`
`PVC_MOUNT_PATH`	共享存储装载路径	`/mnt/data`
`KUEUE_QUEUE`	默认Kueue队列名称	`default-queue`

发展

构建

make build      # Build binary
make test       # Run tests
make lint       # Run linter
make image      # Build container image
make test-e2e   # Run E2E tests (requires kind, helm, kubectl)

项目结构

k8s-compute-mcp/
├── cmd/server/              # Main entry point
├── internal/
│   ├── k8s/                 # Kubernetes client, manifests, retry, status
│   │   ├── client.go        # client-go setup (out-of-cluster)
│   │   ├── mpijob.go        # MPIJob manifest builder
│   │   ├── jobset.go        # JobSet manifest builder
│   │   ├── job.go           # Batch Job manifest builder
│   │   ├── reader.go        # Ephemeral pod artifact reader
│   │   ├── retry.go         # Exponential backoff with jitter
│   │   └── status.go        # Job phase extraction
│   ├── mcp/                 # MCP protocol handling
│   │   ├── server.go        # Server setup & tool registration
│   │   ├── handlers.go      # Tool handlers
│   │   ├── tools.go         # Tool definitions & schemas
│   │   ├── health.go        # /healthz, /readyz, /metrics endpoints
│   │   └── metrics.go       # Prometheus instrumentation
│   └── info/                # Build version info
├── pkg/prompts/             # MCP prompt templates
├── deployment/
│   ├── Dockerfile           # Multi-stage production image
│   ├── Dockerfile.goreleaser # GoReleaser-optimized image
│   └── helm/                # Helm chart
├── test/e2e/                # E2E tests (Ginkgo + KIND)
└── .github/workflows/       # CI, E2E, release, security

用例

1.蒙特卡洛期权定价

User: "Price a European call option using Monte Carlo with 10M simulations"

LLM → k8s-compute-mcp → submit_monte_carlo_batch(replicas=100)
     → Each replica runs 100K simulations
     → submit_reducer aggregates results
     → read_artifact_head returns final price

2.分布式矩阵运算

User: "Multiply these two large matrices using MPI"

LLM → k8s-compute-mcp → submit_mpi_job(nodes=8, code="...")
     → MPI job distributes matrix blocks
     → check_status monitors progress
     → read_artifact_head returns result

3.参数扫描

User: "Run sensitivity analysis across 500 parameter combinations"

LLM → k8s-compute-mcp → submit_monte_carlo_batch(replicas=500)
     → JOB_COMPLETION_INDEX isolates each run
     → Results collected in /mnt/data/results/{index}/

可观测性

服务器公开一个HTTP端点（默认 :8081)对于健康检查和指标：

端点	描述
`/healthz`	活体探针（始终返回200）
`/readyz`	准备就绪探针（检查K8s连接）
`/metrics`	普罗米修斯指标

普罗米修斯指标

度量	类型	描述
`mcp_tool_requests_total`	计数器	按工具名称和状态列出的工具调用总数
`mcp_tool_errors_total`	计数器	按工具名称和错误类型列出的工具错误
`mcp_tool_duration_seconds`	柱状图	工具调用延迟分布
`mcp_active_jobs`	仪表	当前跟踪的活动工单

可靠性

使用回退重试：暂时性K8s API错误（429，5xx，超时）通过指数退避和抖动重试
输入验证：代码大小限制，工具边界处的参数验证
结构化日志记录：klog/v2，带有指向stderr的键值对（stdout保留给MCP协议）

项目状态

当前阶段： 所有核心阶段完成

阶段	状态	描述
第一阶段	完成	存储库设置、K8s客户端、MCP框架
第二阶段	完成	实施并测试了所有5个核心工具
第三阶段	完成	Dockerfile、Helm chart、CI/CD、安全性、可观察性

包含什么

5个MCP工具：submit_mpi_job、submit_monte_carlobatch、submit_reducer、check_status、read_artifact_head
生产部署：多级Dockerfile，带有RBAC/探针/指标的Helm图
CI/CD：对每个PR、GoReleaser发布、安全扫描（gosec+Trivy）进行Lint/test/vet
E2E测试：具有KIND集群生命周期的Ginkgo框架（每晚）
可观测性：Prometheus指标、结构化日志记录、健康/就绪端点
可靠性：使用指数回退、输入验证、代码大小上限重试

看问题为了未来的增强。

贡献

我们欢迎捐款！请参阅贡献.md 作为指导方针。

快速贡献指南

分叉并克隆存储库
创建要素分支： git checkout -b feat/my-feature
进行更改，添加测试
运行检查： make lint && make test
向DCO承诺： git commit -s -S -m "feat(scope): description"
带有标签和里程碑的公开公关

许可证

Apache许可证2.0-请参阅许可证了解详情。

联系

维护人员： @阿兰戈古铁雷斯
问题： GitHub问题

把我们放在GitHub上——这很有帮助！

Kubernetes计算MCP服务器

使用说明

k8s计算mcp

概述

主要特点

建筑

目标集群要求

可用工具

工具示例

快速开始

先决条件

从源代码构建

跑

配置Claude桌面

安装

使用Go

容器图像

Helm 图表

配置

发展

构建

项目结构

用例

1.蒙特卡洛期权定价

2.分布式矩阵运算

3.参数扫描

可观测性

普罗米修斯指标

可靠性

项目状态

包含什么

贡献

快速贡献指南

相关项目

许可证

联系

使用说明

k8s计算mcp

概述

主要特点

建筑

目标集群要求

可用工具

工具示例

快速开始

先决条件

从源代码构建

跑

配置Claude桌面

安装

使用Go

容器图像

Helm 图表

配置

发展

构建

项目结构

用例

1.蒙特卡洛期权定价

2.分布式矩阵运算

3.参数扫描

可观测性

普罗米修斯指标

可靠性

项目状态

包含什么

贡献

快速贡献指南

相关项目

许可证

联系

相关 MCP

Kubernetes集群管理MCP服务

Kubernetes MCP服务器

Kubernetes资源管理工具

Kubernetes MCP 服务器

Kubernetes 多集群管理服务

多集群管理MCP服务器