vcluster-yaml-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,292 @@
+# vCluster YAML MCP Server
+
+A Model Context Protocol (MCP) server that lets AI assistants query and validate [vCluster](https://github.com/loft-sh/vcluster) YAML configurations directly from GitHub.
+
+## What Does It Do?
+
+This MCP server provides AI assistants with tools to:
+- Query vCluster configuration options and schemas
+- Validate YAML configurations
+- Search for specific settings using natural language
+- Query any version with explicit version parameters (stateless)
+- Extract validation rules from comments
+
+**Key feature:** No local files needed. All data is fetched live from the vCluster GitHub repository.
+
+## How It Works
+
+The server uses the GitHub API to fetch vCluster YAML configurations, schemas, and documentation directly from the source:
+
+1. **GitHub as Source of Truth**: Queries `github.com/loft-sh/vcluster` repository
+2. **Stateless Version Queries**: Every tool accepts an optional `version` parameter (e.g., `v0.19.0`, `main`)
+3. **Parallel Version Support**: Query multiple versions simultaneously without state conflicts
+4. **Live Data**: Always fetches the latest configuration for the requested version
+5. **Smart Caching**: 15-minute in-memory cache to avoid overloading GitHub API
+
+```mermaid
+graph LR
+    A[Claude/AI] --> B[MCP Server]
+    B --> C[GitHub API]
+    C --> D[vCluster Repository]
+    B --> E[Parse YAML/JSON]
+    E --> F[Return Structured Data]
+    F --> A
+```
+
+## Installation
+
+### Option 1: Local (stdio)
+
+Run the server locally via npx:
+
+```json
+{
+  "mcpServers": {
+    "vcluster-yaml": {
+      "command": "npx",
+      "args": ["-y", "vcluster-yaml-mcp-server"]
+    }
+  }
+}
+```
+
+### Option 2: Remote (HTTP)
+
+Use the public instance (always running latest version):
+
+```json
+{
+  "mcpServers": {
+    "vcluster-yaml": {
+      "type": "http",
+      "url": "https://vcluster-yaml.cloudrumble.net/mcp"
+    }
+  }
+}
+```
+
+## Command-Line Interface
+
+The package also provides a standalone CLI for quick queries and validation without MCP setup:
+
+```bash
+# Quick start with npx (no installation)
+npx -y vcluster-yaml-mcp-server vcluster-yaml query sync --format table
+
+# Or install globally
+npm install -g vcluster-yaml-mcp-server
+vcluster-yaml query sync --format table
+```
+
+📖 **[Full CLI Documentation →](docs/CLI.md)**
+
+## Available Tools
+
+### Version Discovery
+
+**list-versions** - Browse all available vCluster versions
+```javascript
+// Returns tags (releases) and branches
+// Example output: v0.19.0, v0.20.0, main, etc.
+```
+
+### Configuration Queries
+
+All query tools accept an optional `version` parameter (defaults to "main"):
+
+**smart-query** - Universal search using dot notation or natural language
+```javascript
+smart-query --query="controlPlane.ingress.enabled" --version="v0.19.0"
+smart-query --query="namespace syncing" --version="main"
+smart-query --query="etcd"  // Defaults to "main"
+```
+
+**Output Format (kubectl-style):**
+```
+Found 4 matches for "replicas" in chart/values.yaml (v0.24.0)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+MATCH: controlPlane.statefulSet.highAvailability.replicas
+TYPE:  integer
+VALUE: 1
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+MATCH: controlPlane.coredns.deployment.replicas
+TYPE:  integer
+VALUE: 1
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+MATCH: controlPlane.statefulSet.highAvailability
+TYPE:  object
+
+FIELDS:
+  replicas <integer>
+    value: 1
+
+  leaseDuration <integer>
+    value: 60
+
+  renewDeadline <integer>
+    value: 40
+
+  retryPeriod <integer>
+    value: 15
+
+RELATED CONFIGS:
+  • controlPlane.statefulSet.resources - Resource limits for HA mode
+  • controlPlane.backingStore.etcd.deploy.statefulSet.highAvailability
+```
+
+**Features:**
+- ✅ **Structured output** - kubectl-style format
+- ✅ **Type information** - Every value shows its type (integer, string, boolean, array, object)
+- ✅ **Relevance ranking** - Exact matches appear first, results sorted by relevance
+- ✅ **Related configs** - Suggests commonly configured fields together
+- ✅ **Smart formatting** - Objects show structure, not full content dumps
+- ✅ **LLM-friendly** - Easy to parse and understand for AI assistants
+
+### Config Creation & Validation
+
+All validation tools accept an optional `version` parameter (defaults to "main"):
+
+**create-vcluster-config** - Create and validate configs in one step (PRIMARY TOOL)
+```javascript
+// Claude uses this when generating configs for you
+// Ensures every generated config is validated before you see it
+create-vcluster-config --yaml_content="<generated-yaml>" --description="Node sync config" --version="v0.24.0"
+
+// Returns:
+// ✅ Configuration validated successfully!
+// Version: v0.24.0
+// Section: sync
+// Validation time: 45ms
+//
+// ### Configuration:
+// [your YAML here]
+```
+
+**validate-config** - Validate existing YAML configs
+```javascript
+// Validate user-provided configs against specific version
+validate-config --content="<your-yaml>" --version="v0.24.0"
+
+// Validate files from GitHub
+validate-config --file="chart/values.yaml" --version="main"
+
+// Works with full configs or partial snippets (auto-detects section)
+// Returns: { valid: true/false, errors: [...], section: "...", version: "...", elapsed_ms: <100 }
+```
+
+**extract-validation-rules** - Get validation rules from YAML comments
+```javascript
+extract-validation-rules --section="controlPlane" --version="v0.24.0"
+// Returns: { rules, enums, dependencies, defaults }
+// Extracts constraints like "Valid values: a, b, c"
+```
+
+## Usage Examples
+
+### Interactive Config Creation (Primary Workflow)
+
+Ask Claude:
+> "Create a vCluster config with node sync enabled and etcd embedded"
+
+Claude will:
+1. Use `smart-query` or `extract-validation-rules` to research options
+2. Generate the YAML configuration
+3. **Automatically** call `create-vcluster-config` to validate
+4. Return validated, ready-to-use configuration
+
+**Why this works:** The `create-vcluster-config` tool forces Claude to validate every config it generates. You'll always get validated configs.
+
+### Validate User-Provided Configuration
+
+Ask Claude:
+> "Is this ingress configuration valid for vCluster v0.24?"
+> ```yaml
+> ingress:
+>   enabled: true
+>   host: "my-vcluster.example.com"
+> ```
+
+Claude will:
+1. Use `validate-config` with `--version="v0.24.0"` parameter
+2. Report any validation errors with specific paths
+3. Suggest fixes if needed
+
+### Explore vCluster Options
+
+Ask Claude:
+> "What high availability options are available in vCluster v0.19.0?"
+
+Claude will use:
+- `smart-query` with `--version="v0.19.0"` to find HA-related settings
+- No need to "switch" versions - query directly with version parameter
+
+### Compare Versions
+
+Ask Claude:
+> "How did the sync.fromHost configuration change between v0.19.0 and v0.20.0?"
+
+Claude will use:
+- `smart-query` with `--version="v0.19.0"` for first version
+- `smart-query` with `--version="v0.20.0"` for second version
+- Can query both versions in parallel (stateless design)
+
+## Token Optimization
+
+This server is designed for efficient token usage with the new kubectl-style format:
+
+| Tool | Tokens | Strategy | Performance |
+|------|--------|----------|-------------|
+| create-vcluster-config | ~300-600 | Validation + formatted response with emoji indicators | <100ms |
+| validate-config | ~200-500 | Fast validation, precise errors only | <100ms |
+| smart-query | ~800-1.5K | Structured output (was ~2K with JSON dumps), limits to 50 matches | <100ms |
+| extract-validation-rules | ~2-5K | Section-specific filtering, cache for knowledge base | <100ms |
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run locally (stdio)
+node src/index.js
+
+# Test with MCP Inspector
+npx @modelcontextprotocol/inspector node src/index.js
+# Open http://localhost:5173
+
+# Run tests
+npm test
+
+# Run HTTP server locally
+npm run start:http
+# Server runs on http://localhost:3000
+```
+
+## Technical Details
+
+- **SDK**: `@modelcontextprotocol/sdk` v1.20.1 (Streamable HTTP transport)
+- **Node**: >=18
+- **Transport**: Both stdio (local) and HTTP/SSE (remote)
+- **Dependencies**: `js-yaml` for parsing, `node-jq` for querying, `node-fetch` for GitHub API
+
+## Release Process
+
+This project uses automated CI/CD workflows for releases to npm, Docker Hub, and GitHub Releases.
+
+📖 **[Release Documentation →](docs/RELEASING.md)**
+
+## Links
+
+- [vCluster GitHub](https://github.com/loft-sh/vcluster)
+- [Model Context Protocol](https://modelcontextprotocol.io)
+- [MCP Specification](https://spec.modelcontextprotocol.io)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "vcluster-yaml-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for querying vcluster YAML configurations using jq",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "vcluster-yaml-mcp": "./src/index.js",
+    "vcluster-yaml": "./src/cli.js"
+  },
+  "files": [
+    "src/**/*.js",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "start:http": "node src/http-server.js",
+    "docker:build": "docker build -t piotrzan/vcluster-yaml-mcp-server:latest .",
+    "docker:push": "docker push piotrzan/vcluster-yaml-mcp-server:latest",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:perf": "vitest run tests/performance.test.js",
+    "test:ci": "vitest run tests/ci/",
+    "lint:workflows": "actionlint .github/workflows/*.yml"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.1",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "chalk": "^5.4.1",
+    "cli-table3": "^0.6.5",
+    "commander": "^13.0.0",
+    "express": "^4.18.2",
+    "js-yaml": "^4.1.0",
+    "node-fetch": "^3.3.2",
+    "node-jq": "^6.0.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
+    "execa": "^9.5.2",
+    "json-schema-library": "^10.3.0",
+    "jsonschema": "^1.5.0",
+    "strip-ansi": "^7.1.0",
+    "supertest": "^7.1.4",
+    "vitest": "^3.2.4",
+    "z-schema": "^6.0.2"
+  }
+}

package/src/cli-handlers.js

@@ -0,0 +1,290 @@
+/**
+ * CLI handlers that bridge CLI commands to underlying logic
+ * Reuses githubClient and validation logic from server.js
+ * Returns structured data for CLI formatters
+ */
+
+import yaml from 'js-yaml';
+import { githubClient } from './github.js';
+import { validateSnippet } from './snippet-validator.js';
+
+// Helper function to get the type of a value
+function getType(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (typeof value === 'object') return 'object';
+  if (typeof value === 'number') {
+    return Number.isInteger(value) ? 'integer' : 'number';
+  }
+  return typeof value;
+}
+
+// Helper function to rank search results
+function rankResult(item, searchTerm) {
+  const pathLower = item.path.toLowerCase();
+  const keyLower = item.key.toLowerCase();
+  let score = 0;
+
+  // Exact match
+  if (pathLower === searchTerm || keyLower === searchTerm) {
+    score += 100;
+  }
+
+  // Starts with search term
+  if (pathLower.startsWith(searchTerm) || keyLower.startsWith(searchTerm)) {
+    score += 50;
+  }
+
+  // Ends with search term
+  if (pathLower.endsWith(searchTerm) || keyLower.endsWith(searchTerm)) {
+    score += 40;
+  }
+
+  // Contains search term
+  if (pathLower.includes(searchTerm) || keyLower.includes(searchTerm)) {
+    score += 30;
+  }
+
+  // Prefer leaf nodes (actual values)
+  if (item.isLeaf) {
+    score += 10;
+  }
+
+  // Prefer shorter paths (more specific)
+  const pathDepth = item.path.split('.').length;
+  score -= pathDepth;
+
+  return score;
+}
+
+/**
+ * Handle query command
+ * Searches for configuration fields in vCluster YAML
+ */
+export async function handleQuery(query, options) {
+  const version = options.version || 'main';
+  const fileName = options.file || 'chart/values.yaml';
+
+  let yamlData;
+
+  try {
+    yamlData = await githubClient.getYamlContent(fileName, version);
+  } catch (error) {
+    return {
+      success: false,
+      error: `Could not load ${fileName} from GitHub (version: ${version}). Error: ${error.message}`,
+      metadata: {
+        query,
+        file: fileName,
+        version
+      }
+    };
+  }
+
+  const searchTerm = query.toLowerCase();
+  const results = [];
+
+  // Helper function to extract all paths and values
+  function extractInfo(obj, path = '') {
+    const info = [];
+    if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+      for (const [key, value] of Object.entries(obj)) {
+        const currentPath = path ? `${path}.${key}` : key;
+
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+          info.push({ path: currentPath, key, value, isLeaf: false });
+          info.push(...extractInfo(value, currentPath));
+        } else {
+          info.push({ path: currentPath, key, value, isLeaf: true });
+        }
+      }
+    }
+    return info;
+  }
+
+  const allInfo = extractInfo(yamlData);
+
+  // Support dot notation queries
+  const isDotNotation = searchTerm.includes('.');
+
+  if (isDotNotation) {
+    // Exact and partial dot notation matching
+    for (const item of allInfo) {
+      const pathLower = item.path.toLowerCase();
+
+      if (pathLower === searchTerm ||
+          pathLower.endsWith(searchTerm) ||
+          pathLower.includes(searchTerm)) {
+        results.push(item);
+      }
+    }
+  } else {
+    // Keyword-based search
+    const keywords = searchTerm.split(/\s+/);
+
+    for (const item of allInfo) {
+      const pathLower = item.path.toLowerCase();
+      const keyLower = item.key.toLowerCase();
+      const valueStr = JSON.stringify(item.value).toLowerCase();
+
+      const allKeywordsMatch = keywords.every(kw =>
+        pathLower.includes(kw) || keyLower.includes(kw) || valueStr.includes(kw)
+      );
+
+      if (allKeywordsMatch) {
+        results.push(item);
+      }
+    }
+  }
+
+  // Sort results by relevance
+  results.sort((a, b) => {
+    const scoreA = rankResult(a, searchTerm);
+    const scoreB = rankResult(b, searchTerm);
+    return scoreB - scoreA;
+  });
+
+  // Format results for CLI output
+  const formattedResults = results.slice(0, 50).map(item => ({
+    field: item.path,
+    value: item.value,
+    type: getType(item.value),
+    path: item.path,
+    description: '' // Could be enhanced with comments parsing
+  }));
+
+  return {
+    success: true,
+    results: formattedResults,
+    metadata: {
+      query,
+      file: fileName,
+      version,
+      resultCount: formattedResults.length,
+      totalMatches: results.length
+    }
+  };
+}
+
+/**
+ * Handle list-versions command
+ * Lists available vCluster versions from GitHub
+ */
+export async function handleListVersions() {
+  try {
+    const tags = await githubClient.getTags();
+
+    // Only show versions starting with 'v'
+    const versionTags = tags.filter(tag => tag.startsWith('v'));
+
+    // Always include main branch
+    const versions = ['main', ...versionTags];
+
+    return {
+      success: true,
+      versions,
+      metadata: {
+        totalCount: versions.length,
+        source: 'github'
+      }
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Failed to fetch versions: ${error.message}`,
+      versions: [],
+      metadata: {
+        totalCount: 0,
+        source: 'github'
+      }
+    };
+  }
+}
+
+/**
+ * Handle validate command
+ * Validates vCluster YAML configuration
+ */
+export async function handleValidate(content, options) {
+  const version = options.version || 'main';
+
+  // Validate YAML syntax first
+  let yamlData;
+  try {
+    yamlData = yaml.load(content);
+  } catch (error) {
+    return {
+      success: false,
+      valid: false,
+      errors: [
+        {
+          path: 'root',
+          message: error.message,
+          type: 'syntax'
+        }
+      ],
+      metadata: {
+        version,
+        contentLength: content.length
+      }
+    };
+  }
+
+  // Fetch schema for validation
+  try {
+    const schemaContent = await githubClient.getFileContent('chart/values.schema.json', version);
+    const fullSchema = JSON.parse(schemaContent);
+
+    // Use snippet validator
+    const result = validateSnippet(
+      content,
+      fullSchema,
+      version
+    );
+
+    if (result.valid) {
+      return {
+        success: true,
+        valid: true,
+        errors: [],
+        metadata: {
+          version,
+          contentLength: content.length
+        }
+      };
+    } else {
+      // Format errors for CLI
+      const errors = result.errors.map(err => ({
+        path: err.instancePath || err.dataPath || 'root',
+        message: err.message || 'Validation error',
+        type: err.keyword || 'validation'
+      }));
+
+      return {
+        success: true,
+        valid: false,
+        errors,
+        metadata: {
+          version,
+          contentLength: content.length
+        }
+      };
+    }
+  } catch (error) {
+    return {
+      success: false,
+      valid: false,
+      errors: [
+        {
+          path: 'root',
+          message: `Failed to load schema: ${error.message}`,
+          type: 'schema-error'
+        }
+      ],
+      metadata: {
+        version,
+        contentLength: content.length
+      }
+    };
+  }
+}