星战科技xingzhan.cloud
返回市场
模块化构建平台

模块化构建平台

作者：StacklokLabs54 星标更新：2025-11-24
安装使用来源：spider==github.com

项目介绍

MKP - Kubernetes 的 Model Kontext Protocol 服务器

<p align="center"> <img src="docs/assets/mkp-logo.png" width="400" alt="MKP Logo"> </p>

MKP 是一个用于 Kubernetes 的 Model Context Protocol (MCP) 服务器，它允许由大型语言模型 (LLM) 驱动的应用程序与 Kubernetes 集群进行交互。它提供了通过 MCP 协议列出和应用 Kubernetes 资源的工具。

功能

  • 列出 Kubernetes API 服务器支持的资源
  • 列出集群资源
  • 列出命名空间资源
  • 获取资源及其子资源（包括状态、规模、日志等）
  • 应用（创建或更新）集群资源
  • 应用（创建或更新）命名空间资源
  • 在 Pod 中执行带有超时控制的命令
  • 使用 API Machinery 的无结构客户端实现通用且可插拔的功能
  • 内置速率限制以防止过多的 API 调用

为什么选择 MKP？

作为 Kubernetes 的 Model Context Protocol 服务器，MKP 提供了几个关键优势：

原生 Go 实现

  • 使用与 Kubernetes 相同的语言构建
  • 对于服务器应用程序具有出色的性能特性
  • 强类型安全性和并发支持
  • 无缝集成 Kubernetes 库

直接 API 集成

  • 直接使用 Kubernetes API 机制，无需外部依赖
  • 不依赖于 kubectl、helm 或其他 CLI 工具
  • 直接与 Kubernetes API 服务器通信
  • 减少开销并提高可靠性

普遍资源支持

  • 通过无结构客户端与任何 Kubernetes 资源类型工作
  • 不需要硬编码的资源模式或专门处理程序
  • 自动支持自定义资源定义 (CRD)
  • 为新的 Kubernetes 资源做好准备

极简设计

  • 专注于核心 Kubernetes 资源操作
  • 清晰、易于维护的代码库，职责分离明确
  • 轻量级，依赖最少
  • 易于理解、扩展和贡献

生产就绪架构

  • 设计用于生产环境中的可靠性和性能
  • 正确的错误处理和资源管理
  • 内置速率限制以防止过多的 API 调用
  • 具有全面单元测试的可测试设计
  • 遵循 Kubernetes 开发最佳实践

预备条件

  • Go 1.24 或更高版本
  • Kubernetes 集群和 kubeconfig
  • Task 用于运行任务

安装

  1. 克隆仓库：

    git clone https://github.com/StacklokLabs/mkp.git
cd mkp

  2. 安装依赖：

    task install

  3. 构建服务器：

    task build

使用

运行服务器

要使用默认的 kubeconfig 运行服务器：

task run

要使用特定的 kubeconfig 运行服务器：

KUBECONFIG=/path/to/kubeconfig task run-with-kubeconfig

要在特定端口上运行服务器：

MCP_PORT=9091 task run

使用 ToolHive 运行

MKP 可以作为 Model Context Protocol (MCP) 服务器使用 ToolHive，这简化了 MCP 服务器的部署和管理。

请参阅 ToolHive 文档 了解如何使用 ToolH Hive UI、CLI 或 Kubernetes Operator 设置 MKP 的详细说明。

MCP 工具

MKP 服务器提供以下 MCP 工具：

get_resource

获取 Kubernetes 资源或其子资源。

参数：

  • resource_type（必需）：要获取的资源类型（集群或命名空间）
  • group：API 组（例如，apps，networking.k8s.io）
  • version（必需）：API 版本（例如，v1，v1beta1）
  • resource（必需）：资源名称（例如，deployments，services）
  • namespace：命名空间（对于命名空间资源是必需的）
  • name（必需）：要获取的资源名称
  • subresource：要获取的子资源（例如，status，scale，logs）
  • parameters：请求的可选参数（见下文示例）

示例：

{
  "name": "get_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "apps",
    "version": "v1",
    "resource": "deployments",
    "namespace": "default",
    "name": "nginx-deployment",
    "subresource": "status"
  }
}

获取特定容器日志的示例，带参数：

{
  "name": "get_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    "version": "v1",
    "resource": "pods",
    "namespace": "default",
    "name": "my-pod",
    "subresource": "logs",
    "parameters": {
      "container": "my-container",
      "sinceSeconds": "3600",
      "timestamps": "true",
      "limitBytes": "102400"
    }
  }
}

