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

package/bin/doc-tools-mcp.js

@@ -25,26 +25,14 @@ const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio
 const {
   CallToolRequestSchema,
   ListToolsRequestSchema,
-  ListPromptsRequestSchema,
-  GetPromptRequestSchema,
   ListResourcesRequestSchema,
   ReadResourceRequestSchema,
 } = require('@modelcontextprotocol/sdk/types.js');
 const { findRepoRoot, executeTool } = require('./mcp-tools');
 const { initializeJobQueue, getJob, listJobs } = require('./mcp-tools/job-queue');
 
-// New modules for improved architecture
-const {
-  PromptCache,
-  loadAllPrompts,
-  watchPrompts,
-  buildPromptWithArguments,
-  promptsToMcpFormat
-} = require('./mcp-tools/prompt-discovery');
-const {
-  validatePromptArguments,
-  validateMcpConfiguration
-} = require('./mcp-tools/mcp-validation');
+// Prompts and most resources migrated to docs-team-standards plugin
+// This MCP server now focuses on execution tools only
 const {
   UsageStats,
   createPeriodicReporter,
@@ -57,8 +45,7 @@ const packageJson = require('../package.json');
 // Base directory
 const baseDir = path.join(__dirname, '..');
 
-// Initialize prompt cache and usage stats
-const promptCache = new PromptCache();
+// Initialize usage stats (prompt cache removed - prompts migrated to docs-team-standards)
 const usageStats = new UsageStats();
 
 // Create the MCP server
@@ -70,8 +57,8 @@ const server = new Server(
   {
     capabilities: {
       tools: {},
-      prompts: {},
       resources: {},
+      // prompts: {} - Removed, prompts migrated to docs-team-standards plugin
     },
   }
 );
@@ -394,7 +381,7 @@ const tools = [
   },
   {
     name: 'review_generated_docs',
-    description: 'Review recently generated documentation for quality issues. Checks for missing descriptions, invalid formatting, DRY violations, and other quality problems. Uses the quality criteria from the property-docs-guide and rpcn-connector-docs-guide prompts. Can generate a formatted markdown report for easy review.',
+    description: 'Validate auto-generated documentation for structural issues. Checks for missing descriptions, invalid $refs, DRY violations, invalid xrefs, and calculates quality scores. For style and tone review, use the content-reviewer agent from docs-team-standards.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -415,25 +402,6 @@ const tools = [
       required: ['doc_type']
     }
   },
-  {
-    name: 'review_content',
-    description: 'Review documentation content with automatic style guide context. This tool bundles the style guide and review instructions in a single call, ensuring the LLM has all necessary context. Use this instead of manually fetching resources when you need a quick, comprehensive review.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        content: {
-          type: 'string',
-          description: 'The documentation content to review (can be a file path or raw content)'
-        },
-        focus: {
-          type: 'string',
-          description: 'What aspect to focus on (optional, defaults to comprehensive)',
-          enum: ['comprehensive', 'style', 'terminology', 'clarity']
-        }
-      },
-      required: ['content']
-    }
-  },
   {
     name: 'run_doc_tools_command',
     description: 'Advanced: Run a raw doc-tools command. Only use this if none of the specific tools above fit your needs. Requires knowledge of doc-tools CLI syntax.',
@@ -483,21 +451,21 @@ const tools = [
   }
 ];
 
-// Resource definitions - Team standards and guidelines
+// Resource definitions - Only personas remains (other standards migrated to docs-team-standards plugin)
 const resources = [
   {
-    uri: 'redpanda://style-guide',
-    name: 'Redpanda Documentation Style Guide',
-    description: 'Complete style guide based on Google Developer Documentation Style Guide with Redpanda-specific guidelines, voice/tone standards, and formatting preferences. Includes references to official glossary sources.',
-    mimeType: 'text/markdown',
+    uri: 'redpanda://personas',
+    name: 'Repository Personas',
+    description: 'Target audience personas for this repository. Loaded from docs-data/personas.yaml in the current working directory. Defines reader types, goals, pain points, and content preferences.',
+    mimeType: 'text/yaml',
     version: '1.0.0',
-    lastUpdated: '2025-12-11'
+    lastUpdated: '2025-01-07'
   }
 ];
 
