MCP K3d Poc

MCP k3d沙盒PoC

一个简单的MCP（模型上下文协议）服务器，使用k3d提供临时Kubernetes沙盒用于测试和开发目的。

这是什么？

该项目提供了一种简单的方法来创建隔离的Kubernetes环境（沙盒），用于测试应用程序、运行实验或学习Kubernetes。每个沙箱都是一个完整的k3d集群，具有可配置的节点，可以通过简单的REST API创建、使用和销毁这些节点。

特性

• 🚀 快速创建沙盒：使用自定义服务器/代理配置创建Kubernetes沙盒
• 🔒 审批工作流程：沙盒创建的内置审批系统
• 🧪 冒烟测试：在沙盒上运行自动测试
• 📊 监控：Prometheus指标和审计日志
• 🧹 自动清理：基于TTL的自动销毁
• 🛠️ PowerShell自动化：适用于Windows用户的即用型脚本

先决条件

所需软件

• Docker 桌面版：在资源充足的情况下在当地运行
• k3d：Docker中的Kubernetes- choco install k3d （Windows）或遵循 k3d安装指南
• kubectl 的：Kubernetes CLI工具
• Python 3.9+：使用pip包管理器

可选工具

• jq：用于bash脚本中的JSON处理
• PowerShell 5.1+：用于自动脚本（Windows）

快速开始

1.设置服务器

# Clone the repository
git clone 
cd mcp-k3d-poc

# Setup Python environment
cd server
python -m venv venv
# On Windows:
venv\Scripts\activate
# On Linux/Mac:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2.启动MCP服务器

# Start the server (will run on http://localhost:8000)
uvicorn app:app --reload --port 8000

3.创建你的第一个沙盒

选项A：使用PowerShell脚本（建议用于Windows）

# This script will create, approve, test, and verify a sandbox automatically
.\create_approve_test.ps1

选项B：手动API调用

# Create a sandbox
curl -X POST "http://localhost:8000/create_sandbox" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-test-sandbox", "servers": 1, "agents": 1, "ttl_minutes": 60}'

# Note the sandbox_id and approval_id from the response

# Approve the sandbox creation
curl -X POST "http://localhost:8000/approve?approval_id=&approver=your-email@example.com"

# Check status until it's ACTIVE
curl "http://localhost:8000/get_sandbox_status/"

4.使用你的沙盒

# Get kubeconfig
curl "http://localhost:8000/get_kubeconfig/" | jq -r .kubeconfig > kubeconfig.yaml

# Use kubectl with the sandbox
export KUBECONFIG=./kubeconfig.yaml
kubectl get nodes
kubectl get pods -A

5.运行测试

# Run smoke test
curl -X POST "http://localhost:8000/run_test" \
  -H "Content-Type: application/json" \
  -d '{"sandbox_id": "", "test_id": "smoke"}'

6.清理

选项A：使用PowerShell脚本

# Destroys the latest active sandbox
.\destroy_latest.ps1

选项B：手动API调用

# Destroy the sandbox
curl -X POST "http://localhost:8000/destroy_sandbox?sandbox_id=" \
  -H "Content-Type: application/json"

API 参考

端点

沙盒配置

{
  "name": "my-sandbox",
  "servers": 1,
  "agents": 1,
  "ttl_minutes": 60,
  "owner": "your-email@example.com"
}

建筑

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   PowerShell    │    │   MCP Server    │    │      k3d        │
│   Scripts       │───▶│   (FastAPI)    │ ──▶│   Clusters      │
│                 │    │                 │    │                 │
│ • create_approve│    │ • Sandbox Mgmt  │    │ • Ephemeral K8s │
│   _test.ps1     │    │ • Approval Flow │    │ • Auto Cleanup  │
│ • destroy_latest│    │ • Kubeconfig    │    │                 │
│   .ps1          │    │ • Testing       │    └─────────────────┘
└─────────────────┘    │ • Metrics       │
                       │ • Audit Log     │
                       └─────────────────┘

文件结构

mcp-k3d-poc/
├── server/                    # MCP server code
│   ├── app.py                # Main FastAPI application
│   ├── requirements.txt      # Python dependencies
│   ├── mcp_manifest.json     # MCP manifest
│   ├── mcp.db               # SQLite database (auto-created)
│   └── kubeconfigs/         # Stored kubeconfigs
├── scripts/                  # Bash automation scripts
│   ├── create_demo_cluster.sh
│   └── run_demo_test.sh
├── examples/                 # Example API calls
│   ├── curl_examples.md
│   └── sample_spec.json
├── create_approve_test.ps1   # PowerShell: Create & test sandbox
├── destroy_latest.ps1        # PowerShell: Destroy latest sandbox
└── README.md

故障排除

常见问题

1. kubectl连接失败

- 确保Docker桌面正在运行 - 检查沙盒是否处于活动状态 - 验证kubeconfig是否已正确下载

1. 端口冲突

- k3d使用随机端口；检查 k3d cluster list 对于实际端口

1. kubeconfig上的权限被拒绝

- 服务器自动设置适当的文件权限

日志和调试

• 服务器日志显示在运行uvicorn的终端中
• 检查 server/mcp.db 用于沙盒状态
• 使用 k3d cluster list 查看正在运行的集群
• 检查 kubectl config view 对于当前配置

发展

添加新测试

测试定义见 scripts/run_demo_test.sh。要添加新的测试类型：

1. 修改测试脚本以接受不同的 test_id 价值观
2. 更新API以处理新的测试类型
3. 在bash脚本中添加测试逻辑

扩展API

服务器是用FastAPI构建的。在中添加新端点 server/app.py:

@app.post("/new_endpoint")
def new_endpoint(data: SomeModel):
    # Your logic here
    return {"result": "success"}

安全考虑

这是一个概念验证的实施。用于生产用途：

• 认证：添加适当的用户身份验证和授权
• 加密：将kubeconfigs存储在安全的保险库中（例如HashiCorp保险库）
• 数据库：用PostgreSQL替换SQLite
• 传输层安全：为所有API终结点启用HTTPS
• 基于角色的访问控制：实施基于角色的访问控制
• 审计：加强审计记录和监测
• 资源限制：添加配额和资源限制

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 彻底测试
5. 提交拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。