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

package/mcp/templates/README.adoc

@@ -0,0 +1,212 @@
+= MCP Extension Templates
+:toc:
+
+== Overview
+
+This directory contains ready-to-use templates for extending the MCP server. Copy these templates and customize them for your needs.
+
+== Available templates
+
+[cols="1,3"]
+|===
+|Template |Use For
+
+|`prompt-review-template.md`
+|Creating review prompts for specific content types
+
+|`prompt-write-template.md`
+|Creating writing prompts that generate new content
+
+|`resource-template.md`
+|Creating reference resources (guides, checklists, templates)
+|===
+
+== How to use these templates
+
+=== Quick start
+
+. Copy the template you need
+. Replace `[PLACEHOLDERS]` with your content
+. Add YAML frontmatter (for prompts)
+. Validate with `npx doc-tools validate-mcp`
+. Restart Claude Code and test
+
+=== Detailed steps
+
+**Step 1: Choose a template**
+
+Pick the template that matches what you're creating:
+- Review prompts → `prompt-review-template.md`
+- Writing prompts → `prompt-write-template.md`
+- Resources → `resource-template.md`
+
+**Step 2: Copy and rename**
+
+[source,bash]
+----
+# For a prompt
+cp mcp/templates/prompt-review-template.md mcp/prompts/review-api-docs.md
+
+# For a resource
+cp mcp/templates/resource-template.md mcp/team-standards/api-guide.md
+----
+
+**Step 3: Add frontmatter (prompts only)**
+
+Prompts need YAML frontmatter at the top. The templates include placeholder frontmatter - customize it:
+
+[source,yaml]
+----
+---
+description: "Your prompt description"
+version: "1.0.0"
+arguments:
+  content:
+    description: "The content to process"
+    required: true
+---
+----
+
+**Step 4: Customize the content**
+
+Replace all `[PLACEHOLDERS]` with your specific content:
+
+- `[CONTENT-TYPE]` → "API documentation", "troubleshooting guide", etc.
+- `[First thing to check]` → Specific checks for your use case
+- `[Section names]` → Appropriate section names
+
+**Step 5: Validate**
+
+Check your prompt or resource for errors:
+
+[source,bash]
+----
+npx doc-tools validate-mcp
+----
+
+**Step 6: Test**
+
+Restart Claude Code and test your new prompt or resource.
+
+No code editing required - the MCP server auto-discovers files in `mcp/prompts/` and `mcp/team-standards/`!
+
+== Customization tips
+
+=== For review prompts
+
+Focus on:
+- **Specific checks** relevant to the content type
+- **Common mistakes** you see in reviews
+- **Required elements** that must be present
+- **Output format** that's easy to act on
+
+Good checklist items:
+- Concrete and testable
+- Focused on one aspect
+- Clear about what success looks like
+
+=== For writing prompts
+
+Focus on:
+- **Clear structure** that matches your templates
+- **Specific requirements** for the content type
+- **Quality standards** that must be met
+- **Examples** showing what good looks like
+
+Good requirements:
+- Specific and actionable
+- Based on real patterns
+- Include rationale
+
+=== For resources
+
+Focus on:
+- **Practical examples** showing how to apply rules
+- **Good vs bad** comparisons
+- **Checklists** for quick verification
+- **Clear organization** that's easy to scan
+
+Good resources:
+- Scannable with clear headings
+- More examples than rules
+- Actionable guidance
+
+== Examples
+
+=== Example: Review prompt for API docs
+
+[source,bash]
+----
+# Copy template
+cp mcp/templates/prompt-review-template.md mcp/prompts/review-api-docs.md
+
+# Edit and customize
+vi mcp/prompts/review-api-docs.md
+----
+
+Key customizations:
+- Replace `[CONTENT-TYPE]` with "API documentation"
+- Add checks for: authentication section, request/response examples, error codes
+- Add common issues: missing status codes, unclear parameter descriptions
+- Define output format for API-specific feedback
+
+=== Example: Resource for code examples
+
+[source,bash]
+----
+# Copy template
+cp mcp/templates/resource-template.md mcp/team-standards/code-examples-guide.md
+
+# Edit and customize
+vi mcp/team-standards/code-examples-guide.md
+----
+
+Key customizations:
+- Add language-specific guidelines (bash, Python, YAML)
+- Include examples of good vs bad code formatting
+- Add checklist for code review
+- Show proper use of code block roles
+
+== Template placeholders reference
+
+Common placeholders you'll find in templates:
+
+[cols="1,2"]
+|===
+|Placeholder |Replace With
+
+|`[CONTENT-TYPE]`
+|Specific type: "API docs", "tutorials", "troubleshooting guides"
+
+|`[First thing to check]`
+|Specific checks relevant to your use case
+
+|`[Required section X]`
+|Sections that must be present
+
+|`[Resource Name]`
+|Name of your resource
+
+|`[Main Section X]`
+|Appropriate section names for your content
+
+|`[Check item X]`
+|Specific checklist items
+|===
+
+== Getting help
+
+- See link:../WRITER_EXTENSION_GUIDE.adoc[Writer Extension Guide] for complete instructions
+- Check existing prompts in `mcp/prompts/` for examples
+- Review existing resources in `mcp/team-standards/` for patterns
+- Ask your team lead for guidance
+
+== Contributing
+
+When you create a great prompt or resource:
+
+. Add it to the examples in link:../WRITER_EXTENSION_GUIDE.adoc[Writer Extension Guide]
+. Share it with the team
+. Consider if it should become a new template
+
+The more prompts and resources we build, the more consistent and efficient our docs team becomes!

