Skip to content

Commit 2a9d6f3

Browse files
theletterfclaudecursoragent
authored
fix(mcp): fix document tools and expand MCP documentation (#2731)
* fix(mcp): add missing required fields to document query source filters GetByUrlAsync omitted `search_title` and GetStructureAsync omitted both `search_title` and `type` from the Elasticsearch _source filter. Since DocumentationDocument marks these as `required`, the JSON deserializer threw on every response: "missing required properties including: 'search_title'". Adding them to the source filter fixes the 2 broken document tools. Co-authored-by: Claude <claude@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com> * docs(mcp): expand MCP docs with 4-IDE install tabs and one-click install buttons - Add Cursor and VS Code one-click deep-link install buttons. - Add Claude Code tab with CLI (`claude mcp add`) and `.mcp.json` instructions. - Add IntelliJ IDEA tab with UI navigation steps and JSON config. - Note that the MCP server uses stateless Streamable HTTP transport. - Mention full-URL support in `GetDocumentByUrl` and `AnalyzeDocumentStructure` descriptions in docs. - Update SKILL.md to reflect that both tools accept full URLs or paths (fixing misleading path-only examples). Co-authored-by: Claude <claude@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com> * docs(mcp): add all 14 MCP tools to SKILL.md The skill previously only documented 6 of the 14 tools (search and document tools). Add the missing 8: ResolveCrossLink, ListRepositories, GetRepositoryLinks, FindCrossLinks, ValidateCrossLinks (LinkTools), and ListContentTypes, GenerateTemplate, GetContentTypeGuidelines (ContentTypeTools). Also update the skill name/description and usage guidelines to reflect the full set of capabilities. Co-authored-by: Claude <claude@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com> * fix(docs/mcp): correct VS Code deep link URL encoding The / characters inside the JSON value were not percent-encoded (%2F), which would cause VS Code's protocol handler to misparse the config. Use full encodeURIComponent-style encoding (safe='') so the link matches what the VS Code MCP install handler expects. Co-authored-by: Claude <claude@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com> * docs(mcp): move installation before tool reference Installation instructions are the most common entry point for readers, so surface them before the command reference. Co-authored-by: Claude <claude@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com> * fix: exclude IDE deep-link schemes from cross-link validation cursor:// and vscode: URLs (used for one-click MCP server installation buttons) were not in ExcludedSchemes, so the link validator treated them as cross-repository links and reported 'cursor'/'vscode' not found in the cross-link index. Add cursor, vscode, and vscode-insiders to ExcludedSchemes so they are passed through as plain external links. Co-authored-by: Claude <claude@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com> * fix: treat non-http absolute URIs as opaque external links After the cross-link check passes, ValidateExternalUri only returned true (skip internal-path validation) for http/https and mailto schemes. Any other absolute URI — including cursor:// and vscode: deep links — fell through to ProcessInternalLink, which resolved them as relative file paths and emitted "does not exist" errors. Change the early-return to `true` for any non-http/non-mailto scheme so that opaque protocol links (IDE deep links, ftp://, etc.) are skipped by the file-existence validator entirely. Co-authored-by: Claude <claude@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com> * fix: guard against empty paragraph text in ProcessListBlock GetInlineText returns "" when all inlines in a list item are unhandled types (e.g. HtmlInline). Accessing paragraphText[^1] on an empty string throws IndexOutOfRangeException. Add the same null/empty guard that ProcessParagraph already uses, so empty list items are skipped rather than causing an uncaught exception during description generation. Co-authored-by: Claude <claude@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com> * Revert "fix: guard against empty paragraph text in ProcessListBlock" This reverts commit 3d35fc1. * Revert "fix: treat non-http absolute URIs as opaque external links" This reverts commit 22895b1. * Revert "fix: exclude IDE deep-link schemes from cross-link validation" This reverts commit e136184. * test: remove install buttons to isolate DescriptionGenerator crash Revert CrossLinkValidator and DiagnosticLinkInlineParser changes, and remove cursor:// and vscode: deep-link buttons from docs, to verify whether the DescriptionGenerator IndexOutOfRangeException is caused by these changes or is a pre-existing docs-content issue. Co-authored-by: Claude <claude@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com> * docs(mcp): add install buttons using ela.st redirects Use https://ela.st short links that redirect to cursor:// and vscode: deep-link protocols. This avoids triggering cross-link validation while still providing one-click install buttons for Cursor and VS Code. Co-authored-by: Claude <claude@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com> * docs(mcp): use raw HTML links for IDE install buttons Replace {button} directives with raw <a> tags for the cursor:// and vscode: deep links. The markdown link parser does not process inline HTML, so these bypass cross-link validation entirely. Co-authored-by: Claude <claude@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com> * ci: retrigger CI Co-authored-by: Cursor <cursoragent@cursor.com> * docs(mcp): use copyable code blocks for IDE install deep links Raw HTML links render as static text. Replace with code blocks that readers can copy and paste into their browser's address bar to trigger the IDE install prompt. Co-authored-by: Claude <claude@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Claude <claude@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent 067cea7 commit 2a9d6f3

2 files changed

Lines changed: 233 additions & 55 deletions

File tree

‎.claude/skills/mcp-search/SKILL.md‎

Lines changed: 119 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
---
22
name: mcp-search
3-
description: Search and analyze Elastic documentation using the remote MCP server. Use this when the user asks to search docs, find documentation, check coherence, find inconsistencies, get a document by URL, or analyze document structure. Trigger words: search, find, docs, documentation, coherence, inconsistencies, related, structure, analyze.
3+
description: Search, analyze, and author Elastic documentation using the remote MCP server. Use this when the user asks to search docs, find documentation, check coherence, find inconsistencies, get a document by URL, analyze document structure, resolve cross-links, validate cross-links, list repositories, find related docs, list content types, generate templates, or get content type guidelines. Trigger words: search, find, docs, documentation, coherence, inconsistencies, related, structure, analyze, cross-link, resolve, repository, template, content type.
44
---
55

6-
# Elastic Documentation MCP Search
6+
# Elastic Documentation MCP
77

8-
This skill provides access to Elastic documentation through a remote MCP server. Use these tools to search, analyze, and verify documentation content.
8+
This skill provides access to Elastic documentation through a remote MCP server. Use these tools to search, analyze, author, and validate documentation content.
99

1010
## Available Tools
1111

@@ -16,7 +16,7 @@ This skill provides access to Elastic documentation through a remote MCP server.
1616
**Trigger words:** search, find, docs, documentation, look up, examples, query
1717

1818
**Parameters:**
19-
- `query` (required): The search query - can be a question or keywords
19+
- `query` (required): The search query — can be a question or keywords
2020
- `pageNumber` (optional, default: 1): Page number (1-based)
2121
- `pageSize` (optional, default: 10, max: 50): Number of results per page
2222
- `productFilter` (optional): Filter by product ID (e.g., 'elasticsearch', 'kibana', 'fleet', 'logstash')
@@ -85,7 +85,7 @@ This skill provides access to Elastic documentation through a remote MCP server.
8585
**Trigger words:** get document, fetch, URL, specific page, retrieve, show page
8686

8787
**Parameters:**
88-
- `url` (required): The document URL (e.g., '/docs/elasticsearch/reference/index')
88+
- `url` (required): The document URL. Accepts a full URL (e.g., `https://www.elastic.co/docs/deploy-manage/api-keys`) or a path (e.g., `/docs/deploy-manage/api-keys`). Query strings, fragments, and trailing slashes are ignored.
8989
- `includeBody` (optional, default: false): Include full body content (set true for detailed analysis)
9090

9191
**Returns:** Full document content including:
@@ -106,7 +106,7 @@ This skill provides access to Elastic documentation through a remote MCP server.
106106
**Trigger words:** structure, hierarchy, organization, headings, parents, layout, analyze
107107

108108
**Parameters:**
109-
- `url` (required): Document URL to analyze
109+
- `url` (required): The document URL to analyze. Accepts a full URL (e.g., `https://www.elastic.co/docs/deploy-manage/api-keys`) or a path (e.g., `/docs/deploy-manage/api-keys`). Query strings, fragments, and trailing slashes are ignored.
110110

111111
**Returns:** Structure analysis including:
112112
- Heading count and list of headings
@@ -117,13 +117,121 @@ This skill provides access to Elastic documentation through a remote MCP server.
117117

118118
---
119119

120+
### 7. ResolveCrossLink
121+
122+
**When to use:** User provides a cross-link URI (e.g., `docs-content://get-started/intro.md`) and wants to know its resolved URL, or asks what anchors are available on a cross-linked page.
123+
124+
**Trigger words:** cross-link, resolve, cross link, docs-content://, URI, anchor
125+
126+
**Parameters:**
127+
- `crossLink` (required): The cross-link URI to resolve (e.g., `docs-content://get-started/intro.md`)
128+
129+
**Returns:** Resolved URL, repository, path, available anchors, and any fragment.
130+
131+
---
132+
133+
### 8. ListRepositories
134+
135+
**When to use:** User wants to know which repositories are available in the cross-link index, or asks what repos can be linked to.
136+
137+
**Trigger words:** list repos, repositories, available repos, cross-link index
138+
139+
**Parameters:** None
140+
141+
**Returns:** List of repositories with names, branches, paths, git refs, and last-updated timestamps.
142+
143+
---
144+
145+
### 9. GetRepositoryLinks
146+
147+
**When to use:** User wants to see all pages and anchors published by a specific repository, or is auditing what a repo exposes for cross-linking.
148+
149+
**Trigger words:** repository links, pages in repo, anchors, what does repo publish
150+
151+
**Parameters:**
152+
- `repository` (required): The repository name (e.g., `docs-content`, `elasticsearch`)
153+
154+
**Returns:** Repository metadata, URL path prefix, page count, cross-link count, and a list of pages with their anchors.
155+
156+
---
157+
158+
### 10. FindCrossLinks
159+
160+
**When to use:** User wants to find all cross-links between repositories, either from a specific source repo or pointing to a specific target repo.
161+
162+
**Trigger words:** find cross-links, links between repos, who links to, links from
163+
164+
**Parameters:**
165+
- `from` (optional): Source repository to find links from
166+
- `to` (optional): Target repository to find links to
167+
168+
**Returns:** Count and list of cross-links with source repository, target repository, and the link URI.
169+
170+
---
171+
172+
### 11. ValidateCrossLinks
173+
174+
**When to use:** User wants to validate cross-links pointing to a repository and find any that are broken.
175+
176+
**Trigger words:** validate cross-links, broken links, check links, link validation
177+
178+
**Parameters:**
179+
- `repository` (required): Target repository to validate links to (e.g., `docs-content`)
180+
181+
**Returns:** Valid link count, broken link count, and details of any broken links (source repo, link URI, errors).
182+
183+
---
184+
185+
### 12. ListContentTypes
186+
187+
**When to use:** User wants to know what content types are available, is deciding what type of page to write, or asks for guidance on content type selection.
188+
189+
**Trigger words:** content types, what type, overview vs how-to, tutorial, troubleshooting, changelog type
190+
191+
**Parameters:** None
192+
193+
**Returns:** List of all content types (overview, how-to, tutorial, troubleshooting, changelog) with descriptions and when-to-use guidance.
194+
195+
---
196+
197+
### 13. GenerateTemplate
198+
199+
**When to use:** User wants a starting template for a new documentation page or changelog entry.
200+
201+
**Trigger words:** template, generate, starter, scaffold, new page, new doc
202+
203+
**Parameters:**
204+
- `contentType` (required): One of `overview`, `how-to`, `tutorial`, `troubleshooting`, or `changelog`
205+
- `title` (optional): Pre-fill the page or changelog title
206+
- `description` (optional): Pre-fill the frontmatter description
207+
- `product` (optional): Pre-fill the product field
208+
209+
**Returns:** A ready-to-use Markdown template (or YAML for changelogs) with correct frontmatter and structure.
210+
211+
---
212+
213+
### 14. GetContentTypeGuidelines
214+
215+
**When to use:** User wants detailed authoring guidance for a content type, is evaluating existing content against standards, or asks about best practices for a content type.
216+
217+
**Trigger words:** guidelines, best practices, how to write, checklist, evaluate, anti-patterns
218+
219+
**Parameters:**
220+
- `contentType` (required): One of `overview`, `how-to`, `tutorial`, `troubleshooting`, or `changelog`
221+
222+
**Returns:** Detailed guidelines including required elements checklist, recommended sections, best practices, and anti-patterns for the content type.
223+
224+
---
225+
120226
## Usage Guidelines
121227

122-
1. **For general searches:** Start with `SemanticSearch` to find relevant documentation
123-
2. **For content verification:** Use `CheckCoherence` to see how well a topic is documented
124-
3. **For quality checks:** Use `FindInconsistencies` to identify potential documentation conflicts
125-
4. **For specific pages:** Use `GetDocumentByUrl` when you have an exact URL
126-
5. **For deep analysis:** Use `AnalyzeDocumentStructure` to understand page organization
228+
1. **For general searches:** Start with `SemanticSearch` to find relevant documentation.
229+
2. **For content verification:** Use `CheckCoherence` to see how well a topic is documented.
230+
3. **For quality checks:** Use `FindInconsistencies` to identify potential documentation conflicts.
231+
4. **For specific pages:** Use `GetDocumentByUrl` when you have an exact URL.
232+
5. **For deep analysis:** Use `AnalyzeDocumentStructure` to understand page organization.
233+
6. **For cross-linking:** Use `ResolveCrossLink` to turn a cross-link URI into a real URL, `ListRepositories` to discover available repos, and `ValidateCrossLinks` to find broken links.
234+
7. **For authoring:** Use `ListContentTypes` to pick the right type, `GenerateTemplate` to get a starter, and `GetContentTypeGuidelines` to write or evaluate content correctly.
127235

128236
## Product IDs
129237

‎docs/mcp/index.md‎

Lines changed: 114 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,79 @@
11
# MCP server
22

3-
{{dbuild}} includes an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/introduction) server that allows AI assistants to interact with the documentation tooling directly.
3+
{{dbuild}} includes an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/introduction) server that allows AI assistants and coding agents to interact with Elastic documentation directly.
44

