# KCC MCP Server

Model Context Protocol (MCP) server for contributing to Google Cloud Platform's [k8s-config-connector](https://github.com/GoogleCloudPlatform/k8s-config-connector).

This MCP server provides AI assistants with tools to:
- **Add fields** to existing direct controller resources
- **Migrate resources** from Terraform-based to direct controller architecture
- **Create commits** with enforced attribution rules (NO AI attribution)

## Features

✅ **12 MCP Tools** for k8s-config-connector contributions
✅ **Universal AI Attribution Blocking** - enforces human-only commit authorship
✅ **Resource Detection** - automatically determines controller type
✅ **Migration Planning** - 7-phase workflow for Terraform → Direct migration
✅ **Code Scaffolding** - generates boilerplate for types, controller, MockGCP
✅ **Proto Annotations** - maintains KRM ↔ GCP proto mappings

## Quick Start

### Installation with Gemini CLI (Recommended)

```bash
# 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
```

### Manual Installation

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

# Install dependencies
npm install

# Build
npm run build
```

### Configuration

**Option 1: Interactive Setup (Easiest)**

Run the setup script after installation:

```bash
./setup-config.sh
```

This creates `~/.config/kcc-mcp-server/config.json` with your settings.

**Option 2: Manual Config File**

Create `~/.config/kcc-mcp-server/config.json`:

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

**Option 3: Environment Variables**

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

### Usage with Gemini CLI

```bash
# 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)
```

**Example prompts:**
```
Check if ComputeURLMap needs migration
```
```
Find the EdgeCacheService resource files
```
```
Add a new field called routeMethods to EdgeCacheService
```

See [GEMINI_CLI_USAGE.md](GEMINI_CLI_USAGE.md) for more examples.

### Verifying Installation

After installation, verify the MCP server is connected:

```bash
npx @google/gemini-cli chat
```

Then in the chat:
```
/mcp list
```

You should see:
```
🟢 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
```

If you see `🔴 kccServer - Disconnected`, see [Troubleshooting](#troubleshooting) below.

### Usage with Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

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

## Available Tools

### Resource Detection (3 tools)

#### `kcc_find_resource`
Locate files for a KCC resource (types, controller, mapper, test fixtures).

**Parameters:**
- `resource` (string): Resource name (e.g., "EdgeCacheService")

#### `kcc_detect_controller_type`
Detect if a resource uses direct controller or Terraform-based controller.

**Parameters:**
- `resource` (string): Resource name

**Returns:**
```json
{
  "type": "terraform",
  "migration_needed": true,
  "service": "compute",
  "version": "v1beta1"
}
```

#### `kcc_migration_status`
Get migration status for a resource (shows which phases are complete).

**Parameters:**
- `resource` (string): Resource name

**Returns:**
```json
{
  "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
}
```

### Migration Tools (5 tools)

#### `kcc_plan_migration`
Create a detailed 7-phase migration plan for migrating a Terraform-based resource to direct controller.

**Parameters:**
- `resource` (string): Resource name

#### `kcc_scaffold_types`
Generate API types file (Phase 2 of migration).

**Parameters:**
- `resource`, `service`, `version`, `proto_package`, `proto_message`, `description` (optional)

#### `kcc_scaffold_identity`
Generate identity handler file (Phase 3 of migration).

**Parameters:**
- `resource`, `service`, `version`, `resource_name_format`

#### `kcc_scaffold_controller`
Generate controller file (Phase 5 of migration).

**Parameters:**
- `resource`, `service`, `version`, `proto_package`, `proto_message`

#### `kcc_scaffold_mockgcp`
Generate MockGCP server file (Phase 6 of migration).

**Parameters:**
- `resource`, `service`, `proto_package`, `proto_message`, `resource_name_format`

### Field Addition (2 tools)

#### `kcc_add_field`
Add a field to an existing direct controller with proper proto annotations.

**Parameters:**
```json
{
  "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`
Regenerate KRM ↔ Proto mapper after adding fields.

**Parameters:**
- `resource` (string): Resource name

### Git Operations (2 tools)

#### `kcc_git_commit`
Create git commit with enforced rules: blocks AI attribution, uses your git identity, validates message format.

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

**Validation:**
- ✅ Blocks AI attribution (Claude, Anthropic, Gemini, OpenAI, etc.)
- ✅ Validates conventional commit format (feat:, fix:, chore:, etc.)
- ✅ Uses your configured git identity

#### `kcc_git_status`
Get current git status.

**No parameters required.**

## Example Workflows

### Example 1: Add Field to Existing Direct Controller

**Scenario:** Add `routeMethods` field to EdgeCacheService

```typescript
// 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."
})
```

### Example 2: Migrate Terraform Resource to Direct Controller

**Scenario:** Migrate ComputeURLMap from Terraform to direct controller

```typescript
// 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."
})
```

## Testing

```bash
# Test field addition tools
npm test

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

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

## Troubleshooting

### kccServer shows as Disconnected

If `/mcp list` shows `🔴 kccServer - Disconnected`:

**1. Check config file exists:**
```bash
cat ~/.config/kcc-mcp-server/config.json
```

If missing, run the setup script:
```bash
cd ~/.gemini/extensions/kcc-contributor
./setup-config.sh
```

**2. Verify SDK version (must be 1.11.0+):**
```bash
cat ~/.gemini/extensions/kcc-contributor/package.json | grep "@modelcontextprotocol/sdk"
```

Should show: `"@modelcontextprotocol/sdk": "^1.11.0"`

If it shows `0.5.0` or older, update the extension:
```bash
npx @google/gemini-cli extensions uninstall kcc-contributor
npx @google/gemini-cli extensions install https://github.com/fkc1e100/kcc-mcp-server.git
```

**3. Test server manually:**
```bash
cd ~/.gemini/extensions/kcc-contributor
node dist/index.js
```

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

**4. Check repository path is valid:**

Make sure the `kcc_repo_path` in your config points to a valid k8s-config-connector directory.

### Updating the Extension

To get the latest version:

**Option 1: Reinstall**
```bash
npx @google/gemini-cli extensions uninstall kcc-contributor
npx @google/gemini-cli extensions install https://github.com/fkc1e100/kcc-mcp-server.git
```

**Option 2: Manual update**
```bash
cd ~/.gemini/extensions/kcc-contributor
git pull origin main
npm install
```

Then restart Gemini CLI.

### Config File Not Found

If you see errors about config not found, create the config file:

```bash
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
```

Replace the paths and details with your actual information.

## Migration Phases

The migration process consists of 7 phases:

1. **Proto Definitions** - Verify proto files exist
2. **API Types (KRM)** - Define Kubernetes resource types
3. **Identity Handler** - Implement resource name parsing
4. **Mapper Generation** - Generate KRM ↔ Proto conversions
5. **Controller Implementation** - Implement CRUD operations
6. **MockGCP Implementation** - Create mock GCP server for testing
7. **Test Fixtures** - Create YAML test fixtures

Each phase builds on the previous phase. Use `kcc_migration_status` to track progress.

## Critical Rules

### ⚠️ AI Attribution is BLOCKED

This server **ENFORCES** that only human contributors are credited in git commits. It will **REJECT** any commit message containing:

- AI assistant names (Claude, Gemini, GPT, etc.)
- AI company names (Anthropic, OpenAI, etc.)
- Co-Authored-By lines with AI emails
- Phrases like "Generated with", "AI-generated", etc.

This is a **NON-NEGOTIABLE** requirement for k8s-config-connector contributions.

### Conventional Commits

Commit messages must follow the conventional commits format:

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

<body>
```

**Types:** `feat`, `fix`, `docs`, `chore`, `refactor`, `test`

**Example:**
```
feat(compute): Add defaultCustomErrorResponsePolicy to ComputeURLMap

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

## Architecture

```
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
```

## Configuration Priority

Configuration is loaded in this order (first found wins):

1. **Environment variables** (highest priority)
   - `KCC_REPO_PATH`, `KCC_AUTHOR_NAME`, `KCC_AUTHOR_EMAIL`
2. **Config file** (`~/.config/kcc-mcp-server/config.json`)
3. **Git config** (lowest priority, used as fallback for author name/email only)

## Resources

- [k8s-config-connector repo](https://github.com/GoogleCloudPlatform/k8s-config-connector)
- [Main development guide](https://github.com/GoogleCloudPlatform/k8s-config-connector/blob/master/docs/develop-resources/README.md)
- [Migration guide](https://github.com/GoogleCloudPlatform/k8s-config-connector/blob/master/docs/develop-resources/scenarios/migrate-tf-resource-alpha.md)

## License

Apache License 2.0 (following k8s-config-connector)

## Authors

- Frank Currie (fcurrie@google.com)