package/mcp/templates/prompt-review-template.md

@@ -0,0 +1,80 @@
+---
+description: "Review [CONTENT-TYPE] for [specific aspects you're checking]"
+version: "1.0.0"
+arguments:
+  content:
+    description: "The [CONTENT-TYPE] content to review"
+    required: true
+---
+
+# Review [CONTENT-TYPE]
+
+You are reviewing [CONTENT-TYPE] for the Redpanda documentation team.
+
+## Your Task
+
+Review the provided content and check for:
+
+1. [First thing to check]
+2. [Second thing to check]
+3. [Third thing to check]
+4. [Additional checks...]
+
+## Resources to Reference
+
+Read these resources before reviewing:
+- `redpanda://style-guide` - Complete style guide
+- Official glossary for terminology:
+  - GitHub: https://github.com/redpanda-data/docs/tree/shared/modules/terms/partials
+  - Published: https://docs.redpanda.com/current/reference/glossary/
+- [Add other relevant resources]
+
+## Standards for [CONTENT-TYPE]
+
+[Describe what makes good content of this type]
+
+### Required Sections
+
+All [CONTENT-TYPE] documentation must include:
+- [Required section 1]
+- [Required section 2]
+- [Required section 3]
+
+### Format Requirements
+
+[Specific formatting rules for this content type]
+
+### Common Issues to Check
+
+- [Common mistake 1]
+- [Common mistake 2]
+- [Common mistake 3]
+
+## Output Format
+
+Provide a structured review:
+
+### Critical Issues (must fix)
+
+For each critical issue:
+- **Location**: [Section/paragraph reference]
+- **Issue**: [What's wrong]
+- **Fix**: [Specific correction]
+- **Reason**: [Why it matters]
+
+### Suggestions (should consider)
+
+For each suggestion:
+- **Location**: [Where it appears]
+- **Current**: [What it says now]
+- **Suggested**: [Better alternative]
+- **Reason**: [Why the suggestion helps]
+
+### Positive Elements
+
+What works well:
+- [Good thing 1]
+- [Good thing 2]
+- [Good thing 3]
+
+---

package/mcp/templates/prompt-write-template.md

@@ -0,0 +1,110 @@
+---
+description: "Generate [CONTENT-TYPE] following team standards"
+version: "1.0.0"
+arguments:
+  topic:
+    description: "The topic to write about"
+    required: true
+  target_module:
+    description: "Where in Antora structure this belongs (optional)"
+    required: false
+  context:
+    description: "Additional context or requirements"
+    required: false
+---
+
+# Write [CONTENT-TYPE]
+
+You are writing [CONTENT-TYPE] for the Redpanda documentation team.
+
+## Your Task
+
+Create [CONTENT-TYPE] that follows our team standards.
+
+## Resources to Read First
+
+- `redpanda://style-guide` - Complete style guide
+- Official glossary for terminology:
+  - GitHub: https://github.com/redpanda-data/docs/tree/shared/modules/terms/partials
+  - Published: https://docs.redpanda.com/current/reference/glossary/
+- `redpanda://[content-type]-template` - Template for this content type (if available)
+- [Add other relevant resources]
+
+Use `get_antora_structure` tool to understand the documentation organization.
+
+## Standards for [CONTENT-TYPE]
+
+### Structure
+
+[CONTENT-TYPE] should follow this structure:
+
+1. [Section 1]
+   - [What goes here]
+2. [Section 2]
+   - [What goes here]
+3. [Section 3]
+   - [What goes here]
+
+### Content Requirements
+
+[What must be included:]
+- [Requirement 1]
+- [Requirement 2]
+- [Requirement 3]
+
+### Writing Style
+
+Follow these style guidelines:
+- Present tense
+- Active voice
+- Second person ("you")
+- Sentence case for all headings except title
+- Imperative form for instructions (no gerunds)
+- Avoid overuse of bold or em dashes
+
+### AsciiDoc Format
+
+- All xrefs must include module name
+- Use `glossterm` macro for glossary terms on first mention
+- Code blocks use appropriate roles (`.no-copy` for outputs)
+- Custom macros used correctly
+
+## Quality Checklist
+
+Before finalizing, verify:
+- [ ] Structure follows template
+- [ ] All required sections included
+- [ ] Code examples are realistic and tested
+- [ ] Terminology uses approved terms
+- [ ] Glossary terms use `glossterm` macro
+- [ ] All xrefs include module names
+- [ ] Voice is clear and conversational
+- [ ] Headings use sentence case
+
+## Output Format
+
+Provide complete [CONTENT-TYPE] in AsciiDoc format:
+
+```asciidoc
+= Page Title
+:description: Brief description
+
+Opening content explaining what this covers.
+
+== First section
+
+Content here.
+
+== Second section
+
+More content.
+```
+
+---
+
+Please provide:
+1. **Topic**: What this [CONTENT-TYPE] should cover
+2. **Target module** (optional): Where in Antora structure this belongs
+3. **[Other context]**: [Additional information needed]
+
+I'll create complete [CONTENT-TYPE] following all team standards.

package/mcp/templates/resource-template.md

@@ -0,0 +1,76 @@
+# [Resource Name]
+
+[Brief description of what this resource provides]
+
+## Overview
+
+[1-2 paragraphs explaining when and how to use this resource]
+
+## [Main Section 1]
+
+[Content for this section]
+
+### Subsection
+
+[Details with examples]
+
+Example:
+
+```asciidoc
+[Example code or content here]
+```
+
+## [Main Section 2]
+
+[Content for this section]
+
+### Key Points
+
+- [Important point 1]
+- [Important point 2]
+- [Important point 3]
+
+### Examples
+
+Good:
+```
+[Good example]
+```
+
+Bad:
+```
+[Bad example - what to avoid]
+```
+
+## [Main Section 3]
+
+[Additional content]
+
+## Checklist
+
+Use this checklist to verify compliance:
+
+- [ ] [Check item 1]
+- [ ] [Check item 2]
+- [ ] [Check item 3]
+- [ ] [Check item 4]
+
+## Common Mistakes
+
+[List common mistakes and how to avoid them]
+
+### Mistake 1
+
+Problem: [What people do wrong]
+Solution: [How to do it right]
+
+### Mistake 2
+
+Problem: [What people do wrong]
+Solution: [How to do it right]
+
+## References
+
+- [Link to related resource 1]
+- [Link to related resource 2]
+- [Link to external documentation]

package/package.json

@@ -1,19 +1,21 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "4.12.6",
+  "version": "4.13.1",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
     "extension",
     "macro",
     "documentation",
-    "redpanda"
+    "redpanda",
+    "mcp"
   ],
   "author": {
     "name": "Redpanda Docs Team"
   },
   "bin": {
-    "doc-tools": "./bin/doc-tools.js"
+    "doc-tools": "./bin/doc-tools.js",
+    "doc-tools-mcp": "./bin/doc-tools-mcp.js"
   },
   "scripts": {
     "install-test-dependencies": "doc-tools install-test-dependencies",
@@ -22,8 +24,12 @@
     "build": "antora --to-dir docs --fetch local-antora-playbook.yml",
     "serve": "wds --node-resolve --open preview/test/ --watch --root-dir docs",
     "test": "jest",
+    "test:mcp": "jest __tests__/mcp/",
+    "test:mcp:integration": "jest __tests__/mcp/integration.test.js",
+    "test:mcp:contract": "jest __tests__/mcp/cli-contract.test.js",
     "test:python": "./__tests__/tools/property-extractor/setup-and-test.sh",
     "test:all": "npm run test && npm run test:python",
+    "generate:cli-docs": "node tools/generate-cli-docs.js",
     "bundle:admin": "doc-tools generate bundle-openapi --surface admin",
     "bundle:connect": "doc-tools generate bundle-openapi --surface connect",
     "bundle:both": "doc-tools generate bundle-openapi --surface both"
@@ -75,7 +81,8 @@
     "bin",
     "cli-utils",
     "tools",
-    "docker-compose"
+    "docker-compose",
+    "mcp"
   ],
   "license": "ISC",
   "repository": {
@@ -85,14 +92,17 @@
   "dependencies": {
     "@asciidoctor/tabs": "^1.0.0-beta.6",
     "@bufbuild/buf": "^1.28.1",
+    "@modelcontextprotocol/sdk": "^1.0.4",
     "@octokit/core": "^6.1.2",
     "@octokit/plugin-retry": "^7.1.1",
     "@octokit/rest": "^21.0.1",
     "@redocly/cli": "^2.2.0",
+    "ajv": "^8.12.0",
     "algoliasearch": "^4.17.0",
     "chalk": "4.1.2",
     "cheerio": "^1.1.2",
     "commander": "^14.0.0",
+    "glob": "^11.0.0",
     "gulp": "^4.0.2",
     "gulp-connect": "^5.7.0",
     "handlebars": "^4.7.8",
@@ -117,6 +127,7 @@
     "@antora/cli": "3.1.4",
     "@antora/site-generator": "3.1.4",
     "@web/dev-server": "^0.2.5",
-    "jest": "^29.7.0"
+    "jest": "^29.7.0",
+    "jest-junit": "^16.0.0"
   }
 }

