mcp-operator: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Building and Testing

# Run comprehensive test suite with envtest
make test

# Run specific controller tests
go test ./internal/controller -v -run "TestMCPServer"

# Run tests for a specific component (e.g., transport)
go test ./pkg/transport -v

# Run E2E tests with Kind cluster
make test-e2e

# Build the operator binary
make build

# Run locally for development (requires CRDs installed)
make run

Code Generation and Manifests

# Generate CRDs, RBAC, and webhooks after API changes
make manifests

# Generate deepcopy methods after API changes
make generate

# Install/uninstall CRDs in cluster
make install
make uninstall

# Deploy/undeploy operator to cluster
make deploy IMG=controller:latest
make undeploy

Linting and Quality

# Run golangci-lint
make lint

# Auto-fix linting issues
make lint-fix

# Format code
make fmt

# Vet code
make vet

Container and Distribution

# Build and push container image
make docker-build IMG=myregistry/mcp-operator:tag
make docker-push IMG=myregistry/mcp-operator:tag

# Build multi-platform images
make docker-buildx IMG=myregistry/mcp-operator:tag

# Generate consolidated install.yaml
make build-installer IMG=myregistry/mcp-operator:tag

Architecture Overview

This is a Kubernetes operator for managing Model Context Protocol (MCP) servers. The architecture follows standard controller-runtime patterns with sophisticated transport abstraction.

Core Components

API Layer (api/v1/mcpserver_types.go)

• MCPServer CRD with comprehensive configuration options
• Transport-specific configuration (HTTP/Custom)
• Enterprise features: HPA, ingress, RBAC, security contexts
• Rich status reporting with phase tracking and conditions

Controller (internal/controller/mcpserver_controller.go)

• MCPServerReconciler implements reconciliation loop
• Transport-aware resource management via Strategy pattern
• Retry logic with client-go/util/retry.RetryOnConflict for optimistic concurrency
• Comprehensive status updates with condition management
• Resource ownership and finalizer-based cleanup