Closes#149
As noted in the FAQ update here, this is a helpful starting point in
thinking about this:
```
### What is the difference between "Official MCP Registry", "MCP Registry", "MCP registry", "MCP Registry API", etc?
There are four underlying concepts:
- "MCP Server Registry API" (or "MCP Registry API"): The OpenAPI specification defined in [openapi.yaml](./server-registry-api/openapi.yaml). This is a reusable API specification that anyone building any sort of "MCP server registry" should consider adopting / aligning with.
- "Official MCP Registry" (or "MCP Registry"): The application that lives at `https://registry.modelcontextprotocol.io`. This registry currently only catalogs MCP servers, but may be extended in the future to also catalog MCP client/host apps and frameworks.
- "Official MCP Registry API": The REST API that lives at `https://registry.modelcontextprotocol.io/api`, with an OpenAPI specification defined at [official-registry-openapi.yaml](./server-registry-api/official-registry-openapi.yaml)
- "MCP server registry" (or "MCP registry"): A third party, likely commercial, implementation of the MCP Server Registry API or derivative specification.
```
Prior to this PR, we were just treating "MCP Server Registry API" and
"Official MCP Registry API" to be the same thing. They are not the same:
the latter is inherently a more constrained version of the former. A
private deployment of a similar registry need not have constraints like
"the only valid source code repositories are `github` and `gitlab`".
This PR separates out the definitions to match that path forward.
## Notable Changes
### Base OpenAPI spec (`openapi.yaml`)
- Removed official-registry-specific constraints:
- No maximum limit on `/servers` endpoint
- No enum constraint on `Repository.source`
- No enum constraint on `Package.registry_name`
- Removed `/v0` prefix from paths (it's now just baked into the
`official` one's URL prefix)
- Added `$id` for proper schema identification
### Official Registry OpenAPI spec (`official-registry-openapi.yaml`)
- Created as a derivative of the base spec using `$ref`
- Re-adds official-registry-specific constraints:
- `Repository.source` enum: `[github]`
- `Package.registry_name` enum: `[npm, docker, pypi, nuget]`
### Documentation updates
- Added `server-registry-api/README.md` explaining the relationship
between specs
- Updated FAQ to clarify terminology
- Reorganized docs structure
## Summary
- Adds CLAUDE.md file to provide guidance for Claude Code instances
working with this repository
- Includes essential development commands and high-level architecture
overview
- Follows the standard format for Claude Code documentation
## Details
The CLAUDE.md file contains:
- Common development commands for building, running, testing, and
linting
- Architecture overview explaining the clean architecture pattern
- Request flow documentation
- Key interfaces and their implementations
- Authentication flow details
- Important design patterns used in the codebase
This will help future Claude Code instances be more productive when
working with the MCP Registry codebase.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Avinash Sridhar <sridharavinash@users.noreply.github.com>
Closes#155
The "generalized" `server.json` is the one that can be used in a variety
of situations:
- Discoverability on a centralized registry (i.e. our official Registry
work)
- Discoverability on a decentralized .well-known endpoint
- As a response to an initialization call, so the client knows
information about the MCP server to which it is connecting
- As an input into crafting a [DXT
file](https://www.anthropic.com/engineering/desktop-extensions)
- Packaged in with the source code of an MCP server, so as to have a
structured way context
Of these, the official Registry is but one use case. The Registry has a
unique set of concerns for which we are optimizing, like whitelisting of
specific registries we trust to host MCP server source code for the
public community (`npm`, `pypi`, etc). It is not necessary to have such
a constraint for the generalized server.json, which may be used in, for
example, an internal context where such a validation doesn't make sense.
So I've done the following at a high level:
- Renamed the prior `schema.json` to be `registry-schema.json`
- Introduced a more generic `schema.json` to serve as the schema for the
generalized `server.json`
- Refactored `registry-schema.json` to be simply a constraint on the
base `schema.json`
I made a few small changes in this transition:
- Removed `gitlab` as an option in `repository.source` for
`registry-schema.json`. I'm fine going live with just GitHub support;
would be happy to take a contribution from e.g. Gitlab employees or a
motivated Gitlab customer to expand anytime.
- Removed `homebrew` as an option in `packages.registry_name`; never
really made sense, not a place where folks are publishing MCP servers
- Added `docker` to `packages.runtime_hint`; was just a missing
oversight
- Gave both schemas a global `$id`
~- Removed `release_date` from both schemas. Certainly not something
that makes sense for the generalized schema. It actually doesn't make
sense for the Registry schema either, because this is the server.json
that _users will submit_, i.e. the _input_ into the Registry publication
API. `release_date` will be a piece of _output_ metadata. The Registry
API will be free to append such extra metadata for GET /:id requests of
servers, and the data can be present in the OpenAPI spec, but it does
not need to be in the registry-server.json JSON schema.~
- Note this is no longer in this PR; rebased on #168 which included it
- Removed unnecessary enums from the generalized `schema.json`
<!-- Provide a brief summary of your changes -->
## Motivation and Context
This is in support of
https://github.com/modelcontextprotocol/registry/issues/159, to make it
easier, I hope. My team noticed some differences in the JSON schema,
most notably the "choices" property was missing. I tried to write a tool
to do this but slowed down since I am not experienced with Go. This is a
first pass, maybe someone else can finish the tooling.
I restructured the JSON schema to break out child objects like the YAML
file, and brought the descriptions and example into sync. The only
differences are two extra properties in the YAML which are computed by
the server:
- `VersionDetail.is_latest` is not present in the JSON schema, computed
by the registry based on
https://github.com/modelcontextprotocol/registry/issues/158
- `Server.id` is not present in the JSON schema, generated by the
registry
The idea is the a tool could look at ServerDetail in the YAML and then
generate the schema.json with minimal fix-ups (add a root title, remove
`VersionDetail.is_latest` and `Server.id`.
~Question for @tadasant - should `VersionDetail.release_date` be in the
JSON schema? I think _no_ (and let it be computed) but it's there right
now.~ - aligned with
https://github.com/modelcontextprotocol/registry/pull/167 and removed
## How Has This Been Tested?
I have tested the JSON schema against the sample server.json in the repo
(files and markdown blocks).
## Breaking Changes
None.
## 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)
- [x] 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
- [ ] New and existing tests pass locally
- [ ] 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
-->
<!-- Provide a brief summary of your changes -->
Add more information about the value field under Input in the API doc.
## Motivation and Context
<!-- Why is this change needed? What problem does it solve? -->
the descrioption for
[value](81e5174a59/docs/openapi.yaml (L219))
is not clearly.
## How Has This Been Tested?
<!-- Have you tested this in a real application? Which scenarios were
tested? -->
No need.
## Breaking Changes
<!-- Will users need to update their code or configurations? -->
No
## 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)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ x ] 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
-->
<!-- Provide a brief summary of your changes -->
Add support for specifying database type (MongoDB or in-memory
database).
## Motivation and Context
<!-- Why is this change needed? What problem does it solve? -->
The README states that MCP Registry supports both MongoDB and in-memory
databases, but does not provide the capability to specify which database
type to use.
5d9171bdcc/README.md (L19)
This PR addresses this limitation by adding explicit database type
configuration through the `DATABASE_TYPE` environment variable, allowing
users to choose between `mongodb` and `memory` database types in a
standardized way.
## How Has This Been Tested?
<!-- Have you tested this in a real application? Which scenarios were
tested? -->
Yes
```console
$ export MCP_REGISTRY_DATABASE_TYPE="memory"
$ ./scripts/test_endpoints.sh
Testing health endpoint: http://localhost:8080/v0/health
Status Code: 200
Response:
{
"status": "ok",
"github_client_id": ""
}
Health check successful
-------------------------------------
Testing servers endpoint: http://localhost:8080/v0/servers
Status Code: 200
Response Summary:
Total registries: 0
servers Names:
Pagination Metadata:
{}
servers Details:
{
"servers": [],
"metadata": {}
}
servers request successful
-------------------------------------
Testing ping endpoint: http://localhost:8080/v0/ping
Status Code: 200
Response:
{
"status": "ok",
"version": "dev"
}
Ping successful
-------------------------------------
All tests passed successfully!
```
## Breaking Changes
<!-- Will users need to update their code or configurations? -->
No
## 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)
- [x] 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
-->
Close#63
---------
Co-authored-by: Avinash Sridhar <sridharavinash@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
<!-- Provide a brief summary of your changes -->
Rename mcp.json to server.json
## Motivation and Context
<!-- Why is this change needed? What problem does it solve? -->
## 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: -->
- [ ] 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. -->
- [ ] 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
- [ ] I have added or updated documentation as needed
## Additional context
<!-- Add any other context, implementation notes, or design decisions
-->
Related to #86
Co-authored-by: Avinash Sridhar <sridharavinash@users.noreply.github.com>
This pull request introduces significant updates to the authentication
system for the MCP Registry Publisher Tool. The changes focus on
transitioning to an interface-based authentication system, implementing
GitHub OAuth device flow as the default authentication method, and
restructuring the codebase for better modularity and extensibility.
Adding an interface to the publishing CLI, so that it'll be easier to
add more auth methods as they become available.
- Added error handling for JSON encoding in ServersHandler and ServersDetailHandler.
- Updated test cases to reflect changes in handler functions and improved mock expectations.
- Refactored server initialization to include ReadHeaderTimeout for better request handling.
- Modified GitHubDeviceAuth to accept context in ValidateToken and checkOrgMembership methods.
- Improved error messages in database import functions for better debugging.
- Updated memory and mongo database list functions to accept context and improved filtering logic.
- Enhanced logging in publisher tool for better visibility during execution.
- Cleaned up code formatting and comments for better readability and maintainability.
- Give the correct URL address in the mcp.json and the main README
## Motivation and Context
Improve documentation
## How Has This Been Tested?
No Testing.
## Breaking Changes
N/A
## Types of changes
- [ ] 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)
- [x] Documentation update
## Checklist
- [ ] 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
- [ ] I have added or updated documentation as needed