package/tools/bundle-openapi.js

@@ -12,8 +12,8 @@ const yaml = require('yaml');
  * and validates that the result matches MAJOR.MINOR.PATCH with optional pre-release/build metadata.
  * Throws if the input is not a non-empty string or does not conform to the expected version format.
  *
- * @param {string} tag - Git tag (e.g., 'v25.1.1', '25.1.1', or 'dev').
- * @returns {string} Normalized version (e.g., '25.1.1' or 'dev').
+ * @param {string} tag - Git tag (for example, 'v25.1.1', '25.1.1', or 'dev').
+ * @returns {string} Normalized version (for example, '25.1.1' or 'dev').
  * @throws {Error} If `tag` is not a non-empty string or does not match the semantic version pattern.
  */
 function normalizeTag(tag) {
@@ -44,8 +44,8 @@ function normalizeTag(tag) {
  *
  * Accepts a semantic version like `25.1.1` and yields `25.1`. The special value
  * `'dev'` is returned unchanged.
- * @param {string} version - Semantic version (e.g., `'25.1.1'`) or `'dev'`.
- * @returns {string} The `major.minor` string (e.g., `'25.1'`) or `'dev'`.
+ * @param {string} version - Semantic version (for example, `'25.1.1'`) or `'dev'`.
+ * @returns {string} The `major.minor` string (for example, `'25.1'`) or `'dev'`.
  * @throws {Error} If `version` is not a non-empty string, lacks major/minor parts, or if major/minor are not numeric.
  */
 function getMajorMinor(version) {
@@ -554,13 +554,13 @@ function postProcessBundle(filePath, options, quiet = false) {
  * Bundle OpenAPI fragments for the specified API surface(s) from a repository tag and write the resulting bundled YAML files to disk.
  *
  * @param {Object} options - Configuration options.
- * @param {string} options.tag - Git tag to checkout (e.g., 'v25.1.1').
+ * @param {string} options.tag - Git tag to checkout (for example, 'v25.1.1').
  * @param {'admin'|'connect'|'both'} options.surface - API surface to process.
  * @param {string} [options.output] - Standalone output file path; when provided, used for the single output file.
  * @param {string} [options.outAdmin] - Output path for the admin API when integrating with doc-tools mode.
  * @param {string} [options.outConnect] - Output path for the connect API when integrating with doc-tools mode.
  * @param {string} [options.repo] - Repository URL to clone (defaults to https://github.com/redpanda-data/redpanda.git).
- * @param {string} [options.adminMajor] - Admin API major version string used for metadata (e.g., 'v2.0.0').
+ * @param {string} [options.adminMajor] - Admin API major version string used for metadata (for example, 'v2.0.0').
  * @param {boolean} [options.useAdminMajorVersion] - When true and processing the admin surface, use `adminMajor` for the bundle info.version.
  * @param {boolean} [options.quiet=false] - Suppress logging to stdout/stderr when true.
  * @returns {Object|Object[]} An object (for a single surface) or an array of objects (for both surfaces) with fields:
@@ -625,9 +625,19 @@ async function bundleOpenAPI(options) {
     if (!quiet) {
       console.log('📥 Cloning redpanda repository...');
     }
-    
-    const repositoryUrl = repo || 'https://github.com/redpanda-data/redpanda.git';
-    
+
+    const { getAuthenticatedGitHubUrl, hasGitHubToken } = require('../cli-utils/github-token');
+
+    let repositoryUrl = repo || 'https://github.com/redpanda-data/redpanda.git';
+
+    // Use token if available for better rate limits and reliability
+    if (hasGitHubToken() && repositoryUrl.includes('github.com')) {
+      repositoryUrl = getAuthenticatedGitHubUrl(repositoryUrl);
+      if (!quiet) {
+        console.log('🔑 Using authenticated clone (token provided)');
+      }
+    }
+
     try {
       execSync(`git clone --depth 1 --branch ${tag} ${repositoryUrl} redpanda`, {
         cwd: tempDir,
@@ -778,7 +788,7 @@ if (require.main === module) {
   program
     .name('bundle-openapi')
     .description('Bundle OpenAPI fragments from Redpanda repository')
-    .requiredOption('-t, --tag <tag>', 'Git tag to checkout (e.g., v25.1.1)')
+    .requiredOption('-t, --tag <tag>', 'Git tag to checkout (for example, v25.1.1)')
     .requiredOption('-s, --surface <surface>', 'API surface', (value) => {
       if (!['admin', 'connect', 'both'].includes(value)) {
         throw new Error('Invalid API surface. Must be "admin", "connect", or "both"');

package/tools/cloud-regions/generate-cloud-regions.js

@@ -203,7 +203,7 @@ function processCloudRegions(yamlText) {
  * @param {string} options.repo - GitHub repository name.
  * @param {string} options.path - Path to the YAML file within the repository.
  * @param {string} [options.ref='main'] - Git reference (branch, tag, or commit SHA).
- * @param {string} [options.format='md'] - The output format (e.g., 'md' for Markdown).
+ * @param {string} [options.format='md'] - The output format (for example, 'md' for Markdown).
  * @param {string} [options.token] - Optional GitHub token for authentication.
  * @param {string} [options.template] - Optional path to custom Handlebars template.
  * @returns {string} The rendered cloud regions output.

package/tools/fetch-from-github.js

@@ -27,20 +27,34 @@ async function saveFile(content, saveDir, filename) {
   console.log(`Saved: ${target}`);
 }
 
-async function fetchFromGithub(owner, repo, remotePath, saveDir, customFilename) {
+/**
+ * Fetch file or directory from GitHub repository
+ * @param {string} owner - Repository owner (for example, "redpanda-data")
+ * @param {string} repo - Repository name (for example, "redpanda-operator")
+ * @param {string} remotePath - Path to file or directory in repository
+ * @param {string} saveDir - Local directory to save files to
+ * @param {string} [customFilename] - Optional custom filename (for single files)
+ * @param {string} [ref=null] - Git ref (branch, tag, or commit SHA). Defaults to repository's default branch if null
+ * @returns {Promise<void>}
+ */
+async function fetchFromGithub(owner, repo, remotePath, saveDir, customFilename, ref = null) {
   const octokit = await loadOctokit();
 
   try {
-    const resp = await octokit.repos.getContent({ owner, repo, path: remotePath });
+    const params = { owner, repo, path: remotePath };
+    if (ref) {
+      params.ref = ref;
+    }
+    const resp = await octokit.repos.getContent(params);
     if (Array.isArray(resp.data)) {
       // directory
       for (const item of resp.data) {
         if (item.type === 'file') {
-          await fetchFromGithub(owner, repo, item.path, saveDir, customFilename);
+          await fetchFromGithub(owner, repo, item.path, saveDir, customFilename, ref);
         } else if (item.type === 'dir') {
           // For directories, maintain the directory structure
           const nestedDir = path.join(saveDir, path.basename(item.path));
-          await fetchFromGithub(owner, repo, item.path, nestedDir);
+          await fetchFromGithub(owner, repo, item.path, nestedDir, null, ref);
         }
       }
     } else {

package/tools/gen-rpk-ascii.py

@@ -18,7 +18,9 @@ suggestedReadings = """
 
 
 cmd_dict = {}
-basic_commands_docker = ["docker","exec","-it"]
+# Use 'docker exec' without -it flags for non-interactive/background execution
+# -it flags require a TTY and fail in CI/background jobs
+basic_commands_docker = ["docker", "exec"]
 basic_commands_docker.append("redpanda-1")
 rpk_basic_command = ["rpk"]