Skip to content

Commit 8de42cc

Browse files
authored
Fix MCP server by including mcp directory in npm package. (#161)
* Fix MCP server by including mcp directory in npm package. The MCP server was failing with 'Prompts directory not found' because the mcp/ directory wasn't being published to npm. Added mcp to the files array in package.json to ensure prompts and resources are included in published packages. * Update README * Update README
1 parent e093a2e commit 8de42cc

File tree

4 files changed

+126
-47
lines changed

4 files changed

+126
-47
lines changed

mcp/README.adoc

Lines changed: 35 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -17,19 +17,24 @@ link:USER_GUIDE.adoc[**User guide**]:: Complete guide to using the MCP server wi
1717
* Usage examples and workflows
1818
* Troubleshooting
1919

20-
link:WRITER_EXTENSION_GUIDE.adoc[**Writer extension guide**]:: How to extend the MCP server (no coding required!)
20+
link:WRITER_EXTENSION_GUIDE.adoc[**Writer extension guide**]:: How to extend the MCP server (no coding required)
2121
+
2222
* Adding new prompts for common tasks
2323
* Adding new resources (style guides, templates)
2424
* Validation and preview commands
2525
* Best practices and examples
2626

27-
link:TEAM_ROLLOUT_GUIDE.adoc[**Team rollout guide**]:: Rolling out to your documentation team
27+
link:templates/README.adoc[**Extension templates**]:: Ready-to-use templates for extending the MCP server
2828
+
29-
* Phased rollout plan
30-
* Training materials and best practices
31-
* Operational playbook (rollback, emergency procedures)
32-
* Success metrics and monitoring
29+
* Templates for review prompts, writing prompts, and resources
30+
* Step-by-step customization guide
31+
* No coding required. Just copy and customize
32+
33+
link:COSTS.adoc[**Cost reference**]:: Understanding and optimizing MCP tool costs
34+
+
35+
* Cost breakdown by tool ($0.017 - $0.190 per operation)
36+
* Model selection guidance (Haiku/Sonnet/Opus)
37+
* Cost optimization strategies
3338

3439
=== For developers
3540

@@ -68,18 +73,6 @@ link:prompts/README.adoc[**Prompts documentation**]:: Guide to the MCP prompt sy
6873
* Available prompts
6974
* Adding new prompts
7075

71-
link:AI_CONSISTENCY_ARCHITECTURE.adoc[**AI consistency architecture**]:: Architecture for team-wide AI consistency
72-
+
73-
* Design principles
74-
* Technical implementation
75-
* Extension patterns
76-
77-
link:AI_CONSISTENCY_SHOWCASE.adoc[**AI consistency showcase**]:: Examples and use cases
78-
+
79-
* Real-world examples
80-
* Before/after comparisons
81-
* Best practices
82-
8376
== Quickstart
8477

8578
=== Install and configure
@@ -111,61 +104,61 @@ Claude: *uses generate_property_docs tool*
111104

112105
=== Documentation generation tools
113106

114-
* **Version information** - Get latest Redpanda and Console versions
115-
* **Property docs** - Generate configuration property documentation
116-
* **Metrics docs** - Generate metrics reference documentation
117-
* **RPK docs** - Generate RPK CLI documentation
118-
* **Connector docs** - Generate Redpanda Connect connector documentation
119-
* **Antora structure** - Analyze documentation repository structure
107+
* **Version information**: Get latest Redpanda and Console versions
108+
* **Property docs**: Generate configuration property documentation
109+
* **Metrics docs**: Generate metrics reference documentation
110+
* **RPK docs**: Generate RPK CLI documentation
111+
* **Connector docs**: Generate Redpanda Connect connector documentation
112+
* **Antora structure**: Analyze documentation repository structure
120113

121114
=== AI consistency prompts
122115

123116
Pre-configured instructions that help Claude follow your team standards:
124117

125118
**Review prompts:**
126119

127-
* **review-for-style** - Review content for style guide compliance
128-
* **check-terminology** - Validate terminology against approved terms
129-
* **improve-clarity** - Refactor content for better readability
120+
* **review-for-style**: Review content for style guide compliance
121+
* **check-terminology**: Validate terminology against approved terms
122+
* **improve-clarity**: Refactor content for better readability
130123

131124
**Content creation:**
132125

133-
* **write-new-guide** - Generate new guides following team standards
126+
* **write-new-guide**: Generate new guides following team standards
134127

135128
**Workflow guides:**
136129

137-
* **property-docs-guide** - Workflow for updating property documentation
138-
* **rpcn-connector-docs-guide** - Workflow for updating connector documentation
130+
* **property-docs-guide**: Workflow for updating property documentation
131+
* **rpcn-connector-docs-guide**: Workflow for updating connector documentation
139132

140133
=== Resources
141134

142135
Reference materials that Claude can read:
143136

144-
* **redpanda://style-guide** - Complete team style guide with formatting rules
137+
* **redpanda://style-guide**: Complete team style guide with formatting rules
145138

146139
=== CLI validation commands
147140

148141
For writers extending the MCP server:
149142

150-
* **npx doc-tools validate-mcp** - Validate prompts and resources configuration
151-
* **npx doc-tools preview-prompt** - Preview prompts with test arguments
152-
* **npx doc-tools mcp-version** - Show versions and usage statistics
143+
* **npx doc-tools validate-mcp**: Validate prompts and resources configuration
144+
* **npx doc-tools preview-prompt**: Preview prompts with test arguments
145+
* **npx doc-tools mcp-version**: Show versions and usage statistics
153146

154147
=== Automation
155148

156-
* **setup-mcp** - Automated MCP server configuration for Claude Code/Desktop
157-
* **Auto-discovery** - Prompts automatically loaded from `mcp/prompts/` directory
158-
* **Context detection** - Automatic repository and Antora structure detection
159-
* **Usage telemetry** - Track prompt/resource/tool usage for adoption metrics
149+
* **setup-mcp**: Automated MCP server configuration for Claude Code/Desktop
150+
* **Auto-discovery**: Prompts automatically loaded from `mcp/prompts/` directory
151+
* **Context detection**: Automatic repository and Antora structure detection
152+
* **Usage telemetry**: Track prompt/resource/tool usage for adoption metrics
160153

161154
== Architecture
162155

163156
The MCP server consists of:
164157

165-
* **Server** (`bin/doc-tools-mcp.js`) - Main MCP protocol handler
166-
* **Tool modules** (`bin/mcp-tools/`) - Individual tool implementations
167-
* **Prompts** (`mcp/prompts/`) - Contextual documentation guides
168-
* **Tests** (`__tests__/mcp/`) - Integration, contract, and unit tests
158+
* **Server** (`bin/doc-tools-mcp.js`): Main MCP protocol handler
159+
* **Tool modules** (`bin/mcp-tools/`): Individual tool implementations
160+
* **Prompts** (`mcp/prompts/`): Contextual documentation guides
161+
* **Tests** (`__tests__/mcp/`): Integration, contract, and unit tests
169162

170163
== Support
171164

package-lock.json

Lines changed: 3 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

package.json

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,14 @@
11
{
22
"name": "@redpanda-data/docs-extensions-and-macros",
3-
"version": "4.13.0",
3+
"version": "4.13.1",
44
"description": "Antora extensions and macros developed for Redpanda documentation.",
55
"keywords": [
66
"antora",
77
"extension",
88
"macro",
99
"documentation",
10-
"redpanda"
10+
"redpanda",
11+
"mcp"
1112
],
1213
"author": {
1314
"name": "Redpanda Docs Team"
@@ -80,7 +81,8 @@
8081
"bin",
8182
"cli-utils",
8283
"tools",
83-
"docker-compose"
84+
"docker-compose",
85+
"mcp"
8486
],
8587
"license": "ISC",
8688
"repository": {

sample-doc-for-review.adoc

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
= Configuring Data Archiving to S3
2+
:description: This document explains how data archiving can be configured.
3+
4+
== Overview
5+
6+
Tiered Storage allows data to be moved to object storage like S3 or GCS. This feature was introduced in Redpanda and it is used by many customers to reduce storage costs. In this guide, you will learn how to configure archiving.
7+
8+
== Prerequisites
9+
10+
Before you begin, the following prerequisites must be met:
11+
12+
* A Redpanda cluster should be running
13+
* AWS credentials need to be configured
14+
* The S3 bucket must have been created already
15+
* You should have admin access to the Redpanda UI
16+
17+
== Configuration Steps
18+
19+
=== Step 1: Enable Tiered Storage
20+
21+
First, tiered storage needs to be enabled on your cluster. This can be done by running the following command:
22+
23+
[,bash]
24+
----
25+
rpk cluster config set cloud_storage_enabled true
26+
----
27+
28+
After the command is executed, the cluster will be restarted automatically.
29+
30+
=== Step 2: Configure the S3 Bucket
31+
32+
The bucket needs to be configured next. Go to the Redpanda Console and click on the Settings tab. The following settings should be entered:
33+
34+
|===
35+
| Setting | Value
36+
37+
| cloud_storage_bucket | your-bucket-name
38+
| cloud_storage_region | us-east-1
39+
|===
40+
41+
NOTE: It is recommended that versioning is enabled on your bucket.
42+
43+
=== Step 3: Set Retention Policy
44+
45+
Data retention can be configured at the topic level. You should utilize the `rpk` command line tool:
46+
47+
[,bash]
48+
----
49+
rpk topic alter-config my-topic --set retention.bytes=1000000000
50+
----
51+
52+
The above command sets retention to approximately 1GB. After this is done, old segments will be uploaded to S3 and deleted locally.
53+
54+
== Verifying the Setup
55+
56+
To verify that archiving is working, the following steps can be taken:
57+
58+
1. Data should be produced to a topic
59+
2. Wait for segments to be uploaded (this usually takes a few minutes)
60+
3. The S3 bucket can be checked using the AWS CLI or Console
61+
62+
You can also run this command to check the status:
63+
64+
[,bash]
65+
----
66+
rpk cluster storage status
67+
----
68+
69+
== Troubleshooting
70+
71+
If data is not being uploaded, the following should be checked:
72+
73+
* Credentials - it's possible that the AWS credentials are invalid or expired
74+
* Bucket permissions - write access must be granted to Redpanda
75+
* Network - connectivity to S3 should be verified
76+
77+
TIP: Logs can be very helpful here. They can be viewed using `rpk debug logs`.
78+
79+
== Summary
80+
81+
In this guide, tiered storage configuration was explained. By following these steps, your data will be automatically archived to S3, which helps reduce costs while maintaining data availability.
82+
83+
For more info, see the Redpanda documentation.

0 commit comments

Comments
 (0)