可用的 Pod 日志参数：

  • container：指定要获取哪个容器的日志
  • previous：获取前一个容器实例的日志（true/false）
  • sinceSeconds：仅返回比相对时间更近的日志（秒数）
  • sinceTime：仅返回特定时间之后的日志（RFC3339 格式）
  • timestamps：在每行中包含时间戳（true/false）
  • limitBytes：返回的最大字节数
  • tailLines：从日志末尾返回的行数

默认情况下，Pod 日志限制为最后 100 行和 32KB，以避免压垮 LLM 的上下文窗口。这些默认值可以通过上述参数覆盖。

常规资源的可用参数：

  • resourceVersion：当指定时，显示该特定版本的资源

list_resources

列出特定类型的 Kubernetes 资源。

参数：

  • resource_type（必需）：要列出的资源类型（集群或命名空间）
  • group：API 组（例如，apps，networking.k8s.io）
  • version（必需）：API 版本（例如，v1，v1beta1）
  • resource（必需）：资源名称（例如，deployments，services）
  • namespace：命名空间（对于命名空间资源是必需的）
  • label_selector：用于过滤资源的 Kubernetes 标签选择器（可选）
  • include_annotations：是否在输出中包含注解（默认：true）
  • exclude_annotation_keys：要从输出中排除的注解键列表（支持通配符 *）
  • include_annotation_keys：要包含在输出中的注解键列表（如果指定了，则只包含这些）
注解过滤

list_resources 工具提供了强大的注解过滤能力，以控制元数据输出大小，并防止因大注解（如 GPU 节点注解）而截断问题。

基本用法：

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "namespaced",
    "group": "apps",
    "version": "v1",
    "resource": "deployments",
    "namespace": "default"
  }
}

排除特定注解（对 GPU 节点有用）：

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "clustered",
    "group": "",
    "version": "v1",
    "resource": "nodes",
    "exclude_annotation_keys": [
      "nvidia.com/*",
      "kubectl.kubernetes.io/last-applied-configuration"
    ]
  }
}

仅包含特定注解：

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    "version": "v1",
    "resource": "pods",
    "namespace": "default",
    "include_annotation_keys": ["app", "version", "prometheus.io/scrape"]
  }
}

完全禁用注解以获得最大性能：

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    ersion": "v1",
    "resource": "pods",
    "namespace": "default",
    "include_annotations": false
  }
}

