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>
Update all documentation to reference the stable `/v0.1/` API version
instead of the development `/v0/` version.
Didn't update internal references (e.g. in admin-only docs) as that
probably make sense to keep pointed at v0 as the "dev" option.
Authored by Claude Code, reviewed by me.
---------
Co-authored-by: Claude <noreply@anthropic.com>
Change Format constant from `file_path` to `filepath` to match the
OpenAPI schema definition.
This is not used by any servers yet, nor is it enforced by the database,
so it's safe to change.
## Summary
- Fixes migration 008 failing with "column contains null values" error
- Adds COALESCE protection to handle 126 servers without status fields
- Includes test utilities to reproduce and verify fixes with production
data
## Problem
Migration 008 was failing in production because:
- 126 out of 781 servers have no `status` field in their JSON
- When extracting `rec.value->>'status'`, these became NULL values
- The `ALTER TABLE servers ALTER COLUMN status SET NOT NULL` constraint
then failed
## Solution
1. **Prevent NULLs during migration**: Use COALESCE to provide 'active'
default when status is NULL/empty
2. **Enhanced debugging**: Added RAISE NOTICE statements to log
problematic values
3. **Safety check**: Double-check that throws exception if any NULLs
remain
4. **Test utilities**: Created mirror_data tools to test migrations with
real production data
## Testing
Created and used `scripts/mirror_data/` tools to:
- Fetch all 781 servers from production API
- Load them into a test database
- Verify the migration fix works correctly
### Results:
- **Before fix**: 126 NULL status values created during migration
- **After fix**: 0 NULL status values, all servers have valid status
- Migration completes successfully with NOT NULL constraint
## Test plan
- [x] Tested locally with production data using mirror_data tools
- [x] Verified 0 NULL values after migration (vs 126 before)
- [x] Confirmed NOT NULL constraint adds successfully
- [ ] Deploy to staging and verify migration succeeds
- [ ] Monitor production deployment
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
Wielded Claude Code to do this; across many iterations and have reviewed
all the code + largely rewritten the PR commentary here.
This PR implements the server ID consistency changes from
[#396](https://github.com/modelcontextprotocol/registry/issues/396). Our
goal is to:
- Rename `id` to `versionId` to make it clear that it is the ID for a
specific version, not a server
- Introduce `serverId` as a net new concept. This will be 1:1 with
`name`. While not strictly necessary (we could just use name as a PK),
the convention of having a UUID as an ID on our objects is just a
helpful subjective architecture decision. Plus also leaves open the door
to reconsidering the "should we allow renames" question.
## Key Changes
### 🗄️ Database Schema Changes
- **Renamed**: `id` column → `version_id` (unique identifier for each
server version)
### 📋 Metadata Structure Updates
- **JSON Schema**: Updated
`_meta.io.modelcontextprotocol.registry/official` to include:
- `serverId`: Consistent ID across all versions of a server
- `versionId`: Unique ID for this specific version (renamed from `id`)
### 🔧 API Endpoint Updates
- **New endpoint structure**: Changed from version-ID-based to
server-ID-based URLs:
- `GET /v0/servers/{server_id}` - Get latest version of server
- `GET /v0/servers/{server_id}?version=X.X.X` - Get specific version
- `GET /v0/servers/{server_id}/versions` - List all versions of a server
- `PUT /v0/servers/{server_id}?version=X.X.X` - Edit specific version
- **Consistent URL patterns**: All server endpoints now use `server_id`
as the primary identifier
### Database Migration Strategy
The migration (`005_add_server_id_rename_version_id.sql`):
1. Adds new `version_id` column
2. Generates deterministic UUIDs for servers with the same name
3. Updates JSON metadata to add `serverId` and rename `id` to
`versionId`
4. Copies existing `id` values to `version_id` column
5. Drops old `id` column and makes `version_id` the new primary key
## Testing
Besides of course automated tests passing, I:
1. Set up my local db with the pre-005-migration state, imported all the
production data
2. Ran the migration
3. Spot checked some diffs of the data that resulted --
```json
// before
{
"name": "io.github.ruvnet/ruv-swarm",
"_meta": {
"io.modelcontextprotocol.registry/official": {
"id": "0a9cda7f-2b73-4839-844b-6582f335de42",
"is_latest": false,
"updated_at": "2025-09-10T17:21:34.92137012Z",
"published_at": "2025-09-10T17:15:32.69690433Z"
}
},
"version": "1.0.18",
"repository": {
"url": "",
"source": ""
},
"description": "Neural network swarm orchestration with WebAssembly acceleration and MCP integration"
}
// after
{
"name": "io.github.ruvnet/ruv-swarm",
"_meta": {
"io.modelcontextprotocol.registry/official": {
"serverId": "e8538952-96af-4a33-9e31-7fbed012521e",
"is_latest": false,
"versionId": "0a9cda7f-2b73-4839-844b-6582f335de42",
"updated_at": "2025-09-10T17:21:34.92137012Z",
"published_at": "2025-09-10T17:15:32.69690433Z"
}
},
"version": "1.0.18",
"repository": {
"url": "",
"source": ""
},
"description": "Neural network swarm orchestration with WebAssembly acceleration and MCP integration"
}
```
Servers that have multiple versions stayed consistent in their
`serverId`:
```json
// First version
{
"name": "app.getdialer/dialer",
"_meta": {
"io.modelcontextprotocol.registry/official": {
"serverId": "80f08bdb-f3e4-4f19-b072-1676ae49b663",
"is_latest": false,
"versionId": "04f25b17-331d-48d7-b08b-37baece208a7",
"updated_at": "2025-09-09T00:16:49.162620072Z",
"published_at": "2025-09-08T23:47:09.452137971Z"
}
},
"status": "active",
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
"remotes": [
{
"url": "https://getdialer.app/mcp",
"type": "streamable-http"
},
{
"url": "https://getdialer.app/sse",
"type": "sse"
}
],
"version": "1.0.0",
"repository": {
"url": "",
"source": ""
},
"description": "An MCP server that provides your you make outbound phone calls using your own phone number"
}
// Second version
{
"name": "app.getdialer/dialer",
"_meta": {
"io.modelcontextprotocol.registry/official": {
"serverId": "80f08bdb-f3e4-4f19-b072-1676ae49b663",
"is_latest": true,
"versionId": "faa26cb9-3aad-415e-aece-f715fff5fe5e",
"updated_at": "2025-09-09T00:16:49.107842808Z",
"published_at": "2025-09-09T00:16:49.107842808Z"
}
},
"status": "active",
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
"remotes": [
{
"url": "https://getdialer.app/mcp",
"type": "streamable-http"
},
{
"url": "https://getdialer.app/sse",
"type": "sse"
}
],
"version": "1.0.1",
"repository": {
"url": "",
"source": ""
},
"description": "An MCP server that provides lets you make outbound phone calls using your own phone number"
}
```
And I also tried publishing a test server anew; looked good:
```bash
⏺ Bash(curl -s "http://localhost:8080/v0/servers/102dc4e4-6ca8-40e6-aa11-cd45763d3352" | jq '.')
⎿ {
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
"name": "io.modelcontextprotocol.anonymous/test-claude-migration-server",
"description": "A test server to verify the new migration and API endpoints work correctly",
"status": "active",
"repository": {
"url": "https://github.com/example/test-claude-migration-server",
"source": "github",
"id": "example/test-claude-migration-server"
},
"version": "1.0.0",
"_meta": {
"io.modelcontextprotocol.registry/official": {
"serverId": "102dc4e4-6ca8-40e6-aa11-cd45763d3352",
"versionId": "48c9cd55-7bc4-4ac2-896e-59e81eb653e4",
"published_at": "2025-09-12T18:33:23.264203-07:00",
"updated_at": "2025-09-12T18:33:23.264203-07:00",
"is_latest": true
}
}
}
⏺ Bash(curl -s "http://localhost:8080/v0/servers/102dc4e4-6ca8-40e6-aa11-cd45763d3352/versions" | jq '.')
⎿ {
"servers": [
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
"name": "io.modelcontextprotocol.anonymous/test-claude-migration-server",
"description": "A test server to verify the new migration and API endpoints work correctly",
"status": "active",
"repository": {
"url": "https://github.com/example/test-claude-migration-server",
"source": "github",
"id": "example/test-claude-migration-server"
},
"version": "1.0.0",
"_meta": {
"io.modelcontextprotocol.registry/official": {
"serverId": "102dc4e4-6ca8-40e6-aa11-cd45763d3352",
"versionId": "48c9cd55-7bc4-4ac2-896e-59e81eb653e4",
"published_at": "2025-09-12T18:33:23.264203-07:00",
"updated_at": "2025-09-12T18:33:23.264203-07:00",
"is_latest": true
}
}
}
],
"metadata": {
"count": 1
}
}
```
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Preeti Dewani <preetidewani1990@gmail.com>
Co-authored-by: adam jones <adamj+git@anthropic.com>
Co-authored-by: Adam Jones <adamj@anthropic.com>
## Summary
Simplified the schema structure by:
- Replacing `version_detail.version` with direct `version` field
- Removing unused `release_date` field from seed data
- Updating all API types, models, and tests to match new structure
- Maintaining backwards compatibility in API responses
This change makes the schema more intuitive and reduces nesting depth.
## Motivation and Context
- Add MCPB as a new registry_name option
- Add file_hashes field to package model for integrity verification
- Implement URL validation restricting MCPB packages to GitHub/GitLab
hosts
- Require SHA-256 hash for all MCPB packages
- Add example MCPB package in documentation
- Update schemas and OpenAPI specification
See issue #260
## How Has This Been Tested?
<!-- Have you tested this in a real application? Which scenarios were
tested? -->
## Breaking Changes
N/A, registry has not yet been launched
## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->
- [x] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [ ] My code follows the repository's style guidelines
- [ ] New and existing tests pass locally
- [ ] I have added appropriate error handling
- [x] I have added or updated documentation as needed
---------
Co-authored-by: Adam Jones <adamj+git@anthropic.com>
<!-- Provide a brief summary of your changes -->
Hi Folks, thanks for the great work on MCP Registry!
While running it locally, I noticed a bug with the `make dev-local`
command.
```
$ make dev-local
go run ./cmd/registry/main.go
# command-line-arguments
cmd/registry/main.go:29:36: undefined: Version
cmd/registry/main.go:30:34: undefined: GitCommit
```
## Motivation and Context
<!-- Why is this change needed? What problem does it solve? -->
Command for running MCP Registry locally is broken.
## How Has This Been Tested?
<!-- Have you tested this in a real application? Which scenarios were
tested? -->
## Breaking Changes
<!-- Will users need to update their code or configurations? -->
## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->
- [x] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [x] My code follows the repository's style guidelines
- [x] New and existing tests pass locally
- [x] I have added appropriate error handling
- [x] I have added or updated documentation as needed
## Additional context
<!-- Add any other context, implementation notes, or design decisions
-->
cc @domdomegg @sridharavinash @tadasant
Signed-off-by: Andrey Velichkevich <andrey.velichkevich@gmail.com>
Co-authored-by: adam jones <adamj+git@anthropic.com>
I originally introduced `package_canonical` into the API schema because,
at the time, we were thinking to "pin" the version of the MCP server to
_one_ of the referenced source code packages.
We are no longer doing this (we are maintaining a separate notion of
`version` unique to the MCP server), so I don't believe
`package_canonical` is needed anymore. Does anyone see otherwise?
This change removes all mentions in READMEs and usages in code.
Work in progress .
This commit adds the core registry service implementation with methods to:
- Retrieve all registry entries
- List entries with cursor-based pagination
- Fetch specific server details by ID
