a25f166b4bDeletes `complete.md` and cleans up the last references to the pre-restructuring docs layout. ## Why `complete.md` goes It 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: - **No generator exists.** No make target, no workflow, no script. `grep -rn "complete\.md"` finds **zero** references anywhere in the repo. - **It mirrors a docs tree that no longer exists** — `docs/guides/`, `docs/explanations/`, `docs/concepts/`. - **All 72 of its relative links are broken**, and six of the basenames it references exist nowhere in the repo. - **~14 current docs are missing from it entirely** (`about.mdx`, `authentication.mdx`, `package-types.mdx`, both CHANGELOGs, ...). - **Its `server.json` examples pin the superseded `2025-07-09` schema** (current is `2025-12-11`). The strongest argument is its own last commit. [PR #1278](https://github.com/modelcontextprotocol/registry/pull/1278) closed [issue #767](https://github.com/modelcontextprotocol/registry/issues/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-bundle` target plus a `check-docs-bundle` CI job mirroring the existing `check-schema` pattern — happy to do that instead if you would rather keep it. ## Remaining stale references | File | Was | Now | |---|---|---| | `contributing/add-package-registry.md` | Add `docs/guides/publishing/publish-[yourregistry].md`, update `docs/guides/publishing/README.md` | Add a section to `package-types.mdx`. These were the **last live references** to the obsolete `docs/guides/` layout outside `complete.md` | | `administration/maintainer-onboarding.md` | Add them to "Current key maintainers" in README | "Registry Working Group" — the section that actually exists | | `reference/README.md` | Omitted 6 reference docs | Adds `api/extensions.md`, `api/openapi.yaml`, `api/CHANGELOG.md`, `server-json/CHANGELOG.md`, `server-json/CONTRIBUTING.md`, `server-json/draft/` | | `docs/README.md` | Index omitted `community-projects.md` | Listed | | `reference/api/generic-registry-api.md` | `PUT .../versions/{version}` "not implemented by official registry" | It **is** implemented ([edit.go:36](https://github.com/modelcontextprotocol/registry/blob/main/internal/api/handlers/v0/edit.go#L36)), and `official-registry-api.md` already lists it as an admin endpoint | | `reference/api/official-registry-api.md` | Omitted 3 registered routes | Adds `POST /v0.1/validate` (which `mcp-publisher validate` calls), `GET /v0.1/ping`, `GET /v0.1/version`, and notes these plus `/health` are absent from `openapi.yaml` | | `server-json/official-registry-requirements.md` | Per-registry verification → `quickstart.mdx` | → `package-types.mdx`, which has an Ownership Verification section per registry | | `design/design-principles.md` | Sections 1,2,3,4,**6**,7 | Renumbered 1–6 | | `contributing/releasing.md` | Steps 1,2,3,**5**,6 | Renumbered 1–5 | I left the sibling `DELETE` claim in `generic-registry-api.md` alone — it is accurate, no DELETE route is registered (the `http.MethodDelete` hit in `server.go` is CORS config, not a route). ## Staleness banners rather than rewrites **`design/tech-architecture.md`** is substantially fictional. Rather than a vague "may be outdated", the banner lists what I verified is wrong: - Describes Helm-chart deployment; the registry is a plain `Deployment` ([registry.go:65](https://github.com/modelcontextprotocol/registry/blob/main/deploy/pkg/k8s/registry.go#L65)). Helm is used only for third-party components. - Diagram shows a `StatefulSet` on port **27017** — MongoDB's port. The DB is PostgreSQL on 5432 via the CloudNativePG operator. - Documents a `verify-domain` challenge flow (`POST /verify-domain`, `/verify-domain/check`, server-issued tokens) that **was never built**. - Documents `/admin/*` routes that are not registered. - Says the DB stores user auth state and DNS verification records; only `servers` and `server_extensions` tables exist. **`design/roadmap.md`** still 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`/`.mdx` in 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](https://claude.com/claude-code) Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
1.9 KiB
1.9 KiB
MCP Registry Design Principles
These are the core constraints that guide the design of the MCP Registry. They are not exhaustive, but they are the most important principles that we will use to evaluate design decisions.
1. Single Source of Truth
The registry serves as the authoritative metadata repository for publicly-available MCP servers, both locally-run and remote, open source and closed source. Server creators publish once, and all consumers (MCP clients, aggregators, etc.) reference the same canonical data.
2. Minimal Operational Burden
- Design for low maintenance and operational overhead
- Delegate complexity to existing services where possible (GitHub for auth, npm/PyPI/NuGet for packages)
- Avoid features that require constant human intervention or moderation
- Build for reasonable downtime tolerance (24h acceptable) by having consumers cache data for their end-users
3. Vendor Neutrality
- No preferential treatment for specific servers or organizations
- No built-in ranking, curation, or quality judgments
- Let consumers (MCP clients, aggregators) make their own curation decisions
4. Meets Industry Security Standards
- Leverage existing package registries (npm, PyPI, NuGet, Docker Hub, etc.) for source code distribution, obviating the need to reinvent source code security
- Use mechanisms like DNS verification, OAuth to provide base layer of authentication and trust
- Implement rate limiting, field validation, and blacklisting to prevent abuse
5. Reusable, Extensible Shapes; Not Infrastructure
- API shapes (OpenAPI, server.json) designed for reuse
- Enable private/internal registries using same formats
- Don't mandate infrastructure reuse - focus on interface compatibility
6. Progressive Enhancement
- Start with MVP that provides immediate value
- Build foundation that supports future features
- Don't over-engineer for hypothetical needs
- Each milestone should be independently valuable