vcluster-yaml-mcp-server 0.1.0

package/src/cli.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+
+/**
+ * vCluster CLI - Standalone command-line interface
+ * Provides query, validate, and list-versions commands
+ * Wraps MCP server functionality with user-friendly CLI
+ */
+
+import { Command } from 'commander';
+import { handleQuery, handleListVersions, handleValidate } from './cli-handlers.js';
+import { formatOutput } from './formatters.js';
+
+const program = new Command();
+
+program
+  .name('vcluster-yaml')
+  .description('vCluster YAML configuration CLI')
+  .version('0.1.0');
+
+// Query command
+program
+  .command('query <query>')
+  .description('Search for vCluster configuration fields')
+  .option('--file <file>', 'Configuration file to search', 'chart/values.yaml')
+  .option('--version <version>', 'vCluster version or branch', 'main')
+  .option('-f, --format <format>', 'Output format (json, yaml, table)', 'json')
+  .action(async (query, options) => {
+    try {
+      // Validate format option
+      if (!['json', 'yaml', 'table'].includes(options.format)) {
+        console.error(`Error: Invalid format "${options.format}". Must be one of: json, yaml, table`);
+        process.exit(1);
+      }
+
+      const result = await handleQuery(query, {
+        file: options.file,
+        version: options.version
+      });
+
+      if (!result.success) {
+        // Error case - output error message and exit with code 1
+        if (options.format === 'json') {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.error(result.error);
+        }
+        process.exit(1);
+      }
+
+      const output = formatOutput(result, options.format, 'query');
+      console.log(output);
+      process.exit(0);
+    } catch (error) {
+      console.error(`Error: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+// List versions command
+program
+  .command('list-versions')
+  .description('List available vCluster versions')
+  .option('-f, --format <format>', 'Output format (json, yaml, table)', 'json')
+  .action(async (options) => {
+    try {
+      // Validate format option
+      if (!['json', 'yaml', 'table'].includes(options.format)) {
+        console.error(`Error: Invalid format "${options.format}". Must be one of: json, yaml, table`);
+        process.exit(1);
+      }
+
+      const result = await handleListVersions();
+
+      if (!result.success) {
+        if (options.format === 'json') {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.error(result.error);
+        }
+        process.exit(1);
+      }
+
+      const output = formatOutput(result, options.format, 'list-versions');
+      console.log(output);
+      process.exit(0);
+    } catch (error) {
+      console.error(`Error: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+// Validate command
+program
+  .command('validate <content>')
+  .description('Validate vCluster configuration')
+  .option('--version <version>', 'vCluster version for schema', 'main')
+  .option('-f, --format <format>', 'Output format (json, yaml, table)', 'json')
+  .action(async (content, options) => {
+    try {
+      // Validate format option
+      if (!['json', 'yaml', 'table'].includes(options.format)) {
+        console.error(`Error: Invalid format "${options.format}". Must be one of: json, yaml, table`);
+        process.exit(1);
+      }
+
+      const result = await handleValidate(content, {
+        version: options.version
+      });
+
+      // For validation, always output the result (even if not successful)
+      // The formatOutput will handle error cases appropriately
+      const output = formatOutput(result, options.format, 'validate');
+      console.log(output);
+
+      // Exit with code 1 if validation failed OR if we couldn't load schema
+      if (!result.success || !result.valid) {
+        process.exit(1);
+      }
+
+      process.exit(0);
+    } catch (error) {
+      console.error(`Error: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+// Parse arguments
+program.parse();

package/src/formatters.js

@@ -0,0 +1,168 @@
+/**
+ * Output formatters for CLI
+ * Provides JSON, YAML, and table formatting for command outputs
+ */
+
+import yaml from 'js-yaml';
+import Table from 'cli-table3';
+import chalk from 'chalk';
+
+/**
+ * Format output as JSON
+ * Always returns valid JSON that can be parsed with JSON.parse()
+ */
+export function formatJSON(data) {
+  return JSON.stringify(data, null, 2);
+}
+
+/**
+ * Format output as YAML
+ * Always returns valid YAML that can be parsed with yaml.load()
+ */
+export function formatYAML(data) {
+  return yaml.dump(data, {
+    indent: 2,
+    lineWidth: 120,
+    noRefs: true
+  });
+}
+
+/**
+ * Format query results as a table
+ * Returns formatted table with box-drawing characters and colored headers
+ */
+export function formatQueryTable(results, metadata) {
+  // Handle empty results
+  if (!results || results.length === 0) {
+    return `No results found for query: "${metadata.query}"`;
+  }
+
+  const table = new Table({
+    head: [
+      chalk.cyan('Field'),
+      chalk.cyan('Value'),
+      chalk.cyan('Type'),
+      chalk.cyan('Description')
+    ],
+    style: {
+      head: [],
+      border: []
+    }
+  });
+
+  results.forEach(result => {
+    table.push([
+      result.field || result.path || '',
+      formatValue(result.value),
+      result.type || '',
+      result.description || ''
+    ]);
+  });
+
+  return table.toString();
+}
+
+/**
+ * Format list-versions results as a table
+ */
+export function formatVersionsTable(versions) {
+  if (!versions || versions.length === 0) {
+    return 'No versions found';
+  }
+
+  const table = new Table({
+    head: [chalk.cyan('Version')],
+    style: {
+      head: [],
+      border: []
+    }
+  });
+
+  versions.forEach(version => {
+    table.push([version]);
+  });
+
+  return table.toString();
+}
+
+/**
+ * Format validation results as a table
+ */
+export function formatValidationTable(data) {
+  if (data.valid) {
+    return chalk.green('✓ Configuration is valid');
+  }
+
+  let output = chalk.red('✗ Configuration has errors:\n');
+
+  const table = new Table({
+    head: [
+      chalk.cyan('Path'),
+      chalk.cyan('Error'),
+      chalk.cyan('Type')
+    ],
+    style: {
+      head: [],
+      border: []
+    }
+  });
+
+  data.errors.forEach(error => {
+    table.push([
+      error.path || 'root',
+      error.message || '',
+      error.type || ''
+    ]);
+  });
+
+  output += table.toString();
+  return output;
+}
+
+/**
+ * Helper function to format values for table display
+ * Truncates long values and handles different types
+ */
+function formatValue(value) {
+  if (value === null || value === undefined) {
+    return '';
+  }
+
+  if (typeof value === 'object') {
+    const str = JSON.stringify(value);
+    return str.length > 50 ? str.substring(0, 47) + '...' : str;
+  }
+
+  const str = String(value);
+  return str.length > 50 ? str.substring(0, 47) + '...' : str;
+}
+
+/**
+ * Main formatter function
+ * Routes to appropriate formatter based on format option
+ */
+export function formatOutput(data, format, command) {
+  switch (format) {
+    case 'json':
+      return formatJSON(data);
+
+    case 'yaml':
+      return formatYAML(data);
+
+    case 'table':
+      // Route to appropriate table formatter based on command/data shape
+      if (command === 'query' || data.results !== undefined) {
+        return formatQueryTable(data.results || [], data.metadata || {});
+      } else if (command === 'list-versions' || data.versions !== undefined) {
+        return formatVersionsTable(data.versions || []);
+      } else if (command === 'validate' || data.valid !== undefined) {
+        return formatValidationTable(data);
+      } else {
+        // Fallback: format entire data object as JSON in table
+        return formatJSON(data);
+      }
+
+    default:
+      throw new Error(`Unknown format: ${format}`);
+  }
+}

package/src/github.js

@@ -0,0 +1,170 @@
+import fetch from 'node-fetch';
+import yaml from 'js-yaml';
+
+const GITHUB_API_BASE = 'https://api.github.com';
+const GITHUB_RAW_BASE = 'https://raw.githubusercontent.com';
+const REPO_OWNER = 'loft-sh';
+const REPO_NAME = 'vcluster';
+
+// Cache for fetched content (15 minute TTL)
+const cache = new Map();
+const CACHE_TTL = 15 * 60 * 1000; // 15 minutes
+
+class GitHubClient {
+  constructor() {
+    this.defaultBranch = 'main';
+  }
+
+  // Get list of available tags (versions)
+  async getTags() {
+    const cacheKey = 'tags';
+    const cached = this.getFromCache(cacheKey);
+    if (cached) return cached;
+
+    try {
+      const response = await fetch(`${GITHUB_API_BASE}/repos/${REPO_OWNER}/${REPO_NAME}/tags`, {
+        headers: {
+          'Accept': 'application/vnd.github.v3+json',
+          'User-Agent': 'vcluster-yaml-mcp-server'
+        }
+      });
+
+      if (!response.ok) {
+        throw new Error(`GitHub API error: ${response.statusText}`);
+      }
+
+      const tags = await response.json();
+      const tagNames = tags.map(tag => tag.name);
+      
+      this.setCache(cacheKey, tagNames);
+      return tagNames;
+    } catch (error) {
+      console.error('Error fetching tags:', error);
+      return [];
+    }
+  }
+
+  // Get list of branches
+  async getBranches() {
+    const cacheKey = 'branches';
+    const cached = this.getFromCache(cacheKey);
+    if (cached) return cached;
+
+    try {
+      const response = await fetch(`${GITHUB_API_BASE}/repos/${REPO_OWNER}/${REPO_NAME}/branches`, {
+        headers: {
+          'Accept': 'application/vnd.github.v3+json',
+          'User-Agent': 'vcluster-yaml-mcp-server'
+        }
+      });
+
+      if (!response.ok) {
+        throw new Error(`GitHub API error: ${response.statusText}`);
+      }
+
+      const branches = await response.json();
+      const branchNames = branches.map(branch => branch.name);
+      
+      this.setCache(cacheKey, branchNames);
+      return branchNames;
+    } catch (error) {
+      console.error('Error fetching branches:', error);
+      return ['main'];
+    }
+  }
+
+  // Get file content from GitHub
+  async getFileContent(path, ref = 'main') {
+    const actualRef = ref;
+    const cacheKey = `file:${actualRef}:${path}`;
+    const cached = this.getFromCache(cacheKey);
+    if (cached) return cached;
+
+    try {
+      const url = `${GITHUB_RAW_BASE}/${REPO_OWNER}/${REPO_NAME}/${actualRef}/${path}`;
+      const response = await fetch(url, {
+        headers: {
+          'User-Agent': 'vcluster-yaml-mcp-server'
+        }
+      });
+
+      if (!response.ok) {
+        if (response.status === 404) {
+          throw new Error(`File not found: ${path} (ref: ${actualRef})`);
+        }
+        throw new Error(`GitHub error: ${response.statusText}`);
+      }
+
+      const content = await response.text();
+      this.setCache(cacheKey, content);
+      return content;
+    } catch (error) {
+      throw new Error(`Failed to fetch ${path}: ${error.message}`);
+    }
+  }
+
+  // Get parsed YAML content
+  async getYamlContent(path, ref = null) {
+    const content = await this.getFileContent(path, ref);
+    try {
+      return yaml.load(content);
+    } catch (error) {
+      throw new Error(`Failed to parse YAML from ${path}: ${error.message}`);
+    }
+  }
+
+  // Get vcluster configuration files
+  async getVClusterConfigs(ref = null) {
+    const configs = {};
+    
+    // Known vcluster config files
+    const configPaths = [
+      'chart/values.yaml',
+      'chart/values.schema.json',
+      'config/values.yaml',
+      'values.schema.json'
+    ];
+
+    for (const path of configPaths) {
+      try {
+        if (path.endsWith('.yaml') || path.endsWith('.yml')) {
+          configs[path] = await this.getYamlContent(path, ref);
+        } else if (path.endsWith('.json')) {
+          const content = await this.getFileContent(path, ref);
+          configs[path] = JSON.parse(content);
+        }
+      } catch (error) {
+        // File might not exist in this version, skip it
+        console.debug(`Skipping ${path}: ${error.message}`);
+      }
+    }
+
+    return configs;
+  }
+
+  // Cache helpers
+  getFromCache(key) {
+    const item = cache.get(key);
+    if (!item) return null;
+    
+    if (Date.now() - item.timestamp > CACHE_TTL) {
+      cache.delete(key);
+      return null;
+    }
+    
+    return item.data;
+  }
+
+  setCache(key, data) {
+    cache.set(key, {
+      data,
+      timestamp: Date.now()
+    });
+  }
+
+  clearCache() {
+    cache.clear();
+  }
+}
+
+export const githubClient = new GitHubClient();

package/src/http-server.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createServer } from './server.js';
+import express from 'express';
+import { requireApiKey } from './middleware/auth.js';
+
+const PORT = process.env.PORT || 3000;
+const REQUIRE_AUTH = process.env.REQUIRE_AUTH === 'true';
+
+const app = express();
+app.use(express.json());
+
+// Health check endpoint
+app.get('/health', (_req, res) => {
+  res.json({
+    status: 'ok',
+    name: 'vcluster-yaml-mcp-server',
+    version: '0.1.0',
+    timestamp: new Date().toISOString()
+  });
+});
+
+// Root endpoint info
+app.get('/', (_req, res) => {
+  res.json({
+    name: 'vcluster-yaml-mcp-server',
+    version: '0.1.0',
+    description: 'MCP server for querying vCluster YAML configurations',
+    endpoints: {
+      mcp: '/mcp',
+      health: '/health'
+    },
+    documentation: 'https://github.com/Piotr1215/vcluster-yaml-mcp-server'
+  });
+});
+
+// MCP endpoint with Streamable HTTP transport
+const mcpHandler = async (req, res) => {
+  console.log(`MCP ${req.method} request received`);
+
+  // Create new transport per request to prevent ID collisions
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: undefined,
+    enableJsonResponse: true
+  });
+
+  // Cleanup on connection close
+  res.on('close', () => {
+    transport.close();
+  });
+
+  const server = createServer();
+  await server.connect(transport);
+  await transport.handleRequest(req, res, req.body);
+};
+
+// Support both GET and POST for MCP endpoint
+app.get('/mcp', REQUIRE_AUTH ? requireApiKey : (req, res, next) => next(), mcpHandler);
+app.post('/mcp', REQUIRE_AUTH ? requireApiKey : (req, res, next) => next(), mcpHandler);
+
+app.listen(PORT, () => {
+  console.log(`vcluster-yaml-mcp-server HTTP running on port ${PORT}`);
+  console.log(`Health check: http://localhost:${PORT}/health`);
+  console.log(`MCP endpoint: http://localhost:${PORT}/mcp`);
+  console.log(`Transport: Streamable HTTP (MCP 2025-03-26)`);
+});

package/src/index.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+
+// Create server (no config path needed - uses GitHub)
+const server = createServer();
+
+// Start the server
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/middleware/auth.js

@@ -0,0 +1,25 @@
+// Simple API key authentication middleware
+export function requireApiKey(req, res, next) {
+  const authHeader = req.headers['authorization'];
+
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    return res.status(401).json({
+      error: 'Unauthorized',
+      message: 'Missing or invalid Authorization header'
+    });
+  }
+
+  const token = authHeader.substring(7);
+  const validTokens = (process.env.VALID_API_KEYS || '').split(',');
+
+  if (!validTokens.includes(token)) {
+    return res.status(403).json({
+      error: 'Forbidden',
+      message: 'Invalid API key'
+    });
+  }
+
+  // Optional: Track usage per token
+  req.apiKey = token;
+  next();
+}