docs: remove stale complete.md and fix remaining stale references - #1522
Merged
Conversation
Deletes complete.md and cleans up the last references to the pre-restructuring docs layout. complete.md was a 2,944-line file self-described as "all documentation from the docs/ directory compiled into a single markdown file". It had no generator: no make target, no workflow, no script, and nothing in the repo referenced it. It mirrored a docs tree that no longer exists (docs/guides/, docs/explanations/, docs/concepts/), all 72 of its relative links were broken, ~14 current docs were missing from it entirely, and its server.json examples pinned the superseded 2025-07-09 schema. The clearest argument for deleting it is its own last commit: PR #1278 closed issue #767 -- a real user-reported CLI flag bug -- by editing only complete.md. A genuine fix landed in a file nobody reads, while the docs a reader would actually find stayed wrong. A generated file with no generator degrades into a trap: authoritative enough to edit, with nothing validating it. Remaining fixes, each verified against the code or filesystem: - docs/contributing/add-package-registry.md told contributors to add `docs/guides/publishing/publish-[yourregistry].md` and update `docs/guides/publishing/README.md`. Neither exists; per-package-type docs live in modelcontextprotocol-io/package-types.mdx. These were the last live references to the obsolete docs/guides/ layout outside complete.md. - maintainer-onboarding.md pointed at a "Current key maintainers" README section that does not exist; it is "Registry Working Group". - docs/reference/README.md omitted six reference documents: api/extensions.md, api/openapi.yaml, api/CHANGELOG.md, server-json/CHANGELOG.md, server-json/CONTRIBUTING.md and server-json/draft/. - docs/README.md's index omitted community-projects.md. - generic-registry-api.md described `PUT /v0.1/servers/{serverName}/versions/{version}` as "not implemented by official registry". It is implemented (internal/api/handlers/v0/edit.go:36) and official-registry-api.md already lists it as an admin endpoint. The sibling DELETE claim is correct and is left as is -- no DELETE route is registered. - official-registry-api.md omitted three registered routes: POST /v0.1/validate (which `mcp-publisher validate` calls), GET /v0.1/ping and GET /v0.1/version. Also notes that these and /health are absent from openapi.yaml, which covers the server and publish endpoints only. - official-registry-requirements.md sent readers wanting per-registry verification requirements to quickstart.mdx; that content is in package-types.mdx, which has an Ownership Verification section per registry. - Numbering: design-principles.md skipped 5 (1,2,3,4,6,7) and releasing.md skipped 4 (1,2,3,5,6). - tech-architecture.md gets a warning banner listing its specific verified inaccuracies: it describes Helm-chart deployment (the registry is a plain Deployment; Helm is only used for third-party components), a StatefulSet on port 27017 (MongoDB's port; the DB is PostgreSQL on 5432 via CloudNativePG), a verify-domain challenge flow that was never built, and /admin/* routes that are not registered. - roadmap.md gets a dated note that "Phase 1: MVP/Go-Live (Current Focus)" is stale, since launch was 2025-09-08 and the v0.1 freeze 2025-10-24. The phase content is left for the working group to re-plan rather than guessed at. Verified: all 101 remaining relative links across every .md/.mdx in the repo resolve. The only two non-resolving matches are the intentional `[project-name](link)` template placeholder in community-projects.md and the moderation link fixed separately in #1518. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
rdimitrov
added a commit
that referenced
this pull request
Aug 10, 2026
…1520) The README prerequisites were both stale, and the docs restated the Go version in three places. ## Prerequisites: name the source, do not restate the version | README said | Reality | |---|---| | `Go 1.24.x` | `go 1.26` in [go.mod](https://github.com/modelcontextprotocol/registry/blob/main/go.mod) | | `golangci-lint v2.4.0` | `v2.11.4` pinned in [ci.yml:30](https://github.com/modelcontextprotocol/registry/blob/main/.github/workflows/ci.yml#L30) | Rather than swap in fresher numbers — which only resets the clock on the same drift — this **removes the numbers** and names the authoritative file: ``` - **Go** - version per the `go` directive in go.mod; the Go toolchain fetches it for you - **golangci-lint** - version per the `golangci-lint-action` pin in ci.yml, so local lint matches CI ``` The Go version was stated in **three** places, which is exactly why all three drifted together. All three now point at a single source, so the prerequisites list cannot go stale. Two notes on why the numbers earn so little in prose: - **Go corrects itself.** `go.mod` has no `toolchain` directive, so under the default `GOTOOLCHAIN=auto` the toolchain downloads the required version automatically. A contributor on an older Go gets an upgrade, not a failure — it only hard-errors under `GOTOOLCHAIN=local`. (An earlier version of this description said such a contributor "cannot build"; that was too strong.) - **golangci-lint does not.** Version skew here genuinely changes what you see: running CI's config under a newer golangci-lint (2.12.2) surfaces 23 `goconst` findings in `cmd/publisher/commands/validate_test.go` that CI's pinned 2.11.4 does not report. That is why the README now points at the pin rather than a number someone has to keep in sync. ## `make check` does more than documented Documented in three files as "lint, unit tests and integration tests". Actually [`check: dev-down lint validate test-all`](https://github.com/modelcontextprotocol/registry/blob/main/Makefile#L85) — it also runs schema validation and **stops your running `dev-compose` environment**. Worth knowing before running it mid-session. The Makefile's own `##` help string already said this correctly; only the prose was stale. ## Other verified corrections - **README project structure** omitted `cmd/registry/` — the server entry point and ko/goreleaser build target — and `internal/importer/`. - **`tests/integration/README.md`** said the suite launches **MongoDB**. It launches PostgreSQL (`postgres-integration-test`), as the same file admits nine lines later. It also cited `/v0/servers/{server_id}`, a path removed a while ago; the test actually calls `GET /v0/servers` and `GET /v0/servers/{serverName}/versions/latest` ([main.go:210,255](https://github.com/modelcontextprotocol/registry/blob/main/tests/integration/main.go#L210)). - **`scripts/mirror_data/README.md`** pointed at `internal/database/migrations/008_separate_official_metadata.sql`, which does not exist — that migration is `009_`, while `008_` is `clean_invalid_data.sql`. (Migration 008's own header still calls itself "007a", which is how the numbering slipped.) Also swapped two "edit line NN" pointers for identifier names, since both had already drifted (`maxMigration` is at :30 not :24; the connection string at :23 not :17), and corrected the fetch URL from `/v0.1/servers` to the `/v0/servers` the script actually requests. - **`.env.example`** was missing `MCP_REGISTRY_ENABLE_REGISTRY_VALIDATION`, even though the config reads it ([config.go:18](https://github.com/modelcontextprotocol/registry/blob/main/internal/config/config.go#L18)) and README:50 tells contributors to set it while pointing at `.env.example` as *the* reference. - **`docker-compose.yml`** set `MCP_REGISTRY_ENVIRONMENT`, which nothing reads — no `ENVIRONMENT` env tag in `internal/config`, and no other occurrence in the repo. Removed. (The Pulumi-side `mcp-registry:environment` key is a separate, real thing and is untouched.) - **Deleted `CHANGES.md`** — 0 bytes, untouched since the squashed history base, zero references anywhere. ## Verification `docker compose config` validates. `grep` for `Go 1.x` / `golangci-lint vX` across all `.md`/`.mdx` now returns nothing outside `complete.md` (which #1522 deletes). Both `../../README.md#pre-requisites` links resolve and the anchor matches the real `#### Pre-requisites` heading. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
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.
Deletes
complete.mdand cleans up the last references to the pre-restructuring docs layout.Why
complete.mdgoesIt is 2,944 lines (31% of all documentation lines in the repo) self-described as "all documentation from the docs/ directory compiled into a single markdown file". But:
grep -rn "complete\.md"finds zero references anywhere in the repo.docs/guides/,docs/explanations/,docs/concepts/.about.mdx,authentication.mdx,package-types.mdx, both CHANGELOGs, ...).server.jsonexamples pin the superseded2025-07-09schema (current is2025-12-11).The strongest argument is its own last commit. PR #1278 closed issue #767 — a real user-reported CLI flag bug — by editing only
complete.md. A genuine fix landed in a file nobody reads, while the docs a reader would actually find stayed wrong.A generated file with no generator degrades into a trap: authoritative enough that people edit it, with nothing validating it. If the LLM-consumption use case is worth keeping, the right shape is a
make docs-bundletarget plus acheck-docs-bundleCI job mirroring the existingcheck-schemapattern — happy to do that instead if you would rather keep it.Remaining stale references
contributing/add-package-registry.mddocs/guides/publishing/publish-[yourregistry].md, updatedocs/guides/publishing/README.mdpackage-types.mdx. These were the last live references to the obsoletedocs/guides/layout outsidecomplete.mdadministration/maintainer-onboarding.mdreference/README.mdapi/extensions.md,api/openapi.yaml,api/CHANGELOG.md,server-json/CHANGELOG.md,server-json/CONTRIBUTING.md,server-json/draft/docs/README.mdcommunity-projects.mdreference/api/generic-registry-api.mdPUT .../versions/{version}"not implemented by official registry"official-registry-api.mdalready lists it as an admin endpointreference/api/official-registry-api.mdPOST /v0.1/validate(whichmcp-publisher validatecalls),GET /v0.1/ping,GET /v0.1/version, and notes these plus/healthare absent fromopenapi.yamlserver-json/official-registry-requirements.mdquickstart.mdxpackage-types.mdx, which has an Ownership Verification section per registrydesign/design-principles.mdcontributing/releasing.mdI left the sibling
DELETEclaim ingeneric-registry-api.mdalone — it is accurate, no DELETE route is registered (thehttp.MethodDeletehit inserver.gois CORS config, not a route).Staleness banners rather than rewrites
design/tech-architecture.mdis substantially fictional. Rather than a vague "may be outdated", the banner lists what I verified is wrong:Deployment(registry.go:65). Helm is used only for third-party components.StatefulSeton port 27017 — MongoDB's port. The DB is PostgreSQL on 5432 via the CloudNativePG operator.verify-domainchallenge flow (POST /verify-domain,/verify-domain/check, server-issued tokens) that was never built./admin/*routes that are not registered.serversandserver_extensionstables exist.design/roadmap.mdstill says "Phase 1: MVP/Go-Live (Current Focus)" ~11 months after launch. I added a dated note rather than inventing a current phase — that is a working-group call.Verification
All 101 remaining relative links across every
.md/.mdxin the repo resolve. The only two non-resolving matches are the intentional[project-name](link)template placeholder and the moderation link fixed in #1518.🤖 Generated with Claude Code