[RUN-0000] Rework MCP server docs: split setup pages, unified config reference - #1928
Open
smartinellibenedetti wants to merge 2 commits into
Open
[RUN-0000] Rework MCP server docs: split setup pages, unified config reference#1928smartinellibenedetti wants to merge 2 commits into
smartinellibenedetti wants to merge 2 commits into
Conversation
… configuration reference - index.md: lead with a concrete scenario and a direct two-point "why use it" instead of jargon-forward prose; demote the tools/resources/prompts primitive breakdown to a closing aside. - Split the old monolithic installation.md (Docker + every npx client) into installation.md (Docker + Claude Code, the fastest path) and other-setups.md (every other client, plus npx). - Add best-practices.md: dedicated-token, ACL-scoping, non-prod-first checklist for pointing this at a real instance. - Add configuration.md: every environment variable the server reads, in one place, grouped by concern. installation.md and other-setups.md now point here instead of each carrying a partial, duplicate table. - Fix the minimum-Rundeck-version claim: it was "6.0", but the default RUNDECK_API_VERSION (59) was introduced in 6.1.0, not 6.0.0/6.0.1 - confirmed via git history on rundeck-api.yml (the version bump commit is titled "6.1.0 Release Prep") and the 5.20.0/6.1.0 changelogs. - faq.md: add the Docker-image OpenAPI-validation gap (spec file excluded from the sparse checkout, so api_call never rejects bad params there). - tools.md: document the api_call fallback that job_create/job_validate/ runner_create/acl_manage guidance mode points to. - Update the sidebar to match the new page set and order.
smartinellibenedetti
changed the title
…bilities page Replace tools.md, resources.md, and prompts.md with capabilities.md, rewritten as prose rather than exhaustive parameter/argument tables. Those tables duplicated what the tool Zod schemas and each MCP client's own prompt picker already surface authoritatively - same staleness risk resources.md already had by its own admission. What's kept is the part that isn't duplicated anywhere: when each tool is (and isn't) the right choice, and the scope/ACL trust caveats (job_create not enforcing org conventions, Runner-level ACL behavior) that best-practices.md and faq.md actually link to. Update every cross-reference (index.md, installation.md, best-practices.md, faq.md, sidebar) accordingly, and re-verify all internal links/anchors across the whole docs/mcp/ set.
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
1 participant
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
index.md: leads with a concrete scenario and a direct two-point "why use it" instead of jargon-forward prose; the tools/resources/prompts primitive breakdown moves to a closing aside rather than interrupting the pitch.installation.md(Docker + every npx client crammed together) intoinstallation.md(Docker + Claude Code, the fastest path) andother-setups.md(every other client, plus npx).best-practices.md: dedicated-token, ACL-scoping, non-prod-first checklist for pointing this at a real instance.configuration.md: every environment variable the server reads, in one place, grouped by concern —installation.md/other-setups.mdnow point here instead of each carrying a partial, duplicate table.RUNDECK_API_VERSION(59) was introduced in 6.1.0, not 6.0.0/6.0.1 — confirmed via therundeck-api.ymlgit history (the version-bump commit is titled "6.1.0 Release Prep") and the 5.20.0/6.1.0 changelogs.faq.md: added the Docker-image OpenAPI-validation gap (the spec file is excluded from the sparse checkout, soapi_callnever rejects bad params there).tools.md: documented theapi_callfallback thatjob_create/job_validate/runner_create/acl_manageguidance mode points to.Every technical claim (schemas, enums, defaults, the Docker sparse-checkout behavior) was cross-checked against
rundeck/mcp'ssrc/before merging.Test plan
index.md's "In this section"index.md,installation.md,other-setups.md,configuration.md,resources.md)