Improve MCP devex

docs-data/personas.yaml

@@ -0,0 +1,153 @@
+# Redpanda Cloud Documentation Personas
+#
+# These personas represent the target audience for Redpanda Cloud documentation.
+# Use these when assigning :personas: attributes to documentation pages.
+
+schema_version: "1.0"
+repository: cloud-docs
+
+personas:
+  - id: app_developer
+    name: Application Developer
+    description: Builds applications that produce and consume data from Redpanda Cloud
+    experience_level: intermediate
+    goals:
+      - Connect applications to Redpanda Cloud clusters
+      - Produce and consume messages reliably
+      - Implement proper error handling and retries
+      - Optimize client performance
+    pain_points:
+      - Authentication and connection configuration
+      - Understanding Kafka client options
+      - Debugging connectivity issues
+      - Choosing the right client library
+    content_preferences:
+      - Working code examples in multiple languages
+      - Connection configuration templates
+      - Client library comparisons
+      - Performance tuning guides
+    typical_content_types:
+      - how-to
+      - tutorial
+      - reference
+
+  - id: platform_admin
+    name: Platform Administrator
+    description: Manages Redpanda Cloud clusters, users, security, and billing
+    experience_level: intermediate
+    goals:
+      - Provision and configure clusters
+      - Manage user access and security
+      - Monitor cluster health and usage
+      - Control costs and optimize resources
+    pain_points:
+      - Complex security configuration
+      - Understanding billing and usage metrics
+      - Managing access across teams
+      - Capacity planning
+    content_preferences:
+      - Step-by-step administration guides
+      - Security best practices
+      - Billing and cost optimization tips
+      - Monitoring and alerting setup
+    typical_content_types:
+      - how-to
+      - reference
+      - best-practices
+
+  - id: data_engineer
+    name: Data Engineer
+    description: Builds data pipelines using managed connectors and Redpanda Connect
+    experience_level: intermediate
+    goals:
+      - Set up managed connectors to move data between systems
+      - Transform and route data reliably
+      - Monitor connector and pipeline health
+      - Handle errors and retries
+    pain_points:
+      - Connector configuration complexity
+      - Debugging failed connectors
+      - Schema management and evolution
+      - Performance tuning
+    content_preferences:
+      - Connector setup guides
+      - Transformation examples
+      - Error handling patterns
+      - Monitoring and troubleshooting
+    typical_content_types:
+      - how-to
+      - cookbook
+      - troubleshooting
+
+  - id: ai_agent_developer
+    name: AI Agent Developer
+    description: Builds AI agents and integrations using MCP tools and LLM frameworks
+    experience_level: intermediate
+    goals:
+      - Create MCP tools that AI assistants can discover and use
+      - Deploy MCP servers to Redpanda Cloud
+      - Integrate with AI/LLM applications
+      - Debug agent-tool interactions
+    pain_points:
+      - MCP configuration syntax
+      - Testing tools before deployment
+      - Limited AI-specific examples
+    content_preferences:
+      - Working code examples with AI context
+      - Testing and debugging workflows
+      - Integration patterns
+    typical_content_types:
+      - tutorial
+      - how-to
+      - cookbook
+      - best-practices
+
+  - id: streaming_developer
+    name: Streaming Platform Developer
+    description: Works with Kafka/Redpanda streaming systems at scale
+    experience_level: advanced
+    goals:
+      - Build event-driven architectures on Redpanda Cloud
+      - Optimize for high throughput and low latency
+      - Implement exactly-once semantics
+      - Migrate from self-hosted Kafka
+    pain_points:
+      - Consumer group behavior differences
+      - Schema registry configuration
+      - Performance at scale
+      - Migration complexity
+    content_preferences:
+      - Advanced configuration options
+      - Performance tuning guides
+      - Migration documentation
+      - Architecture patterns
+    typical_content_types:
+      - concepts
+      - how-to
+      - reference
+      - best-practices
+
+  - id: evaluator
+    name: Technical Evaluator
+    description: Assessing Redpanda Cloud for their organization
+    experience_level: beginner
+    goals:
+      - Understand Redpanda Cloud capabilities quickly
+      - Evaluate fit for specific use cases
+      - Understand pricing and billing
+      - Compare with alternatives
+    pain_points:
+      - Hard to find high-level overview
+      - Too much detail too soon
+      - Unclear pricing structure
+      - Missing comparison information
+    content_preferences:
+      - High-level overviews
+      - Use case examples
+      - Quick start guides
+      - Pricing documentation
+    typical_content_types:
+      - overview
+      - concepts
+      - tutorial
+      - get-started

