使用说明

KCC MCP服务器

用于为谷歌云平台做出贡献的模型上下文协议（MCP）服务器 k8s配置连接器.

此MCP服务器为AI助手提供以下工具：

添加字段 到现有的直接控制器资源
迁移资源 从基于Terraform到直接控制器架构
创建提交 具有强制归因规则（无人工智能归因）

特性

✅ 12个MCP工具 k8s配置连接器贡献 ✅ 通用AI归因阻断 -强制执行仅限人类的作者身份 ✅ 资源检测 -自动确定控制器类型 ✅ 迁移规划 -Terraform的7阶段工作流程→ 直接迁移 ✅ 脚手架规范 -为类型、控制器、MockGCP生成样板 ✅ 原型注释 -维护KRM↔ GCP原型映射

快速开始

使用Gemini CLI安装（推荐）

# Install from GitHub
npx @google/gemini-cli extensions install https://github.com/fkc1e100/kcc-mcp-server.git

# Run setup
cd ~/.gemini/extensions/kcc-contributor
./setup-config.sh

# Start using it
npx @google/gemini-cli chat

手动安装

# Clone or copy this repository
cd kcc-mcp-server

# Install dependencies
npm install

# Build
npm run build

配置

选项1：交互式设置（最简单）

安装后运行安装脚本：

./setup-config.sh

这创造了 ~/.config/kcc-mcp-server/config.json 使用您的设置。

选项2：手动配置文件

创建 ~/.config/kcc-mcp-server/config.json:

{
  "git": {
    "author_name": "Your Name",
    "author_email": "you@example.com"
  },
  "kcc_repo_path": "/path/to/k8s-config-connector"
}

选项3：环境变量

export KCC_REPO_PATH="/path/to/k8s-config-connector"
export KCC_AUTHOR_NAME="Your Name"
export KCC_AUTHOR_EMAIL="you@example.com"

使用Gemini CLI

# Start chat session
npx @google/gemini-cli chat
# or
gemini --yolo

# Check MCP server status
/mcp list

# Should show:
# 🟢 kccServer (from kcc-contributor) - Ready (12 tools)

示例提示：

Check if ComputeURLMap needs migration

Find the EdgeCacheService resource files

Add a new field called routeMethods to EdgeCacheService

看双子座_CLI_USAGE.md 更多示例。

验证安装

安装后，验证MCP服务器是否已连接：

npx @google/gemini-cli chat

然后在聊天中：

/mcp list

您应该看到：

🟢 kccServer (from kcc-contributor) - Ready (12 tools)
  Tools:
  - kcc_add_field
  - kcc_detect_controller_type
  - kcc_find_resource
  - kcc_generate_mapper
  - kcc_git_commit
  - kcc_git_status
  - kcc_migration_status
  - kcc_plan_migration
  - kcc_scaffold_controller
  - kcc_scaffold_identity
  - kcc_scaffold_mockgcp
  - kcc_scaffold_types

如果你看到 🔴 kccServer - Disconnected，请参阅故障排除在......下面

使用Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）：

{
  "mcpServers": {
    "kcc-contributor": {
      "command": "node",
      "args": ["/path/to/kcc-mcp-server/dist/index.js"],
      "env": {
        "KCC_REPO_PATH": "/path/to/k8s-config-connector"
      }
    }
  }
}

可用工具

资源检测（3个工具）

`kcc_find_resource`

查找KCC资源的文件（类型、控制器、映射器、测试夹具）。

参数：

resource （string）：资源名称（例如，“EdgeCacheService”）

`kcc_detect_controller_type`

检测资源是使用直接控制器还是基于Terraform的控制器。

参数：

resource （string）：资源名称

退货：

{
  "type": "terraform",
  "migration_needed": true,
  "service": "compute",
  "version": "v1beta1"
}

`kcc_migration_status`

获取资源的迁移状态（显示哪些阶段已完成）。

参数：

resource （string）：资源名称

