feat(poc): catalog-gen, a cli tool to generate new entity catalogs

[Al-Pragliola]

Description

This PR introduces catalog-gen, a code generation CLI tool that scaffolds complete catalog services from a declarative YAML configuration. It generates all necessary boilerplate including models, repositories, OpenAPI specs, Kubernetes manifests, and AI agent integration files.

Key Features

• Declarative Configuration: Define your entity catalog in a single catalog.yaml file
• Full Stack Generation: Generates models, repositories, service layers, OpenAPI specs, and K8s manifests
• Artifact Support: Add typed artifacts linked to entities (e.g., Tool artifacts for MCP servers)
• AI Agent Integration: Generates .claude/ skills and commands for AI-assisted development
• Incremental Updates: generate command regenerates only non-editable files, preserving manual customizations

Project Structure

cmd/catalog-gen/
├── main.go              # CLI entry point
├── init.go              # `init` command - scaffolds new catalog
├── generate.go          # `generate` command - regenerates from config
├── add_provider.go      # `add-provider/artifact` commands
├── types.go             # Configuration types (CatalogConfig, etc.)
├── templates.go         # Template loading & constants
├── helpers.go           # Shared utilities
├── gen_models.go        # Entity & artifact model generation
├── gen_service.go       # Repository & spec generation
├── gen_api.go           # OpenAPI generation
├── gen_manifests.go     # Kubernetes manifest generation
├── gen_providers.go     # Provider (YAML/HTTP) generation
└── templates/           # 45+ Go templates organized by domain
    ├── agent/           # AI agent skills & commands
    ├── api/             # OpenAPI specs
    ├── catalog/         # Loader
    ├── cmd/             # Main entry point
    ├── docs/            # Documentation
    ├── manifests/       # Kubernetes manifests
    ├── misc/            # Makefile, README, gitignore
    ├── models/          # Entity & artifact models
    ├── providers/       # YAML & HTTP providers
    ├── server/          # OpenAPI service impl
    └── service/         # Repositories & specs

How Has This Been Tested?

1. Build catalog-gen

go build -o bin/catalog-gen ./cmd/catalog-gen/...

2. Initialize a new MCP Server catalog

./bin/catalog-gen init mcp-catalog \
  --entity=McpServer \
  --package=github.com/kubeflow/model-registry/mcp-catalog

3. Add entity properties

Edit mcp-catalog/catalog.yaml and add properties under spec.entity.properties:

properties:
  - name: name
    type: string
  - name: source_id
    type: string
  - name: logo
    type: string
  - name: license
    type: string
  - name: license_link
    type: string
  - name: provider
    type: string
  - name: version
    type: string
  - name: tags
    type: array
    items:
      type: string

4. Regenerate code

cd mcp-catalog
../bin/catalog-gen generate

5. Generate OpenAPI server

make gen/openapi-server

6. Build and verify

go build ./...

7. Add artifacts (optional)

Edit catalog.yaml and add artifacts:

artifacts:
  - name: Tool
    properties:
      - name: schema
        type: string
      - name: inputType
        type: string
      - name: description
        type: string

Then either:

• With AI Agent: Run /regenerate command in Claude CLI - the agent will handle all manual steps automatically
• Without AI Agent: Run ../bin/catalog-gen generate and follow the manual steps in .claude/skills/regenerate.md

⚠️ Important: Running catalog-gen generate alone is NOT enough! Manual code changes are required to map properties through the service layer, YAML provider, and OpenAPI converters. The generated .claude/skills/regenerate.md contains the exact code snippets needed. For artifacts, see docs/post-artifact-generation.md.

8. Seed test data

Use the /seed-data command in Claude CLI, or manually edit:

• manifests/kustomize/overlays/dev/sample-catalog.yaml - Entity data
• manifests/kustomize/overlays/dev/artifacts.yaml - Artifact data

9. Run locally with PostgreSQL

# Start PostgreSQL
docker run -d --name mcp-catalog-db \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=mcp-catalog \
  -p 5432:5432 \
  postgres:16

# Run the server
cd mcp-catalog
PGHOST=localhost PGUSER=postgres PGPASSWORD=postgres \
  go run ./cmd/... -catalogs-path=./manifests/kustomize/overlays/dev/sources.yaml -logtostderr

10. Test the API

# List entities
curl -s "http://localhost:8080/api/mcp-catalog/v1alpha1/mcpservers" | jq

# Get specific entity
curl -s "http://localhost:8080/api/mcp-catalog/v1alpha1/mcpservers/{name}" | jq

Merge criteria:

• All the commits have been signed-off (To pass the DCO check)

• The commits have meaningful messages
• Automated tests are provided as part of the PR for major new functionalities; testing instructions have been added in the PR body (for PRs involving changes that are not immediately obvious).
• The developer has manually tested the changes and verified that the changes work.
• Code changes follow the kubeflow contribution guidelines.
• For first time contributors: Please reach out to the Reviewers to ensure all tests are being run, ensuring the label ok-to-test has been added to the PR.

[google-oss-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please ask for approval from al-pragliola. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment