vcluster-yaml-mcp-server 1.0.7 → 1.0.9

package/src/tool-handlers.js

@@ -0,0 +1,384 @@
+/**
+ * Pure tool handler functions
+ * Each handler is a pure function: input → output (no side effects except I/O)
+ * Easy to test in isolation
+ */
+
+import { validateSnippet } from './snippet-validator.js';
+import { extractValidationRulesFromComments } from './validation-rules.js';
+
+// ============================================================================
+// RESPONSE BUILDERS (Pure Functions)
+// ============================================================================
+
+/**
+ * Build success response
+ * Pure function: same input → same output
+ */
+export function buildSuccessResponse(text) {
+  return {
+    content: [{ type: 'text', text }],
+    isError: false
+  };
+}
+
+/**
+ * Build error response
+ * Pure function: same input → same output
+ */
+export function buildErrorResponse(text) {
+  return {
+    content: [{ type: 'text', text }],
+    isError: true
+  };
+}
+
+// ============================================================================
+// FORMATTING (Pure Functions)
+// ============================================================================
+
+/**
+ * Format validation result to markdown
+ * Pure function - no side effects
+ */
+export function formatValidationResult(result, {yaml_content, description, version}) {
+  let response = '';
+
+  if (description) {
+    response += `## ${description}\n\n`;
+  }
+
+  if (result.valid) {
+    response += `✅ **Configuration validated successfully!**\n\n`;
+    response += `Version: ${version}\n`;
+    if (result.section) {
+      response += `Section: ${result.section}\n`;
+    }
+    response += `Validation time: ${result.elapsed_ms}ms\n\n`;
+    response += `### Configuration:\n\`\`\`yaml\n${yaml_content}\n\`\`\`\n`;
+  } else {
+    response += `❌ **Validation failed**\n\n`;
+
+    if (result.syntax_valid === false) {
+      response += `**Syntax Error:**\n${result.syntax_error}\n\n`;
+    } else if (result.errors && result.errors.length > 0) {
+      response += `**Validation Errors:**\n`;
+      result.errors.forEach((err, idx) => {
+        response += `${idx + 1}. **${err.path}**: ${err.message}\n`;
+      });
+      response += `\n`;
+    } else if (result.error) {
+      response += `**Error:** ${result.error}\n\n`;
+      if (result.hint) {
+        response += `**Hint:** ${result.hint}\n\n`;
+      }
+    }
+    response += `### Provided Configuration:\n\`\`\`yaml\n${yaml_content}\n\`\`\`\n`;
+  }
+
+  return response;
+}
+
+/**
+ * Format versions list
+ * Pure function
+ */
+export function formatVersionsList(versions) {
+  const display = versions.slice(0, 20);
+  const more = versions.length > 20 ? `... and ${versions.length - 20} more\n` : '';
+
+  return `Available vCluster versions:\n\n${display.map(v => `- ${v}`).join('\n')}\n${more}`;
+}
+
+/**
+ * Format query results
+ * Pure function
+ */
+export function formatQueryResults(results, { query, fileName, version, maxResults }) {
+  const limitedResults = results.slice(0, maxResults);
+  const hasMore = results.length > maxResults;
+
+  const formattedResults = limitedResults.map((item, idx) =>
+    formatMatch(item, idx, limitedResults.length)
+  );
+
+  return `Found ${results.length} match${results.length === 1 ? '' : 'es'} for "${query}" in ${fileName} (${version})\n\n` +
+         formattedResults.join('\n') +
+         (hasMore ? `\n\n... showing ${maxResults} of ${results.length} total matches` : '');
+}
+
+/**
+ * Format single match
+ * Pure function
+ */
+function formatMatch(item, idx, total) {
+  const prefix = `**[${idx + 1}/${total}]** \`${item.path}\``;
+
+  if (item.isLeaf) {
+    const valueStr = JSON.stringify(item.value, null, 2);
+    return `${prefix}\n\`\`\`\n${valueStr}\n\`\`\`\n`;
+  } else {
+    const keys = Object.keys(item.value || {});
+    return `${prefix}\n  Contains: ${keys.join(', ')}\n`;
+  }
+}
+
+/**
+ * Format no-match message
+ * Pure function
+ */
+export function formatNoMatches({ query, fileName, version, similarPaths, yamlData }) {
+  return `No matches found for "${query}" in ${fileName} (${version}).\n\n` +
+         (similarPaths.length > 0 ? `Similar paths:\n${similarPaths.map(p => `  - ${p}`).join('\n')}\n\n` : '') +
+         `Tips:\n` +
+         `  - Use dot notation: "controlPlane.ingress.enabled"\n` +
+         `  - Try broader terms: "${query.split('.')[0] || query.split(/\s+/)[0]}"\n` +
+         `  - Use extract-validation-rules for section details\n\n` +
+         `Top-level sections:\n${Object.keys(yamlData || {}).map(k => `  - ${k}`).join('\n')}`;
+}
+
+// ============================================================================
+// TOOL HANDLERS (Each is a pure async function)
+// ============================================================================
+
+/**
+ * Handle: create-vcluster-config
+ * Pure function except for I/O (githubClient)
+ */
+export async function handleCreateConfig(args, githubClient) {
+  const { yaml_content, description, version = 'main' } = args;
+
+  const schemaContent = await githubClient.getFileContent('chart/values.schema.json', version);
+  const fullSchema = JSON.parse(schemaContent);
+
+  const validationResult = validateSnippet(
+    yaml_content,
+    fullSchema,
+    version,
+    null  // Auto-detect section
+  );
+
+  const formattedResponse = formatValidationResult(validationResult, {
+    yaml_content,
+    description,
+    version
+  });
+
+  return {
+    content: [{ type: 'text', text: formattedResponse }],
+    isError: !validationResult.valid
+  };
+}
+
+/**
+ * Handle: list-versions
+ * Pure function except for I/O
+ */
+export async function handleListVersions(args, githubClient) {
+  const tags = await githubClient.getTags();
+  const versionTags = tags.filter(tag => tag.startsWith('v'));
+  const versions = ['main', ...versionTags];
+
+  const formatted = formatVersionsList(versions);
+  return buildSuccessResponse(formatted);
+}
+
+/**
+ * Handle: smart-query
+ * Pure function except for I/O
+ */
+export async function handleSmartQuery(args, githubClient) {
+  const { query, version = 'main', file = 'chart/values.yaml' } = args;
+
+  const yamlData = await githubClient.getYamlContent(file, version);
+  const searchTerm = query.toLowerCase();
+
+  // Extract all paths (pure function)
+  const allInfo = extractYamlInfo(yamlData);
+
+  // Search (pure function)
+  const results = searchYaml(allInfo, searchTerm);
+
+  // Handle no matches
+  if (results.length === 0) {
+    const similarPaths = findSimilarPaths(allInfo, searchTerm);
+    const formatted = formatNoMatches({ query, fileName: file, version, similarPaths, yamlData });
+    return buildSuccessResponse(formatted);
+  }
+
+  // Sort by relevance (pure function)
+  const sorted = sortByRelevance(results, searchTerm);
+
+  // Format results
+  const formatted = formatQueryResults(sorted, {
+    query,
+    fileName: file,
+    version,
+    maxResults: 50
+  });
+
+  return buildSuccessResponse(formatted);
+}
+
+/**
+ * Handle: extract-validation-rules
+ * Pure function except for I/O
+ */
+export async function handleExtractRules(args, githubClient) {
+  const { version = 'main', file = 'chart/values.yaml', section } = args;
+
+  const content = await githubClient.getFileContent(file, version);
+  const rules = extractValidationRulesFromComments(content, section);
+
+  return buildSuccessResponse(JSON.stringify(rules, null, 2));
+}
+
+/**
+ * Handle: validate-config
+ * Pure function except for I/O
+ */
+export async function handleValidateConfig(args, githubClient) {
+  const { version = 'main', content, file } = args;
+
+  // Get YAML content
+  let yamlContent;
+  if (content) {
+    yamlContent = content;
+  } else if (file) {
+    yamlContent = await githubClient.getFileContent(file, version);
+  } else {
+    yamlContent = await githubClient.getFileContent('chart/values.yaml', version);
+  }
+
+  // Get schema
+  const schemaContent = await githubClient.getFileContent('chart/values.schema.json', version);
+  const schema = JSON.parse(schemaContent);
+
+  // Validate (pure function)
+  const result = validateSnippet(yamlContent, schema, version, null);
+
+  return buildSuccessResponse(JSON.stringify(result, null, 2));
+}
+
+// ============================================================================
+// QUERY HELPERS (Pure Functions)
+// ============================================================================
+
+/**
+ * Extract all paths and values from YAML
+ * Pure function
+ */
+export function extractYamlInfo(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(...extractYamlInfo(value, currentPath));
+      } else {
+        info.push({ path: currentPath, key, value, isLeaf: true });
+      }
+    }
+  }
+
+  return info;
+}
+
+/**
+ * Search YAML info for query
+ * Pure function
+ */
+export function searchYaml(allInfo, searchTerm) {
+  const results = [];
+  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) {
+        results.push(item);
+      } else if (pathLower.endsWith(searchTerm)) {
+        results.push(item);
+      } else if (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);
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Find similar paths
+ * Pure function
+ */
+export function findSimilarPaths(allInfo, searchTerm) {
+  return allInfo
+    .filter(item => {
+      const pathParts = item.path.toLowerCase().split('.');
+      return pathParts.some(part => part.includes(searchTerm) || searchTerm.includes(part));
+    })
+    .slice(0, 5)
+    .map(item => item.path);
+}
+
+/**
+ * Sort results by relevance
+ * Pure function
+ */
+export function sortByRelevance(results, searchTerm) {
+  return [...results].sort((a, b) => {
+    const scoreA = rankResult(a, searchTerm);
+    const scoreB = rankResult(b, searchTerm);
+    return scoreB - scoreA;
+  });
+}
+
+/**
+ * Rank search result
+ * Pure function
+ */
+function rankResult(item, searchTerm) {
+  let score = 0;
+  const pathLower = item.path.toLowerCase();
+  const keyLower = item.key.toLowerCase();
+
+  // Exact path match (highest priority)
+  if (pathLower === searchTerm) score += 100;
+
+  // Exact key match
+  if (keyLower === searchTerm) score += 50;
+
+  // Path contains exact term
+  if (pathLower.includes(searchTerm)) score += 20;
+
+  // Key contains term
+  if (keyLower.includes(searchTerm)) score += 10;
+
+  // Leaf nodes are more relevant
+  if (item.isLeaf) score += 5;
+
+  return score;
+}