退货：

{
  "resource": "ComputeURLMap",
  "overall_progress": "2/7 phases",
  "current_phase": { "number": 2, "name": "API Types", "status": "not_started" },
  "next_action": "Use kcc_scaffold_types to create API types file",
  "can_add_fields": false
}

迁移工具（5个工具）

`kcc_plan_migration`

制定详细的7阶段迁移计划，将基于Terraform的资源迁移到直接控制器。

参数：

resource （string）：资源名称

`kcc_scaffold_types`

生成API类型文件（迁移的第2阶段）。

参数：

resource, service, version, proto_package, proto_message, description （可选）

`kcc_scaffold_identity`

生成身份处理程序文件（迁移的第3阶段）。

参数：

resource, service, version, resource_name_format

`kcc_scaffold_controller`

生成控制器文件（迁移的第5阶段）。

参数：

resource, service, version, proto_package, proto_message

`kcc_scaffold_mockgcp`

生成MockGCP服务器文件（迁移的第6阶段）。

参数：

resource, service, proto_package, proto_message, resource_name_format

现场添加（2个工具）

`kcc_add_field`

使用适当的原型注释向现有的直接控制器添加字段。

参数：

{
  "resource": "EdgeCacheService",
  "field_name": "RouteMethods",
  "field_type": "array",
  "proto_path": "google.cloud.networkservices.v1.EdgeCacheService.routing.route_rule.route_methods",
  "parent_type": "ComputeURLMapSpec",
  "description": "HTTP methods to match for routing"
}

`kcc_generate_mapper`

重新生成KRM↔ 添加字段后的原型映射器。

参数：

resource （string）：资源名称

Git操作（2个工具）

`kcc_git_commit`

使用强制规则创建git commit：阻止AI归因，使用您的git身份，验证消息格式。

参数：

{
  "message": "feat(networkservices): Add routeMethods to EdgeCacheService\n\nAdds support for HTTP method-based routing.",
  "files": ["apis/networkservices/v1alpha1/edgecacheservice_types.go"]
}

验证：

✅ 阻止人工智能归因（Claude、Anthropic、Gemini、OpenAI等）
✅ 验证常规提交格式（feat:、fix:、chore：等）
✅ 使用您配置的git标识

`kcc_git_status`

获取当前git状态。

无需参数。

示例工作流

示例1：向现有直接控制器添加字段

脚本： 添加 routeMethods 字段到EdgeCacheService

// 1. Find the resource
kcc_find_resource({ resource: "EdgeCacheService" })

// 2. Add the field
kcc_add_field({
  resource: "EdgeCacheService",
  field_name: "RouteMethods",
  field_type: "array",
  proto_path: "google.cloud.networkservices.v1.EdgeCacheService.routing.route_rule.route_methods",
  description: "HTTP methods to match for routing"
})

// 3. Regenerate mapper
kcc_generate_mapper({ resource: "EdgeCacheService" })

// 4. Commit changes
kcc_git_commit({
  message: "feat(networkservices): Add routeMethods to EdgeCacheService\n\nAdds support for HTTP method-based routing."
})

示例2：将地形资源迁移到直接控制器

脚本： 将ComputeURLMap从Terraform迁移到直接控制器

// 1. Detect controller type
kcc_detect_controller_type({ resource: "ComputeURLMap" })
// Returns: { type: "terraform", migration_needed: true }

// 2. Check migration status
kcc_migration_status({ resource: "ComputeURLMap" })
// Shows: 2/7 phases complete, next: scaffold types

// 3. Get detailed migration plan
kcc_plan_migration({ resource: "ComputeURLMap" })
// Returns: 7 phases with specific tasks

// 4. Phase 2: Scaffold API types
kcc_scaffold_types({
  resource: "ComputeURLMap",
  service: "compute",
  version: "v1beta1",
  proto_package: "google.cloud.compute.v1",
  proto_message: "UrlMap"
})