注解过滤规则：

  • 默认情况下，kubectl.kubernetes.io/last-applied-configuration 被排除以防止大量配置数据
  • exclude_annotation_keys 支持使用 * 的通配符模式（例如，nvidia.com/* 排除所有 NVIDIA 注解）
  • 当指定了 include_annotation_keys 时，它优先考虑并且只有那些注解被包含
  • 设置 include_annotations: false 完全移除输出中的所有注解
  • 通配符模式仅支持在键的末尾使用 *（例如，nvidia.com/*）

apply_resource

应用（创建或更新）Kubernetes 资源。

参数：

  • resource_type（必需）：要应用的资源类型（集群或命名空间）
  • group：API 组（例如，apps，networking.k8s.io）
  • version（必需）：API 版本（例如，v1，v1beta1）
  • resource（必需）：资源名称（例如，deployments，services）
  • namespace：命名空间（对于命名空间资源是必需的）
  • manifest（必需）：资源清单

示例：

{
  "name": "apply_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "apps",
    "version": "v1",
    "resource": "deployments",
    "namespace": "default",
    "manifest": {
      "apiVersion": "apps/v1",
      "kind": "Deployment",
      "metadata": {
        "name": "nginx-deployment",
        "namespace": "default"
      },
      "spec": {
        "replicas": 3,
        "selector": {
          "matchLabels": {
            "app": "nginx"
          }
        },
        "template": {
          "metadata": {
            "labels": {
              "app": "nginx"
            }
          },
          "spec": {
            "containers": [
              {
                "name": "nginx",
                "image": "nginx:latest",
                "ports": [
                  {
                    "containerPort": 80
                  }
                ]
              }
            ]
          }
        }
      }
    }
  }
}

post_resource

向 Kubernetes 资源或其子资源发布内容，特别适用于在 Pod 中执行命令。

参数：

  • resource_type（必需）：要发布的资源类型（集群或命名空间）
  • group：API 组（例如，apps，networking.k8s.io）
  • version（必需）：API 版本（例如，v1，v1beta1）
  • resource（必需）：资源名称（例如，deployments，services）
  • namespace：命名空间（对于命名空间资源是必需的）
  • name（必需）：要发布的资源名称
  • subresource：要发布的子资源（例如，exec）
  • body（必需）：要发布到资源的内容
  • parameters：请求的可选参数

在 Pod 中执行命令的示例：

{
  "name": "post_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    "version": "v1",
    "resource": "pods",
    "namespace": "default",
    "name": "my-pod",
    "subresource": "exec",
    "body": {
      "command": ["ls", "-la", "/"],
      "container": "my-container",
      "timeout": 30
    }
  }
}

Pod 执行的 body 支持以下字段：

  • command（必需）：要执行的命令，可以是字符串或字符串数组
  • container（可选）：要执行命令的容器名称（默认为第一个容器）
  • timeout（可选）：超时时间（秒），默认为 15 秒，最大 60 秒

关于超时的注意事项：

  • 默认超时：未指定时为 15 秒
  • 最大超时：60 秒（任何更大的值会被限制）
  • 超过超时的命令将被终止并返回超时错误

响应包括标准输出、标准错误和任何错误消息：

{
  "apiVersion": "v1",
  "kind": "Pod",
  "metadata": {
    "name": "my-pod",
    "namespace": "default"
  },
  "spec": {
    "command": ["ls", "-la", "/"]
  },
  "status": {
    "stdout": "total 48\ndrwxr-xr-x   1 root root 4096 May  5 14:30 .\ndrwxr-xr-x   1 root root 4096 May  5 14:30 ..\n...",
    "stderr": "",
    "error": ""
  }
}

MCP 资源

MKP 服务器通过 MCP 资源提供对 Kubernetes 资源的访问。资源 URI 遵循以下格式：

  • 集群资源：k8s://clustered/{group}/{version}/{resource}/{name}
  • 命名空间资源：k8s://namespaced/{namespace}/{group}/{version}/{resource}/{name}

配置

传输协议

MKP 支持两种 MCP 服务器的传输协议：

  • 流式 HTTP：默认传输协议，适合大多数用例
  • SSE（服务器发送事件）：遗留传输协议，主要用于兼容旧客户端

您可以使用 CLI 标志或环境变量来配置传输协议：

# 使用 CLI 标志
./build/mkp-server --transport=sse

# 使用环境变量
MCP_TRANSPORT=sse ./build/mkp-server

# 默认（流式 HTTP）
./build/mkp-server

MCP_TRANSPORT 环境变量在使用 ToolHive 运行 MKP 时会自动设置。

控制资源发现

默认情况下，MKP 将所有 Kubernetes 资源作为 MCP 资源提供，这对于 LLM 来说非常有用。然而，在拥有许多资源的大集群中，这可能会消耗大量的 LLM 上下文空间。

您可以通过使用 --serve-resources 标志来禁用此行为：

# 不提供集群资源运行
./build/mkp-server --serve-resources=false

# 使用特定的 kubeconfig 并不提供集群资源运行
./build/mkp-server --kubeconfig=/path/to/kubeconfig --serve-resources=false

即使禁用了资源发现，MCP 工具（get_resource、list_resources、apply_resource、delete_resource 和 post_resource）仍然完全可用，允许您与 Kubernetes 集群进行交互。

启用写操作

默认情况下，MKP 处于只读模式，这意味着它不允许对集群进行写操作，即 apply_resource、delete_resource 和 post_resource 工具不可用。您可以通过使用 --read-write 标志来启用写操作：

# 启用写操作运行
./build/mkp-server --read-write=true

# 使用特定的 kubeconfig 并启用写操作运行
./build/mkp-server --kubeconfig=/path/to/kubeconfig --read-write=true

速率限制

MKP 包含内置的速率限制机制，以保护服务器免受过多的 API 调用，这对于与 AI 代理一起使用尤为重要。速率限制器使用令牌桶算法，并根据操作类型应用不同的限制：

  • 读取操作（list_resources，get_resource）：每分钟 120 次请求
  • 写入操作（apply_resource，delete_resource）：每分钟 30 次请求
  • 其他操作的默认值：每分钟 60 次请求

速率限制按客户端会话应用，确保多个客户端之间的公平资源分配。速率限制功能可以通过命令行标志启用或禁用：

# 启用速率限制运行（默认）
./build/mkp-server

# 禁用速率限制运行
./build/mkp-server --enable-rate-limiting=false

开发

运行测试

task test

格式化代码

task fmt

代码检查

task lint

更新依赖项

task deps

贡献

我们欢迎对此 MCP 服务器的贡献！如果您想贡献，请查看 CONTRIBUTING 指南 以了解如何开始。

如果您遇到 Bug 或有功能请求，请在存储库中 打开一个问题 或加入我们的社区 Discord 服务器上的 #mcp-servers 频道。

许可证

本项目根据 Apache v2 许可证发布 - 详情请参阅 LICENSE 文件。