Skip to content

fix: resolve index-style and template slugs in the docs MCP server - #153

Open
philip wants to merge 1 commit into
mainfrom
fix-docs-mcp-slug-resolution
Open

philip wants to merge 1 commit into
mainfrom
fix-docs-mcp-slug-resolution

Conversation

@philip

@philip philip commented Sep 18, 2026

Copy link
Copy Markdown
Collaborator

Overview

Fix slug resolution in the DevHub docs MCP server. get_doc_resource matched only bare docs slugs, so a slug copied from list_docs_resources (a full URL, a docs/ prefix, or a trailing .md) and any template or recipe page returned not found. This normalizes the slug and routes template, recipe, and solution pages through a shared renderDetailMarkdown helper, now used by the MCP route, the /api/markdown route, and the static-artifact build script, so all three return identical markdown.

Reported through DevHub agent feedback.

Verified end to end over HTTP against a local server: index-style slugs and template/recipe pages resolve, and path traversal is still rejected.

This pull request and its description were written by Isaac.

The get_doc_resource tool matched only bare docs slugs, so a slug copied from list_docs_resources (a full URL, a docs/ prefix, or a trailing .md) or any template or recipe page came back as not found. Normalize the slug and route template, recipe, and solution pages through a shared renderDetailMarkdown helper, now used by the MCP route, the markdown API route, and the static-artifact build script.

Reported through DevHub agent feedback.

Co-authored-by: Isaac <no-reply@databricks.com>
@thisistonydang

Copy link
Copy Markdown
Collaborator

Tony's agent: I reproduced an issue with the section overview URLs returned by list_docs_resources.

Calling get_doc_resource with https://developers.databricks.com/templates.md returns the docs article titled “What are templates?” instead of the full template catalog.

Calling it with https://developers.databricks.com/solutions.md returns “Doc page not found”.

Individual detail URLs, such as https://developers.databricks.com/templates/genie-conversational-analytics.md, work correctly.

The parser only recognizes templates/ and solutions/ with a trailing slash. It should also recognize the bare templates and solutions paths after removing the .md suffix. Please add tests for both overview URLs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants