This PR adds proper kubeconfig validation and improves the MCP Orchestrator startup experience in development.

What’s fixed

Archestra no longer crashes with unclear internal Kubernetes client errors.

When a developer provides a custom kubeconfig, we now validate it early with clear, human-readable error messages.

When no kubeconfig is provided, the orchestrator safely falls back to the OS default (~/.kube/config), exactly as Kubernetes tooling expects.

What’s added

A new validateKubeconfig() function with structured, developer-friendly errors.

A full documentation page: Kubeconfig Setup, covering exporting configs, required fields, common errors, and troubleshooting.

Tests for missing files, malformed YAML, missing sections, and correct fallback behavior.

Result

Developers can now successfully run Archestra with Kubernetes in development and install local MCP servers (e.g., context7) without the orchestrator failing unexpectedly.

Before: After:

(Now able to install MCP Server in dev environment)

/claim #1426

[!NOTE] Introduce explicit kubeconfig validation with clear errors, default fallback behavior, updated runtime loading logic, and comprehensive setup docs with tests.

• Backend (Kubernetes runtime):
  • Add validateKubeconfig(path?) in platform/backend/src/mcp-server-runtime/manager.ts to parse and validate kubeconfig (checks clusters, contexts, users; handles missing file/parse errors) and log success.
  • Update McpServerRuntimeManager constructor to:
    • Validate only when a custom kubeconfig path is provided and not loading in-cluster.
    • Support in-cluster loading, custom file loading, or default ~/.kube/config fallback with informative logs.
    • Throw on config load errors; expose isEnabled via status.
• Tests:
  • Add manager.test.ts covering validation cases (no path, missing file, parse failure, missing sections, valid config) and basic exports.
• Docs:
  • Add docs/pages/kubeconfig-setup.md with environment variables, default behavior, required structure, common errors/fixes, examples, testing, and troubleshooting.

^{Written by Cursor Bugbot for commit bdfcb00f40c30d475da051e8bfe49dba25873c8f. This will update automatically on new commits. Configure here.}