5-
The MCP server is deployed as an HTTP service and exposes all tools through a single endpoint.
5+
The MCP server is deployed as a stateless HTTP service and exposes all tools through a single Streamable HTTP endpoint at `https://www.elastic.co/docs/_mcp/`.
66

7-
## Available tools
7+
## Installation
88

9-
### Cross-link tools
9+
Add the {{dbuild}} MCP server to your editor or AI assistant using one of the options below.
1010

11-
| Tool | Description |
12-
|------|-------------|
13-
| `ResolveCrossLink` | Resolves a cross-link (like `docs-content://get-started/intro.md`) to its target URL and returns available anchors. |
14-
| `ListRepositories` | Lists all repositories available in the cross-link index with their metadata. |
15-
| `GetRepositoryLinks` | Gets all pages and their anchors published by a specific repository. |
16-
| `FindCrossLinks` | Finds all cross-links between repositories. Can filter by source or target repository. |
17-
| `ValidateCrossLinks` | Validates cross-links to a repository and reports any broken links. |
11+
:::::{tab-set}
1812

19-
### Content type tools
13+
::::{tab-item} Cursor
2014

21-
These tools help authors create and evaluate documentation using the [Elastic Docs content types](https://www.elastic.co/docs/contribute-docs/content-types).
15+
To install automatically, copy and paste the following link into your browser's address bar:
2216

23-
| Tool | Description |
24-
|------|-------------|
25-
| `ListContentTypes` | Lists all Elastic Docs content types with descriptions and guidance on when to use each. |
26-
| `GenerateTemplate` | Generates a ready-to-use template for a specific content type (overview, how-to, tutorial, troubleshooting, or changelog). Optionally pre-fills title, description, and product. |
27-
| `GetContentTypeGuidelines` | Returns detailed authoring and evaluation guidelines for a content type, including required elements, best practices, and anti-patterns. |
17+
```text
18+
cursor://anysphere.cursor-deeplink/mcp/install?name=elastic-docs&config=eyJ1cmwiOiJodHRwczovL3d3dy5lbGFzdGljLmNvL2RvY3MvX21jcC8ifQ==
19+
```
2820

29-
### Search tools
21+
Cursor will prompt you to install the `elastic-docs` MCP server.
3022

31-
| Tool | Description |
32-
|------|-------------|
33-
| `SemanticSearch` | Performs semantic search across all Elastic documentation. Returns relevant documents with summaries, scores, and navigation context. |
34-
| `FindRelatedDocs` | Finds documents related to a given topic or document. Useful for discovering related content and building context. |
23+
Or configure manually. Create or edit `.cursor/mcp.json` in your workspace:
3524

36-
### Document tools
25+
```json
26+
{
27+
"mcpServers": {
28+
"elastic-docs": {
29+
"url": "https://www.elastic.co/docs/_mcp/"
30+
}
31+
}
32+
}
33+
```
3734

38-
| Tool | Description |
39-
|------|-------------|
40-
| `GetDocumentByUrl` | Gets a specific documentation page by its URL. Returns full document content including AI summaries and metadata. |
41-
| `AnalyzeDocumentStructure` | Analyzes the structure of a documentation page. Returns heading count, links, parents, and AI enrichment status. |
35+
Then restart Cursor or reload the window. The tools will be available in **Agent mode**.
36+
::::
4237

43-
### Coherence tools
38+
::::{tab-item} Claude Code
4439

45-
| Tool | Description |
46-
|------|-------------|
47-
| `CheckCoherence` | Checks documentation coherence for a given topic by finding all related documents and analyzing their coverage. |
48-
| `FindInconsistencies` | Finds potential inconsistencies in documentation by comparing documents about the same topic. |
40+
Run the following command to add the server to your current project:
4941

50-
## Configuration
42+
```bash
43+
claude mcp add --transport http elastic-docs https://www.elastic.co/docs/_mcp/
44+
```
5145

52-
To use the {{dbuild}} MCP server, add it to your IDE's MCP configuration.
46+
To make it available across all your projects, add the `--scope user` flag:
5347

54-
::::{tab-set}
48+
```bash
49+
claude mcp add --scope user --transport http elastic-docs https://www.elastic.co/docs/_mcp/
50+
```
5551

56-
:::{tab-item} Cursor
57-
Create or edit `.cursor/mcp.json` in your workspace:
52+
Or add it manually to your project's `.mcp.json` file:
5853

5954
```json
6055
{
6156
"mcpServers": {
6257
"elastic-docs": {
58+
"type": "http",
6359
"url": "https://www.elastic.co/docs/_mcp/"
6460
}
6561
}
6662
}
6763
```
64+
::::
6865

69-
Then restart Cursor or reload the window. The tools will be available in **Agent mode**.
70-
:::
66+
::::{tab-item} Visual Studio Code
7167

72-
:::{tab-item} Visual Studio Code
73-
Create or edit `.vscode/mcp.json` in your workspace:
68+
To install automatically (requires VS Code 1.99+), copy and paste the following link into your browser's address bar:
69+
70+
```text
71+
vscode:mcp/install?%7B%22name%22%3A%22elastic-docs%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fwww.elastic.co%2Fdocs%2F_mcp%2F%22%7D
72+
```
73+
74+
VS Code will prompt you to install the `elastic-docs` MCP server.
75+
76+
Or configure manually. Create or edit `.vscode/mcp.json` in your workspace:
7477

7578
```json
7679
{
@@ -83,11 +86,78 @@ Create or edit `.vscode/mcp.json` in your workspace:
8386
}
8487
```
8588

86-
Requires GitHub Copilot with MCP support enabled.
87-
:::
89+
Requires GitHub Copilot with agent mode enabled.
90+
::::
91+
92+
::::{tab-item} IntelliJ IDEA
93+
94+
Configure the server through the IDE settings:
8895

96+
1. Open **Settings** → **Tools** → **AI Assistant** → **Model Context Protocol**.
97+
2. Click **Add** and select **HTTP** as the connection type.
98+
3. Enter `https://www.elastic.co/docs/_mcp/` as the server URL, and `elastic-docs` as the name.
99+
4. Click **OK** and apply the settings.
100+
101+
Or configure it directly via JSON by adding the following to your MCP settings file:
102+
103+
```json
104+
{
105+
"mcpServers": {
106+
"elastic-docs": {
107+
"url": "https://www.elastic.co/docs/_mcp/"
108+
}
109+
}
110+
}
111+
```
112+
113+
Requires JetBrains AI Assistant plugin version 2025.2 or later.
89114
::::
90115

116+
:::::
117+
118+
## Available tools
119+
120+
### Cross-link tools
121+
122+
| Tool | Description |
123+
|------|-------------|
124+
| `ResolveCrossLink` | Resolves a cross-link (like `docs-content://get-started/intro.md`) to its target URL and returns available anchors. |
125+
| `ListRepositories` | Lists all repositories available in the cross-link index with their metadata. |
126+
| `GetRepositoryLinks` | Gets all pages and their anchors published by a specific repository. |
127+
| `FindCrossLinks` | Finds all cross-links between repositories. Can filter by source or target repository. |
128+
| `ValidateCrossLinks` | Validates cross-links to a repository and reports any broken links. |
129+
130+
### Content type tools
131+
132+
These tools help authors create and evaluate documentation using the [Elastic Docs content types](https://www.elastic.co/docs/contribute-docs/content-types).
133+
134+
| Tool | Description |
135+
|------|-------------|
136+
| `ListContentTypes` | Lists all Elastic Docs content types with descriptions and guidance on when to use each. |
137+
| `GenerateTemplate` | Generates a ready-to-use template for a specific content type (overview, how-to, tutorial, troubleshooting, or changelog). Optionally pre-fills title, description, and product. |
138+
| `GetContentTypeGuidelines` | Returns detailed authoring and evaluation guidelines for a content type, including required elements, best practices, and anti-patterns. |
139+
140+
### Search tools
141+
142+
| Tool | Description |
143+
|------|-------------|
144+
| `SemanticSearch` | Performs semantic search across all Elastic documentation. Returns relevant documents with summaries, scores, and navigation context. Supports filtering by product and navigation section. |
145+
| `FindRelatedDocs` | Finds documents related to a given topic or document. Useful for discovering related content and building context. |
146+
147+
### Document tools
148+
149+
| Tool | Description |
150+
|------|-------------|
151+
| `GetDocumentByUrl` | Gets a specific documentation page by its URL. Accepts a full URL or a path. Returns full document content including AI summaries and metadata. |
152+
| `AnalyzeDocumentStructure` | Analyzes the structure of a documentation page. Accepts a full URL or a path. Returns heading count, links, parents, and AI enrichment status. |
153+
154+
### Coherence tools
155+
156+
| Tool | Description |
157+
|------|-------------|
158+
| `CheckCoherence` | Checks documentation coherence for a given topic by finding all related documents and analyzing their coverage. |
159+
| `FindInconsistencies` | Finds potential inconsistencies in documentation by comparing documents about the same topic. |
160+
91161
## Testing with MCP Inspector
92162

93163
You can test the MCP server using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

0 commit comments

Comments
 (0)