Improve developer experience of MCP dev guide#347
Conversation
✅ Deploy Preview for redpanda-connect ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
📝 WalkthroughWalkthroughThis pull request substantially revises the MCP Server developer guide documentation across multiple files. Changes include adding a new quickstart section, comprehensive examples, and a redesigned multi-step development workflow (Initialize, Design Contract, Implement, Test, Connect Client, Publish). The guide introduces a tabular Concepts and architecture section, updates troubleshooting content with observable guidance, reworks project scaffolding instructions with directory structure illustrations, and enhances YAML configuration examples and rules with common mistakes section. Related partials and pipeline patterns are also restructured for improved organization and consistency. Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
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/pipeline-patterns.adoc (1)
119-131: Resolve the unresolved merge conflict and consolidate overlapping content sections.The documentation contains an unresolved merge conflict marker (
>>>>>>> Stashed changes) at line 117, and two overlapping sections both covering outputs with processors (lines 100-131). While the two example files serve different purposes—redpanda-output-with-processors.yamldemonstrates LLM-based preprocessing, andredpanda-publish-with-processors.yamldemonstrates metadata enrichment and validation—they should be consolidated into a single well-organized section. Either combine both examples in one section with clear use case distinctions, or restructure to eliminate the duplication and clarify when to use each pattern.
📜 Review details
Configuration used: Organization 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 (3)
modules/ai-agents/examples/resources/outputs/redpanda-publish-with-processors.yamlmodules/ai-agents/pages/mcp-server/developer-guide.adocmodules/ai-agents/pages/mcp-server/pipeline-patterns.adoc
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-11-25T10:26:50.930Z
Learnt from: CR
Repo: redpanda-data/rp-connect-docs PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T10:26:50.930Z
Learning: The Redpanda Connect reference documentation uses a two-tier approach combining autogenerated content from source code and schemas with overrides managed in a central DRY (Don't Repeat Yourself) system
Applied to files:
modules/ai-agents/pages/mcp-server/developer-guide.adoc
🪛 GitHub Actions: Test MCP Examples
modules/ai-agents/examples/resources/outputs/redpanda-publish-with-processors.yaml
[error] 26-26: rpk connect mcp-server lint failed: value object is not a valid option for this field. Exit code 1.
⏰ 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 (4)
modules/ai-agents/pages/mcp-server/developer-guide.adoc (4)
12-68: Excellent quick reference section achieving PR objectives.The new quick reference section successfully addresses the PR's stated goal of enabling "< 5 min to first tool":
- Clear 6-step initialization workflow with actual commands
- Inline common tool examples (weather API, database query, Redpanda consumer)
- Examples use include directives for maintainability
- Tip pointing to full pipeline patterns documentation
This is a significant improvement to developer experience and makes the guide much more actionable for first-time users.
83-137: Well-structured concepts and workflow tables.The conversion from prose to scannable tables (concepts at lines 83-101, workflow at lines 105-137) significantly improves readability and navigation:
- Concepts table clearly defines key terminology
- Workflow table provides step-by-step progression with section anchors
- Visual stepper diagram (lines 105-108) gives clear mental model
These changes align with the PR objective of creating "scannable tables and callouts" instead of "dense paragraphs."
404-453: Valuable troubleshooting section with concrete examples.The new troubleshooting section addresses a common pain point with:
- Clear explanation of "unable to infer component type" error (lines 415-427)
- Side-by-side incorrect vs. correct YAML examples (lines 429-452)
- Explanation of the subtle distinction between multiple top-level types vs. processors within outputs/inputs
This should significantly reduce developer frustration and support questions.
286-286: Ensure merge conflict resolution aligns with cross-reference in developer-guide.adoc.Line 286 in developer-guide.adoc references the anchor
[[outputs-with-processors]]viaxref:ai-agents:mcp-server/pipeline-patterns.adoc#outputs-with-processors[]. This anchor exists only in the stashed changes section of the pipeline-patterns.adoc merge conflict (line 96). If the merge conflict is resolved in favor of the updated upstream version, the anchor will be removed and the cross-reference will break. Ensure both files are resolved consistently to preserve the cross-reference functionality.
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
|
closing in favor of #348 |
1 participant
Description
Addresses negative feedback received on the docs site about developer experience and findability.
Changes
Developer Guide (
modules/ai-agents/pages/mcp-server/developer-guide.adoc):Pipeline Patterns (
modules/ai-agents/pages/mcp-server/pipeline-patterns.adoc):New Example:
modules/ai-agents/examples/resources/outputs/redpanda-publish-with-processors.yamlImpact
Reduces time to value and improves findability for developers.
Page previews
Checks