@redpanda-data/docs-extensions-and-macros 4.13.6 → 4.14.0

package/bin/mcp-tools/generated-docs-review.js

@@ -1,16 +1,16 @@
 /**
- * MCP Tools - Documentation Review
+ * MCP Tools - Generated Documentation Review
  *
- * OPTIMIZATION: This tool uses programmatic checks instead of LLM for most validations.
- * - Caches style guide content
- * - Programmatic checks for: missing descriptions, invalid xrefs, DRY violations
- * - Only style/tone review requires LLM processing
+ * Programmatic validation for auto-generated documentation.
+ * Checks for: missing descriptions, invalid xrefs, DRY violations, quality scoring.
+ *
+ * Note: Style and tone review is handled by the style-guide skill in docs-team-standards.
+ * This tool focuses on structural and technical validation only.
  */
 
 const fs = require('fs');
 const path = require('path');
 const { findRepoRoot, formatDate } = require('./utils');
-const cache = require('./cache');
 
 /**
  * Sanitize version string to prevent path traversal
@@ -53,54 +53,6 @@ function sanitizeVersion(version) {
   return sanitized;
 }
 
-/**
- * Build style review instructions for LLM-based review
- * @param {string} docType - Type of documentation being reviewed
- * @returns {string} Review instructions
- */
-function buildStyleReviewInstructions(docType) {
-  const baseInstructions = `
-# Style Guide Review Instructions
-
-You are reviewing autogenerated ${docType} documentation for Redpanda.
-
-## Your Task
-
-Review the content sample below against the style guide and identify:
-
-1. **Terminology issues**
-   - Incorrect capitalization (e.g., "RedPanda" should be "Redpanda")
-   - Deprecated terms (e.g., "whitelist/blacklist" should be "allowlist/denylist")
-   - Incorrect technical terms
-
-2. **Voice and tone issues**
-   - Passive voice (should be active)
-   - Wrong tense (should be present tense)
-   - Wrong person (should be second person "you")
-
-3. **Formatting issues**
-   - Heading capitalization (should be sentence case, not title case)
-   - Overuse of bold
-   - Use of em dashes (should use parentheses or colons instead)
-
-4. **Structural issues**
-   - Incorrect heading hierarchy
-   - Missing descriptions or context
-   - Unclear explanations
-
-## Output Format
-
-For each issue found, provide:
-- Line number or section reference
-- Issue type (terminology/voice/formatting/structure)
-- Specific problem
-- Suggested fix
-
-If no issues are found in a category, state "No issues found."
-`;
-
-  return baseInstructions;
-}
 
 /**
  * Generate an AsciiDoc report from review results
@@ -337,22 +289,6 @@ function reviewGeneratedDocs(args) {
   const repoRoot = findRepoRoot();
   const { doc_type, version, generate_report } = args;
 
-  // Load style guide from cache or file (cache for 1 hour)
-  const styleGuidePath = path.join(repoRoot.root, 'mcp', 'team-standards', 'style-guide.md');
-  let styleGuide = null;
-
-  const cacheKey = 'style-guide-content';
-  styleGuide = cache.get(cacheKey);
-
-  if (!styleGuide && fs.existsSync(styleGuidePath)) {
-    try {
-      styleGuide = fs.readFileSync(styleGuidePath, 'utf8');
-      cache.set(cacheKey, styleGuide, 60 * 60 * 1000); // Cache for 1 hour
-    } catch (err) {
-      console.error(`Warning: Could not load style guide: ${err.message}`);
-    }
-  }
-
   if (!doc_type) {
     return {
       success: false,
@@ -365,9 +301,6 @@ function reviewGeneratedDocs(args) {
   const suggestions = [];
   let filesAnalyzed = 0;
   let qualityScore = 100;
-  let contentSample = ''; // For storing content samples for LLM review
-  let contentFilePath = null; // Path to full content file for deep review if needed
-  let contentTotalLines = 0; // Total lines in the content file
 
   try {
     switch (doc_type) {
@@ -587,19 +520,6 @@ function reviewGeneratedDocs(args) {
           qualityScore -= Math.min(5, Math.floor(propertiesNeedingExamples.length / 5));
         }
 
-        // Sample generated property docs for style review (hybrid approach)
-        const clusterPropsPath = path.join(repoRoot.root, propertiesBaseDir, 'partials', 'properties', 'cluster-properties.adoc');
-        if (fs.existsSync(clusterPropsPath)) {
-          const fullContent = fs.readFileSync(clusterPropsPath, 'utf8');
-          const lines = fullContent.split('\n');
-          // Sample first 300 lines to catch systematic issues
-          // (enough to see multiple properties and their patterns)
-          contentSample = lines.slice(0, 300).join('\n');
-          // Store file path for full review if needed
-          contentFilePath = clusterPropsPath;
-          contentTotalLines = lines.length;
-        }
-
         break;
       }
 
@@ -699,29 +619,12 @@ function reviewGeneratedDocs(args) {
           suggestions.push('All $ref references are valid and DRY principles are maintained');
         }
 
-        // Sample connector descriptions for style review
-        // Collect sample descriptions from inputs/outputs
-        const sampleDescriptions = [];
-        ['inputs', 'outputs'].forEach(section => {
-          if (overrides[section]) {
-            Object.entries(overrides[section]).slice(0, 5).forEach(([name, config]) => {
-              if (config.description) {
-                sampleDescriptions.push(`\n== ${name} (${section})\n\n${config.description}`);
-              }
-            });
-          }
-        });
-
-        if (sampleDescriptions.length > 0) {
-          contentSample = `= RPCN Connector Descriptions Sample\n${sampleDescriptions.join('\n\n')}`;
-        }
-
         break;
       }
 
       case 'metrics':
       case 'rpk': {
-        // For metrics and RPK, check files exist and sample content for style review
+        // For metrics and RPK, check files exist
         if (!version) {
           return {
             success: false,
@@ -740,11 +643,9 @@ function reviewGeneratedDocs(args) {
           };
         }
 
-        let filePath;
-
         if (doc_type === 'metrics') {
           // Use custom path or default
-          filePath = args.metrics_file ?
+          const filePath = args.metrics_file ?
             path.join(repoRoot.root, args.metrics_file) :
             path.join(repoRoot.root, 'modules', 'reference', 'pages', 'public-metrics-reference.adoc');
 
@@ -755,14 +656,6 @@ function reviewGeneratedDocs(args) {
               suggestion: 'Generate metrics docs first using generate_metrics_docs tool, or specify custom path with metrics_file parameter'
             };
           }
-
-          // Read first 300 lines as sample for style review (hybrid approach)
-          const fullContent = fs.readFileSync(filePath, 'utf8');
-          const lines = fullContent.split('\n');
-          contentSample = lines.slice(0, 300).join('\n');
-          contentFilePath = filePath;
-          contentTotalLines = lines.length;
-
         } else {
           // RPK files are version-specific
           const normalizedVersion = sanitizedVersion.startsWith('v') ? sanitizedVersion : `v${sanitizedVersion}`;
@@ -778,22 +671,6 @@ function reviewGeneratedDocs(args) {
               suggestion: 'Generate RPK docs first using generate_rpk_docs tool, or specify custom path with rpk_dir parameter'
             };
           }
-          filePath = rpkDir;
-
-          // Sample 3 command files for review (hybrid approach)
-          const rpkFiles = fs.readdirSync(rpkDir).filter(f => f.endsWith('.adoc'));
-          if (rpkFiles.length > 0) {
-            const samplesToRead = Math.min(3, rpkFiles.length);
-            const samples = [];
-            for (let i = 0; i < samplesToRead; i++) {
-              const sampleFile = path.join(rpkDir, rpkFiles[i]);
-              const content = fs.readFileSync(sampleFile, 'utf8');
-              samples.push(`\n// File: ${rpkFiles[i]}\n${content}`);
-            }
-            contentSample = samples.join('\n\n---\n\n');
-            contentFilePath = rpkDir;
-            contentTotalLines = rpkFiles.length; // Total number of command files
-          }
         }
 
         filesAnalyzed++;
@@ -822,33 +699,9 @@ function reviewGeneratedDocs(args) {
       quality_score: qualityScore,
       suggestions,
       summary: `Reviewed ${doc_type} documentation. Quality score: ${qualityScore}/100. Found ${issues.length} issues.`,
-      style_guide_loaded: styleGuide !== null,
-      style_guide: styleGuide,
-      // Hybrid review approach: sample for quick check, full content path if deeper review needed
-      content_sample: contentSample || null,
-      content_file_path: contentFilePath,
-      content_total_lines: contentTotalLines || null,
-      content_sample_info: contentSample ?
-        (doc_type === 'rpk' ?
-          `Sample includes ${Math.min(3, contentTotalLines)} of ${contentTotalLines} command files` :
-          `Sample includes first 300 of ${contentTotalLines} lines`) : null,
-      // Instructions for LLM-based review
-      review_instructions: styleGuide && contentSample ? buildStyleReviewInstructions(doc_type) : null,
-      additional_review_needed: styleGuide && contentSample ?
-        'IMPORTANT: HYBRID REVIEW APPROACH\n\n' +
-        '1. First, review the content sample below against the style guide:\n' +
-        '   - Terminology compliance (correct capitalization, approved terms)\n' +
-        '   - Voice and tone (active voice, present tense, second person)\n' +
-        '   - Formatting (heading capitalization, bold usage, em dashes)\n' +
-        '   - Clarity and readability\n\n' +
-        '2. If you find style issues in the sample:\n' +
-        '   - Report the issues found in the sample\n' +
-        '   - Use the Read tool on content_file_path to review more content\n' +
-        '   - Look for patterns that indicate systematic problems\n\n' +
-        '3. If no issues found in sample, the docs are likely good throughout.' :
-        styleGuide ?
-        'IMPORTANT: The programmatic review above checks for technical quality issues (missing descriptions, invalid xrefs, etc.). You should ALSO review the generated content against the style guide below for terminology, tone, and formatting compliance.' :
-        'Note: Style guide not available for additional review.'
+      // Note: Style review is handled by the style-guide skill in docs-team-standards
+      next_steps: 'This tool validates structural issues (missing descriptions, invalid refs, DRY violations). ' +
+        'For style and tone review, use the content-reviewer agent from docs-team-standards plugin.'
     };
 
     // Generate AsciiDoc report if requested

package/bin/mcp-tools/index.js

@@ -25,7 +25,6 @@ const { generateBundleOpenApi } = require('./openapi');
 
 // Review tools
 const { reviewGeneratedDocs, generateReviewReport } = require('./generated-docs-review');
-const { reviewContent } = require('./content-review');
 
 // Job queue
 const { initializeJobQueue, createJob, getJob, listJobs, cleanupOldJobs } = require('./job-queue');
@@ -77,9 +76,6 @@ function executeTool(toolName, args = {}) {
       case 'review_generated_docs':
         return reviewGeneratedDocs(args);
 
-      case 'review_content':
-        return reviewContent(args, repoRoot.root);
-
       case 'run_doc_tools_command': {
         // Validate and execute raw doc-tools command
         if (!args || typeof args !== 'object') {

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

@@ -1,171 +1,78 @@
 /**
  * MCP Configuration Validation
  *
- * Validates prompts, resources, and overall MCP server configuration.
- * Used at startup and by the validate-mcp CLI command.
+ * Validates MCP server configuration.
+ * Note: Prompts and most resources have been migrated to docs-team-standards plugin.
+ * This now only validates the personas resource and tools configuration.
  */
 
 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
