From 3e463e52bbd17167f1b5bff1ba49c3259bd7ed0f Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Mon, 10 Aug 2026 16:32:25 +0300 Subject: [PATCH] docs: correct contributor prerequisites and stale dev-env references (#1520) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .env.example | 5 +++++ .github/copilot-instructions.md | 2 +- CHANGES.md | 0 CONTRIBUTING.md | 3 ++- README.md | 11 +++++++---- docker-compose.yml | 1 - scripts/mirror_data/README.md | 20 ++++++++++---------- tests/integration/README.md | 6 +++--- 8 files changed, 28 insertions(+), 20 deletions(-) delete mode 100644 CHANGES.md diff --git a/.env.example b/.env.example index 786fc1b..6deabd0 100644 --- a/.env.example +++ b/.env.example @@ -11,6 +11,11 @@ MCP_REGISTRY_DATABASE_URL=postgres://username:password@localhost:5432/mcp-regist # For offline development, use: data/seed.json MCP_REGISTRY_SEED_FROM=https://registry.modelcontextprotocol.io/v0/servers +# Validate seed data against the registry rules on import (default: true) +# Set to false for offline development when seeding from a local file, since +# data/seed.json is not guaranteed to pass validation +MCP_REGISTRY_ENABLE_REGISTRY_VALIDATION=true + # GitHub OAuth configuration # These creds are for local development with the 'MCP Registry Login (Local)' GitHub App # They don't provide any real privileged access, hence why it's okay that they're here diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index b37dd38..e373661 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -9,5 +9,5 @@ To publish an MCP server to the registry, use the `mcp-publisher` CLI tool. See ## Development - Use `make` targets where possible (run `make help` to see available targets) -- Run `make check` to run lint, unit tests, and integration tests +- Run `make check` to run lint, schema validation, and all tests (this also stops any running dev-compose environment) - Run `make dev-compose` to start the local development environment \ No newline at end of file diff --git a/CHANGES.md b/CHANGES.md deleted file mode 100644 index e69de29..0000000 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a5a42cb..7a1e1b5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,7 +32,8 @@ See the [README](README.md#quick-start) for prerequisites and instructions on ru ### Running checks ```bash -# Run lint, unit tests and integration tests +# Run lint, schema validation, and all tests +# Note: this also runs `make dev-down`, stopping any running dev-compose environment make check ``` diff --git a/README.md b/README.md index 5424e0d..8178365 100644 --- a/README.md +++ b/README.md @@ -32,9 +32,9 @@ Often (but not always) ideas flow through this pipeline: #### Pre-requisites - **Docker** -- **Go 1.24.x** +- **Go** - version per the `go` directive in [go.mod](./go.mod); the Go toolchain fetches it for you - **ko** - Container image builder for Go ([installation instructions](https://ko.build/install/)) -- **golangci-lint v2.4.0** +- **golangci-lint** - version per the `golangci-lint-action` pin in [ci.yml](./.github/workflows/ci.yml), so local lint matches CI #### Running the server @@ -94,7 +94,8 @@ See [the publisher guide](./docs/modelcontextprotocol-io/quickstart.mdx) for mor #### Other commands ```bash -# Run lint, unit tests and integration tests +# Run lint, schema validation, and all tests +# Note: this also runs `make dev-down`, stopping any running dev-compose environment make check ``` @@ -110,7 +111,8 @@ For Claude and other AI tools: Always prefer make targets over custom commands w ``` ├── cmd/ # Application entry points -│ └── publisher/ # Server publishing tool +│ ├── publisher/ # Server publishing tool +│ └── registry/ # Registry API server ├── data/ # Seed data ├── deploy/ # Deployment configuration (Pulumi) ├── docs/ # Documentation @@ -119,6 +121,7 @@ For Claude and other AI tools: Always prefer make targets over custom commands w │ ├── auth/ # Authentication (GitHub OAuth, JWT, namespace blocking) │ ├── config/ # Configuration management │ ├── database/ # Data persistence (PostgreSQL) +│ ├── importer/ # Seed data import │ ├── service/ # Business logic │ ├── telemetry/ # Metrics and monitoring │ └── validators/ # Input validation diff --git a/docker-compose.yml b/docker-compose.yml index 7eb71c2..3fff7bc 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -10,7 +10,6 @@ services: # See .env.example for more documentation environment: - MCP_REGISTRY_DATABASE_URL=${MCP_REGISTRY_DATABASE_URL:-postgres://mcpregistry:mcpregistry@postgres:5432/mcp-registry} - - MCP_REGISTRY_ENVIRONMENT=${MCP_REGISTRY_ENVIRONMENT:-test} - MCP_REGISTRY_GITHUB_CLIENT_ID=${MCP_REGISTRY_GITHUB_CLIENT_ID:-Iv23licy3GSiM9Km5jtd} - MCP_REGISTRY_GITHUB_CLIENT_SECRET=${MCP_REGISTRY_GITHUB_CLIENT_SECRET:-0e8db54879b02c29adef51795586f3c510a9341d} - MCP_REGISTRY_JWT_PRIVATE_KEY=${MCP_REGISTRY_JWT_PRIVATE_KEY:-8103179d8ef955f6d3de6d6217224a909ec4060529dfeb1d4ca5a994537658cd} diff --git a/scripts/mirror_data/README.md b/scripts/mirror_data/README.md index 3237211..2cc3a87 100644 --- a/scripts/mirror_data/README.md +++ b/scripts/mirror_data/README.md @@ -14,7 +14,7 @@ These scripts help you: ## Prerequisites -- Go 1.24.x +- Go — see the [prerequisites in the root README](../../README.md#pre-requisites) for the required version - PostgreSQL (via Docker or local installation) - Required Go packages: ```bash @@ -31,7 +31,7 @@ go run scripts/mirror_data/fetch_production_data.go ``` This will: -- Fetch all servers from https://registry.modelcontextprotocol.io/v0.1/servers +- Fetch all servers from https://registry.modelcontextprotocol.io/v0/servers - Handle pagination automatically - Save data to `scripts/mirror_data/production_servers.json` - Be respectful to the API with rate limiting @@ -71,7 +71,7 @@ This will: 4. Analyze the data and report statistics 5. Show sample servers with NULL status values -To test a different migration, edit `maxMigration` in the script (line 24) +To test a different migration, edit `maxMigration` in `load_production_data.go` ### 4. Test Migrations @@ -80,8 +80,8 @@ After loading the data, you can test migrations against real production data. #### Testing a Single Migration ```bash -# Test migration 008 -cat internal/database/migrations/008_separate_official_metadata.sql | \ +# Test the separate_official_metadata migration +cat internal/database/migrations/009_separate_official_metadata.sql | \ docker exec -i test-postgres psql -U postgres -d registry_test ``` @@ -90,7 +90,7 @@ cat internal/database/migrations/008_separate_official_metadata.sql | \ 1. **Check the error output:** ```bash # Run migration and capture all output -cat internal/database/migrations/008_separate_official_metadata.sql | \ +cat internal/database/migrations/009_separate_official_metadata.sql | \ docker exec -i test-postgres psql -U postgres -d registry_test 2>&1 | \ grep -E "(ERROR|NOTICE|WARNING)" ``` @@ -126,7 +126,7 @@ EOF # Start a transaction to test and rollback docker exec test-postgres psql -U postgres -d registry_test <