Single source MCP server docs#344
Conversation
- Add pattern selection guide at top for quick navigation - Add 'When to use' and 'Example use cases' to all patterns - Add new pattern sections: * Data generators (generate input for testing) * Data transformation (Bloblang mapping examples) * AI/LLM integration (OpenAI chat completion and embeddings) * Caching systems (memory cache) - Use environment variables for API keys (self-hosted context) These improvements make the patterns catalog more discoverable and provide clearer guidance on when to use each pattern for self-hosted Redpanda Connect MCP servers.
Create reusable content partials to be shared between rp-connect-docs and cloud-docs repositories: - Use cases table and customer analytics example - Tool contract guidance and specification support - YAML config rules (separate for Cloud vs Connect) - Property restrictions table - Production workflows (split before/after secrets) - Secrets management (deployment-specific for Cloud vs Connect) These partials enable maintaining consistent MCP documentation across both self-hosted and Cloud deployments while allowing deployment-specific customization where needed.
Refactor MCP server documentation to include reusable partials: - developer-guide.adoc: Include tool contract guidance, YAML config rules, and production workflows - overview.adoc: Include use cases table and specification support - quickstart.adoc: Include config examples This enables consistent content between rp-connect-docs and cloud-docs while maintaining deployment-specific variations where needed.
- Add GitHub Actions workflow to test MCP configuration examples - Create test-mcp-examples.sh script to validate YAML configs - Add testing.adoc documentation for test infrastructure This ensures MCP example configurations remain valid and working as the codebase evolves.
- Create generate-input.yaml example file in resources/inputs/ - Update include path in pipeline-patterns.adoc to reference correct location - Example demonstrates generating realistic user events for testing This enables the CI/CD testing infrastructure to validate the example.
✅ Deploy Preview for redpanda-connect ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 📝 WalkthroughWalkthroughThis PR adds MCP example testing infrastructure, updates GitHub Actions workflow runtimes, and performs comprehensive documentation refactoring. It introduces a new test-mcp-examples.yaml workflow and corresponding Bash test script to lint and validate MCP example configurations. The PR updates Node.js runtime from version 18 to 22 in CI workflows, updates the Antora playbook to reference a specific documentation branch, and adds a sample MCP input generator configuration. The primary focus is refactoring MCP server documentation by extracting inline content into reusable AsciiDoc partials for use across self-managed Redpanda Connect and Cloud-based MCP server guides, while rewriting quickstart and pipeline pattern sections to align with updated architectural guidance. Estimated code review effort🎯 4 (Complex) | ⏱️ ~75 minutes
Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches❌ Failed checks (2 inconclusive)
✅ Passed checks (3 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Use --no-install flag with npx to prevent it from trying to download doc-tools from npm. The doc-tools binary is provided by the @redpanda-data/docs-extensions-and-macros package and is already available in node_modules/.bin/ after npm install.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
modules/ai-agents/pages/mcp-server/quickstart.adoc (1)
39-39: Fix incorrect cross-reference filename at line 39.Line 39 links to
ROOT:get-started:rpk-install.adoc, but the actual file isrpk.adocnotrpk-install.adoc. Change the reference toxref:ROOT:get-started:pages/quickstarts/rpk.adoc[Redpanda CLI (\rpk`)]or verify the correct file path in the get-started module. Line 86's reference toinstall:rpk.adoc#upgrade` is correct.
🧹 Nitpick comments (2)
modules/ai-agents/partials/mcp/config-examples.adoc (1)
51-76: Enhance the explanation of incorrect patterns.The two incorrect examples effectively demonstrate anti-patterns, but adding brief explanatory comments would help readers understand why these patterns are wrong. Consider augmenting the incorrect example warnings with guidance on:
- Why the input wrapper is incorrect (single-component-per-file design)
- Why multiple component types in one file is problematic (lifecycle/reusability concerns)
modules/ai-agents/pages/mcp-server/quickstart.adoc (1)
297-300: NOTE about restarting the server on YAML changes is helpful, but could be more prominent.Line 297-300 includes an important NOTE about restarting the MCP server when tool YAML changes. This is a frequent source of confusion for developers. Consider making this more prominent in the main workflow or adding a troubleshooting entry for "tool changes not appearing."
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Jira integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (23)
.github/workflows/test-mcp-examples.yaml(1 hunks).github/workflows/update-docs.yml(1 hunks).github/workflows/update-extensions.yml(1 hunks)local-antora-playbook.yml(1 hunks)modules/ai-agents/examples/resources/inputs/generate-input.yaml(1 hunks)modules/ai-agents/examples/test-mcp-examples.sh(1 hunks)modules/ai-agents/examples/testing.adoc(1 hunks)modules/ai-agents/pages/mcp-server/developer-guide.adoc(2 hunks)modules/ai-agents/pages/mcp-server/overview.adoc(2 hunks)modules/ai-agents/pages/mcp-server/pipeline-patterns.adoc(4 hunks)modules/ai-agents/pages/mcp-server/quickstart.adoc(6 hunks)modules/ai-agents/partials/mcp/config-examples.adoc(1 hunks)modules/ai-agents/partials/mcp/customer-analytics-example.adoc(1 hunks)modules/ai-agents/partials/mcp/production-workflows-after-secrets.adoc(1 hunks)modules/ai-agents/partials/mcp/production-workflows-before-secrets.adoc(1 hunks)modules/ai-agents/partials/mcp/property-restrictions-table.adoc(1 hunks)modules/ai-agents/partials/mcp/secrets-cloud.adoc(1 hunks)modules/ai-agents/partials/mcp/secrets-connect.adoc(1 hunks)modules/ai-agents/partials/mcp/specification-support.adoc(1 hunks)modules/ai-agents/partials/mcp/tool-contract-guidance.adoc(1 hunks)modules/ai-agents/partials/mcp/use-cases-table.adoc(1 hunks)modules/ai-agents/partials/mcp/yaml-config-rules-cloud.adoc(1 hunks)modules/ai-agents/partials/mcp/yaml-config-rules-connect.adoc(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-05-13T13:10:20.555Z
Learnt from: asimms41
Repo: redpanda-data/rp-connect-docs PR: 248
File: modules/components/pages/processors/google_drive_download.adoc:80-89
Timestamp: 2025-05-13T13:10:20.555Z
Learning: The include directive syntax with colons and dollar sign (e.g., `include::components:partial$secret_warning.adoc[]`) is the correct format in the Redpanda Connect documentation, which appears to use Antora's resource ID format for includes.
Applied to files:
modules/ai-agents/partials/mcp/yaml-config-rules-connect.adoc
🪛 Shellcheck (0.11.0)
modules/ai-agents/examples/test-mcp-examples.sh
[warning] 79-79: Declare and assign separately to avoid masking return values.
(SC2155)
[warning] 80-80: Declare and assign separately to avoid masking return values.
(SC2155)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Redirect rules - redpanda-connect
- GitHub Check: Header rules - redpanda-connect
- GitHub Check: Pages changed - redpanda-connect
🔇 Additional comments (29)
local-antora-playbook.yml (1)
21-21: Confirm branch targeting is intentional and document for developers.The local Antora playbook now points to the
DOC-1844branch for cloud-docs instead ofmain. While this aligns with the PR objectives, ensure developers are aware that local builds will consume content from a feature branch rather than the stable main branch.Consider adding a note to the README or a comment in the playbook if this is temporary for staging/testing purposes.
.github/workflows/update-extensions.yml (1)
35-35: Node.js version update is appropriate.Upgrading Node.js from 18 to 22 is a good housekeeping change, as Node 18 reached end-of-life support in October 2024. Node 22 is the current stable release and aligns with the broader Node.js version updates in the PR.
.github/workflows/update-docs.yml (1)
21-21: Node.js version upgrade is consistent and appropriate.The NODE_VERSION environment variable correctly updates to '22', maintaining consistency with the parallel update in update-extensions.yml and ensuring the doc-tools and npm ecosystem use a current, stable Node.js runtime.
modules/ai-agents/partials/mcp/secrets-connect.adoc (1)
1-32: AsciiDoc syntax and content are solid; structure mirrors Cloud variant.The Connect secrets partial correctly documents environment variable-based secret handling with clear examples and appropriate warnings. The section anchor
[[secrets]]and structure align with the Cloud variant, enabling consistent partial inclusion across contexts.modules/ai-agents/partials/mcp/secrets-cloud.adoc (1)
11-11: Verify xref link resolves correctly from Cloud documentation context.Line 11 contains an xref to
xref:develop:connect/configuration/secret-management.adoc[]. When this partial is included from the cloud-docs repository, verify that this cross-reference resolves correctly. You may need to adjust the xref to use an absolute component reference (e.g.,xref:redpanda-connect:develop:connect/configuration/secret-management.adoc[]) depending on how cloud-docs Antora configuration handles component boundaries.modules/ai-agents/partials/mcp/yaml-config-rules-connect.adoc (1)
1-24: Include syntax and table structure are well-formatted.The Connect-specific YAML rules partial correctly documents component type mapping with proper AsciiDoc table syntax. The include directive syntax shown in the header comment aligns with established patterns. The directory-to-component-type mapping is clear and covers all relevant component types.
modules/ai-agents/partials/mcp/yaml-config-rules-cloud.adoc (1)
10-13: Verify xref links resolve correctly from Cloud documentation context.Lines 10-13 contain four xref links pointing to Connect component documentation (e.g.,
xref:develop:connect/components/inputs/about.adoc[...]). When this partial is included from cloud-docs, verify these cross-references resolve correctly. Depending on Antora configuration, you may need to use absolute component references (e.g.,xref:redpanda-connect:develop:...[]).modules/ai-agents/partials/mcp/production-workflows-after-secrets.adoc (2)
15-15: Verify included YAML example files exist at referenced paths.This partial includes three external YAML files using Antora resource syntax:
- Line 15:
observable-tool.yaml- Line 58:
customer-enrichment.yaml- Line 71:
order-workflow.yamlEnsure these files exist at
modules/ai-agents/examples/resources/processors/and contain the expected configuration content. If these are new files added in the PR, confirm they are committed and located at the correct paths.Also applies to: 58-58, 71-71
48-48: Verify xref links to processor and Bloblang documentation resolve correctly.Lines 48 and 61 contain xref links:
xref:components:processors/log.adoc[...]xref:guides:bloblang/functions.adoc[...]When this partial is included from cloud-docs context, verify these cross-component references resolve correctly. You may need to prefix them with the component reference (e.g.,
xref:redpanda-connect:components:...[]).Also applies to: 61-61
modules/ai-agents/partials/mcp/config-examples.adoc (1)
1-27: Clarify whether inputs can expose MCP tools.The first correct example shows an input component with a
meta.mcpmetadata block but no properties or tool contract. Please clarify whether input components themselves can be exposed as MCP tools, or if only processors/pipelines should have MCP metadata. If inputs cannot be MCP tools, this metadata block is misleading.modules/ai-agents/partials/mcp/customer-analytics-example.adoc (1)
8-48: Well-structured customer analytics example.The example demonstrates proper MCP tool contract, conditional environment handling, and realistic processor logic. YAML structure, Bloblang syntax, and MCP metadata are all correct.
modules/ai-agents/partials/mcp/production-workflows-before-secrets.adoc (1)
1-104: Comprehensive and well-structured production workflow patterns.All four subsections (parameter validation, dynamic configuration, error handling, conditional processing) demonstrate correct Bloblang and Redpanda Connect processor syntax. The examples are practical, follow enterprise patterns, and align with the stated goal of building robust production tools.
modules/ai-agents/partials/mcp/specification-support.adoc (1)
1-12: Clear and concise specification support documentation.Content accurately describes MCP support scope (tools only) and provides link to authoritative source. The versioned URL (2025-06-18) is good practice for stability, though monitor for future MCP spec updates that may require URL refresh.
modules/ai-agents/partials/mcp/use-cases-table.adoc (1)
1-33: Well-organized use cases table.Table structure is correct, categories are distinct and meaningful, and example prompts are realistic and specific. The AsciiDoc formatting with proper column specifications supports good readability.
modules/ai-agents/pages/mcp-server/overview.adoc (1)
11-25: Successful refactoring to single-sourced partials.The overview page correctly includes three partials, replacing inline content with references to reusable fragments. Include syntax is correct and consistent. Single-sourcing goal is properly achieved, allowing cloud-docs to reference the same partials via remote catalog.
Confirm that Antora catalog and component boundaries are configured to support the remote partial includes from cloud-docs (i.e.,
include::redpanda-connect:ai-agents:partial$...syntax). The local-antora-playbook.yml update references DOC-1844 for cloud-docs, but verify the namespace and module paths are correctly registered.modules/ai-agents/examples/resources/inputs/generate-input.yaml (1)
1-9: Valid and well-structured input generator for MCP testing.The YAML configuration correctly uses Bloblang functions to generate realistic event data with conditional fields (amount only for purchase events). The generate interval and count settings support continuous testing. No issues identified.
modules/ai-agents/partials/mcp/tool-contract-guidance.adoc (1)
7-39: Clear and practical MCP tool contract guidance.Callout annotations explain the three key components (enabled flag, description, properties), and the guidance section covers property types, validation approaches, and required/default handling. Structure and examples are consistent with other MCP partials in the PR.
Verify that the cross-reference to
xref:guides:bloblang/about.adoc[Bloblang](line 35) points to the correct module and document path in your Antora configuration.modules/ai-agents/partials/mcp/property-restrictions-table.adoc (1)
1-30: Well-structured partial for property restrictions documentation.The table clearly documents property support across component types with appropriate detail levels. The include syntax comments (lines 4-5) are helpful for maintainers referencing this partial.
.github/workflows/test-mcp-examples.yaml (1)
1-67: Workflow structure looks solid with appropriate tool setup and matrix parallelization.The dual-job approach (lint-and-test all examples + test-matrix by component) provides both quick feedback and comprehensive coverage. The path filter ensures the workflow runs only when relevant files change.
Verify that
npx doc-tools install-test-dependenciesandrpk connect installare available in the GitHub Actions environment and that the script atmodules/ai-agents/examples/test-mcp-examples.shproperly handles the component type arguments (line 67:${{ matrix.component }}).modules/ai-agents/examples/testing.adoc (3)
1-50: Excellent introduction to testing strategies with clear guidance on automation.The documentation clearly explains the three testing approaches (linting, metadata validation, manual testing) and their purpose. The emphasis on MCP metadata requirements is particularly helpful given the test script's focus.
61-68: Important clarification about unit testing limitations in MCP context.The IMPORTANT note at lines 61-68 clearly explains why MCP tool examples cannot use inline
tests:sections. This is valuable context for developers familiar with cookbook examples.
323-328: Verify that example tool paths referenced in documentation exist.The documentation references example files like
resources/processors/weather-api.yaml(line 145),resources/processors/database-query.yaml(line 69), and others. Confirm that these example files exist in the repository at the specified paths, or update the references if they've been renamed or relocated.modules/ai-agents/pages/mcp-server/developer-guide.adoc (2)
105-106: Verify example file path is correct.The document includes an example at line 105:
include::ai-agents:example$resources/processors/weather-service.yaml[]Confirm this file exists at
modules/ai-agents/examples/resources/processors/weather-service.yaml.
85-86: All referenced MCP partials exist and are correctly structured.The four include directives reference existing partial files with appropriate content:
tool-contract-guidance.adoc(39 lines)yaml-config-rules-connect.adoc(25 lines)property-restrictions-table.adoc(30 lines)config-examples.adoc(76 lines)All files are present in
modules/ai-agents/partials/mcp/and use the correct Antorapartial$syntax for single-sourcing documentation.modules/ai-agents/pages/mcp-server/pipeline-patterns.adoc (3)
10-24: Pattern selection guide significantly improves usability.The new guide at the beginning provides clear navigation options for readers looking for specific use cases. This is a strong improvement over undifferentiated content.
37-37: All referenced example files exist and contain content. No issues identified.
resources/inputs/generate-input.yaml✓resources/processors/weather-api.yaml✓resources/processors/database-query.yaml✓resources/outputs/redpanda-publish.yaml✓resources/inputs/redpanda-consume.yaml✓resources/inputs/stream-analytics.yaml✓resources/inputs/event-workflow.yaml✓
217-225: All production workflow partials exist and are properly configured for Connect-specific secrets handling.Lines 217-225 correctly include three partials for production workflows:
- Line 219:
production-workflows-before-secrets.adoc✓- Line 222:
secrets-connect.adoc✓ (Connect-specific, uses environment variables)- Line 225:
production-workflows-after-secrets.adoc✓The Connect-specific secrets section properly demonstrates environment variable-based credential handling, aligning with the deployment approach for self-managed Redpanda Connect MCP servers.
modules/ai-agents/pages/mcp-server/quickstart.adoc (2)
1-34: Excellent rewrite that sets clear expectations and explains MCP concepts upfront.The new introduction, "What you'll learn" section, and "How MCP works" explanation significantly improve the quickstart's accessibility. The concrete example of Claude calling the
search-bluesky-poststool makes the concept tangible.
173-220: mcp-remote bridge explanation is clear and addresses a key technical hurdle.The detailed explanation of how
mcp-remotebridges HTTP/SSE to stdio (lines 177-185) helps developers understand the architecture and why this extra step is necessary. This is valuable context that was missing in many MCP quickstarts.
- Add MCP_FAILS counter to track validation failures - Remove '|| true' that was suppressing validation failures - Increment MCP_FAILS when validate_mcp_metadata returns non-zero - Display MCP validation failures in test summary - Exit with non-zero code when MCP validations fail This ensures missing descriptions or other MCP metadata issues cause the test suite to fail.
Separate variable declaration from assignment in validate_mcp_metadata to avoid masking return values and resolve ShellCheck warnings.
- Create reusable example showing output with LLM processor - Address customer confusion about combining processors with outputs - Clarify that outputs CAN have processors, but processor tools CANNOT have outputs
|
|
||
| == Start the MCP server | ||
|
|
||
| . Navigate to your MCP server project directory if you're not already there: |
There was a problem hiding this comment.
| . Navigate to your MCP server project directory, if you're not already there: |
|
|
||
| == Summary | ||
|
|
||
| You extended Claude's capabilities with a custom tool built from Redpanda Connect components. Claude can now search Bluesky through natural language commands—no manual API calls or scripting required. |
There was a problem hiding this comment.
| You extended Claude's capabilities with a custom tool built from Redpanda Connect components. Claude can now search Bluesky through natural language commands—no manual API calls or scripting required. | |
| This quickstart extended Claude's capabilities with a custom tool built from Redpanda Connect components. Claude can now search Bluesky through natural language commands—no manual API calls or scripting required. |
| *Solution*: Upgrade to at least version 4.66.1 of Redpanda Connect. | ||
|
|
||
| [source,bash] | ||
| ---- | ||
| rpk connect --version | ||
| ---- | ||
|
|
||
| If you need to upgrade, see xref:install:rpk.adoc#upgrade[Upgrade Redpanda Connect]. |
There was a problem hiding this comment.
| *Solution*: Upgrade to at least version 4.66.1 of Redpanda Connect. See xref:install:rpk.adoc#upgrade[Upgrade Redpanda Connect]. | |
| [source,bash] | |
| ---- | |
| rpk connect --version | |
| ---- |
micheleRP
left a comment
micheleRP
left a comment
There was a problem hiding this comment.
looks good, but please see my comments!
Co-authored-by: Michele Cyran <michele@redpanda.com>
Co-authored-by: Michele Cyran <michele@redpanda.com>
s not exit with error code 1
2 participants
Description
Review deadline: December 10
Part of redpanda-data/cloud-docs#472
This pull request introduces automated testing for Redpanda Connect MCP example configurations and refactors documentation to use single-sourced partials for consistency and maintainability. The most significant changes include the addition of a comprehensive test script and CI workflow, updates to documentation describing testing strategies, and improvements to developer guides by centralizing YAML configuration guidance.
Automated testing and CI/CD:
.github/workflows/test-mcp-examples.yamlto run linting and MCP metadata validation for all example configs on push and PR, including a matrix job for component types.modules/ai-agents/examples/test-mcp-examples.sh, a bash script that automates linting and MCP metadata validation for example YAMLs, with color-coded output and summary.Documentation improvements:
modules/ai-agents/examples/testing.adocto document automated testing strategies, test script usage, and best practices for MCP example development.modules/ai-agents/pages/mcp-server/developer-guide.adoc) and overview (modules/ai-agents/pages/mcp-server/overview.adoc) to use single-sourced partials for tool contract guidance, YAML rules, property restrictions, use cases, and example configurations, improving maintainability and consistency. [1] [2] [3] [4]Other changes:
local-antora-playbook.ymltoDOC-1844for documentation builds.modules/ai-agents/examples/resources/inputs/generate-input.yamlfor generating test data.Page previews
Checks