// 5. Phase 3: Scaffold identity handler
kcc_scaffold_identity({
  resource: "ComputeURLMap",
  service: "compute",
  version: "v1beta1",
  resource_name_format: "projects/{project}/global/urlMaps/{urlMap}"
})

// 6. Phase 4: Generate mapper
kcc_generate_mapper({ resource: "ComputeURLMap" })

// 7. Phase 5: Scaffold controller
kcc_scaffold_controller({
  resource: "ComputeURLMap",
  service: "compute",
  version: "v1beta1",
  proto_package: "google.cloud.compute.v1",
  proto_message: "UrlMap"
})

// 8. Phase 6: Scaffold MockGCP
kcc_scaffold_mockgcp({
  resource: "ComputeURLMap",
  service: "compute",
  proto_package: "google.cloud.compute.v1",
  proto_message: "UrlMap",
  resource_name_format: "projects/{project}/global/urlMaps/{urlMap}"
})

// 9. Manually create test fixtures (Phase 7)
// ... create YAML files in pkg/test/resourcefixture/testdata/

// 10. Commit the migration
kcc_git_commit({
  message: "feat(compute)!: Migrate ComputeURLMap to direct controller\n\nMigrates from Terraform-based to direct controller architecture.\n\nBREAKING CHANGE: Resource moves from terraform to direct controller."
})

测试

# Test field addition tools
npm test

# Test migration tools
node test/test-migration-tools.js

测试结果：

✅ Test 1: Detect Controller Type - PASS
✅ Test 2: Get Migration Status - PASS
✅ Test 3: Plan Migration - PASS
✅ Test 4: Verify EdgeCacheService (Direct Controller) - PASS

故障排除

kccServer显示为已断开连接

如果 /mcp list 显示 🔴 kccServer - Disconnected:

1.检查配置文件是否存在：

cat ~/.config/kcc-mcp-server/config.json

如果缺少，请运行安装脚本：

cd ~/.gemini/extensions/kcc-contributor
./setup-config.sh

2.验证SDK版本（必须为1.11.0+）：

cat ~/.gemini/extensions/kcc-contributor/package.json | grep "@modelcontextprotocol/sdk"

应显示： "@modelcontextprotocol/sdk": "^1.11.0"

如果它显示 0.5.0 或更旧版本，请更新扩展名：

npx @google/gemini-cli extensions uninstall kcc-contributor
npx @google/gemini-cli extensions install https://github.com/fkc1e100/kcc-mcp-server.git

3.手动测试服务器：

cd ~/.gemini/extensions/kcc-contributor
node dist/index.js

应显示：

✅ KCC MCP Server initialized
📁 Repository: /path/to/k8s-config-connector
👤 Author: Your Name <you@example.com>
🚀 KCC MCP Server running

4.检查存储库路径是否有效：

确保 kcc_repo_path 在您的配置中，指向一个有效的k8s配置连接器目录。

更新扩展

要获取最新版本：

选项1：重新安装

npx @google/gemini-cli extensions uninstall kcc-contributor
npx @google/gemini-cli extensions install https://github.com/fkc1e100/kcc-mcp-server.git

选项2：手动更新

cd ~/.gemini/extensions/kcc-contributor
git pull origin main
npm install

然后重新启动Gemini CLI。

未找到配置文件

如果您看到有关未找到配置的错误，请创建配置文件：

mkdir -p ~/.config/kcc-mcp-server
cat > ~/.config/kcc-mcp-server/config.json << 'EOF'
{
  "git": {
    "author_name": "Your Name",
    "author_email": "you@example.com"
  },
  "kcc_repo_path": "/path/to/k8s-config-connector"
}
EOF

用您的实际信息替换路径和详细信息。

迁移阶段

迁移过程包括7个阶段：

