No repair lever for a README that failed to resolve on first ingest
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 43/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Quiet
- Tech stack
- typescript
- Domain
- backend
Research direction
Read apps/registry/src/services/mcp-registry/ingest.ts and readme.ts, then trace how versions store README data and how fetchGithubReadme is called. The issue proposes a targeted repair for versions with no README and a GitHub repository, plus run report counters; done means these can be handled without downloading bundles or changing ingest watermark behavior.
Written by the indexing model from the issue text.
Description
A mirrored version's README is resolved exactly once, at first write, and never revisited.
versionIsCurrent (apps/registry/src/services/mcp-registry/ingest.ts:732-745) compares only artifact digests, so once a version is stored, every later run skips it before the wire. --full does not bypass this — there is no full field in IngestOptions; the flag only widens the since window. deleteMirror is reachable solely from the upstream-removal path (ingest.ts:382), so an operator has no lever either.
That is correct and deliberate for the download — it is what makes a nightly run cheap. It is wrong for the README, because the README resolution can fail transiently in a way the download cannot:
fetchOne(readme.ts) collapses 404, 429, 5xx, timeout, and DNS failure into the samenull. A throttled response is indistinguishable from a genuine absence.- The fallback issues up to 10 sequential unauthenticated requests per README-less server (5 filenames × 2 refs). Across a backfill of ~305 servers, roughly half of which ship no in-bundle README, that is exactly the shape that draws throttling.
So a full backfill can permanently blank a subset of package pages, and nothing in the system will ever notice or retry.
Not fixed inline, deliberately
Two in-PR remedies were considered and rejected in review:
- Gate
versionIsCurrentonreadme != null— re-downloads every README-less bundle nightly, forever, to retry a fetch that will usually keep returning nothing. Trades a rare permanent gap for a permanent recurring cost. - Add a
full/refreshMetadataoption threaded to the skip — net-new surface on the hot path for a repair used maybe twice a year.
Suggested shape
A separate, targeted repair that does not touch the ingest hot path: select versions where readme IS NULL and the package has a githubRepo, and run only fetchGithubReadme against them. No bundle download, no watermark interaction, no change to versionIsCurrent. Runnable on demand after a backfill, and cheap enough to schedule occasionally.
Worth pairing with a counter in the run report (readmesResolved / readmeFetchFailed) so a throttled backfill is visible at the time rather than discovered later as blank pages.
Context: #158 (which introduced README ingestion), #159, #160.
- Dominant language
- TypeScript
- Stars
- 14
- Forks
- 13
- Avg merge
- 16m
- Merged PRs (30d)
- 4
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from NimbleBrainInc/mpak
-
Difficulty 1/5 Under an hour Newbie friendliness 88/100
NimbleBrainInc/mpak#180 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
NimbleBrainInc/mpak#175 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 73/100
NimbleBrainInc/mpak#159 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
NimbleBrainInc/mpak#120 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 77/100
NimbleBrainInc/mpak#112 ·
All issues in NimbleBrainInc/mpak
Similar issues
-
bug documentation
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Potential Bug
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Comfy-Org/ComfyUI_frontend#23773 ·
Maintainers usually reply within 1 day
-
community first-timers-only good first issue hacktoberfest help wanted low hanging fruit up-for-grabs
Difficulty 1/5 Under an hour Newbie friendliness 85/100
lingdojo/kana-dojo#34301 · 1 comment · 5 reactions ·
Maintainers usually reply within 1 day
-
code-quality refactoring
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
github/gh-aw-firewall#11797 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
code-yeongyu/senpi#7007 ·
Maintainers usually reply within 1 day