MKP-Kubernetes的Kontext协议服务器模型
MKP是Kubernetes的模型上下文协议（MCP）服务器，允许 LLM驱动的应用程序与Kubernetes集群交互。它提供工具 用于通过MCP协议列出和应用Kubernetes资源。
特性
- 列出Kubernetes API服务器支持的资源
- 列出群集资源
- 列出命名空间资源
- 获取资源及其子资源（包括状态、规模、日志等）
- 应用（创建或更新）群集资源
- 应用（创建或更新）命名空间资源
- 在带有超时控制的Pod中执行命令
- 使用API机械的非结构化客户端的通用和可插拔实现
- 内置速率限制，可防止API调用过多
为什么选择MKP？
MKP作为模型上下文协议服务器提供了几个关键优势 库贝内特斯：
原生Go实现
- 使用与Kubernetes本身相同的语言构建
- 服务器应用程序的卓越性能特性
- 强大的类型安全和并发支持
- 与Kubernetes库无缝集成
API直接集成
- 直接使用Kubernetes API机器，无需外部依赖
- 不依赖kubectl、helm或其他CLI工具
- 与Kubernetes API服务器直接通信
- 减少开销，提高可靠性
通用资源支持
- 通过非结构化客户端使用任何Kubernetes资源类型
- 不需要硬编码的资源模式或专门的处理程序
- 自动支持自定义资源定义（CRD）
- 面向未来的新Kubernetes资源
极简设计
- 专注于核心Kubernetes资源操作
- 干净、可维护的代码库，关注点明确分离
- 轻量级，依赖性最小
- 易于理解、扩展和贡献
生产就绪架构
- 专为生产环境中的可靠性和性能而设计
- 正确的错误处理和资源管理
- 内置速率限制，以防止过多的API调用
- 具有全面单元测试的可测试设计
- 遵循Kubernetes开发最佳实践
先决条件
- 转到1.24或更高版本
- Kubernetes集群和kubeconfig
- 任务 用于运行任务
安装
- 克隆存储库：
git clone https://github.com/StacklokLabs/mkp.git
cd mkp- 安装依赖项：
task install- 构建服务器：
task build用法
运行服务器
要使用默认kubeconfig运行服务器：
task run要使用特定的kubeconfig运行服务器：
KUBECONFIG=/path/to/kubeconfig task run-with-kubeconfig要在特定端口上运行服务器，请执行以下操作：
MCP_PORT=9091 task run使用ToolHive运行
MKP可以作为模型上下文协议（MCP）服务器运行，使用 ToolHive，这简化了 MCP服务器的部署和管理。
请参阅 ToolHive文档 为了 关于如何使用ToolHive UI、CLI或 Kubernetes操作员。
MCP工具
MKP服务器提供以下MCP工具：
获取资源
获取Kubernetes资源或其子资源。
参数：
resource_type（必填）：要获取的资源类型（集群或命名空间）group：API组（例如，应用程序、网络.k8s.io）version（必需）：API版本（例如，v1、v1beta1）resource（必填）：资源名称（例如，部署、服务）namespace：命名空间（命名空间资源所需）name（必填）：要获取的资源的名称subresource：要获取的子资源（例如，状态、规模、日志）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：每行包含时间戳（真/假）limitBytes：要返回的最大字节数tailLines：从日志末尾返回的行数
默认情况下，pod日志限制为最后100行和32KB，以避免 淹没了LLM的上下文窗口。这些默认值可以使用以下命令覆盖 上面的参数。
经常资源的可用参数：
resourceVersion：指定时，显示该特定位置的资源
版本
列表_资源
列出特定类型的Kubernetes资源。
参数：
resource_type（必填）：要列出的资源类型（集群或命名空间）group：API组（例如，应用程序、网络.k8s.io）version（必需）：API版本（例如，v1、v1beta1）resource（必填）：资源名称（例如，部署、服务）namespace：命名空间（命名空间资源所需）label_selector：用于过滤资源的Kubernetes标签选择器（可选）include_annotations：是否在输出中包含注释（默认值：
真的）
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": "",
"version": "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/*)
应用程序_资源
应用（创建或更新）Kubernetes资源。
参数：
resource_type（必填）：要应用的资源类型（群集或
命名空间）
group：API组（例如，应用程序、网络.k8s.io）version（必需）：API版本（例如，v1、v1beta1）resource（必填）：资源名称（例如，部署、服务）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组（例如，应用程序、网络.k8s.io）version（必需）：API版本（例如，v1、v1beta1）resource（必填）：资源名称（例如，部署、服务）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
}
}
}这 body for pod exec支持以下字段：
command（必填）：要执行的命令，可以是字符串或数组
字符串
container（可选）：在其中执行命令的容器名称（默认为
第一个容器）
timeout（可选）：超时时间（秒）（默认为15秒，最多60秒
秒）
关于超时的注意事项：
- 默认超时：如果未指定，则为15秒
- 最长超时时间：60秒（任何较大的值都将被限制）
- 超过超时的命令将被终止并返回超时错误
响应包括stdout、stderr和任何错误消息：
{
"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标志或 环境变量：
# Using CLI flag
./build/mkp-server --transport=sse
# Using environment variable
MCP_TRANSPORT=sse ./build/mkp-server
# Default (Streamable HTTP)
./build/mkp-server这 MCP_TRANSPORT 环境变量在以下情况下由ToolHive自动设置 在该环境中运行MKP。
控制资源发现
默认情况下，MKP将所有Kubernetes资源作为MCP资源提供，这提供了 LLM的有用上下文。然而，在拥有许多资源的大型集群中 可能会占用LLM中的大量上下文空间。
您可以使用以下命令禁用此行为 --serve-resources 标志：
# Run without serving cluster resources
./build/mkp-server --serve-resources=false
# Run with a specific kubeconfig without serving cluster resources
./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 标志：
# Run with write operations enabled
./build/mkp-server --read-write=true
# Run with a specific kubeconfig and write operations enabled
./build/mkp-server --kubeconfig=/path/to/kubeconfig --read-write=true速率限制
MKP包括一个内置的速率限制机制，以保护服务器免受 过多的API调用，这在与AI代理一起使用时尤为重要。 速率限制器使用令牌桶算法并应用不同的限制 根据操作类型：
- 读取操作（list_resources，get_source）：每分钟120个请求
- 写入操作（apply_resource、delete_resource）：每分钟30个请求
- 其他操作的默认值：每分钟60个请求
每个客户端会话都应用速率限制，确保公平的资源分配 跨多个客户。可以启用或禁用速率限制功能 通过命令行标志：
# Run with rate limiting enabled (default)
./build/mkp-server
# Run with rate limiting disabled
./build/mkp-server --enable-rate-limiting=false发展
运行测试
task test格式化代码
task fmtLinting代码
task lint更新依赖项
task deps贡献
我们欢迎对MCP服务器的贡献！如果你想捐款，请 审查 贡献指南 有关如何获取的详细信息 起动。
如果您遇到错误或有功能请求，请 打开一个问题 在存储库中或 加入我们 #mcp-servers 我们的频道 社区Discord服务器.
许可证
此项目在Apache v2许可证下获得许可-请参阅License文件 细节。