原型定义 -验证原型文件是否存在
API类型（KRM） -定义Kubernetes资源类型
身份处理程序 -实现资源名称解析
映射器生成 -生成KRM↔ 原型转换
控制器实现 -执行CRUD操作
MockGCP实现 -创建模拟GCP服务器进行测试
测试夹具 -创建YAML测试夹具

每个阶段都建立在前一个阶段的基础上。使用 kcc_migration_status 跟踪进展。

关键规则

⚠️ AI归因被阻止

此服务器 强制执行 git commits中只记入人类贡献者。它将拒绝任何包含以下内容的提交消息：

AI助手名称（Claude、Gemini、GPT等）
人工智能公司名称（Anthropic、OpenAI等）
与人工智能电子邮件共同撰写
短语如“生成”、“人工智能生成”等。

这是一个 不可转让 k8s配置连接器贡献的要求。

约定式提交

提交消息必须遵循传统的提交格式：

<type>(<scope>): <subject>

<body>

类型： feat, fix, docs, chore, refactor, test

例子：

feat(compute): Add defaultCustomErrorResponsePolicy to ComputeURLMap

Adds support for configuring custom error response policies
at the URL map level.

建筑

kcc-mcp-server/
├── src/
│   ├── index.ts              # MCP server implementation
│   ├── config.ts             # Configuration management
│   ├── git-validator.ts      # Git attribution enforcement
│   └── tools/
│       ├── find-resource.ts          # Resource file location
│       ├── detect-controller-type.ts # Controller type detection
│       ├── migration-status.ts       # Migration progress tracking
│       ├── plan-migration.ts         # Migration plan generation
│       ├── scaffold-types.ts         # API types scaffolding
│       ├── scaffold-identity.ts      # Identity handler scaffolding
│       ├── scaffold-controller.ts    # Controller scaffolding
│       ├── scaffold-mockgcp.ts       # MockGCP scaffolding
│       ├── add-field.ts              # Field addition
│       └── generate-mapper.ts        # Mapper generation
├── test/
│   ├── test-edgecacheservice.js      # Field addition tests
│   └── test-migration-tools.js       # Migration tools tests
└── README.md

配置优先

配置按以下顺序加载（先找到获胜）：

环境变量 （最高优先级）
- KCC_REPO_PATH, KCC_AUTHOR_NAME, KCC_AUTHOR_EMAIL
配置文件 (~/.config/kcc-mcp-server/config.json)
Git配置 （最低优先级，仅用作作者姓名/电子邮件的回退）

使用说明

KCC MCP服务器

特性

快速开始

使用Gemini CLI安装（推荐）

手动安装

配置

使用Gemini CLI

验证安装

使用Claude Desktop

可用工具

资源检测（3个工具）

kcc_find_resource

kcc_detect_controller_type

kcc_migration_status

迁移工具（5个工具）

kcc_plan_migration

kcc_scaffold_types

kcc_scaffold_identity

kcc_scaffold_controller

kcc_scaffold_mockgcp

现场添加（2个工具）

kcc_add_field

kcc_generate_mapper

Git操作（2个工具）

kcc_git_commit

kcc_git_status

示例工作流

示例1：向现有直接控制器添加字段

示例2：将地形资源迁移到直接控制器

测试

故障排除

kccServer显示为已断开连接

更新扩展

未找到配置文件

迁移阶段

关键规则

⚠️ AI归因被阻止

约定式提交

建筑

配置优先

资源

许可证

作者

相关 MCP

Kubernetes集群管理MCP服务

Unity MCP AI游戏开发工具

MATLAB代码执行与生成服务

Kubernetes MCP服务器

Claude代码MCP服务器

Kubernetes资源管理工具

`kcc_find_resource`

`kcc_detect_controller_type`

`kcc_migration_status`

`kcc_plan_migration`

`kcc_scaffold_types`

`kcc_scaffold_identity`

`kcc_scaffold_controller`

`kcc_scaffold_mockgcp`

`kcc_add_field`

`kcc_generate_mapper`

`kcc_git_commit`

`kcc_git_status`