package/src/tool-registry.js

@@ -0,0 +1,45 @@
+/**
+ * Tool Registry (Strategy Pattern)
+ * Maps tool names to handler functions
+ * Complexity: 1 (just a lookup, no conditionals)
+ */
+
+import {
+  handleCreateConfig,
+  handleListVersions,
+  handleSmartQuery,
+  handleExtractRules,
+  handleValidateConfig,
+  buildErrorResponse
+} from './tool-handlers.js';
+
+/**
+ * Tool registry - Strategy pattern instead of switch statement
+ * Pure object mapping: tool name → handler function
+ */
+export const toolHandlers = {
+  'create-vcluster-config': handleCreateConfig,
+  'list-versions': handleListVersions,
+  'smart-query': handleSmartQuery,
+  'extract-validation-rules': handleExtractRules,
+  'validate-config': handleValidateConfig
+};
+
+/**
+ * Execute tool handler
+ * Complexity: 2 (single if statement)
+ * Pure function except for handler execution
+ */
+export async function executeToolHandler(toolName, args, githubClient) {
+  const handler = toolHandlers[toolName];
+
+  if (!handler) {
+    return buildErrorResponse(`Unknown tool: ${toolName}`);
+  }
+
+  try {
+    return await handler(args, githubClient);
+  } catch (error) {
+    return buildErrorResponse(`Error executing ${toolName}: ${error.message}`);
+  }
+}

