Skip to content

Commit 87df153

Browse files
JakeSCahillclaude
JakeSCahill
and
claude
committed
Improve MCP documentation for team standards compliance
Applied comprehensive improvements to all MCP documentation files based on docs team standards review: Style improvements: - Added glossterm macros for key technical terms (tools, resources, prompts, topics, clusters, ACLs) on first mention - Added explicit link text to all xrefs for better accessibility - Fixed heading capitalization to sentence case - Improved introduction paragraphs to lead with value/outcome Content quality: - Rewrote introductions to be more outcome-focused - Standardized xref link text across all files - Improved consistency in terminology usage Testing: - Generated Doc Detective test specifications for create-server.adoc (4 tests, 41 steps validated) - Generated Doc Detective test specifications for test-tools.adoc (7 tests, 41 steps validated) - Both test specs validated successfully Files modified: - modules/mcp/pages/index.adoc - modules/mcp/pages/create-server.adoc - modules/mcp/pages/register-remote.adoc - modules/mcp/pages/test-tools.adoc - modules/mcp/pages/user-delegated-oauth.adoc - modules/mcp/pages/managed-catalog.adoc Files added: - modules/mcp/doc-detective-create-server.json - modules/mcp/doc-detective-test-tools.json These changes address all critical issues identified in the documentation review and prepare the content for GA publication. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent 77ed2e1 commit 87df153

8 files changed

Lines changed: 474 additions & 46 deletions

‎modules/mcp/doc-detective-create-server.json‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
{
2+
"tests": [
3+
{
4+
"testId": "create-managed-mcp-server",
5+
"description": "Create a managed MCP server following the documented procedure",
6+
"steps": [
7+
{
8+
"description": "Navigate to ADP UI",
9+
"goTo": "https://adp.redpanda.com"
10+
},
11+
{
12+
"description": "Verify user is on the ADP UI home page",
13+
"find": "MCP Servers"
14+
},
15+
{
16+
"description": "Navigate to MCP Servers section",
17+
"click": "MCP Servers"
18+
},
19+
{
20+
"description": "Verify MCP Servers page loaded",
21+
"find": "Create Server"
22+
},
23+
{
24+
"description": "Click Create Server button to open marketplace picker",
25+
"click": "Create Server"
26+
},
27+
{
28+
"description": "Verify marketplace picker opened",
29+
"find": "Remote (Proxied)"
30+
},
31+
{
32+
"description": "Select a managed type card (SQL example)",
33+
"click": "SQL"
34+
},
35+
{
36+
"description": "Verify server configuration form loaded",
37+
"find": "Name"
38+
},
39+
{
40+
"description": "Enter server name (lowercase, hyphens, starts with letter)",
41+
"type": {
42+
"keys": "test-sql-server",
43+
"selector": "input[name='name']"
44+
}
45+
},
46+
{
47+
"description": "Enter server description",
48+
"type": {
49+
"keys": "Test SQL server for documentation testing",
50+
"selector": "input[name='description']"
51+
}
52+
},
53+
{
54+
"description": "Verify Enabled toggle is present",
55+
"find": "Enabled"
56+
},
57+
{
58+
"description": "Configure authentication - select None mode",
59+
"click": "None"
60+
},
61+
{
62+
"description": "Click Create button to save the server",
63+
"click": "Create"
64+
},
65+
{
66+
"description": "Verify server was created and appears in list",
67+
"find": "test-sql-server"
68+
},
69+
{
70+
"description": "Verify Type badge shows server type",
71+
"find": "Managed"
72+
}
73+
]
74+
},
75+
{
76+
"testId": "verify-mcp-server-details",
77+
"description": "Verify server details and tool discovery after creation",
78+
"steps": [
79+
{
80+
"description": "Open the newly created server detail page",
81+
"click": "test-sql-server"
82+
},
83+
{
84+
"description": "Verify Overview tab is shown",
85+
"find": "Overview"
86+
},
87+
{
88+
"description": "Verify API URL is displayed",
89+
"find": "API URL"
90+
},
91+
{
92+
"description": "Switch to Inspector tab",
93+
"click": "Inspector"
94+
},
95+
{
96+
"description": "Verify Inspector tab loaded",
97+
"find": "Tools"
98+
},
99+
{
100+
"description": "Verify tools list is populated (not empty)",
101+
"find": "query"
102+
}
103+
]
104+
},
105+
{
106+
"testId": "create-self-managed-mcp-server",
107+
"description": "Create a self-managed (Remote/Proxied) MCP server",
108+
"steps": [
109+
{
110+
"description": "Navigate to MCP Servers section",
111+
"goTo": "https://adp.redpanda.com/mcp-servers"
112+
},
113+
{
114+
"description": "Click Create Server button",
115+
"click": "Create Server"
116+
},
117+
{
118+
"description": "Select Remote (Proxied) option for self-managed server",
119+
"click": "Remote (Proxied)"
120+
},
121+
{
122+
"description": "Verify self-managed configuration form loaded",
123+
"find": "URL"
124+
},
125+
{
126+
"description": "Enter server name",
127+
"type": {
128+
"keys": "test-remote-server",
129+
"selector": "input[name='name']"
130+
}
131+
},
132+
{
133+
"description": "Enter server URL (must start with http:// or https://)",
134+
"type": {
135+
"keys": "https://mcp-server.example.com",
136+
"selector": "input[name='url']"
137+
}
138+
},
139+
{
140+
"description": "Verify Transport field is present",
141+
"find": "Transport"
142+
},
143+
{
144+
"description": "Select SSE transport",
145+
"click": "SSE"
146+
},
147+
{
148+
"description": "Configure authentication - select None mode",
149+
"click": "None"
150+
},
151+
{
152+
"description": "Click Create button",
153+
"click": "Create"
154+
},
155+
{
156+
"description": "Verify self-managed server was created",
157+
"find": "test-remote-server"
158+
},
159+
{
160+
"description": "Verify Type badge shows Self-managed",
161+
"find": "Self-managed"
162+
}
163+
]
164+
},
165+
{
166+
"testId": "verify-authentication-modes",
167+
"description": "Verify all five authentication modes are available",
168+
"steps": [
169+
{
170+
"description": "Navigate to create server flow",
171+
"goTo": "https://adp.redpanda.com/mcp-servers"
172+
},
173+
{
174+
"description": "Click Create Server",
175+
"click": "Create Server"
176+
},
177+
{
178+
"description": "Select a managed type",
179+
"click": "SQL"
180+
},
181+
{
182+
"description": "Verify None auth mode is available",
183+
"find": "None"
184+
},
185+
{
186+
"description": "Verify Static key auth mode is available",
187+
"find": "Static key"
188+
},
189+
{
190+
"description": "Verify Token passthrough auth mode is available",
191+
"find": "Token passthrough"
192+
},
193+
{
194+
"description": "Verify Service-account OAuth auth mode is available",
195+
"find": "Service-account OAuth"
196+
},
197+
{
198+
"description": "Verify User-delegated OAuth auth mode is available",
199+
"find": "User-delegated OAuth"
200+
}
201+
]
202+
}
203+
]
204+
}

0 commit comments

Comments
 (0)