-// Resource file mappings
+// Resource file mappings (most resources migrated to docs-team-standards plugin)
 const resourceMap = {
-  'redpanda://style-guide': { file: 'style-guide.md', mimeType: 'text/markdown' }
+  // Only personas remains - it's loaded dynamically from cwd, not from team-standards/
 };
 
 /**
@@ -506,12 +474,17 @@ const resourceMap = {
  * @returns {Object} Resource content
  */
 function getResourceContent(uri) {
+  // Special handling for personas - load from current working directory
+  if (uri === 'redpanda://personas') {
+    return getPersonasResource();
+  }
+
   const resource = resourceMap[uri];
   if (!resource) {
     throw new Error(`Unknown resource: ${uri}`);
   }
 
-  const resourcePath = path.join(baseDir, 'mcp', 'team-standards', resource.file);
+  const resourcePath = path.join(baseDir, 'team-standards', resource.file);
   try {
     const content = fs.readFileSync(resourcePath, 'utf8');
     return {
@@ -527,16 +500,71 @@ function getResourceContent(uri) {
   }
 }
 
+/**
+ * Load personas from current repository's docs-data/personas.yaml
+ * Falls back to a helpful message if not found
+ * @returns {Object} Resource content
+ */
+function getPersonasResource() {
+  const cwd = process.cwd();
+  const personasPath = path.join(cwd, 'docs-data', 'personas.yaml');
+
+  try {
+    if (fs.existsSync(personasPath)) {
+      const content = fs.readFileSync(personasPath, 'utf8');
+      return {
+        contents: [{
+          uri: 'redpanda://personas',
+          mimeType: 'text/yaml',
+          text: content
+        }]
+      };
+    } else {
+      // Return helpful message when no personas file exists
+      const fallbackContent = `# No personas defined for this repository
+#
+# To define personas, create: docs-data/personas.yaml
+#
+# Example:
+# personas:
+#   - id: developer
+#     name: Application Developer
+#     description: Builds applications using this product
+#     goals:
+#       - Integrate quickly
+#       - Find working examples
+#     pain_points:
+#       - Complex configuration
+#       - Missing examples
+#     content_preferences:
+#       - Code-first explanations
+#       - Copy-paste examples
+#
+# For the full template, see:
+# https://github.com/redpanda-data/docs-extensions-and-macros/blob/main/team-standards/personas-template.yaml
+#
+# Current working directory: ${cwd}
+`;
+      return {
+        contents: [{
+          uri: 'redpanda://personas',
+          mimeType: 'text/yaml',
+          text: fallbackContent
+        }]
+      };
+    }
+  } catch (err) {
+    console.error(`Error loading personas: ${err.message}`);
+    throw new Error(`Failed to load personas: ${err.message}`);
+  }
+}
+
 // Handle list tools request
 server.setRequestHandler(ListToolsRequestSchema, async () => {
   return { tools };
 });
 
-// Handle list prompts request
-server.setRequestHandler(ListPromptsRequestSchema, async () => {
-  const allPrompts = promptCache.getAll();
-  return { prompts: promptsToMcpFormat(allPrompts) };
-});
+// Prompts handler removed - prompts migrated to docs-team-standards plugin
 
 // Handle list resources request
 server.setRequestHandler(ListResourcesRequestSchema, async () => {
@@ -553,49 +581,7 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
   return getResourceContent(uri);
 });
 
-// Handle get prompt request
-server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
-
-  // Record usage
-  usageStats.recordPrompt(name);
-
-  // Get prompt from cache
-  const prompt = promptCache.get(name);
-  if (!prompt) {
-    throw new Error(`Unknown prompt: ${name}`);
-  }
-
-  // Validate arguments if schema exists
-  if (prompt.arguments && prompt.arguments.length > 0) {
-    try {
-      validatePromptArguments(name, args, prompt.arguments);
-    } catch (err) {
-      return {
-        messages: [{
-          role: 'user',
-          content: {
-            type: 'text',
-            text: `Error: ${err.message}`
-          }
-        }]
-      };
-    }
-  }
-
-  // Build prompt with arguments
-  const promptText = buildPromptWithArguments(prompt, args);
-
-  return {
-    messages: [{
-      role: 'user',
-      content: {
-        type: 'text',
-        text: promptText
-      }
-    }]
-  };
-});
+// Get prompt handler removed - prompts migrated to docs-team-standards plugin
 
 // Handle tool execution
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -666,40 +652,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
 // Start the server
 async function main() {
-  // Load and validate prompts
-  console.error('Loading prompts...');
-  const prompts = loadAllPrompts(baseDir, promptCache);
-  console.error(`Loaded ${prompts.length} prompts`);
-
-  // Validate configuration at startup
-  console.error('Validating MCP configuration...');
-  const validation = validateMcpConfiguration({
-    resources,
-    resourceMap,
-    prompts,
-    baseDir
-  });
-
-  if (!validation.valid) {
-    console.error('\nMCP Configuration validation FAILED:');
-    validation.errors.forEach(err => console.error(`  ${err}`));
-    console.error('\nServer cannot start with invalid configuration.');
-    process.exit(1);
-  }
-
-  if (validation.warnings.length > 0) {
-    console.error('\nWarnings:');
-    validation.warnings.forEach(warn => console.error(`  ⚠ ${warn}`));
-  }
-
-  console.error('Configuration valid');
-
-  // Enable file watching in dev mode
-  if (process.env.MCP_DEV_MODE === 'true') {
-    watchPrompts(baseDir, promptCache, (reloadedPrompts) => {
-      console.error(`Prompts reloaded: ${reloadedPrompts.length} available`);
-    });
-  }
+  // Prompts have been migrated to docs-team-standards plugin (skills/agents)
+  // No prompts to load from this MCP server
+  console.error('Prompts: migrated to docs-team-standards plugin');
 
   // Initialize usage tracking
   createShutdownHandler(usageStats, baseDir);
@@ -722,11 +677,9 @@ async function main() {
   console.error(`Server version: ${packageJson.version}`);
   console.error(`Working directory: ${process.cwd()}`);
   console.error(`Repository root: ${repoInfo.root} (${repoInfo.detected ? repoInfo.type : 'not detected'})`);
+  console.error('Mode: execution tools only (prompts/resources migrated to docs-team-standards)');
   console.error('Background job queue: enabled');
   console.error('Command timeout: 10 minutes');
-  console.error('Auto-discovery: enabled');
-  console.error('Startup validation: enabled');
-  console.error('Usage telemetry: enabled');
 }
 
 main().catch((error) => {

package/bin/doc-tools.js

@@ -400,10 +400,8 @@ programCli
   })
 
 /**
- * @description Validate the MCP server configuration including prompts, resources,
- * and metadata. Reports any issues with prompt definitions or missing files.
- * @why Use this command to verify that all MCP prompts and resources are properly
- * configured before deploying or after making changes to prompt files.
+ * @description Validate the MCP server configuration including tools and resources.
+ * @why Use this command to verify the MCP server is properly configured.
  * @example
  * # Validate MCP configuration
  * npx doc-tools validate-mcp
@@ -411,49 +409,44 @@ programCli
  */
 programCli
   .command('validate-mcp')
-  .description('Validate MCP server configuration (prompts, resources, metadata)')
+  .description('Validate MCP server configuration (tools, resources)')
   .action(() => {
-    const {
-      PromptCache,
-      loadAllPrompts
-    } = require('./mcp-tools/prompt-discovery')
     const {
       validateMcpConfiguration,
       formatValidationResults
     } = require('./mcp-tools/mcp-validation')
 
-    const baseDir = findRepoRoot()
-    const promptCache = new PromptCache()
+    // Tools are defined in doc-tools-mcp.js - we validate the structure
+    const tools = [
+      { name: 'get_antora_structure', description: 'Get Antora documentation structure' },
+      { name: 'get_redpanda_version', description: 'Get latest Redpanda version' },
+      { name: 'get_console_version', description: 'Get latest Console version' },
+      { name: 'generate_property_docs', description: 'Generate property documentation' },
+      { name: 'generate_metrics_docs', description: 'Generate metrics documentation' },
+      { name: 'generate_rpk_docs', description: 'Generate rpk CLI documentation' },
+      { name: 'generate_rpcn_connector_docs', description: 'Generate connector documentation' },
+      { name: 'generate_helm_docs', description: 'Generate Helm chart documentation' },
+      { name: 'generate_crd_docs', description: 'Generate CRD documentation' },
+      { name: 'generate_cloud_regions', description: 'Generate cloud regions documentation' },
+      { name: 'generate_bundle_openapi', description: 'Bundle OpenAPI specifications' },
+      { name: 'review_generated_docs', description: 'Review generated documentation' },
+      { name: 'run_doc_tools_command', description: 'Run raw doc-tools command' },
+      { name: 'get_job_status', description: 'Get background job status' },
+      { name: 'list_jobs', description: 'List background jobs' }
+    ]
 
     const resources = [
       {
-        uri: 'redpanda://style-guide',
-        name: 'Redpanda Documentation Style Guide',
-        description: 'Complete style guide based on Google Developer Documentation Style Guide with Redpanda-specific guidelines',
-        mimeType: 'text/markdown',
-        version: '1.0.0',
-        lastUpdated: '2025-12-11'
+        uri: 'redpanda://personas',
+        name: 'Repository Personas',
+        description: 'Target audience personas loaded from docs-data/personas.yaml'
       }
     ]
 
-    const resourceMap = {
-      'redpanda://style-guide': { file: 'style-guide.md', mimeType: 'text/markdown' }
-    }
-
     try {
-      console.log('Loading prompts...')
-      const prompts = loadAllPrompts(baseDir, promptCache)
-      console.log(`Found ${prompts.length} prompts`)
-
-      console.log('\nValidating configuration...')
-      const validation = validateMcpConfiguration({
-        resources,
-        resourceMap,
-        prompts,
-        baseDir
-      })
-
-      const output = formatValidationResults(validation, { resources, prompts })
+      console.log('Validating MCP configuration...')
+      const validation = validateMcpConfiguration({ tools, resources })
+      const output = formatValidationResults(validation, { tools, resources })
       console.log('\n' + output)
 
       if (!validation.valid) {
@@ -466,74 +459,9 @@ programCli
   })
 
 /**
- * @description Preview an MCP prompt with sample arguments to see the final rendered
- * output. Useful for testing and debugging prompt templates.
- * @why Use this command when developing or modifying MCP prompts to verify the
- * output format and argument substitution works correctly.
- * @example
- * # Preview a prompt with content argument
- * npx doc-tools preview-prompt review-content --content "Sample text"
- *
- * # Preview a prompt with topic and audience
- * npx doc-tools preview-prompt write-docs --topic "Kafka" --audience "developers"
- * @requirements None.
- */
-programCli
-  .command('preview-prompt')
-  .description('Preview a prompt with arguments to see the final output')
-  .argument('<prompt-name>', 'Name of the prompt to preview')
-  .option('--content <text>', 'Content argument (for review/check prompts)')
-  .option('--topic <text>', 'Topic argument (for write prompts)')
-  .option('--audience <text>', 'Audience argument (for write prompts)')
-  .action((promptName, options) => {
-    const {
-      PromptCache,
-      loadAllPrompts,
-      buildPromptWithArguments
-    } = require('./mcp-tools/prompt-discovery')
-
-    const baseDir = findRepoRoot()
-    const promptCache = new PromptCache()
-
-    try {
-      loadAllPrompts(baseDir, promptCache)
-
-      const prompt = promptCache.get(promptName)
-      if (!prompt) {
-        console.error(`Error: Prompt not found: ${promptName}`)
-        console.error(`\nAvailable prompts: ${promptCache.getNames().join(', ')}`)
-        process.exit(1)
-      }
-
-      const args = {}
-      if (options.content) args.content = options.content
-      if (options.topic) args.topic = options.topic
-      if (options.audience) args.audience = options.audience
-
-      const promptText = buildPromptWithArguments(prompt, args)
-
-      console.log('='.repeat(70))
-      console.log(`PROMPT PREVIEW: ${promptName}`)
-      console.log('='.repeat(70))
-      console.log(`Description: ${prompt.description}`)
-      console.log(`Version: ${prompt.version}`)
-      if (prompt.arguments.length > 0) {
-        console.log(`Arguments: ${prompt.arguments.map(a => a.name).join(', ')}`)
-      }
-      console.log('='.repeat(70))
-      console.log('\n' + promptText)
-      console.log('\n' + '='.repeat(70))
-    } catch (err) {
-      console.error(`Error: Preview failed: ${err.message}`)
-      process.exit(1)
-    }
-  })
-
-/**
- * @description Show MCP server version information including available prompts,
- * resources, and optionally usage statistics from previous sessions.
- * @why Use this command to see what MCP capabilities are available and to review
- * usage patterns for optimization.
+ * @description Show MCP server version information including available tools
+ * and optionally usage statistics from previous sessions.
+ * @why Use this command to see what MCP capabilities are available.
  * @example
  * # Show version and capabilities
  * npx doc-tools mcp-version
@@ -548,105 +476,90 @@ programCli
   .option('--stats', 'Show usage statistics if available', false)
   .action((options) => {
     const packageJson = require('../package.json')
-    const {
-      PromptCache,
-      loadAllPrompts
-    } = require('./mcp-tools/prompt-discovery')
-
-    const baseDir = findRepoRoot()
-    const promptCache = new PromptCache()
 
-    try {
-      const prompts = loadAllPrompts(baseDir, promptCache)
-
-      const resources = [
-        {
-          uri: 'redpanda://style-guide',
-          name: 'Redpanda Documentation Style Guide',
-          version: '1.0.0',
-          lastUpdated: '2025-12-11'
-        }
-      ]
+    const tools = [
+      { name: 'get_antora_structure', description: 'Get Antora documentation structure' },
+      { name: 'get_redpanda_version', description: 'Get latest Redpanda version' },
+      { name: 'get_console_version', description: 'Get latest Console version' },
+      { name: 'generate_property_docs', description: 'Generate property documentation' },
+      { name: 'generate_metrics_docs', description: 'Generate metrics documentation' },
+      { name: 'generate_rpk_docs', description: 'Generate rpk CLI documentation' },
+      { name: 'generate_rpcn_connector_docs', description: 'Generate connector documentation' },
+      { name: 'generate_helm_docs', description: 'Generate Helm chart documentation' },
+      { name: 'generate_crd_docs', description: 'Generate CRD documentation' },
+      { name: 'generate_cloud_regions', description: 'Generate cloud regions documentation' },
+      { name: 'generate_bundle_openapi', description: 'Bundle OpenAPI specifications' },
+      { name: 'review_generated_docs', description: 'Structural validation of generated docs' },
+      { name: 'run_doc_tools_command', description: 'Run raw doc-tools command' },
+      { name: 'get_job_status', description: 'Get background job status' },
+      { name: 'list_jobs', description: 'List background jobs' }
+    ]
 
-      console.log('Redpanda Doc Tools MCP Server')
-      console.log('='.repeat(60))
-      console.log(`Server version: ${packageJson.version}`)
-      console.log(`Base directory: ${baseDir}`)
-      console.log('')
+    const resources = [
+      {
+        uri: 'redpanda://personas',
+        name: 'Repository Personas',
+        description: 'Loaded from docs-data/personas.yaml'
+      }
+    ]
 
-      console.log(`Prompts (${prompts.length} available):`)
-      prompts.forEach(prompt => {
-        const args = prompt.arguments.length > 0
-          ? ` [${prompt.arguments.map(a => a.name).join(', ')}]`
-          : ''
-        console.log(`  - ${prompt.name} (v${prompt.version})${args}`)
-        console.log(`    ${prompt.description}`)
-      })
-      console.log('')
+    console.log('Redpanda Doc Tools MCP Server')
+    console.log('='.repeat(60))
+    console.log(`Server version: ${packageJson.version}`)
+    console.log('')
 
-      console.log(`Resources (${resources.length} available):`)
-      resources.forEach(resource => {
-        console.log(`  - ${resource.name} (v${resource.version})`)
-        console.log(`    URI: ${resource.uri}`)
-        console.log(`    Last updated: ${resource.lastUpdated}`)
-      })
-      console.log('')
+    console.log(`Tools (${tools.length} available):`)
+    tools.forEach(tool => {
+      console.log(`  - ${tool.name}`)
+      console.log(`    ${tool.description}`)
+    })
+    console.log('')
 
-      if (options.stats) {
-        const statsPath = path.join(os.tmpdir(), 'mcp-usage-stats.json')
-        if (fs.existsSync(statsPath)) {
-          try {
-            const stats = JSON.parse(fs.readFileSync(statsPath, 'utf8'))
-            console.log('Usage Statistics:')
-            console.log('='.repeat(60))
-
-            if (stats.tools && Object.keys(stats.tools).length > 0) {
-              console.log('\nTool Usage:')
-              Object.entries(stats.tools)
-                .sort(([, a], [, b]) => b.count - a.count)
-                .forEach(([name, data]) => {
-                  console.log(`  ${name}:`)
-                  console.log(`    Invocations: ${data.count}`)
-                  if (data.errors > 0) {
-                    console.log(`    Errors: ${data.errors}`)
-                  }
-                })
-            }
-
-            if (stats.prompts && Object.keys(stats.prompts).length > 0) {
-              console.log('\nPrompt Usage:')
-              Object.entries(stats.prompts)
-                .sort(([, a], [, b]) => b - a)
-                .forEach(([name, count]) => {
-                  console.log(`  ${name}: ${count} invocations`)
-                })
-            }
-
-            if (stats.resources && Object.keys(stats.resources).length > 0) {
-              console.log('\nResource Access:')
-              Object.entries(stats.resources)
-                .sort(([, a], [, b]) => b - a)
-                .forEach(([uri, count]) => {
-                  console.log(`  ${uri}: ${count} reads`)
-                })
-            }
-          } catch (err) {
-            console.error('Failed to parse usage statistics:', err.message)
+    console.log(`Resources (${resources.length} available):`)
+    resources.forEach(resource => {
+      console.log(`  - ${resource.name}`)
+      console.log(`    URI: ${resource.uri}`)
+      console.log(`    ${resource.description}`)
+    })
+    console.log('')
+
+    console.log('Note: Prompts and most resources have been migrated to')
+    console.log('the docs-team-standards Claude Code plugin.')
+    console.log('')
+
+    if (options.stats) {
+      const statsPath = path.join(os.tmpdir(), 'mcp-usage-stats.json')
+      if (fs.existsSync(statsPath)) {
+        try {
+          const stats = JSON.parse(fs.readFileSync(statsPath, 'utf8'))
+          console.log('Usage Statistics:')
+          console.log('='.repeat(60))
+
+          if (stats.tools && Object.keys(stats.tools).length > 0) {
+            console.log('\nTool Usage:')
+            Object.entries(stats.tools)
+              .sort(([, a], [, b]) => b.count - a.count)
+              .forEach(([name, data]) => {
+                console.log(`  ${name}:`)
+                console.log(`    Invocations: ${data.count}`)
+                if (data.errors > 0) {
+                  console.log(`    Errors: ${data.errors}`)
+                }
+              })
           }
-        } else {
-          console.log('No usage statistics available yet.')
-          console.log('Statistics are exported when the MCP server shuts down.')
+        } catch (err) {
+          console.error('Failed to parse usage statistics:', err.message)
         }
+      } else {
+        console.log('No usage statistics available yet.')
+        console.log('Statistics are exported when the MCP server shuts down.')
       }
-
-      console.log('')
-      console.log('For more information, see:')
-      console.log('  mcp/WRITER_EXTENSION_GUIDE.adoc')
-      console.log('  mcp/AI_CONSISTENCY_ARCHITECTURE.adoc')
-    } catch (err) {
-      console.error(`Error: Failed to retrieve version information: ${err.message}`)
-      process.exit(1)
     }
+
+    console.log('')
+    console.log('For more information, see:')
+    console.log('  mcp/WRITER_EXTENSION_GUIDE.adoc')
+    console.log('  mcp/README.adoc')
   })
 
 // ====================================================================