Skip to content

docs(mcp): surface install extra in quick-start and add stdio caveat#216

Open
rodboev wants to merge 1 commit into
NVIDIA:mainfrom
rodboev:pr/mcp-docs-install-scope
Open

docs(mcp): surface install extra in quick-start and add stdio caveat#216
rodboev wants to merge 1 commit into
NVIDIA:mainfrom
rodboev:pr/mcp-docs-install-scope

Conversation

@rodboev

@rodboev rodboev commented Jun 27, 2026

Copy link
Copy Markdown

Summary

Surface the MCP-capable install path at the first Quick Start decision point, then tighten the README and CLI help so skillspector mcp is described as the current FastMCP stdio path that requires skillspector[mcp].

Refs #199

Root cause

The README leads with a base-only uv tool install command, while the MCP-specific install requirement appears later in the MCP section. The skillspector mcp help text repeats that split by describing stdio before users see the optional-extra requirement, so they can hit the missing-dependency path before they ever learn which install command they needed.

Diff Notes

  • README.md
    • Make the first uv install path explicitly CLI-only.
    • Add an MCP-capable direct-URL install command beside it so users can choose the right path before invoking skillspector mcp.
    • State plainly that skillspector mcp requires skillspector[mcp].
    • Narrow the stdio wording to the current FastMCP transport scope and call out the existing initialize hang in issue #199 without framing it as fixed.
  • src/skillspector/cli.py
    • Update the mcp command help text so the optional mcp extra is visible before the import-failure path.
    • Align the transport wording with the README by naming FastMCP stdio for local CLI agents and http for remote or A2A callers.

Scope

This PR changes only README.md and src/skillspector/cli.py. It does not change src/skillspector/mcp_server.py, add transport diagnostics, or claim to resolve the stdio initialize hang from #199.

Verification

  • rtk git -C "D:\Repos\SkillSpector-pr-mcp-docs-install-scope" diff -- README.md src\skillspector\cli.py - keeps the slice to the intended README and CLI help surfaces.
  • Select-String -Pattern 'skillspector[mcp]' -SimpleMatch -Path 'D:\Repos\SkillSpector-pr-mcp-docs-install-scope\README.md','D:\Repos\SkillSpector-pr-mcp-docs-install-scope\src\skillspector\cli.py' - confirms the optional-extra guidance is visible on both user-facing surfaces.
  • rtk grep "skillspector mcp" "D:\Repos\SkillSpector-pr-mcp-docs-install-scope\README.md" "D:\Repos\SkillSpector-pr-mcp-docs-install-scope\src\skillspector\cli.py" - confirms the updated MCP wording appears in both places users read it.
  • cmd /d /s /c "cd /d D:\Repos\SkillSpector-pr-mcp-docs-install-scope && rtk uv run skillspector mcp --help" - verifies the rendered help surfaces the optional extra before the runtime import-failure path.
  • CI Lint & Test (Python 3.12), Lint & Test (Python 3.13), and DCO Check - pending maintainer approval if fork checks are gated.

Notes

This is the repo-owned docs and help-text slice only. The runtime stdio initialize hang remains outside this PR.

Signed-off-by: Rod Boev <rod.boev@gmail.com>
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.

1 participant