Docs/improve installation experience (#117)

* Fix MCP configuration format - use array instead of object

- Change from {command, args} object format to [command, flag, script] array format
- VS Code MCP installer expects array of command arguments instead of object
- Fixes 'Failed to parse scanned MCP servers: [object Object]' error
- Update all 8 installation links to use proper array format
- Should resolve VS Code MCP integration parsing issues

* Fix MCP configuration: use proper object format with type field

- Revert to {type, command, args} object format instead of array
- Include explicit 'type': 'stdio' field as required by VS Code MCP
- Fix VS Code showing 'Type: http' instead of 'stdio' in installation dialog
- Ensure proper JSON structure for VS Code MCP server configuration
- Update all 8 installation links with correct MCP server format

* fix: redesign installation to create persistent MCP configurations

- Replace temporary download-and-run URLs with proper setup approach
- Add automated setup scripts for Windows/macOS/Linux
- Provide direct download links for all platforms
- Include comprehensive manual configuration examples
- Update getting started guide with clearer troubleshooting tips

This addresses the fundamental issue where 1-click installation was creating
temporary execution commands instead of permanent .vscode/mcp.json configurations.

* docs: improve installation experience and fix linting issues

- Fix markdown linting issues (line length, emphasis as headings, bare URLs)
- Add user-level MCP server configuration option for persistent GitHub Copilot setup
- Improve readability with proper line wrapping and formatting
- Add both workspace-specific and global configuration options for flexibility

* Update README.md

Co-authored-by: Copilot <[email protected]>

* Update README.md

Co-authored-by: Copilot <[email protected]>

---------

Co-authored-by: Copilot <[email protected]>

Author: pavneeta

README.md

@@ -1,6 +1,10 @@
-# AKS-MCP
+# AKS-MCP
 
-The AKS-MCP is a Model Context Protocol (MCP) server that enables AI assistants to interact with Azure Kubernetes Service (AKS) clusters. It serves as a bridge between AI tools (like GitHub Copilot, Claude, and other MCP-compatible AI assistants) and AKS, translating natural language requests into AKS operations and returning the results in a format the AI tools can understand.
+The AKS-MCP is a Model Context Protocol (MCP) server that enables AI assistants
+to interact with Azure Kubernetes Service (AKS) clusters. It serves as a bridge
+between AI tools (like GitHub Copilot, Claude, and other MCP-compatible AI
+assistants) and AKS, translating natural language requests into AKS operations
+and returning the results in a format the AI tools can understand.
 
 It allows AI tools to:
 
@@ -10,11 +14,16 @@ It allows AI tools to:
 
 ## How it works
 
-AKS-MCP connects to Azure using the Azure SDK and provides a set of tools that AI assistants can use to interact with AKS resources. It leverages the Model Context Protocol (MCP) to facilitate this communication, enabling AI tools to make API calls to Azure and interpret the responses.
+AKS-MCP connects to Azure using the Azure SDK and provides a set of tools that
+AI assistants can use to interact with AKS resources. It leverages the Model
+Context Protocol (MCP) to facilitate this communication, enabling AI tools to
+make API calls to Azure and interpret the responses.
 
 ## Available Tools
 
-The AKS-MCP server provides consolidated tools for interacting with AKS clusters. These tools have been designed to provide comprehensive functionality through unified interfaces:
+The AKS-MCP server provides consolidated tools for interacting with AKS
+clusters. These tools have been designed to provide comprehensive functionality
+through unified interfaces:
 
 <details>
 <summary>AKS Cluster Management</summary>
@@ -24,6 +33,7 @@ The AKS-MCP server provides consolidated tools for interacting with AKS clusters
 Unified tool for managing Azure Kubernetes Service (AKS) clusters and related operations.
 
 **Available Operations:**
+
 - **Read-Only** (all access levels):
   - `show`: Show cluster details
   - `list`: List clusters in subscription/resource group
@@ -59,6 +69,7 @@ Unified tool for managing Azure Kubernetes Service (AKS) clusters and related op
 Unified tool for getting Azure network resource information used by AKS clusters.
 
 **Available Resource Types:**
+
 - `all`: Get information about all network resources
 - `vnet`: Virtual Network information
 - `subnet`: Subnet information  
@@ -77,21 +88,25 @@ Unified tool for getting Azure network resource information used by AKS clusters
 Unified tool for Azure monitoring and diagnostics operations for AKS clusters.
 
 **Available Operations:**
+
 - `metrics`: List metric values for resources
 - `resource_health`: Retrieve resource health events for AKS clusters
 - `app_insights`: Execute KQL queries against Application Insights telemetry data
 - `diagnostics`: Check if AKS cluster has diagnostic settings configured
-- `control_plane_logs`: Query AKS control plane logs with safety constraints and time range validation
+- `control_plane_logs`: Query AKS control plane logs with safety constraints
+  and time range validation
 
 </details>
 
 <details>
 <summary>Compute Resources</summary>
 
 **Tool:** `get_aks_vmss_info`
+
 - Get detailed VMSS configuration for node pools in the AKS cluster
 
 **Tool:** `az_vmss_run-command_invoke` *(readwrite/admin only)*
+
 - Execute commands on Virtual Machine Scale Set instances
 
 </details>
@@ -104,28 +119,35 @@ Unified tool for Azure monitoring and diagnostics operations for AKS clusters.
 Comprehensive Azure Fleet management for multi-cluster scenarios.
 
 **Available Operations:**
+
 - **Fleet Operations**: list, show, create, update, delete, get-credentials
 - **Member Operations**: list, show, create, update, delete
 - **Update Run Operations**: list, show, create, start, stop, delete
 - **Update Strategy Operations**: list, show, create, delete
 - **ClusterResourcePlacement Operations**: list, show, get, create, delete
 
-Supports both Azure Fleet management and Kubernetes ClusterResourcePlacement CRD operations.
+Supports both Azure Fleet management and Kubernetes ClusterResourcePlacement
+CRD operations.
 
 </details>
 
 <details>
 <summary>Diagnostic Detectors</summary>
 
 **Tool:** `list_detectors`
+
 - List all available AKS cluster detectors
 
 **Tool:** `run_detector`
+
 - Run a specific AKS diagnostic detector
 
 **Tool:** `run_detectors_by_category`
+
 - Run all detectors in a specific category
-- **Categories**: Best Practices, Cluster and Control Plane Availability and Performance, Connectivity Issues, Create/Upgrade/Delete and Scale, Deprecations, Identity and Security, Node Health, Storage
+- **Categories**: Best Practices, Cluster and Control Plane Availability and
+  Performance, Connectivity Issues, Create/Upgrade/Delete and Scale,
+  Deprecations, Identity and Security, Node Health, Storage
 
 </details>
 
@@ -137,30 +159,37 @@ Supports both Azure Fleet management and Kubernetes ClusterResourcePlacement CRD
 Retrieve and manage Azure Advisor recommendations for AKS clusters.
 
 **Available Operations:**
+
 - `list`: List recommendations with filtering options
 - `report`: Generate recommendation reports
-- **Filter Options**: resource_group, cluster_names, category (Cost, HighAvailability, Performance, Security), severity (High, Medium, Low)
+- **Filter Options**: resource_group, cluster_names, category (Cost,
+  HighAvailability, Performance, Security), severity (High, Medium, Low)
 
 </details>
 
 <details>
 <summary>Kubernetes Tools</summary>
 
-*Note: kubectl commands are available with all access levels. Additional tools require explicit enablement via `--additional-tools`*
+*Note: kubectl commands are available with all access levels. Additional tools
+require explicit enablement via `--additional-tools`*
 
 **kubectl Commands (Read-Only):**
+
 - `kubectl_get`, `kubectl_describe`, `kubectl_explain`, `kubectl_logs`
 - `kubectl_api-resources`, `kubectl_api-versions`, `kubectl_diff`
 - `kubectl_cluster-info`, `kubectl_top`, `kubectl_events`, `kubectl_auth`
 
 **kubectl Commands (Read-Write/Admin):**
-- `kubectl_create`, `kubectl_delete`, `kubectl_apply`, `kubectl_expose`, `kubectl_run`
+
+- `kubectl_create`, `kubectl_delete`, `kubectl_apply`, `kubectl_expose`,
+  `kubectl_run`
 - `kubectl_set`, `kubectl_rollout`, `kubectl_scale`, `kubectl_autoscale`
 - `kubectl_label`, `kubectl_annotate`, `kubectl_patch`, `kubectl_replace`
 - `kubectl_cp`, `kubectl_exec`, `kubectl_cordon`, `kubectl_uncordon`
 - `kubectl_drain`, `kubectl_taint`, `kubectl_certificate`
 
 **Additional Tools (Optional):**
+
 - `helm`: Helm package manager (requires `--additional-tools helm`)
 - `cilium`: Cilium CLI for eBPF networking (requires `--additional-tools cilium`)
 
@@ -171,9 +200,11 @@ Retrieve and manage Azure Advisor recommendations for AKS clusters.
 
 **Tool:** `inspektor_gadget` *(requires `--additional-tools inspektor-gadget`)*
 
-Real-time observability tool for Azure Kubernetes Service (AKS) clusters using eBPF.
+Real-time observability tool for Azure Kubernetes Service (AKS) clusters using
+eBPF.
 
 **Available Actions:**
+
 - `deploy`: Deploy Inspektor Gadget to cluster
 - `undeploy`: Remove Inspektor Gadget from cluster
 - `is_deployed`: Check deployment status
@@ -184,6 +215,7 @@ Real-time observability tool for Azure Kubernetes Service (AKS) clusters using e
 - `list_gadgets`: List available gadgets
 
 **Available Gadgets:**
+
 - `observe_dns`: Monitor DNS requests and responses
 - `observe_tcp`: Monitor TCP connections
 - `observe_file_open`: Monitor file system operations
@@ -200,6 +232,7 @@ Real-time observability tool for Azure Kubernetes Service (AKS) clusters using e
 ### Prerequisites
 
 1. Set up [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) and authenticate:
+
    ```bash
    az login
    ```
@@ -208,35 +241,62 @@ Real-time observability tool for Azure Kubernetes Service (AKS) clusters using e
 
 ### VS Code with GitHub Copilot (Recommended)
 
-#### 🚀 1-Click Installation
+#### 🚀 Quick Setup Guide
+
+#### Step 1: Download the Binary
+
+Choose your platform and download the latest AKS-MCP binary:
+
+| Platform | Architecture | Download Link |
+|----------|-------------|---------------|
+| **Windows** | AMD64 | [📥 aks-mcp-windows-amd64.exe](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-windows-amd64.exe) |
+| | ARM64 | [📥 aks-mcp-windows-arm64.exe](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-windows-arm64.exe) |
+| **macOS** | Intel (AMD64) | [📥 aks-mcp-darwin-amd64](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-darwin-amd64) |
+| | Apple Silicon (ARM64) | [📥 aks-mcp-darwin-arm64](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-darwin-arm64) |
+| **Linux** | AMD64 | [📥 aks-mcp-linux-amd64](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-linux-amd64) |
+| | ARM64 | [📥 aks-mcp-linux-arm64](https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-linux-arm64) |
+
+#### Step 2: Configure VS Code
+
+After downloading, create a `.vscode/mcp.json` file in your workspace root with the path to your downloaded binary.
+
+##### Option A: Automated Setup Script
 
-Install AKS-MCP server directly into VS Code with one click:
+For quick setup, you can use these one-liner scripts that download the binary
+and create the configuration:
 
-[![Install AKS-MCP Server](https://img.shields.io/badge/Install-AKS--MCP%20Server-blue?style=for-the-badge&logo=visual-studio-code)](https://vscode.dev/redirect/mcp/install?name=AKS-MCP%20Server&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22bash%22%2C%22args%22%3A%5B%22-c%22%2C%22curl%20-sL%20https%3A%2F%2Fgithub.com%2FAzure%2Faks-mcp%2Freleases%2Flatest%2Fdownload%2Faks-mcp-linux-amd64%20-o%20aks-mcp%20%26%26%20chmod%20%2Bx%20aks-mcp%20%26%26%20.%2Faks-mcp%20--transport%20stdio%22%5D%7D)
+*Windows (PowerShell):*
 
-> **✨ Seamless Installation**: This automatically downloads the latest AKS-MCP binary from GitHub releases and configures it in VS Code. After installation, restart VS Code to activate the server.
+```powershell
+# Download binary and create VS Code configuration
+mkdir -p .vscode ; Invoke-WebRequest -Uri "https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-windows-amd64.exe" -OutFile "aks-mcp.exe" ; @{servers=@{"aks-mcp-server"=@{type="stdio";command="$PWD\aks-mcp.exe";args=@("--transport","stdio")}}} | ConvertTo-Json -Depth 3 | Out-File ".vscode/mcp.json" -Encoding UTF8
+```
+
+*macOS/Linux (Bash):*
+
+```bash
+# Download binary and create VS Code configuration  
+mkdir -p .vscode && curl -sL https://github.com/Azure/aks-mcp/releases/latest/download/aks-mcp-linux-amd64 -o aks-mcp && chmod +x aks-mcp && echo '{"servers":{"aks-mcp-server":{"type":"stdio","command":"'$PWD'/aks-mcp","args":["--transport","stdio"]}}}' > .vscode/mcp.json
+```
 
-#### 💻 Platform-Specific 1-Click Installation
+##### Option B: Manual Configuration
 
-| Platform | Architecture | 1-Click Installation |
-|----------|-------------|---------------------|
-| **Windows** | AMD64 | [![Install for Windows x64](https://img.shields.io/badge/Install%20for-Windows%20x64-0078d4?style=for-the-badge&logo=windows)](https://vscode.dev/redirect/mcp/install?name=AKS-MCP%20Server&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22powershell%22%2C%22args%22%3A%5B%22-c%22%2C%22Invoke-WebRequest%20-Uri%20https%3A%2F%2Fgithub.com%2FAzure%2Faks-mcp%2Freleases%2Flatest%2Fdownload%2Faks-mcp-windows-amd64.exe%20-OutFile%20aks-mcp.exe%3B%20.%2Faks-mcp.exe%20--transport%20stdio%22%5D%7D) |
-| | ARM64 | [![Install for Windows ARM64](https://img.shields.io/badge/Install%20for-Windows%20ARM64-0078d4?style=for-the-badge&logo=windows)](https://vscode.dev/redirect/mcp/install?name=AKS-MCP%20Server&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22powershell%22%2C%22args%22%3A%5B%22-c%22%2C%22Invoke-WebRequest%20-Uri%20https%3A%2F%2Fgithub.com%2FAzure%2Faks-mcp%2Freleases%2Flatest%2Fdownload%2Faks-mcp-windows-arm64.exe%20-OutFile%20aks-mcp.exe%3B%20.%2Faks-mcp.exe%20--transport%20stdio%22%5D%7D) |
-| **macOS** | Intel (AMD64) | [![Install for macOS Intel](https://img.shields.io/badge/Install%20for-macOS%20Intel-000000?style=for-the-badge&logo=apple)](https://vscode.dev/redirect/mcp/install?name=AKS-MCP%20Server&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22bash%22%2C%22args%22%3A%5B%22-c%22%2C%22curl%20-sL%20https%3A%2F%2Fgithub.com%2FAzure%2Faks-mcp%2Freleases%2Flatest%2Fdownload%2Faks-mcp-darwin-amd64%20-o%20aks-mcp%20%26%26%20chmod%20%2Bx%20aks-mcp%20%26%26%20.%2Faks-mcp%20--transport%20stdio%22%5D%7D) |
-| | Apple Silicon (ARM64) | [![Install for macOS M1/M2](https://img.shields.io/badge/Install%20for-macOS%20M1%2FM2-000000?style=for-the-badge&logo=apple)](https://vscode.dev/redirect/mcp/install?name=AKS-MCP%20Server&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22bash%22%2C%22args%22%3A%5B%22-c%22%2C%22curl%20-sL%20https%3A%2F%2Fgithub.com%2FAzure%2Faks-mcp%2Freleases%2Flatest%2Fdownload%2Faks-mcp-darwin-arm64%20-o%20aks-mcp%20%26%26%20chmod%20%2Bx%20aks-mcp%20%26%26%20.%2Faks-mcp%20--transport%20stdio%22%5D%7D) |
-| **Linux** | AMD64 | [![Install for Linux x64](https://img.shields.io/badge/Install%20for-Linux%20x64-FCC624?style=for-the-badge&logo=linux&logoColor=black)](https://vscode.dev/redirect/mcp/install?name=AKS-MCP%20Server&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22bash%22%2C%22args%22%3A%5B%22-c%22%2C%22curl%20-sL%20https%3A%2F%2Fgithub.com%2FAzure%2Faks-mcp%2Freleases%2Flatest%2Fdownload%2Faks-mcp-linux-amd64%20-o%20aks-mcp%20%26%26%20chmod%20%2Bx%20aks-mcp%20%26%26%20.%2Faks-mcp%20--transport%20stdio%22%5D%7D) |
-| | ARM64 | [![Install for Linux ARM64](https://img.shields.io/badge/Install%20for-Linux%20ARM64-FCC624?style=for-the-badge&logo=linux&logoColor=black)](https://vscode.dev/redirect/mcp/install?name=AKS-MCP%20Server&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22bash%22%2C%22args%22%3A%5B%22-c%22%2C%22curl%20-sL%20https%3A%2F%2Fgithub.com%2FAzure%2Faks-mcp%2Freleases%2Flatest%2Fdownload%2Faks-mcp-linux-arm64%20-o%20aks-mcp%20%26%26%20chmod%20%2Bx%20aks-mcp%20%26%26%20.%2Faks-mcp%20--transport%20stdio%22%5D%7D) |
+> **✨ Simple Setup**: Download the binary for your platform, then use the manual configuration below to set up the MCP server in VS Code.
 
 #### Manual VS Code Configuration
 
-Alternatively, create a `.vscode/mcp.json` file in your workspace:
+You can configure the AKS-MCP server in two ways:
+
+**1. Workspace-specific configuration** (recommended for project-specific usage):
+
+Create a `.vscode/mcp.json` file in your workspace with the path to your downloaded binary:
 
 ```json
 {
   "servers": {
     "aks-mcp-server": {
       "type": "stdio",
-      "command": "<path of binary aks-mcp>",
+      "command": "<enter the file path>",
       "args": [
         "--transport", "stdio"
       ]
@@ -245,18 +305,39 @@ Alternatively, create a `.vscode/mcp.json` file in your workspace:
 }
 ```
 
-#### 🚀 Getting Started with VS Code
+**2. User-level configuration** (persistent across all workspaces):
+
+For a persistent configuration that works across all your VS Code workspaces, add the MCP server to your VS Code user settings:
+
+1. Open VS Code Settings (Ctrl+, or Cmd+,)
+2. Search for "mcp" in the settings
+3. Add the following to your User Settings JSON:
+
+```json
+{
+  "github.copilot.chat.mcp.servers": {
+    "aks-mcp-server": {
+      "type": "stdio",
+      "command": "<enter the file path>",
+      "args": [
+        "--transport", "stdio"
+      ]
+    }
+  }
+}
+```
 
-After installing the AKS-MCP server:
+#### Step 3: Load the AKS-MCP server tools to Github Copilot
 
-1. **Restart VS Code** - Close and reopen VS Code to load the new MCP server configuration
+1. If running on an older version of VS Code: restart VS Code i.e. close and
+   reopen VS Code to load the new MCP server configuration.
 2. Open GitHub Copilot in VS Code and [switch to Agent mode](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode)
-3. Click the **Tools** button to view available tools
+3. Click the **Tools** button or run /list in the Github Copilot window to see the list of available tools
 4. You should see the AKS-MCP tools in the list
 5. Try a prompt like: *"List all my AKS clusters in subscription xxx"*
 6. The agent will automatically use AKS-MCP tools to complete your request
 
-> **💡 Tip**: If you don't see the AKS-MCP tools after restarting, check the VS Code output panel for any MCP server connection errors.
+> **💡 Tip**: If you don't see the AKS-MCP tools after restarting, check the VS Code output panel for any MCP server connection errors and verify your binary path in `.vscode/mcp.json`.
 
 **Note**: Ensure you have authenticated with Azure CLI (`az login`) for the server to access your Azure resources.