local-antora-playbook.yml

@@ -26,7 +26,7 @@ content:
     branches: main
     start_paths: [docs,'*/docs']
   - url: https://github.com/redpanda-data/rp-connect-docs
-    branches: main
+    branches: improve-mcp-devex
 ui:
   bundle:
     url: https://github.com/redpanda-data/docs-ui/releases/latest/download/ui-bundle.zip

modules/ROOT/nav.adoc

@@ -78,12 +78,15 @@
 ** xref:ai-agents:mcp/remote/index.adoc[Remote MCP]
 *** xref:ai-agents:mcp/remote/overview.adoc[Overview]
 *** xref:ai-agents:mcp/remote/quickstart.adoc[Quickstart]
-*** xref:ai-agents:mcp/remote/developer-guide.adoc[Developer Guide]
+*** xref:ai-agents:mcp/remote/concepts.adoc[Concepts]
+*** xref:ai-agents:mcp/remote/create-tool.adoc[Create a Tool]
+*** xref:ai-agents:mcp/remote/best-practices.adoc[Best Practices]
+*** xref:ai-agents:mcp/remote/tool-patterns.adoc[Tool Patterns]
+*** xref:ai-agents:mcp/remote/troubleshooting.adoc[Troubleshooting]
 *** xref:ai-agents:mcp/remote/admin-guide.adoc[Admin Guide]
 **** xref:ai-agents:mcp/remote/manage-servers.adoc[Manage Servers]
 **** xref:ai-agents:mcp/remote/scale-resources.adoc[Scale Resources]
 **** xref:ai-agents:mcp/remote/monitor-activity.adoc[Monitor Activity]
-*** xref:ai-agents:mcp/remote/pipeline-patterns.adoc[MCP Server Patterns]
 
 * xref:develop:connect/about.adoc[Redpanda Connect]
 ** xref:develop:connect/connect-quickstart.adoc[Quickstart]

modules/ai-agents/examples/redpanda_output_with_processors.yaml

@@ -1,12 +1,4 @@
-redpanda:
-  seed_brokers: [ "${REDPANDA_BROKERS}" ]
-  topic: "llm-responses"
-  tls:
-    enabled: true
-  sasl:
-    - mechanism: "${REDPANDA_SASL_MECHANISM}"
-      username: "${REDPANDA_SASL_USERNAME}"
-      password: "${REDPANDA_SASL_PASSWORD}"
+label: summarize_and_publish
 
 processors:
   - openai_chat_completion:
@@ -17,3 +9,23 @@ processors:
       root.question = this.question
       root.answer = this.content
       root.timestamp = now().ts_format("2006-01-02T15:04:05Z07:00")
+
+redpanda:
+  seed_brokers: [ "${REDPANDA_BROKERS}" ]
+  topic: "llm-responses"
+  tls:
+    enabled: true
+  sasl:
+    - mechanism: SCRAM-SHA-256
+      username: "${secrets.MCP_USERNAME}"
+      password: "${secrets.MCP_PASSWORD}"
+
+meta:
+  mcp:
+    enabled: true
+    description: "Process a question through an LLM and publish the response to Redpanda"
+    properties:
+      - name: question
+        type: string
+        description: "The question to send to the LLM"
+        required: true