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

package/mcp/CLI_INTERFACE.adoc

@@ -0,0 +1,384 @@
+= CLI Interface Contract
+:toc:
+:toclevels: 3
+
+This document describes the CLI interface contract that the MCP server depends on. These contracts are verified by the CLI contract tests to ensure the MCP server continues to work as expected when the CLI changes.
+
+The MCP server wraps the `npx doc-tools` CLI to provide a natural language interface to Claude Code. The CLI must maintain specific commands, flags, and output formats for the MCP server to function correctly.
+
+== Command structure
+
+All commands follow the pattern:
+
+[,bash]
+----
+npx doc-tools <command> [subcommand] [flags]
+----
+
+== Top-level commands
+
+=== generate
+
+Generate various types of documentation.
+
+[,bash]
+----
+npx doc-tools generate <subcommand> [flags]
+----
+
+Subcommands are documented in the <<Generate subcommands>> section.
+
+=== get-redpanda-version
+
+Get the latest Redpanda version information.
+
+[,bash]
+----
+npx doc-tools get-redpanda-version [--beta]
+----
+
+*Output format:*
+
+[,bash]
+----
+REDPANDA_VERSION=v25.3.1
+REDPANDA_DOCKER_TAG=docker.redpanda.com/redpandadata/redpanda:v25.3.1
+REDPANDA_RELEASE_NOTES=https://github.com/redpanda-data/redpanda/releases/tag/v25.3.1
+----
+
+*Flags:*
+
+--beta:: Get the latest beta/RC version instead of stable (optional)
+
+=== get-console-version
+
+Get the latest Redpanda Console version information.
+
+[,bash]
+----
+npx doc-tools get-console-version
+----
+
+*Output format:*
+
+[,bash]
+----
+CONSOLE_VERSION=v2.7.2
+CONSOLE_DOCKER_TAG=docker.redpanda.com/redpandadata/console:v2.7.2
+CONSOLE_RELEASE_NOTES=https://github.com/redpanda-data/console/releases/tag/v2.7.2
+----
+
+=== --version
+
+Display the doc-tools version.
+
+[,bash]
+----
+npx doc-tools --version
+----
+
+*Output format:*
+
+[,bash]
+----
+<major>.<minor>.<patch>
+----
+
+Example: `1.2.3`
+
+== Generate subcommands
+
+=== property-docs
+
+Generate Redpanda configuration property documentation.
+
+[,bash]
+----
+npx doc-tools generate property-docs --tag <version> [options]
+----
+
+*Required flags:*
+
+--tag:: Redpanda version to generate docs for (for example, `v25.3.1`, `25.3.1`, or `latest`)
+
+*Optional flags:*
+
+--generate-partials:: Generate AsciiDoc partials in addition to JSON
+--cloud-support:: Include cloud support information
+--overrides:: Path to property overrides JSON file
+
+*Output:*
+
+Creates one or more of:
+
+* `modules/reference/partials/properties.json`
+* `modules/reference/partials/cluster-properties.adoc` (with `--generate-partials`)
+* `modules/reference/partials/broker-properties.adoc` (with `--generate-partials`)
+* `modules/reference/partials/tunable-properties.adoc` (with `--generate-partials`)
+* `modules/reference/partials/topic-properties.adoc` (with `--generate-partials`)
+
+=== metrics-docs
+
+Generate Redpanda metrics documentation.
+
+[,bash]
+----
+npx doc-tools generate metrics-docs --tag <version>
+----
+
+*Required flags:*
+
+--tag:: Redpanda version to generate docs for
+
+*Output:*
+
+Creates `modules/reference/pages/public-metrics-reference.adoc`
+
+=== rpk-docs
+
+Generate RPK command-line documentation.
+
+[,bash]
+----
+npx doc-tools generate rpk-docs --tag <version>
+----
+
+*Required flags:*
+
+--tag:: Redpanda version to generate docs for
+
+*Output:*
+
+Creates AsciiDoc files in `autogenerated/v<version>/rpk/`
+
+=== rpcn-connector-docs
+
+Generate Redpanda Connect connector documentation.
+
+[,bash]
+----
+npx doc-tools generate rpcn-connector-docs [options]
+----
+
+*Optional flags:*
+
+--fetch-connectors:: Fetch connector definitions from Redpanda Connect repository
+--draft-missing:: Create draft pages for missing connectors
+--update-whats-new:: Update the what's new page
+--include-bloblang:: Include Bloblang documentation
+--data-dir:: Directory containing connector data
+--old-data:: Path to previous connector data for comparison
+--csv:: Export connector data as CSV
+--overrides:: Path to overrides JSON file
+
+*Output:*
+
+Creates component documentation files in `modules/reference/pages/redpanda-connect/components/`
+
+=== helm-spec
+
+Generate Helm chart specification documentation.
+
+[,bash]
+----
+npx doc-tools generate helm-spec [options]
+----
+
+*Optional flags:*
+
+--chart-dir:: Path to Helm chart directory
+--tag:: Helm chart version
+--readme:: Include README content
+--output-dir:: Output directory for generated files
+--output-suffix:: Suffix for output files
+
+=== cloud-regions
+
+Generate cloud regions documentation.
+
+[,bash]
+----
+npx doc-tools generate cloud-regions [options]
+----
+
+*Optional flags:*
+
+--output:: Output file path
+--format:: Output format (json, yaml, adoc)
+--owner:: GitHub repository owner
+--repo:: GitHub repository name
+--path:: Path to regions file in repository
+--ref:: Git reference (branch, tag, commit)
+--template:: AsciiDoc template file
+--dry-run:: Show what would be generated without writing files
+
+=== crd-spec
+
+Generate Custom Resource Definition (CRD) specification documentation.
+
+[,bash]
+----
+npx doc-tools generate crd-spec --tag <version> [options]
+npx doc-tools generate crd-spec --branch <branch> [options]
+----
+
+*Required flags (one of):*
+
+--tag:: Redpanda Operator version tag (for released content)
+--branch:: Branch name (for in-progress content)
+
+*Optional flags:*
+
+--source-path:: Path to CRD source files
+--depth:: Maximum depth for nested properties
+--templates-dir:: Directory containing documentation templates
+--output:: Output directory
+
+=== bundle-openapi
+
+Bundle OpenAPI specifications.
+
+[,bash]
+----
+npx doc-tools generate bundle-openapi --tag <version> [options]
+----
+
+*Required flags:*
+
+--tag:: Redpanda version for API specifications
+
+*Optional flags:*
+
+--repo:: Repository to fetch from
+--surface:: API surface to bundle (admin, connect, or both)
+--out-admin:: Output path for admin API bundle
+--out-connect:: Output path for connect API bundle
+--admin-major:: Major version for admin API
+--use-admin-major-version:: Use major version in admin API bundle
+--quiet:: Suppress output messages
+
+== Output format contracts
+
+=== Version commands
+
+Version commands (`get-redpanda-version`, `get-console-version`) must output key-value pairs in the format:
+
+[,bash]
+----
+KEY=value
+----
+
+Lines starting with `#` are treated as comments and ignored by the MCP server.
+
+=== Generate commands
+
+Generate commands should:
+
+* Write to stdout for informational messages
+* Write to stderr for errors
+* Exit with code 0 on success
+* Exit with non-zero code on failure
+
+The MCP server parses stdout to extract:
+
+* File counts (for example, "Generated 342 properties")
+* File paths created
+* Success/failure status
+
+== Error handling contracts
+
+=== Missing required parameters
+
+Commands must exit with non-zero status when required parameters are missing.
+
+Example:
+
+[,bash]
+----
+$ npx doc-tools generate property-docs
+Error: Required flag --tag is missing
+$ echo $?
+1
+----
+
+=== Invalid flags
+
+Commands must exit with non-zero status when invalid flags are provided.
+
+Example:
+
+[,bash]
+----
+$ npx doc-tools generate property-docs --invalid-flag-xyz
+Error: Unknown flag: --invalid-flag-xyz
+$ echo $?
+1
+----
+
+=== Nonexistent commands
+
+The CLI must exit with non-zero status when nonexistent commands are called.
+
+Example:
+
+[,bash]
+----
+$ npx doc-tools generate nonexistent-command
+Error: Unknown command: nonexistent-command
+$ echo $?
+1
+----
+
+=== Network errors
+
+Network errors (for example, GitHub API failures) are acceptable for version commands, but:
+
+* Must write error message to stderr
+* Must exit with non-zero status
+* Error message should indicate the network issue
+
+== Version compatibility
+
+The CLI must support the `--version` flag to output the current version.
+
+Format: `<major>.<minor>.<patch>`
+
+This allows the MCP server to verify compatibility and provide helpful error messages if the CLI version is incompatible.
+
+== Stability guarantees
+
+The MCP server depends on these CLI contracts remaining stable:
+
+*Command names and subcommands* must not change without a major version bump.
+
+*Required flags* must not be removed or renamed without a major version bump.
+
+*Output formats* for version commands must remain parseable.
+
+*Exit codes* must follow Unix conventions (0 = success, non-zero = failure).
+
+*Optional flags* may be added without breaking the MCP server.
+
+*New subcommands* may be added without breaking the MCP server.
+
+== Testing
+
+The `cli-contract.test.js` test suite verifies these contracts automatically. All tests must pass before releasing a new version of doc-tools that could affect the MCP server.
+
+Test categories:
+
+* Command structure - Verifies commands and subcommands exist
+* Flag support - Verifies required and optional flags are present
+* Output format - Verifies output can be parsed correctly
+* Error handling - Verifies proper exit codes and error messages
+* Version compatibility - Verifies version information is available
+
+== Breaking changes
+
+If a breaking change to the CLI is necessary:
+
+. Update the CLI with the breaking change
+. Increment the major version in package.json
+. Update the MCP server to handle both old and new interfaces (if possible)
+. Update the CLI contract tests to verify the new interface
+. Update this document with the new contract