+ * Resources that are loaded dynamically (from current working directory)
  */
-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')}`
-    );
-  }
-}
+const DYNAMIC_RESOURCES = ['redpanda://personas'];
 
 /**
- * Validate all resources are accessible
+ * Validate resources configuration
  * @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) {
+function validateResources(resources) {
   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}`);
+    // All remaining resources should be dynamic (loaded from cwd)
+    if (!DYNAMIC_RESOURCES.includes(resource.uri)) {
+      warnings.push(`Unexpected resource: ${resource.uri} - static resources should be in docs-team-standards plugin`);
       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
+    // Validate metadata for dynamic resources
     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
+ * Validate tools configuration
+ * @param {Array} tools - Tool definitions
  * @returns {{ errors: string[], warnings: string[] }}
  */
-function validatePrompts(prompts) {
+function validateTools(tools) {
   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)`);
+  for (const tool of tools) {
+    if (!tool.name) {
+      errors.push('Tool missing name');
+      continue;
     }
 
-    // Check for version
-    if (!prompt.version) {
-      warnings.push(`Prompt "${prompt.name}" missing version metadata`);
+    if (!tool.description || tool.description.length < 10) {
+      warnings.push(`Tool "${tool.name}" has a very short description`);
     }
 
-    // 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}`
-        );
-      }
+    if (!tool.inputSchema) {
+      warnings.push(`Tool "${tool.name}" missing inputSchema`);
     }
