Crossplane Compass

Understand your control plane. Diagnose with evidence. Propose changes through GitOps.

Crossplane Compass is an independently implemented MCP server for platform engineers and AI assistants. It connects installed Crossplane APIs to 24 focused tools over stdio or authenticated Streamable HTTP. It works from actual CRD schemas, scope and API discovery—not hard-coded cloud resources or guessed plural names.

Release: v0.1.0 · License: Apache-2.0 · Runtime: Python 3.12+ · Deployment: Helm / container / local

Initial release, not a zero-bug guarantee. See validation evidence for checks actually run and live-cluster gates still to run. Published image/chart URLs become available only after you push this repository and the release workflow succeeds.

Why Compass?

Related MCP server: mctl

Start locally

Install uv, clone or extract this repository, and use a trusted kubeconfig:

uv sync --frozen
uv run crossplane-compass --version
uv run crossplane-compass   --context dev=your-kubeconfig-context   --groups platform.example.org,cosmosdb.azure.upbound.io   --namespaces team-a

The last command starts the stdio MCP server; it waits for an MCP client and does not print a chat UI. Use your actual API groups from kubectl api-resources. Only the explicitly selected context is exposed. When --context is omitted, alias default uses in-cluster credentials or the current kubeconfig context.

MCP client

{
  "mcpServers": {
    "crossplane-compass": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/crossplane-compass",
        "run", "--frozen", "crossplane-compass",
        "--context", "dev=your-kubeconfig-context",
        "--groups", "platform.example.org,cosmosdb.azure.upbound.io"
      ]
    }
  }
}

For VS Code use servers instead of mcpServers and add "type": "stdio". Desktop clients may need KUBECONFIG and PATH configured to find cloud authentication plugins.

Install with Helm

Build and push your image first, or use the image from your successful GitHub release:

export IMAGE=ghcr.io/YOUR_OWNER/crossplane-compass
# For a local build published manually:
docker build -t "$IMAGE:v0.1.0" .
docker push "$IMAGE:v0.1.0"

kubectl create namespace compass
# Generate locally; do not commit or paste the token into a chat.
umask 077
openssl rand -hex 32 > token
kubectl -n compass create secret generic crossplane-compass-auth --from-file=token

helm upgrade --install compass ./charts/crossplane-compass   --namespace compass   --set fullnameOverride=crossplane-compass   --set image.repository="$IMAGE"   --set image.tag=v0.1.0   --set 'access.groups={platform.example.org,cosmosdb.azure.upbound.io}'   --wait

kubectl -n compass port-forward svc/crossplane-compass 8080:8080

Connect an HTTP-capable MCP client to http://localhost:8080/mcp, with Authorization: Bearer <contents-of-token>. Keep the local token file private or import it into your secret manager and remove it. For remote access, use TLS through your authenticated gateway. The Helm service is ClusterIP; no public ingress is created.

The release workflow also publishes oci://ghcr.io/YOUR_OWNER/charts/crossplane-compass, version 0.1.0, with the released image digest embedded. See installation for Flux, namespace isolation, network policy and dry-run permissions.

Architecture

flowchart TD
    Client["MCP client / AI assistant"] --> Transport["stdio or authenticated HTTP"]
    Transport --> Policy["Cluster, group and namespace policy"]
    Policy --> Tools["24 bounded diagnostic and proposal tools"]
    Tools --> Discovery["Cached CRD and API discovery"]
    Discovery --> API["Kubernetes API"]
    Tools --> Review["Schema checks and GitOps review diff"]

The MCP host supplies the language model. Compass does not require an LLM key, vector database or cloud credentials of its own. Provider credentials remain in the cluster; Compass never reads Kubernetes Secrets. Kubeconfig credentials authenticate only to the Kubernetes API.

Tools at a glance

• Discover: clusters_list, discover, catalog_search, resource_schema

• Inspect: resources_list, resource_get, resource_events, inventory_summary, external_lookup

• Diagnose: resource_trace, diagnose, packages_health, resource_owners, provider_config_check, incident_bundle

• Compose: composition_explain, composition_compare, composition_impact

• Propose: manifest_scaffold, manifest_validate, manifest_plan

• Operate: adoption_check, migration_assess, deletion_assess

See the complete tool contract. Every cluster tool requires an explicit cluster alias. A small compass://guide MCP resource and troubleshoot prompt guide evidence-based use.

Design boundaries

• No apply, delete, force-reconcile, finalizer removal, shell execution or cloud API calls.

• Optional Kubernetes server-side dry-run is disabled by default. Its RBAC needs patch permissions, even though the application always sends dryRun=All.

• Local schema validation covers a JSON Schema/OpenAPI subset. It does not execute CEL or admission webhooks, render functions, estimate cost or guarantee provider behavior.

• Compact summaries are default; detailed manifests are opt-in. Redaction cannot guarantee removal of credentials embedded in arbitrary strings. Review incident exports.

• HTTP uses a shared bearer credential, not OAuth or per-user Kubernetes impersonation. Deploy a separate instance/service account for each trust boundary.

• Crossplane v2 can compose ordinary Kubernetes resources; this release traces only allowed CRD-backed resources, not core Secrets, Deployments or arbitrary core objects. Unavailable references are explicit errors.

Documentation

Install · Tools · Architecture · Security · Examples · Reference review · Release process · Contribute · Validation · Changelog

Development

uv sync --frozen
make check
make build
make chart  # Helm 3.19+ required

Contributions are welcome. Start with CONTRIBUTING.md: local setup, repository map, tool extension recipe, testing expectations and PR checklist are included.