package/src/validation-rules.js

@@ -0,0 +1,181 @@
+/**
+ * Validation Rules Extraction
+ * Pure functions for parsing YAML comments and extracting validation rules
+ */
+
+/**
+ * Extract validation rules from YAML comments
+ * Pure function except for complex internal state management
+ * Complexity: 23 → Will refactor separately
+ */
+export function extractValidationRulesFromComments(yamlContent, section) {
+  const lines = yamlContent.split('\n');
+  const rules = [];
+  const enums = {};
+  const dependencies = [];
+  const defaults = {};
+
+  let currentPath = [];
+  let currentComments = [];
+  let indentStack = [0];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmedLine = line.trim();
+
+    // Skip empty lines
+    if (!trimmedLine) {
+      currentComments = [];
+      continue;
+    }
+
+    // Collect comments
+    if (trimmedLine.startsWith('#')) {
+      const comment = trimmedLine.substring(1).trim();
+      if (comment && !comment.startsWith('#')) {
+        currentComments.push(comment);
+      }
+      continue;
+    }
+
+    // Parse YAML structure
+    const indent = line.search(/\S/);
+    const keyMatch = line.match(/^(\s*)([a-zA-Z0-9_-]+):\s*(.*)?$/);
+
+    if (keyMatch) {
+      const key = keyMatch[2];
+      const value = keyMatch[3];
+
+      // Update path based on indentation
+      while (indentStack.length > 1 && indent <= indentStack[indentStack.length - 1]) {
+        indentStack.pop();
+        currentPath.pop();
+      }
+
+      if (indent > indentStack[indentStack.length - 1]) {
+        indentStack.push(indent);
+      } else if (indent < indentStack[indentStack.length - 1]) {
+        while (indentStack.length > 1 && indent < indentStack[indentStack.length - 1]) {
+          indentStack.pop();
+          currentPath.pop();
+        }
+      } else {
+        currentPath.pop();
+      }
+
+      currentPath.push(key);
+      const fullPath = currentPath.join('.');
+
+      // Filter by section if specified
+      if (section && !fullPath.startsWith(section)) {
+        currentComments = [];
+        continue;
+      }
+
+      // Extract validation instructions from comments
+      if (currentComments.length > 0) {
+        const instructions = [];
+
+        for (const comment of currentComments) {
+          // Extract enum values (e.g., "Valid values: a, b, c")
+          const enumMatch = comment.match(/(?:valid values?|options?|choices?|possible values?):\s*(.+)/i);
+          if (enumMatch) {
+            const values = enumMatch[1].split(/[,;]/).map(v => v.trim()).filter(v => v);
+            enums[fullPath] = values;
+            instructions.push(`Valid values: ${values.join(', ')}`);
+          }
+
+          // Extract required dependencies
+          if (comment.match(/requires?|depends on|needs?/i)) {
+            dependencies.push(`${fullPath}: ${comment}`);
+            instructions.push(comment);
+          }
+
+          // Extract defaults
+          const defaultMatch = comment.match(/default(?:s)?\s*(?:is|:)?\s*(.+)/i);
+          if (defaultMatch) {
+            defaults[fullPath] = defaultMatch[1].trim();
+          }
+
+          // Extract validation rules
+          if (comment.match(/must|should|cannot|only|at least|minimum|maximum|required/i)) {
+            instructions.push(comment);
+          }
+
+          // Extract warnings
+          if (comment.match(/warning|note|important|deprecated/i)) {
+            instructions.push(`⚠️ ${comment}`);
+          }
+        }
+
+        if (instructions.length > 0) {
+          rules.push({
+            path: fullPath,
+            instructions: instructions,
+            originalComments: currentComments
+          });
+        }
+      }
+
+      currentComments = [];
+    }
+  }
+
+  // Generate AI validation instructions
+  const aiInstructions = {
+    summary: `Extracted ${rules.length} validation rules from YAML comments`,
+    rules: rules,
+    enums: enums,
+    dependencies: dependencies,
+    defaults: defaults,
+    instructions: generateAiValidationInstructions(rules, enums, dependencies)
+  };
+
+  return aiInstructions;
+}
+
+/**
+ * Generate AI validation instructions
+ * Pure function - formats rules into markdown
+ */
+function generateAiValidationInstructions(rules, enums, dependencies) {
+  let instructions = '### AI Validation Instructions\n\n';
+  instructions += 'Please validate the configuration using these rules extracted from comments:\n\n';
+
+  if (rules.length > 0) {
+    instructions += '#### Field-Specific Rules:\n';
+    rules.forEach(rule => {
+      instructions += `- **${rule.path}**:\n`;
+      rule.instructions.forEach(inst => {
+        instructions += `  - ${inst}\n`;
+      });
+    });
+    instructions += '\n';
+  }
+
+  if (Object.keys(enums).length > 0) {
+    instructions += '#### Enumeration Constraints:\n';
+    instructions += 'Ensure these fields only contain the specified values:\n';
+    Object.entries(enums).forEach(([field, values]) => {
+      instructions += `- ${field}: [${values.join(', ')}]\n`;
+    });
+    instructions += '\n';
+  }
+
+  if (dependencies.length > 0) {
+    instructions += '#### Dependencies to Check:\n';
+    dependencies.forEach(dep => {
+      instructions += `- ${dep}\n`;
+    });
+    instructions += '\n';
+  }
+
+  instructions += '#### Validation Approach:\n';
+  instructions += '1. Check if all enumeration constraints are satisfied\n';
+  instructions += '2. Verify all dependency requirements are met\n';
+  instructions += '3. Validate against the specific rules for each field\n';
+  instructions += '4. Flag any deprecated fields or configurations\n';
+  instructions += '5. Provide helpful suggestions for fixing any issues found\n';
+
+  return instructions;
+}