[kbn-docs-utils] Add MCP documentation tools and flat stats output#254836
Draft
clintandrewhall wants to merge 6 commits intoelastic:mainfrom
Draft
[kbn-docs-utils] Add MCP documentation tools and flat stats output#254836clintandrewhall wants to merge 6 commits intoelastic:mainfrom
clintandrewhall wants to merge 6 commits intoelastic:mainfrom
Conversation
…erformance - Refactor metrics output to use structured table helpers (`printIssueTable`, `printMissingExportsTable`) and improve GitHub links with line-number anchors via `getLink`. - Introduce two-pass plugin discovery so filtered builds receive an `allPlugins` list for accurate cross-reference resolution while scoping the TypeScript project to a single plugin's directory for faster compilation. - Gate aggregate documentation (plugin directory, deprecation summaries) behind a check for both `pluginFilter` and `packageFilter` to avoid writing partial data.
…tility - Add `--write` flag to `check_package_docs` CLI that writes per-plugin/package `stats.json` to `target/api_docs/` for MCP tools. - Add `write` to `CliFlags` and `writeStats` to `CliOptions` with corresponding flag parsing. - Extract `getLink` from `report_metrics.ts` into shared `get_link.ts` module, reused by both `report_metrics.ts` and `flat_stats.ts`.
…tools - Add `check_package_docs` tool that runs doc validation on a plugin, package, or file and returns pass/fail status with issue counts by category. - Add `fix_package_docs` tool that returns detailed issues grouped by file with source snippets and fix templates for agent-assisted remediation. - Both tools support flexible targeting via plugin ID, manifest ID (`@kbn/...`), or file path with auto-detection. - Document both tools in the `kbn-mcp-dev-server` README with parameter tables, example responses, and recommended workflow. - Register both tools in the MCP server entry point.
Contributor
|
🤖 Jobs for this PR can be triggered through checkboxes. 🚧
ℹ️ To trigger the CI, please tick the checkbox below 👇
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Important
Depends on #254835. Merge that PR first, then rebase this branch onto
main.Adds two new MCP tools to
kbn-mcp-dev-serverfor checking and fixing API documentation issues, along with the flat stats JSON infrastructure they consume.Note
This PR is a subset of #247688 for ease of review.
This PR was written with Cursor and
claude-4.5-opus-high.check_package_docsquickly validates a plugin, package, or file and returns pass/fail with issue counts by category.fix_package_docsreturns detailed issues grouped by file with source snippets and fix templates for agent-assisted remediation.@kbn/...), or file path with auto-detection.--writeflag on thecheck_package_docsCLI writes per-packagestats.jsonfiles totarget/api_docs/, which the MCP tools consume.docs_utils.ts(package resolution, target detection, stats generation) andget_link.ts(GitHub source link generation).Commit structure
[kbn-docs-utils] Add flat stats JSON output, extract shared getLink utilityFlatStatsinterfaces,--writeflag,flat_stats.ts, and extractsgetLinkinto a shared module.[kbn-mcp-dev-server] Add check_package_docs and fix_package_docs MCP toolsdocs_utils.ts, registers them in the server, and documents them in the README.TestsNotes
FlatStatstype is defined canonically in@kbn/docs-utilsand replicated (not imported) inkbn-mcp-dev-serverto avoid a direct package dependency; a comment links to the source of truth.