ARC Config MCP Server

# Hybrid Workflow Clarity & Transparency Improvements **Date**: October 31, 2025 **Status**: Proposed Improvements **Priority**: High - User Experience & Confidence ## Problem Statement When users run `#arc_install_controller_hybrid --apply false`, the output message about manual Helm installation is **misleading** because: 1. **Disconnect between config file and manual command**: The tool generates a `controller.yaml` config file, but the "manual" Helm command shown doesn't actually use this file 2. **Confusion about purpose**: Users might think "I generated a config file, here's how to manually use it" when in fact the manual command bypasses the config entirely 3. **Custom values ignored**: If users add custom Helm values to `controller.yaml`, the manual command won't pick them up ## Current Behavior ### What Gets Generated (`configs/controller.yaml`) ```yaml chart: repository: oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller name: gha-runner-scale-set-controller version: latest release: name: arc-controller namespace: arc-systems createNamespace: true values: {} # Empty, but users can add custom Helm values here metadata: managedBy: arc-config-mcp mode: hybrid generatedAt: '2025-10-31T19:27:10.002Z' ``` ### What Gets Shown to Users ``` Option 2: Install manually with Helm ```bash helm install arc-controller \ oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller \ --namespace arc-systems \ --create-namespace ``` ``` **Problem**: This command doesn't reference `configs/controller.yaml` at all! ## Actual Workflow ### How `#arc_apply_config` Actually Works When you run `#arc_apply_config --configType controller`, the tool: 1. **Reads** `configs/controller.yaml` 2. **Extracts** chart info, release details, and values 3. **Builds** a Helm command dynamically: ```bash helm upgrade arc-controller \ oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller \ --install \ --namespace arc-systems \ --create-namespace \ --set key1=value1 \ --set key2=value2 \ # ... (all values from the values: section) ``` 4. **Executes** the command **Source**: `src/tools/hybrid-tools.ts` lines 305-450 ## Proposed Solutions ### Solution 1: Enhanced Output Messages (Recommended) Update the output in `src/tools/hybrid-tools.ts` (lines 102-119) to: ```typescript } else { response += '## 📋 Step 3: Configuration Generated (Not Applied)\n\n'; response += `⚠️ **Configuration generated but NOT applied to cluster** (--apply false)\n\n`; response += `### 📄 What was created?\n\n`; response += `The configuration file at \`${result.configPath}\` contains:\n`; response += `- **Chart information**: Repository URL and version\n`; response += `- **Release details**: Name and namespace\n`; response += `- **Helm values**: Custom configuration (currently empty, but you can add values)\n\n`; response += `### 🔄 How to apply:\n\n`; response += `**Option 1: Use the apply tool (Recommended)**\n`; response += `\`\`\`\n`; response += `#arc_apply_config --configType controller\n`; response += `\`\`\`\n`; response += `This command reads your config file and executes:\n`; response += `\`\`\`bash\n`; response += `helm upgrade arc-controller \\\n`; response += ` oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller \\\n`; response += ` --install \\\n`; response += ` --namespace ${namespace} \\\n`; response += ` --create-namespace`; if (version !== 'latest') { response += ` \\\n --version ${version}`; } response += `\n # Plus any --set flags from the values section\n`; response += `\`\`\`\n\n`; response += `**Option 2: Manual installation (bypasses config file)**\n`; response += `If you want to install without using the generated config:\n`; response += `\`\`\`bash\n`; response += `helm install arc-controller \\\n`; response += ` oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller \\\n`; response += ` --namespace ${namespace} \\\n`; response += ` --create-namespace`; if (version !== 'latest') { response += ` \\\n --version ${version}`; } response += `\n\`\`\`\n`; response += `⚠️ **Note**: This uses default settings and ignores any custom values in your config file.\n\n`; response += `💡 **Tip**: You can edit \`${result.configPath}\` to add custom Helm values before applying.\n`; } ``` ### Solution 2: Example Configuration with Values Create an example showing how users can customize `controller.yaml`: **File**: `configs/controller.yaml` (with custom values) ```yaml chart: repository: oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller name: gha-runner-scale-set-controller version: latest release: name: arc-controller namespace: arc-systems createNamespace: true values: # Example custom values - these get translated to --set flags replicaCount: 2 resources: limits: cpu: 500m memory: 512Mi requests: cpu: 250m memory: 256Mi nodeSelector: kubernetes.io/os: linux metadata: managedBy: arc-config-mcp mode: hybrid generatedAt: '2025-10-31T19:27:10.002Z' ``` **When applied**, `#arc_apply_config` translates this to: ```bash helm upgrade arc-controller \ oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller \ --install \ --namespace arc-systems \ --create-namespace \ --set replicaCount=2 \ --set resources.limits.cpu=500m \ --set resources.limits.memory=512Mi \ --set resources.requests.cpu=250m \ --set resources.requests.memory=256Mi \ --set nodeSelector.kubernetes\.io/os=linux ``` ### Solution 3: Comprehensive Code Documentation Add detailed comments to `src/services/hybrid-deployment.ts`: ```typescript /** * Hybrid Deployment Service * * WORKFLOW OVERVIEW: * ================== * * 1. GENERATE: Create a config file (controller.yaml or runner-set-{name}.yaml) * - Contains: chart info, release details, Helm values, metadata * - Location: configs/ directory (version controlled) * - Purpose: Declarative configuration that can be reviewed, edited, and versioned * * 2. REVIEW/EDIT (Optional): * - Users can edit the generated YAML to add custom Helm values * - Example: Add resource limits, node selectors, tolerations, etc. * - All values in the `values:` section become --set arguments * * 3. APPLY: Use arc_apply_config tool * - Reads the config file * - Extracts chart, release, and values information * - Builds dynamic Helm command with all --set flags * - Executes helm upgrade --install * * CONFIG FILE STRUCTURE: * ====================== * chart: # Where to get the Helm chart * repository: # OCI registry URL * name: # Chart name * version: # Chart version or 'latest' * * release: # How to install it * name: # Helm release name * namespace: # K8s namespace * createNamespace: boolean * * values: # Custom Helm values (gets flattened to --set arguments) * key1: value1 # Becomes: --set key1=value1 * nested: * key2: value2 # Becomes: --set nested.key2=value2 * * metadata: # Tracking information (not used by Helm) * managedBy: # Tool identifier * mode: # Deployment mode * generatedAt: # Timestamp * * BENEFITS: * ========= * - Version control: Config changes tracked in Git * - Audit trail: Git history shows who changed what and when * - Review process: PRs for infrastructure changes * - Rollback: Git revert to previous configuration * - Team collaboration: Multiple people can propose changes * - Drift detection: Compare repo config vs. cluster state */ ``` ## Implementation Checklist - [ ] **Update output messages** in `src/tools/hybrid-tools.ts` (lines 102-119) - [ ] **Add example config** to `examples/controller-with-values.yaml` - [ ] **Document workflow** with comprehensive comments in `src/services/hybrid-deployment.ts` - [ ] **Create quick-start guide** showing: generate → edit → apply workflow - [ ] **Update README** with clear examples of the hybrid workflow - [ ] **Rebuild** the project: `npm run build` - [ ] **Rebuild Docker image** with changes - [ ] **Test** the updated output messages ## Benefits of These Changes ### For Users: 1. **Clarity**: Understand exactly what the config file contains and how it's used 2. **Confidence**: Know which command actually uses their configuration 3. **Transparency**: See the actual Helm command that will be executed 4. **Guidance**: Clear path for customizing configurations ### For the Project: 1. **Better UX**: Reduced confusion and support questions 2. **Adoption**: Users more likely to use the hybrid workflow correctly 3. **Trust**: Transparent about what the tool does 4. **Documentation**: Self-documenting through clear output messages ## Example User Journey (After Improvements) ### Step 1: Generate Config ```bash #arc_install_controller_hybrid --apply false ``` **Output**: ```markdown ## 📋 Step 3: Configuration Generated (Not Applied) ⚠️ **Configuration generated but NOT applied to cluster** (--apply false) ### 📄 What was created? The configuration file at `configs/controller.yaml` contains: - **Chart information**: Repository URL and version - **Release details**: Name and namespace - **Helm values**: Custom configuration (currently empty, but you can add values) ### 🔄 How to apply: **Option 1: Use the apply tool (Recommended)** ``` #arc_apply_config --configType controller ``` This command reads your config file and executes: ```bash helm upgrade arc-controller \ oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller \ --install \ --namespace arc-systems \ --create-namespace # Plus any --set flags from the values section ``` **Option 2: Manual installation (bypasses config file)** If you want to install without using the generated config: ```bash helm install arc-controller \ oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller \ --namespace arc-systems \ --create-namespace ``` ⚠️ **Note**: This uses default settings and ignores any custom values in your config file. 💡 **Tip**: You can edit `configs/controller.yaml` to add custom Helm values before applying. ``` ### Step 2: User edits config (optional) ```yaml # configs/controller.yaml values: replicaCount: 2 resources: limits: memory: 512Mi ``` ### Step 3: Apply ```bash #arc_apply_config --configType controller ``` **Confidence**: User knows exactly what will happen because the output clearly explained it! ## Related Files - **Main logic**: `src/services/hybrid-deployment.ts` - **Output messages**: `src/tools/hybrid-tools.ts` lines 17-130 - **Apply logic**: `src/tools/hybrid-tools.ts` lines 305-510 - **Examples**: `examples/` directory - **Documentation**: `docs/WORKFLOW_GUIDE.md` ## Next Steps 1. Review this document with the team 2. Prioritize which solutions to implement first 3. Implement changes incrementally 4. Test with real users 5. Gather feedback and iterate --- **Key Takeaway**: The goal is to make users feel **confident** and **informed** about what the tool is doing, how their config files are used, and what commands will be executed. Transparency builds trust!