# MCP Remote Server for Kubernetes

🚀 **通用远程 MCP 服务器** - 基于 MCP (Model Context Protocol) 协议的 Kubernetes 管理服务器，支持通过 HTTP/SSE 协议远程访问，为各种 AI 平台和应用程序提供 Kubernetes 集群的自然语言管理能力。

## 🌟 核心优势

- **🔌 通用兼容性**: 支持所有遵循 MCP 协议的客户端（Dify、Claude Desktop、自定义客户端等）
- **🌐 远程访问**: 通过 HTTP/SSE 协议提供远程 MCP 服务，无需本地部署
- **🔒 企业级安全**: JWT 认证、RBAC 权限控制、速率限制等安全机制
- **☸️ 完整 K8s 支持**: 涵盖 Pod、Service、Deployment 等资源的完整生命周期管理
- **📊 生产就绪**: 健康检查、结构化日志、错误处理、监控告警等企业特性

## 🚀 主要特性

### MCP 协议支持
- **标准协议**: 完整实现 MCP 2024-11-05 协议规范
- **多传输方式**: 支持 HTTP POST 和 SSE (Server-Sent Events)
- **实时通信**: 支持双向通信和事件推送

### Kubernetes 集成
- **API 代理**: 通过代理模式提供完整的 Kubernetes API 访问
- **资源管理**: 支持 Pod、Service、Deployment、ConfigMap 等资源操作
- **日志查看**: 实时获取容器日志
- **多集群**: 支持集群内和集群外两种部署模式

### 安全和认证
- **JWT 认证**: 基于 JSON Web Token 的安全认证
- **RBAC 权限**: 细粒度的角色权限控制
- **速率限制**: 防止 API 滥用和 DDoS 攻击
- **安全传输**: 支持 HTTPS 和安全头部配置

### 多平台支持
- **🤖 Dify**: 完整的 Dify 平台集成支持
- **💬 Claude Desktop**: 原生 MCP 客户端支持
- **🔧 自定义客户端**: 提供多语言 SDK 和示例
- **🌐 Web 应用**: 支持浏览器直接访问

## 📋 系统要求

- Node.js >= 18.0.0
- Kubernetes 集群访问权限
- Docker (可选，用于容器化部署)

## 🛠️ 安装和配置

### 1. 克隆项目

```bash
git clone <repository-url>
cd mcp-remote-server-kubernetes
```

### 2. 安装依赖

```bash
npm install
```

### 3. 配置环境变量

复制环境变量模板并根据需要修改：

```bash
cp .env.example .env
```

主要配置项：

```env
# 服务器配置
PORT=3000
HOST=0.0.0.0

# Kubernetes 配置
KUBECONFIG=/path/to/your/kubeconfig
K8S_IN_CLUSTER=false
K8S_NAMESPACE=default

# 认证配置
AUTH_ENABLED=true
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=24h

# 日志配置
LOG_LEVEL=info
LOG_CONSOLE=true
```

### 4. 构建项目

```bash
npm run build
```

### 5. 启动服务

```bash
# 开发模式
npm run dev

# 生产模式
npm start
```

## 🐳 Docker 部署

### 使用 Docker Compose

```bash
# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

### 手动 Docker 部署

```bash
# 构建镜像
docker build -t mcp-kubernetes-server .

# 运行容器
docker run -d \
  --name mcp-kubernetes-server \
  -p 3000:3000 \
  -v ~/.kube/config:/app/.kube/config:ro \
  -e AUTH_ENABLED=true \
  -e JWT_SECRET=your-secret-key \
  mcp-kubernetes-server
```

## ☸️ Kubernetes 部署

```bash
# 应用部署配置
kubectl apply -f k8s/deployment.yaml

# 检查部署状态
kubectl get pods -l app=mcp-kubernetes-server

# 查看服务
kubectl get svc mcp-kubernetes-server
```

## 🔌 多平台集成

### 支持的客户端平台

| 平台 | 状态 | 集成方式 | 文档链接 |
|------|------|----------|----------|
| 🤖 **Dify** | ✅ 完全支持 | HTTP MCP | [Dify 集成指南](examples/dify-integration.md) |
| 💬 **Claude Desktop** | ✅ 完全支持 | 标准 MCP | [MCP 客户端集成](docs/mcp-client-integration.md) |
| 🔧 **自定义客户端** | ✅ 完全支持 | HTTP/SSE API | [API 文档](docs/mcp-client-integration.md) |
| 🌐 **Web 应用** | ✅ 完全支持 | REST API | [使用示例](examples/usage-examples.md) |

### 快速集成示例

#### 1. Dify 平台集成

在 Dify 中配置 MCP 服务器：

```json
{
  "name": "Kubernetes MCP Server",
  "endpoint": "http://your-server:3000/mcp",
  "auth": {
    "type": "bearer",
    "token": "YOUR_JWT_TOKEN"
  },
  "capabilities": ["tools"]
}
```

**自然语言使用示例**：
- "显示默认命名空间中的所有 Pod"
- "部署一个 nginx 应用，使用 3 个副本"
- "获取 nginx Pod 的最近 100 行日志"
- "删除名为 test-pod 的 Pod"

#### 2. Claude Desktop 集成

创建 MCP 客户端代理脚本 `mcp-client-proxy.js`：

```javascript
const axios = require('axios');

const serverUrl = process.env.MCP_SERVER_URL;
const token = process.env.MCP_AUTH_TOKEN;

