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

package/mcp/README.adoc

@@ -0,0 +1,172 @@
+= MCP Server Documentation
+:toc:
+:toclevels: 2
+
+Documentation for the Redpanda Doc Tools MCP (Model Context Protocol) server.
+
+The MCP server exposes `doc-tools` functionality to Claude Code, allowing technical writers to automate documentation tasks through natural conversation. No CLI knowledge required.
+
+== Documentation
+
+=== For users (technical writers)
+
+link:USER_GUIDE.adoc[**User guide**]:: Complete guide to using the MCP server with Claude Code
++
+* Setup and installation
+* Available tools, prompts, and resources
+* Usage examples and workflows
+* Troubleshooting
+
+link:WRITER_EXTENSION_GUIDE.adoc[**Writer extension guide**]:: How to extend the MCP server (no coding required)
++
+* Adding new prompts for common tasks
+* Adding new resources (style guides, templates)
+* Validation and preview commands
+* Best practices and examples
+
+link:templates/README.adoc[**Extension templates**]:: Ready-to-use templates for extending the MCP server
++
+* Templates for review prompts, writing prompts, and resources
+* Step-by-step customization guide
+* No coding required. Just copy and customize
+
+link:COSTS.adoc[**Cost reference**]:: Understanding and optimizing MCP tool costs
++
+* Cost breakdown by tool ($0.017 - $0.190 per operation)
+* Model selection guidance (Haiku/Sonnet/Opus)
+* Cost optimization strategies
+
+=== For developers
+
+link:DEVELOPMENT.adoc[**Development guide**]:: Guide for working on the MCP server
++
+* Architecture overview
+* Adding new tools programmatically
+* Auto-discovery system details
+* Testing guidelines
+* Security and best practices
+
+link:CLI_INTERFACE.adoc[**CLI interface contract**]:: Contract specification for the `doc-tools` CLI
++
+* Command structure and syntax
+* Output format contracts
+* Error handling requirements
+* Stability guarantees
+
+link:../CLI_REFERENCE.adoc[**CLI reference**]:: Complete command reference for `doc-tools`
++
+* All commands and subcommands
+* Options and usage examples
+* Auto-generated from CLI help
+
+link:../\__tests__/mcp/README.adoc[**Test documentation**]:: How to run and write MCP tests
++
+* Test types (integration, contract, unit)
+* Running tests
+* Understanding failures
+
+=== Advanced
+
+link:prompts/README.adoc[**Prompts documentation**]:: Guide to the MCP prompt system
++
+* What prompts are and how they work
+* Available prompts
+* Adding new prompts
+
+== Quickstart
+
+=== Install and configure
+
+[,bash]
+----
+cd /path/to/docs-extensions-and-macros
+npm install
+npx doc-tools setup-mcp --local
+----
+
+=== Restart Claude Code
+
+After setup, restart Claude Code to load the MCP server.
+
+=== Start using it
+
+Navigate to any Redpanda repository and start chatting:
+
+----
+You: "What's the latest Redpanda version?"
+Claude: *uses get_redpanda_version tool*
+
+You: "Generate property docs for v25.3.1"
+Claude: *uses generate_property_docs tool*
+----
+
+== What's included
+
+=== Documentation generation tools
+
+* **Version information**: Get latest Redpanda and Console versions
+* **Property docs**: Generate configuration property documentation
+* **Metrics docs**: Generate metrics reference documentation
+* **RPK docs**: Generate RPK CLI documentation
+* **Connector docs**: Generate Redpanda Connect connector documentation
+* **Antora structure**: Analyze documentation repository structure
+
+=== AI consistency prompts
+
+Pre-configured instructions that help Claude follow your team standards:
+
+**Review prompts:**
+
+* **review-for-style**: Review content for style guide compliance
+* **check-terminology**: Validate terminology against approved terms
+* **improve-clarity**: Refactor content for better readability
+
+**Content creation:**
+
+* **write-new-guide**: Generate new guides following team standards
+
+**Workflow guides:**
+
+* **property-docs-guide**: Workflow for updating property documentation
+* **rpcn-connector-docs-guide**: Workflow for updating connector documentation
+
+=== Resources
+
+Reference materials that Claude can read:
+
+* **redpanda://style-guide**: Complete team style guide with formatting rules
+
+=== CLI validation commands
+
+For writers extending the MCP server:
+
+* **npx doc-tools validate-mcp**: Validate prompts and resources configuration
+* **npx doc-tools preview-prompt**: Preview prompts with test arguments
+* **npx doc-tools mcp-version**: Show versions and usage statistics
+
+=== Automation
+
+* **setup-mcp**: Automated MCP server configuration for Claude Code/Desktop
+* **Auto-discovery**: Prompts automatically loaded from `mcp/prompts/` directory
+* **Context detection**: Automatic repository and Antora structure detection
+* **Usage telemetry**: Track prompt/resource/tool usage for adoption metrics
+
+== Architecture
+
+The MCP server consists of:
+
+* **Server** (`bin/doc-tools-mcp.js`): Main MCP protocol handler
+* **Tool modules** (`bin/mcp-tools/`): Individual tool implementations
+* **Prompts** (`mcp/prompts/`): Contextual documentation guides
+* **Tests** (`__tests__/mcp/`): Integration, contract, and unit tests
+
+== Support
+
+* link:USER_GUIDE.adoc#troubleshooting[Troubleshooting guide]
+* link:../\__tests__/mcp/README.adoc#understanding-test-failures[Test failures]
+* https://github.com/redpanda-data/docs-extensions-and-macros/issues[Report issues]
+
+== External resources
+
+* https://modelcontextprotocol.io/[MCP Protocol Specification]
+* https://docs.anthropic.com/claude[Claude Code Documentation]