Skip to content

docs(mcp-governance): show how to point uvx at a kirocrew mirror - #28559

Closed
cruisercohen wants to merge 1 commit into
mainfrom
fix/23488-mcp-registry-mirror
Closed

cruisercohen wants to merge 1 commit into
mainfrom
fix/23488-mcp-registry-mirror

Conversation

@cruisercohen

@cruisercohen cruisercohen commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: The enterprise MCP governance guide tells an admin, before they copy the registry example, that it cannot launch without a private index hosting the kirocrew wheel, and shows how to point uvx at that index.

kirocrew is not on public PyPI, so the guide's pypi entries launch as uvx kirocrew@<version> mcp-core and fail; the session gets none of Kiro Crew's tools. The guide states the mirror requirement in one sentence before the example, but two reporters on #23488 read the example as working by default, and the guide never shows how to point uvx at a mirror.

Why it matters

The reader is an enterprise admin configuring a governed fleet. Copying the example as written leaves every session without Kiro Crew's tools, while kiro-cli mcp list still shows the servers as accepted, so nothing points at the cause.

Not a goal

What changed (motivation → approach → change)

Observed: the example fails without a mirror, and the guide gives no way to configure one. Approach: document the failure and the mirror setup through uv's own configuration, which does not depend on how kiro-cli parses the registry entry. Change, after the JSON example:

Backwards compatibility

Documentation only. No documented capability is removed.

Tests

N/A, documentation. ./scripts/docs-lint.sh passes locally with no finding on this file.

Manual verification

The launch form (uvx kirocrew@<version> <subcommand>) and the failure text are taken from the two reports on #23488. The uv.toml [[index]] form is uv's documented index configuration; an index listed without default = true is checked before PyPI, which stays the fallback.

Screenshots / video

N/A, documentation.

Related Issues

Fixes #23488 (together with #23494 for the server list).

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

This contribution is made under the project's Apache-2.0 license (see the Licensing section of CONTRIBUTING.md).

@cruisercohen
cruisercohen requested review from a team and KiroCrewCaptain as code owners November 2, 2026 21:39
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 2, 2026
@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision be79740cba6ba7a6a02fd17f6229b1b64a4a147a ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision be79740cba6ba7a6a02fd17f6229b1b64a4a147a touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of be79740cba6ba7a6a02fd17f6229b1b64a4a147a — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Docs-only change, and it fixes the stated problem: the copy-paste trap gets an explicit warning and a mirror setup that only uses uv's own config.

Notes

[DESIGN-REVIEWED] be79740

Description read

[DESCRIPTION-READ] 43ec905cc70c566536f28e6265f7a456955607352cdc36b98b621b49087a8247

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed be79740cba6ba7a6a02fd17f6229b1b64a4a147a — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] be79740

Verdict parsed from the review's SHA-scoped output markers for commit be79740cba6ba7a6a02fd17f6229b1b64a4a147a.

False positive or not applicable? A repository writer can comment:
/ai-review override fable be79740cba6ba7a6a02fd17f6229b1b64a4a147a false-positive: <reason, 20 to 500 characters>

The registry example cannot launch without a private index hosting the
kirocrew wheel. Say so before the reader copies it, show the failure they
will see, and show how to point uvx at the mirror through uv's own config.

Fixes #23488
@cruisercohen
cruisercohen force-pushed the fix/23488-mcp-registry-mirror branch from a43fe2a to be79740 Compare November 2, 2026 22:17
@cruisercohen

Copy link
Copy Markdown
Contributor Author

Opus 5.5 Review finding on a43fe2a (default = true drops PyPI, so the wheel's dependencies cannot resolve): fixed in be79740. The uv.toml snippet no longer sets default = true; the guide now says uv checks the listed index first and falls back to PyPI for packages it does not host, and that default = true is only for an index that proxies PyPI or hosts every dependency, because it removes the fallback for every uv/uvx call that reads the file. Design Review's matching note is answered by the same change.

@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of be79740cba6ba7a6a02fd17f6229b1b64a4a147a and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] be79740

False positive or not applicable? A repository writer can comment:
/ai-review override gpt be79740cba6ba7a6a02fd17f6229b1b64a4a147a false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 3, 2026
@bolichen97

Copy link
Copy Markdown
Contributor

Thanks for this PR. The CI run on this head never got runners, so its jobs were cancelled, and the branch is based on an older main. Could you update it onto the latest main (rebase or merge)? That starts a fresh CI run against current main, and we will review it once it is green.

@bolichen97

Copy link
Copy Markdown
Contributor

[operator: bolichen97] Continuing this in #33143; thanks for the start.

bolichen97 added a commit that referenced this pull request Nov 8, 2026
The enterprise MCP governance guide says its pypi registry example needs
an index hosting the kirocrew wheel, but never shows how to make uvx use
one, and a reader who copies the example sees accepted servers that
never start. Describe that failure after the example, show the uv index
configuration for the release CDN's per-channel index (picked by the
fleet's version, since each version is listed only on the channel that
released it; the CDN answers 403 for packages it does not host, so uv
needs ignore-error-codes to move on to PyPI) or an organisation's own
index, and say why default = true would drop PyPI for the wheel's
dependencies.

Builds on #28559.
bolichen97 added a commit that referenced this pull request Nov 8, 2026
The enterprise MCP governance guide says its pypi registry example needs
an index hosting the kirocrew wheel, but never shows how to make uvx use
one, and a reader who copies the example sees accepted servers that
never start. Describe that failure after the example, show the uv index
configuration for the release CDN's per-channel index (picked by the
fleet's version, since each version is listed only on the channel that
released it; the CDN answers 403 for packages it does not host, so uv
needs ignore-error-codes to move on to PyPI) or an organisation's own
index, and say why default = true would drop PyPI for the wheel's
dependencies.

Builds on #28559.
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 8, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Thanks for this docs fix. Closing because the same guidance has landed on main: #33143 (#33143, "docs: show how to point uvx at an index hosting kirocrew") merged and closed the linked issue #23488. If something from this branch is still missing on main, please reopen with the gap.

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(enterprise-mcp-governance): the documented kirocrew registry entry can't launch, because kirocrew isn't on PyPI

3 participants