package/mcp/COSTS.adoc

@@ -0,0 +1,167 @@
+= MCP Tool Costs
+:description: Cost reference for Redpanda documentation MCP server tools
+
+The typical cost range is $0.017 - $0.190 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).
+
+== Cost factors
+
+You control costs through:
+
+* *Model selection*: Choose the appropriate model when starting Claude Code (Haiku for simple tasks, Sonnet for most work, Opus for complex reasoning)
+* *Prompt caching*: The MCP server caches style guides and frequently-used content, reducing costs for repeated operations
+* *Content size*: Larger documents and more comprehensive reviews increase costs proportionally
+
+== Cost by tool
+
+[cols="2m,4a,1a"]
+|===
+|Tool |Prompt |Cost (USD)
+
+|get_antora_structure
+|Get the Antora structure
+|0.055
+
+|get_redpanda_version
+|Get the latest Redpanda version
+|0.033
+
+|get_console_version
+|Get the latest Redpanda Console version
+|0.033
+
+|generate_property_docs
+|Generate property docs for tag v25.3.1
+|0.076
+
+|generate_metrics_docs
+|Generate metrics docs for tag v25.3.1
+|0.072
+
+|generate_rpk_docs
+|Generate RPK docs for tag v25.3.1
+|0.034
+
+|generate_rpcn_connector_docs
+|Generate Redpanda Connect connector docs
+|0.072
+
+|generate_helm_docs
+|Generate Helm docs for tag v25.1.2
+|0.052
+
+|generate_crd_docs
+|Generate CRD docs for tag operator/v25.3.1
+|0.084
+
+|generate_bundle_openapi
+|Bundle OpenAPI for tag v25.3.1
+|0.068
+
+|generate_cloud_regions
+|Generate cloud regions table
+|0.051
+
+|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
+|===
+
+== How to measure costs
+
+To track costs during testing:
+
+. Run a single MCP tool operation.
+. Use the `/cost` command to view accumulated costs.
+. Record the cost for that operation.
+. Restart Claude Code to reset costs for the next measurement.
+
+Example:
+
+[source,bash]
+----
+# In Claude Code CLI
+> Get the latest Redpanda version
+> /cost
+----
+
+The `/cost` command shows:
+
+* Total cost for the session
+* Duration (API time and wall time)
+* Code changes made
+* Usage breakdown by model (input/output tokens, cache usage)
+
+=== API time and wall time
+
+*API time (API duration)*:: The total time the Claude API spent actively processing and generating responses. This is what you're billed for.
+
+*Wall time (wall clock time)*:: The total elapsed time from start to finish of your session. This includes API processing time, network latency, time between requests, and time spent reading/thinking.
+
+For example:
+----
+Total duration (API):  52s
+Total duration (wall): 3m 31s
+----
+
+In this case:
+
+* API used 52 seconds of compute time (billable)
+* The session took 3 minutes 31 seconds total (user experience)
+* The 159-second difference includes network time, reading responses, and pauses between operations
+
+== Choosing the right model
+
+The model you use significantly affects costs. Start Claude Code with the appropriate model for your work:
+
+[source,bash]
+----
+# Haiku - Fast and cheap (best for simple tasks)
+claude --model haiku
+
+# Sonnet - Balanced (default, good for most work)
+claude --model sonnet
+
+# Opus - Most capable (use for complex reasoning)
+claude --model opus
+----
+
+=== Model recommendations by task
+
+*Use Haiku for:*
+
+* Generating documentation from structured data (properties, metrics, RPK commands)
+* Simple content reviews focused on terminology or style
+* Quick operations that don't require deep reasoning
+
+*Use Sonnet for:*
+
+* Comprehensive content reviews
+* Working on complex documentation tasks
+* Most day-to-day documentation work
+
+*Use Opus for:*
+
+* Extremely complex reasoning tasks
+* Architectural decisions about documentation structure
+* Currently not needed for most documentation tasks
+
+== 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