+  }
 
-    // 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);
-      }
+  // Check for duplicate names
+  const toolNames = new Set();
+  for (const tool of tools) {
+    if (tool.name && toolNames.has(tool.name)) {
+      errors.push(`Duplicate tool name: ${tool.name}`);
     }
+    toolNames.add(tool.name);
   }
 
   return { errors, warnings };
@@ -175,9 +82,7 @@ function validatePrompts(prompts) {
  * 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
+ * @param {Array} config.tools - Tools
  * @returns {{ valid: boolean, errors: string[], warnings: string[] }}
  */
 function validateMcpConfiguration(config) {
@@ -185,26 +90,17 @@ function validateMcpConfiguration(config) {
   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);
+  if (config.resources) {
+    const resourceValidation = validateResources(config.resources);
+    allErrors.push(...resourceValidation.errors);
+    allWarnings.push(...resourceValidation.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);
+  // Validate tools
+  if (config.tools) {
+    const toolValidation = validateTools(config.tools);
+    allErrors.push(...toolValidation.errors);
+    allWarnings.push(...toolValidation.warnings);
   }
 
   return {
@@ -217,6 +113,7 @@ function validateMcpConfiguration(config) {
 /**
  * Format validation results for display
  * @param {{ valid: boolean, errors: string[], warnings: string[] }} results
+ * @param {Object} config - Configuration object
  * @returns {string} Formatted output
  */
 function formatValidationResults(results, config) {
@@ -227,8 +124,8 @@ function formatValidationResults(results, config) {
   lines.push('');
 
   // Summary
-  lines.push(`Prompts found: ${config.prompts.length}`);
-  lines.push(`Resources found: ${config.resources.length}`);
+  lines.push(`Tools found: ${config.tools?.length || 0}`);
+  lines.push(`Resources found: ${config.resources?.length || 0}`);
   lines.push('');
 
   // Warnings
@@ -257,10 +154,8 @@ function formatValidationResults(results, config) {
 }
 
 module.exports = {
-  validatePromptName,
-  validatePromptArguments,
   validateResources,
-  validatePrompts,
+  validateTools,
   validateMcpConfiguration,
   formatValidationResults
 };

package/mcp/COSTS.adoc

@@ -1,9 +1,9 @@
 = MCP Tool Costs
 :description: Cost reference for Redpanda documentation MCP server tools
 
-The typical cost range is $0.017 - $0.190 per operation.
+The typical cost range is $0.03 - $0.19 per operation.
 
-Most operations cost between $0.03 - $0.08. Content review operations range from $0.017 (simple terminology checks) to $0.19 (comprehensive generated docs reviews).
+Most operations cost between $0.03 - $0.08. Generated docs review costs up to $0.19 for comprehensive reviews.
 
 == Cost factors
 
@@ -66,20 +66,10 @@ You control costs through:
 |review_generated_docs
 |Review the autogenerated metrics docs
 |0.104 - 0.190
-
-|review_content (terminology)
-|Check terminology in a sentence
-|0.017
-
-|review_content (style)
-|Review content for style guide compliance
-|0.065
-
-|review_content (comprehensive)
-|Comprehensive content review
-|0.062
 |===
 
+NOTE: The `review_content` tool was migrated to the `content-reviewer` agent in docs-team-standards. Content review now uses skills directly without MCP tool costs.
+
 == How to measure costs
 
 To track costs during testing:
@@ -162,6 +152,6 @@ claude --model opus
 == Cost optimization tips
 
 * *Choose the right model*: Use Haiku for simple generation tasks, Sonnet for most work
-* *Leverage caching*: The MCP server caches style guides and prompts - repeated operations in the same session are cheaper
-* *Batch similar work*: Do multiple reviews or generations in one session to maximize cache benefits
-* *Use focused reviews*: For content review, use `focus: "terminology"` or `focus: "style"` instead of `focus: "comprehensive"` when you only need specific feedback
+* *Leverage caching*: Repeated operations in the same session benefit from prompt caching
+* *Batch similar work*: Do multiple generations in one session to maximize cache benefits
+* *Use skills for review*: Content review now uses the docs-team-standards plugin (no MCP tool costs)