process.stdin.on('data', async (data) => {
  try {
    const message = JSON.parse(data.toString());
    const response = await axios.post(serverUrl, message, {
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
      }
    });
    console.log(JSON.stringify(response.data));
  } catch (error) {
    console.log(JSON.stringify({
      jsonrpc: '2.0',
      id: message?.id || null,
      error: { code: -32603, message: error.message }
    }));
  }
});
```

然后在 Claude Desktop 配置中：

```json
{
  "mcpServers": {
    "kubernetes": {
      "command": "node",
      "args": ["mcp-client-proxy.js"],
      "env": {
        "MCP_SERVER_URL": "http://your-server:3000/mcp",
        "MCP_AUTH_TOKEN": "YOUR_JWT_TOKEN"
      }
    }
  }
}
```

#### 3. 自定义客户端集成

```javascript
class MCPKubernetesClient {
  constructor(serverUrl, token) {
    this.serverUrl = serverUrl;
    this.token = token;
    this.requestId = 1;
  }

  async callTool(name, arguments) {
    const message = {
      jsonrpc: '2.0',
      id: this.requestId++,
      method: 'tools/call',
      params: { name, arguments }
    };

    const response = await fetch(this.serverUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.token}`
      },
      body: JSON.stringify(message)
    });

    return response.json();
  }

  async getPods(namespace = 'default') {
    return this.callTool('kubectl_get', {
      resource: 'pods',
      namespace
    });
  }
}

// 使用示例
const client = new MCPKubernetesClient(
  'http://your-server:3000/mcp',
  'YOUR_JWT_TOKEN'
);

const pods = await client.getPods();
console.log(pods.result);
```

## 📡 API 接口

### 支持的 MCP 方法

| 方法 | 描述 | 参数 |
|------|------|------|
| `initialize` | 初始化连接 | 协议版本、客户端信息 |
| `tools/list` | 获取工具列表 | 无 |
| `tools/call` | 调用工具 | 工具名称、参数 |
| `resources/list` | 获取资源列表 | 无 |
| `prompts/list` | 获取提示列表 | 无 |

### 可用工具

| 工具名称 | 功能描述 | 必需参数 | 可选参数 |
|----------|----------|----------|----------|
| `kubectl_get` | 获取 K8s 资源 | `resource` | `namespace`, `name` |
| `kubectl_apply` | 应用配置 | `yaml` | `namespace` |
| `kubectl_delete` | 删除资源 | `resource`, `name` | `namespace` |
| `kubectl_logs` | 获取日志 | `pod` | `namespace`, `container`, `lines` |

### API 端点

- **认证**: `POST /auth/login`
- **MCP 协议**: `POST /mcp`
- **SSE 实时**: `GET /mcp/sse`
- **健康检查**: `GET /health`

## 📡 API 使用

### 认证

首先获取访问令牌：

```bash
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'
```

### MCP 协议调用

使用获取的令牌调用 MCP 接口：

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'
```

### 支持的工具

- `kubectl_get`: 获取 Kubernetes 资源
- `kubectl_apply`: 应用资源配置
- `kubectl_delete`: 删除资源
- `kubectl_logs`: 获取 Pod 日志

#### 示例：获取 Pods

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "kubectl_get",
    "arguments": {
      "resource": "pods",
      "namespace": "default"
    }
  }
}
```

#### 示例：应用部署

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "kubectl_apply",
    "arguments": {
      "yaml": "apiVersion: v1\nkind: Pod\nmetadata:\n  name: test-pod\nspec:\n  containers:\n  - name: nginx\n    image: nginx:latest",
      "namespace": "default"
    }
  }
}
```

## 🔧 开发

### 项目结构

```
src/
├── auth/              # 认证相关
├── config/            # 配置管理
├── kubernetes/        # Kubernetes API 代理
├── middleware/        # 中间件
├── server/           # MCP 服务器实现
├── utils/            # 工具类
└── index.ts          # 应用入口
```

### 开发命令

```bash
# 开发模式（热重载）
npm run watch

# 代码检查
npm run lint

# 修复代码格式
npm run lint:fix

# 运行测试
npm test

# 构建项目
npm run build
```

## 🔒 安全考虑

1. **更改默认密钥**: 生产环境中务必更改 `JWT_SECRET`
2. **RBAC 权限**: 根据需要调整 Kubernetes RBAC 权限
3. **网络安全**: 使用 HTTPS 和适当的网络策略
4. **速率限制**: 根据需要调整请求频率限制
5. **日志审计**: 启用详细的访问日志记录

## 📊 监控和日志

### 健康检查

```bash
curl http://localhost:3000/health
```

### 日志配置

支持多种日志级别和输出格式：

- `LOG_LEVEL`: error, warn, info, debug, verbose
- `LOG_FORMAT`: combined, json, simple
- `LOG_FILE`: 日志文件路径（可选）
- `LOG_CONSOLE`: 控制台输出开关

## 🤝 贡献

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🆘 故障排除

### 常见问题

1. **Kubernetes 连接失败**
   - 检查 `KUBECONFIG` 路径是否正确
   - 验证集群访问权限
   - 确认网络连接

2. **认证失败**
   - 检查 JWT 密钥配置
   - 验证令牌是否过期
   - 确认用户权限

3. **端口冲突**
   - 修改 `PORT` 环境变量
   - 检查端口是否被占用

### 调试模式

启用详细日志：

```bash
LOG_LEVEL=debug npm run dev
```

## 📞 支持

如有问题或建议，请：

1. 查看 [Issues](../../issues) 页面
2. 创建新的 Issue
3. 联系维护者

---

**注意**: 这是一个开发版本，请在生产环境使用前进行充分测试。