@redpanda-data/docs-extensions-and-macros 4.12.6 → 4.13.0

package/bin/mcp-tools/mcp-validation.js

@@ -0,0 +1,266 @@
+/**
+ * MCP Configuration Validation
+ *
+ * Validates prompts, resources, and overall MCP server configuration.
+ * Used at startup and by the validate-mcp CLI command.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parsePromptFile } = require('./frontmatter');
+
+/**
+ * Validate that a prompt name is safe (no path traversal)
+ * @param {string} name - Prompt name to validate
+ * @throws {Error} If name is invalid
+ */
+function validatePromptName(name) {
+  if (!name || typeof name !== 'string') {
+    throw new Error('Prompt name must be a non-empty string');
+  }
+
+  // Only allow alphanumeric, hyphens, and underscores
+  if (!/^[a-z0-9_-]+$/i.test(name)) {
+    throw new Error(
+      `Invalid prompt name: ${name}. Use only letters, numbers, hyphens, and underscores.`
+    );
+  }
+
+  return name;
+}
+
+/**
+ * Validate that required arguments are provided
+ * @param {string} promptName - Name of the prompt
+ * @param {Object} providedArgs - Arguments provided by user
+ * @param {Array} schema - Argument schema from prompt metadata
+ * @throws {Error} If validation fails
+ */
+function validatePromptArguments(promptName, providedArgs, schema) {
+  if (!schema || schema.length === 0) {
+    return; // No validation needed
+  }
+
+  const errors = [];
+
+  // Check required arguments
+  schema
+    .filter(arg => arg.required)
+    .forEach(arg => {
+      if (!providedArgs || !providedArgs[arg.name]) {
+        errors.push(`Missing required argument: ${arg.name}`);
+      }
+    });
+
+  if (errors.length > 0) {
+    throw new Error(
+      `Invalid arguments for prompt "${promptName}":\n${errors.join('\n')}`
+    );
+  }
+}
+
+/**
+ * Validate all resources are accessible
+ * @param {Array} resources - Resource definitions
+ * @param {Object} resourceMap - Resource file mappings
+ * @param {string} baseDir - Base directory for resources
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+function validateResources(resources, resourceMap, baseDir) {
+  const errors = [];
+  const warnings = [];
+
+  for (const resource of resources) {
+    // Check mapping exists
+    const mapping = resourceMap[resource.uri];
+    if (!mapping) {
+      errors.push(`Resource ${resource.uri} has no file mapping in resourceMap`);
+      continue;
+    }
+
+    // Check file exists
+    const filePath = path.join(baseDir, 'mcp', 'team-standards', mapping.file);
+    if (!fs.existsSync(filePath)) {
+      errors.push(`Resource file missing: ${mapping.file} for ${resource.uri}`);
+      continue;
+    }
+
+    // Check file is readable
+    try {
+      fs.readFileSync(filePath, 'utf8');
+    } catch (err) {
+      errors.push(`Resource file not readable: ${mapping.file} - ${err.message}`);
+      continue;
+    }
+
+    // Validate resource metadata
+    if (!resource.name || resource.name.length < 3) {
+      warnings.push(`Resource ${resource.uri} has a very short name`);
+    }
+
+    if (!resource.description || resource.description.length < 10) {
+      warnings.push(`Resource ${resource.uri} has a very short description`);
+    }
+
+    // Check for versioning
+    if (!resource.version) {
+      warnings.push(`Resource ${resource.uri} missing version metadata`);
+    }
+
+    if (!resource.lastUpdated) {
+      warnings.push(`Resource ${resource.uri} missing lastUpdated metadata`);
+    }
+  }
+
+  return { errors, warnings };
+}
+
+/**
+ * Validate all prompts are loadable
+ * @param {Array} prompts - Discovered prompts
+ * @returns {{ errors: string[], warnings: string[] }}
+ */
+function validatePrompts(prompts) {
+  const errors = [];
+  const warnings = [];
+
+  for (const prompt of prompts) {
+    // Check basic metadata
+    if (!prompt.description || prompt.description.length < 10) {
+      warnings.push(`Prompt "${prompt.name}" has a very short description`);
+    }
+
+    if (!prompt.content || prompt.content.trim().length < 100) {
+      warnings.push(`Prompt "${prompt.name}" has very little content (< 100 chars)`);
+    }
+
+    // Check for version
+    if (!prompt.version) {
+      warnings.push(`Prompt "${prompt.name}" missing version metadata`);
+    }
+
+    // Validate argument format if specified
+    if (prompt.argumentFormat) {
+      const validFormats = ['content-append', 'structured'];
+      if (!validFormats.includes(prompt.argumentFormat)) {
+        errors.push(
+          `Prompt "${prompt.name}" has invalid argumentFormat: ${prompt.argumentFormat}`
+        );
+      }
+    }
+
+    // Check for argument schema consistency
+    if (prompt.arguments && prompt.arguments.length > 0) {
+      if (!prompt.argumentFormat) {
+        warnings.push(
+          `Prompt "${prompt.name}" has arguments but no argumentFormat specified`
+        );
+      }
+
+      // Check for duplicate argument names
+      const argNames = new Set();
+      for (const arg of prompt.arguments) {
+        if (argNames.has(arg.name)) {
+          errors.push(`Prompt "${prompt.name}" has duplicate argument: ${arg.name}`);
+        }
+        argNames.add(arg.name);
+      }
+    }
+  }
+
+  return { errors, warnings };
+}
+
+/**
+ * Validate entire MCP configuration
+ * @param {Object} config - Configuration object
+ * @param {Array} config.resources - Resources
+ * @param {Object} config.resourceMap - Resource mappings
+ * @param {Array} config.prompts - Prompts
+ * @param {string} config.baseDir - Base directory
+ * @returns {{ valid: boolean, errors: string[], warnings: string[] }}
+ */
+function validateMcpConfiguration(config) {
+  const allErrors = [];
+  const allWarnings = [];
+
+  // Validate resources
+  const resourceValidation = validateResources(
+    config.resources,
+    config.resourceMap,
+    config.baseDir
+  );
+  allErrors.push(...resourceValidation.errors);
+  allWarnings.push(...resourceValidation.warnings);
+
+  // Validate prompts
+  const promptValidation = validatePrompts(config.prompts);
+  allErrors.push(...promptValidation.errors);
+  allWarnings.push(...promptValidation.warnings);
+
+  // Check for name collisions
+  const promptNames = new Set();
+  for (const prompt of config.prompts) {
+    if (promptNames.has(prompt.name)) {
+      allErrors.push(`Duplicate prompt name: ${prompt.name}`);
+    }
+    promptNames.add(prompt.name);
+  }
+
+  return {
+    valid: allErrors.length === 0,
+    errors: allErrors,
+    warnings: allWarnings
+  };
+}
+
+/**
+ * Format validation results for display
+ * @param {{ valid: boolean, errors: string[], warnings: string[] }} results
+ * @returns {string} Formatted output
+ */
+function formatValidationResults(results, config) {
+  const lines = [];
+
+  lines.push('MCP Configuration Validation');
+  lines.push('='.repeat(60));
+  lines.push('');
+
+  // Summary
+  lines.push(`Prompts found: ${config.prompts.length}`);
+  lines.push(`Resources found: ${config.resources.length}`);
+  lines.push('');
+
+  // Warnings
+  if (results.warnings.length > 0) {
+    lines.push('Warnings:');
+    results.warnings.forEach(w => lines.push(`  ⚠ ${w}`));
+    lines.push('');
+  }
+
+  // Errors
+  if (results.errors.length > 0) {
+    lines.push('Errors:');
+    results.errors.forEach(e => lines.push(`  ✗ ${e}`));
+    lines.push('');
+  }
+
+  // Result
+  if (results.valid) {
+    lines.push('✓ Validation passed');
+  } else {
+    lines.push('✗ Validation failed');
+    lines.push(`  ${results.errors.length} error(s) must be fixed`);
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  validatePromptName,
+  validatePromptArguments,
+  validateResources,
+  validatePrompts,
+  validateMcpConfiguration,
+  formatValidationResults
+};

package/bin/mcp-tools/metrics-docs.js

@@ -0,0 +1,146 @@
+/**
+ * MCP Tools - Metrics Documentation Generation
+ *
+ * OPTIMIZATION: This tool calls CLI, doesn't use LLM directly.
+ * - No model recommendation (CLI tool)
+ * - Cost comes from doc-tools CLI execution
+ */
+
+const { spawnSync } = require('child_process');
+const { findRepoRoot, getDocToolsCommand, MAX_EXEC_BUFFER_SIZE, DEFAULT_COMMAND_TIMEOUT } = require('./utils');
+const { getAntoraStructure } = require('./antora');
+const { createJob } = require('./job-queue');
+
+/**
+ * Generate Redpanda metrics documentation
+ *
+ * Use tags for released content (GA or beta), branches for in-progress content.
+ * Defaults to branch "dev" if neither tag nor branch is provided.
+ *
+ * @param {Object} args - Arguments
+ * @param {string} [args.tag] - Git tag for released content (for example, "v25.3.1")
+ * @param {string} [args.branch] - Branch name for in-progress content (for example, "dev", "main")
+ * @param {boolean} [args.background] - Run as background job
+ * @returns {Object} Generation results
+ */
+function generateMetricsDocs(args) {
+  const repoRoot = findRepoRoot();
+  const structure = getAntoraStructure(repoRoot);
+
+  if (!structure.hasDocTools) {
+    return {
+      success: false,
+      error: 'doc-tools not found in this repository',
+      suggestion: 'Navigate to the docs-extensions-and-macros repository'
+    };
+  }
+
+  // Validate that tag and branch are mutually exclusive
+  if (args.tag && args.branch) {
+    return {
+      success: false,
+      error: 'Cannot specify both tag and branch',
+      suggestion: 'Use either --tag or --branch, not both'
+    };
+  }
+
+  // Default to 'dev' branch if neither provided
+  const gitRef = args.tag || args.branch || 'dev';
+  const refType = args.tag ? 'tag' : 'branch';
+
+  // Normalize version (add 'v' prefix if tag and not present)
+  let version = gitRef;
+  if (args.tag && !version.startsWith('v')) {
+    version = `v${version}`;
+  }
+
+  // Validate version string to prevent command injection
+  const versionRegex = /^[0-9A-Za-z._\/-]+$/;
+  if (!versionRegex.test(version)) {
+    return {
+      success: false,
+      error: 'Invalid version format',
+      suggestion: 'Version must contain only alphanumeric characters, dots, underscores, slashes, and hyphens (for example, "v25.3.1", "v25.3.1-rc1", "dev", "main")'
+    };
+  }
+
+  // Get doc-tools command (handles both local and installed)
+  const docTools = getDocToolsCommand(repoRoot);
+
+  // Build command arguments
+  const baseArgs = ['generate', 'metrics-docs'];
+
+  if (args.tag) {
+    baseArgs.push('--tag');
+    baseArgs.push(version);
+  } else {
+    baseArgs.push('--branch');
+    baseArgs.push(version);
+  }
+
+  // If background mode, create job and return immediately
+  if (args.background) {
+    const cmdArgs = [docTools.program, ...docTools.getArgs(baseArgs)];
+    const jobId = createJob('generate_metrics_docs', cmdArgs, {
+      cwd: repoRoot.root
+    });
+
+    return {
+      success: true,
+      background: true,
+      job_id: jobId,
+      message: `Metrics docs generation started in background. Use get_job_status with job_id: ${jobId} to check progress.`,
+      [refType]: version
+    };
+  }
+
+  // Otherwise run synchronously
+  try {
+    const result = spawnSync(docTools.program, docTools.getArgs(baseArgs), {
+      cwd: repoRoot.root,
+      encoding: 'utf8',
+      stdio: 'pipe',
+      maxBuffer: MAX_EXEC_BUFFER_SIZE,
+      timeout: DEFAULT_COMMAND_TIMEOUT
+    });
+
+    // Check for spawn errors
+    if (result.error) {
+      throw new Error(`Failed to execute command: ${result.error.message}`);
+    }
+
+    // Check for non-zero exit codes
+    if (result.status !== 0) {
+      const errorMsg = result.stderr || `Command failed with exit code ${result.status}`;
+      throw new Error(errorMsg);
+    }
+
+    const output = result.stdout;
+
+    const metricsCountMatch = output.match(/(\d+) metrics/i);
+
+    return {
+      success: true,
+      [refType]: version,
+      files_generated: [
+        'modules/reference/pages/public-metrics-reference.adoc'
+      ],
+      metrics_count: metricsCountMatch ? parseInt(metricsCountMatch[1]) : null,
+      output: output.trim(),
+      summary: `Generated metrics documentation for Redpanda ${refType} ${version}`
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: err.message,
+      stdout: err.stdout || '',
+      stderr: err.stderr || '',
+      exitCode: err.status,
+      suggestion: 'Check that the version exists in the Redpanda repository'
+    };
+  }
+}
+
+module.exports = {
+  generateMetricsDocs
+};

package/bin/mcp-tools/openapi.js

@@ -0,0 +1,174 @@
+/**
+ * MCP Tools - OpenAPI Bundle Generation
+ */
+
+const { spawnSync } = require('child_process');
+const { findRepoRoot, MAX_EXEC_BUFFER_SIZE, normalizeVersion, DEFAULT_COMMAND_TIMEOUT } = require('./utils');
+const { getAntoraStructure } = require('./antora');
+
+/**
+ * Generate bundled OpenAPI documentation
+ *
+ * Use tags for released content (GA or beta), branches for in-progress content.
+ * Requires either --tag or --branch to be specified.
+ *
+ * @param {Object} args - Arguments
+ * @param {string} [args.tag] - Git tag for released content (for example, "v24.3.2" or "24.3.2")
+ * @param {string} [args.branch] - Branch name for in-progress content (for example, "dev", "main")
+ * @param {string} [args.repo] - Repository URL
+ * @param {string} [args.surface] - Which API surface(s) to bundle: 'admin', 'connect', or 'both'
+ * @param {string} [args.out_admin] - Output path for admin API
+ * @param {string} [args.out_connect] - Output path for connect API
+ * @param {string} [args.admin_major] - Admin API major version
+ * @param {boolean} [args.use_admin_major_version] - Use admin major version for info.version
+ * @param {boolean} [args.quiet] - Suppress logs
+ * @returns {Object} Generation results
+ */
+function generateBundleOpenApi(args) {
+  const repoRoot = findRepoRoot();
+  const structure = getAntoraStructure(repoRoot);
+
+  if (!structure.hasDocTools) {
+    return {
+      success: false,
+      error: 'doc-tools not found in this repository',
+      suggestion: 'Navigate to the docs-extensions-and-macros repository'
+    };
+  }
+
+  // Validate that either tag or branch is provided (but not both)
+  if (!args.tag && !args.branch) {
+    return {
+      success: false,
+      error: 'Either tag or branch is required',
+      suggestion: 'Provide --tag "v24.3.2" or --branch "dev"'
+    };
+  }
+
+  if (args.tag && args.branch) {
+    return {
+      success: false,
+      error: 'Cannot specify both tag and branch',
+      suggestion: 'Use either --tag or --branch, not both'
+    };
+  }
+
+  try {
+    const gitRef = args.tag || args.branch;
+    const refType = args.tag ? 'tag' : 'branch';
+
+    // Normalize version (add 'v' prefix if tag and not present and not branch-like names)
+    let version = gitRef;
+    if (args.tag && !version.startsWith('v') && version !== 'dev' && version !== 'main') {
+      version = `v${version}`;
+    }
+
+    // Build command arguments array (no shell interpolation)
+    const cmdArgs = ['doc-tools', 'generate', 'bundle-openapi'];
+
+    // Add flags only when present, each as separate array entries
+    if (args.tag) {
+      cmdArgs.push('--tag');
+      cmdArgs.push(version);
+    } else {
+      cmdArgs.push('--branch');
+      cmdArgs.push(version);
+    }
+
+    if (args.repo) {
+      cmdArgs.push('--repo');
+      cmdArgs.push(args.repo);
+    }
+
+    if (args.surface) {
+      cmdArgs.push('--surface');
+      cmdArgs.push(args.surface);
+    }
+
+    if (args.out_admin) {
+      cmdArgs.push('--out-admin');
+      cmdArgs.push(args.out_admin);
+    }
+
+    if (args.out_connect) {
+      cmdArgs.push('--out-connect');
+      cmdArgs.push(args.out_connect);
+    }
+
+    if (args.admin_major) {
+      cmdArgs.push('--admin-major');
+      cmdArgs.push(args.admin_major);
+    }
+
+    if (args.use_admin_major_version) {
+      cmdArgs.push('--use-admin-major-version');
+    }
+
+    if (args.quiet) {
+      cmdArgs.push('--quiet');
+    }
+
+    const result = spawnSync('npx', cmdArgs, {
+      cwd: repoRoot.root,
+      encoding: 'utf8',
+      stdio: 'pipe',
+      maxBuffer: MAX_EXEC_BUFFER_SIZE,
+      timeout: DEFAULT_COMMAND_TIMEOUT
+    });
+
+    // Check for spawn errors
+    if (result.error) {
+      const err = new Error(`Failed to execute command: ${result.error.message}`);
+      err.stdout = result.stdout || '';
+      err.stderr = result.stderr || '';
+      err.status = result.status;
+      throw err;
+    }
+
+    // Check for non-zero exit codes
+    if (result.status !== 0) {
+      const errorMsg = result.stderr || `Command failed with exit code ${result.status}`;
+      const err = new Error(errorMsg);
+      err.stdout = result.stdout || '';
+      err.stderr = result.stderr || '';
+      err.status = result.status;
+      throw err;
+    }
+
+    const output = result.stdout;
+
+    // Determine which files were generated based on surface
+    const filesGenerated = [];
+    const surface = args.surface || 'both';
+
+    if (surface === 'admin' || surface === 'both') {
+      filesGenerated.push(args.out_admin || 'admin/redpanda-admin-api.yaml');
+    }
+
+    if (surface === 'connect' || surface === 'both') {
+      filesGenerated.push(args.out_connect || 'connect/redpanda-connect-api.yaml');
+    }
+
+    return {
+      success: true,
+      [refType]: version,
+      surface,
+      files_generated: filesGenerated,
+      output: output.trim(),
+      summary: `Bundled OpenAPI documentation for ${surface} API(s) at ${refType} ${version}`
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: err.message,
+      stdout: err.stdout || '',
+      stderr: err.stderr || '',
+      exitCode: err.status,
+      suggestion: 'Check that the tag exists in the Redpanda repository'
+    };
+  }
+}
+
+module.exports = {
+  generateBundleOpenApi
+};