fix(mcp): fix GetDocumentByUrl and AnalyzeDocumentStructure returning 'Document not found'

[theletterf]

Issue

Closes #2722.

GetDocumentByUrl and AnalyzeDocumentStructure returned "Document not found" for every URL, including paths returned by other MCP tools such as SemanticSearch.

Root cause

Two independent bugs in DocumentGateway:

1. Non-existent Elasticsearch field (url.keyword)

The query used .Suffix("keyword") to construct the field path url.keyword. However, the index mapping defines url as type: keyword directly — its only sub-fields are url.match and url.prefix. The field url.keyword does not exist, so the Term query produced zero hits for every input.

Fix: remove .Suffix("keyword") and query the url field directly.

2. No URL normalization

The URL was passed to the Term query unchanged. The index stores path-only values like /docs/deploy-manage/api-keys, so full URLs such as https://www.elastic.co/docs/deploy-manage/api-keys never matched, nor did bare paths without a leading slash.

Fix: added NormalizeUrl, which:

• Parses absolute URLs and extracts the path component via Uri.AbsolutePath.
• Ensures a leading slash on relative paths.
• Strips trailing slashes.

Changes

• DocumentGateway.GetByUrlAsync / GetStructureAsync: fix field reference, add normalization call.
• DocumentGateway.NormalizeUrl: new private static helper.
• DocumentTools: updated parameter descriptions to document accepted URL formats.

Trade-offs

• The normalizer is deliberately minimal: it does not validate that the path starts with /docs/, because path prefixes may change across deployments and the gateway should not encode that assumption.
• Fragment identifiers (#heading) in absolute URLs are silently dropped by Uri.AbsolutePath; this is the correct behavior since the index does not store fragment-level granularity.

LLM usage

This fix was developed with Claude 4.6 Sonnet and Cursor.

Made with Cursor