Update documentation structure and content (#302)
## Summary - Restructure main README to focus on registry purpose and quick start guide - Streamline docs/README.md with better organization and linking - Update FAQ with current publishing methods, security approach, and community practices - Simplify roadmap to focus on go-live blockers rather than exhaustive backlog - Add ecosystem diagram to visualize registry architecture
This commit is contained in:
parent
60c75b6591
commit
d663406280
5 changed files with 177 additions and 292 deletions
320
README.md
320
README.md
|
|
@ -1,214 +1,86 @@
|
||||||
# MCP Registry
|
# MCP Registry
|
||||||
|
|
||||||
A community driven registry service for Model Context Protocol (MCP) servers.
|
> [!WARNING]
|
||||||
|
> The registry is under [active development](#development-status). The registry API spec is unstable and the official MCP registry database may be wiped at any time.
|
||||||
|
|
||||||
|
📖 **[API Documentation](https://staging.registry.modelcontextprotocol.io/docs)** | 📚 **[Technical Docs](./docs)**
|
||||||
|
|
||||||
|
## What is the registry?
|
||||||
|
|
||||||
|
The registry will provide MCP clients with a list of MCP servers. Like an app store for MCP servers. (In future it might do more, like also hosting a list of clients.)
|
||||||
|
|
||||||
|
There are two parts to the registry project:
|
||||||
|
1. 🟦 **The MCP registry spec**: An [API specification](./docs/server-registry-api/) that allows anyone to implement a registry.
|
||||||
|
2. 🟥 **The Official MCP registry**: A hosted registry following the MCP registry spec at [`registry.modelcontextprotocol.io`](https://registry.modelcontextprotocol.io). This serves as the **authoritative repository** for publicly-available MCP servers. Server creators publish once, and all consumers (MCP clients, aggregators, marketplaces) reference the same canonical data. This is owned by the MCP open-source community, backed by major trusted contributors to the MCP ecosystem such as Anthropic, GitHub, PulseMCP and Microsoft.
|
||||||
|
|
||||||
|
The registry is built around the [`server.json`](./docs/server-json/) format - a standardized way to describe MCP servers that works across discovery, initialization, and packaging scenarios.
|
||||||
|
|
||||||
|
In time, we expect the ecosystem to look a bit like this:
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
Note that MCP registries are _metaregistries_. They host metadata about packages, but not the package code or binaries. Instead, they reference other package registries (like NPM, PyPi or Docker) for this.
|
||||||
|
|
||||||
|
Additionally, we expect clients pull from _subregistries_. These subregistries add value to the registry ecosystem by providing curation, or extending it with additional metadata. The Official MCP registry expects a lot of API requests from ETL jobs from these subregistries.
|
||||||
|
|
||||||
## Development Status
|
## Development Status
|
||||||
|
|
||||||
This project is being built in the open and is currently in the early stages of development. Please see the [overview discussion](https://github.com/modelcontextprotocol/registry/discussions/11) for the project scope and goals.
|
**2025-08-26 update**: We're targeting a 'preview' go-live on 4th September. This may still be unstable and not provide durability guarantees, but is a step towards being more solidified. A general availability (GA) release will follow later.
|
||||||
|
|
||||||
### Contributing
|
Current key maintainers:
|
||||||
|
- **Adam Jones** (Anthropic) [@domdomegg](https://github.com/domdomegg)
|
||||||
|
- **Tadas Antanavicius** (PulseMCP) [@tadasant](https://github.com/tadasant)
|
||||||
|
- **Toby Padilla** (GitHub) [@toby](https://github.com/toby)
|
||||||
|
|
||||||
Use [Discussions](https://github.com/modelcontextprotocol/registry/discussions) to propose and discuss product and/or technical **requirements**.
|
## Contributing
|
||||||
|
|
||||||
Use [Issues](https://github.com/modelcontextprotocol/registry/issues) to track **well-scoped technical work** that the community agrees should be done at some point.
|
We use multiple channels for collaboration - see [modelcontextprotocol.io/community/communication](https://modelcontextprotocol.io/community/communication).
|
||||||
|
|
||||||
Open [Pull Requests](https://github.com/modelcontextprotocol/registry/pulls) when you want to **contribute work towards an Issue**, or you feel confident that your contribution is desireable and small enough to forego community discussion at the requirements and planning levels.
|
Often (but not always) ideas flow through this pipeline:
|
||||||
|
|
||||||
## Overview
|
- **[Discord](https://modelcontextprotocol.io/community/communication)** - Real-time community discussions
|
||||||
|
- **[Discussions](https://github.com/modelcontextprotocol/registry/discussions)** - Propose and discuss product/technical requirements
|
||||||
|
- **[Issues](https://github.com/modelcontextprotocol/registry/issues)** - Track well-scoped technical work
|
||||||
|
- **[Pull Requests](https://github.com/modelcontextprotocol/registry/pulls)** - Contribute work towards issues
|
||||||
|
|
||||||
The MCP Registry service provides a centralized repository for MCP server entries. It allows discovery and management of various MCP implementations with their associated metadata, configurations, and capabilities.
|
### Quick start:
|
||||||
|
|
||||||
## Features
|
#### Pre-requisites
|
||||||
|
|
||||||
- RESTful API for managing MCP registry entries (list, get, create, update, delete)
|
- **Docker**
|
||||||
- Health check endpoint for service monitoring
|
- **Go 1.24.x**
|
||||||
- Support for various environment configurations
|
- **golangci-lint v2.4.0**
|
||||||
- Graceful shutdown handling
|
|
||||||
- PostgreSQL and in-memory database support
|
|
||||||
- Comprehensive API documentation
|
|
||||||
- Pagination support for listing registry entries
|
|
||||||
- Seed data export/import composability with HTTP support
|
|
||||||
- Registry instance data sharing via HTTP endpoints
|
|
||||||
|
|
||||||
## Getting Started
|
#### Running the server
|
||||||
|
|
||||||
### Prerequisites
|
|
||||||
|
|
||||||
- Go 1.24.x (required - check with `go version`)
|
|
||||||
- PostgreSQL
|
|
||||||
- Docker (optional, but recommended for development)
|
|
||||||
|
|
||||||
For development:
|
|
||||||
- golangci-lint v2.4.0 - Install with:
|
|
||||||
```bash
|
|
||||||
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.4.0
|
|
||||||
```
|
|
||||||
|
|
||||||
## Running
|
|
||||||
|
|
||||||
The easiest way to get the registry running is uses docker compose. This will setup the MCP Registry service, import the seed data and run PostgreSQL in a local Docker environment.
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
# Start full development environment
|
||||||
make dev-compose
|
make dev-compose
|
||||||
```
|
```
|
||||||
|
|
||||||
This will start the MCP Registry service running at [`localhost:8080`](http://localhost:8080).
|
This starts the registry at [`localhost:8080`](http://localhost:8080) with PostgreSQL and seed data. It can be configured with environment variables in [docker-compose.yml](./docker-compose.yml) - see [.env.example](./.env.example) for a reference.
|
||||||
|
|
||||||
## Building
|
<details>
|
||||||
|
<summary>Alternative: Local setup without Docker</summary>
|
||||||
|
|
||||||
If you prefer to run the service locally without Docker, you can build and run it directly:
|
**Prerequisites:**
|
||||||
|
- PostgreSQL running locally
|
||||||
|
- Go 1.24.x installed
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Build a registry executable
|
# Build and run locally
|
||||||
make build
|
make build
|
||||||
```
|
|
||||||
This will create the `registry` binary in the current directory.
|
|
||||||
|
|
||||||
To run the service locally:
|
|
||||||
```bash
|
|
||||||
# Run registry locally
|
|
||||||
make dev-local
|
make dev-local
|
||||||
```
|
```
|
||||||
|
|
||||||
By default, the service will run on [`localhost:8080`](http://localhost:8080). You'll need to use the in-memory database or have PostgreSQL running.
|
The service runs on [`localhost:8080`](http://localhost:8080) by default. This can be configured with environment variables in `.env` - see [.env.example](./.env.example) for a reference.
|
||||||
|
|
||||||
To build the CLI tool for publishing MCP servers to the registry:
|
</details>
|
||||||
|
|
||||||
```bash
|
<details>
|
||||||
# Build the publisher tool
|
<summary>Alternative: Running a pre-built Docker image</summary>
|
||||||
make publisher
|
|
||||||
```
|
|
||||||
|
|
||||||
## Development
|
Pre-built Docker images are automatically published to GitHub Container Registry:
|
||||||
|
|
||||||
### Available Make Targets
|
|
||||||
|
|
||||||
To see all available make targets:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
make help
|
|
||||||
```
|
|
||||||
|
|
||||||
Key development commands:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Development
|
|
||||||
make dev-compose # Start development environment with Docker Compose
|
|
||||||
make dev-local # Run registry locally
|
|
||||||
|
|
||||||
# Build targets
|
|
||||||
make build # Build the registry application
|
|
||||||
make publisher # Build the publisher tool
|
|
||||||
make migrate # Build the database migration tool
|
|
||||||
|
|
||||||
# Testing
|
|
||||||
make test-unit # Run unit tests with coverage report
|
|
||||||
make test-integration # Run integration tests
|
|
||||||
make test-endpoints # Test API endpoints (requires running server)
|
|
||||||
make test-publish # Test publish endpoint (requires BEARER_TOKEN)
|
|
||||||
make test-all # Run all tests
|
|
||||||
|
|
||||||
# Code quality
|
|
||||||
make lint # Run linter (same as CI)
|
|
||||||
make lint-fix # Run linter with auto-fix
|
|
||||||
|
|
||||||
# Validation
|
|
||||||
make validate-schemas # Validate JSON schemas
|
|
||||||
make validate-examples # Validate examples against schemas
|
|
||||||
make validate # Run all validation checks
|
|
||||||
|
|
||||||
# Combined workflows
|
|
||||||
make check # Run all checks (lint, validate, unit tests)
|
|
||||||
|
|
||||||
# Utilities
|
|
||||||
make clean # Clean build artifacts and coverage files
|
|
||||||
```
|
|
||||||
|
|
||||||
### Linting
|
|
||||||
|
|
||||||
The project uses golangci-lint with extensive checks. Always run linting before pushing:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Run all linters (same as CI)
|
|
||||||
make lint
|
|
||||||
|
|
||||||
# Run linter with auto-fix
|
|
||||||
make lint-fix
|
|
||||||
```
|
|
||||||
|
|
||||||
### Git Hooks (Optional)
|
|
||||||
|
|
||||||
To automatically run linting before commits:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git config core.hooksPath .githooks
|
|
||||||
```
|
|
||||||
|
|
||||||
This will prevent commits that fail linting or have formatting issues.
|
|
||||||
|
|
||||||
### Project Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
├── api/ # OpenApi specification
|
|
||||||
├── cmd/ # Application entry points
|
|
||||||
├── config/ # Configuration files
|
|
||||||
├── internal/ # Private application code
|
|
||||||
│ ├── api/ # HTTP server and request handlers (routing)
|
|
||||||
│ ├── auth/ # GitHub OAuth integration
|
|
||||||
│ ├── config/ # Configuration management
|
|
||||||
│ ├── database/ # Data persistence abstraction
|
|
||||||
│ ├── model/ # Data models and domain structures
|
|
||||||
│ └── service/ # Business logic implementation
|
|
||||||
├── pkg/ # Public libraries
|
|
||||||
├── scripts/ # Utility scripts
|
|
||||||
└── tools/ # Command line tools
|
|
||||||
└── publisher/ # Tool to publish MCP servers to the registry
|
|
||||||
```
|
|
||||||
|
|
||||||
### Architecture Overview
|
|
||||||
|
|
||||||
### Request Flow
|
|
||||||
1. HTTP requests enter through router (`internal/api/router/`)
|
|
||||||
2. Handlers in `internal/api/handlers/v0/` validate and process requests
|
|
||||||
3. Service layer executes business logic
|
|
||||||
4. Database interface handles persistence
|
|
||||||
5. JSON responses returned to clients
|
|
||||||
|
|
||||||
### Key Interfaces
|
|
||||||
- **Database Interface** (`internal/database/database.go`) - Abstracts data persistence with PostgreSQL and in-memory implementations
|
|
||||||
- **RegistryService** (`internal/service/service.go`) - Business logic abstraction over database
|
|
||||||
- **Auth Service** (`internal/auth/jwt.go`) - Registry token creation and validation
|
|
||||||
|
|
||||||
### Authentication Flow
|
|
||||||
Publishing requires GitHub OAuth validation:
|
|
||||||
1. Extract bearer token from Authorization header
|
|
||||||
2. Validate token with GitHub API
|
|
||||||
3. Verify repository ownership matches token owner
|
|
||||||
4. Check organization membership if applicable
|
|
||||||
|
|
||||||
### Design Patterns
|
|
||||||
- **Factory Pattern** for service creation with dependency injection
|
|
||||||
- **Repository Pattern** for database abstraction
|
|
||||||
- **Context Pattern** for timeout management (5-second DB operations)
|
|
||||||
- **Cursor-based Pagination** using UUIDs for stateless pagination
|
|
||||||
|
|
||||||
## API Endpoints
|
|
||||||
|
|
||||||
### API Documentation
|
|
||||||
|
|
||||||
```
|
|
||||||
GET /docs
|
|
||||||
```
|
|
||||||
|
|
||||||
The API is documented using Swagger/OpenAPI. This page provides a complete reference of all endpoints with request/response schemas and examples, and allows you to test the API directly from your browser.
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
The service can be configured using environment variables. See [.env.example](./.env.example) for details.
|
|
||||||
|
|
||||||
## Pre-built Docker Images
|
|
||||||
|
|
||||||
Pre-built Docker images are automatically published to GitHub Container Registry on each release and main branch commit:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Run latest from main branch
|
# Run latest from main branch
|
||||||
|
|
@ -218,41 +90,75 @@ docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:latest
|
||||||
docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main-20250806-a1b2c3d
|
docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main-20250806-a1b2c3d
|
||||||
```
|
```
|
||||||
|
|
||||||
**Available image tags:**
|
**Available tags:** `latest`, `main-<date>-<sha>`
|
||||||
- `latest` - Latest commit from main branch
|
|
||||||
- `main-<date>-<sha>` - Specific commit builds
|
|
||||||
|
|
||||||
**Configuration:** The Docker images support all environment variables listed in the [Configuration](#configuration) section. For production deployments, you'll need to configure the database connection and other settings via environment variables.
|
</details>
|
||||||
|
|
||||||
### Import Seed Data
|
#### Publishing a server
|
||||||
|
|
||||||
Registry instances can import data from:
|
To publish a server, we've built a simple CLI. You can use it with:
|
||||||
|
|
||||||
**Local files:**
|
|
||||||
```bash
|
|
||||||
MCP_REGISTRY_SEED_FROM=data/seed.json ./registry
|
|
||||||
```
|
|
||||||
|
|
||||||
**HTTP endpoints:**
|
|
||||||
```bash
|
|
||||||
MCP_REGISTRY_SEED_FROM=http://other-registry:8080 ./registry
|
|
||||||
```
|
|
||||||
|
|
||||||
## Testing
|
|
||||||
|
|
||||||
Run the test script to validate API endpoints:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
./scripts/test_endpoints.sh
|
# Build the latest CLI
|
||||||
|
make publisher
|
||||||
|
|
||||||
|
# Use it!
|
||||||
|
./tools/publisher/bin/mcp-publisher --help
|
||||||
```
|
```
|
||||||
|
|
||||||
You can specify specific endpoints to test:
|
See [the publisher README](./tools/publisher/README.md) for more details.
|
||||||
|
|
||||||
|
#### Other commands
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
./scripts/test_endpoints.sh --endpoint health
|
# Run lint, unit tests and integration tests
|
||||||
./scripts/test_endpoints.sh --endpoint servers
|
make check
|
||||||
```
|
```
|
||||||
|
|
||||||
## License
|
There are also a few more helpful commands for development. Run `make help` to learn more, or look in [Makefile](./Makefile).
|
||||||
|
|
||||||
See the [LICENSE](LICENSE) file for details.
|
<!--
|
||||||
|
For Claude and other AI tools: Always prefer make targets over custom commands where possible.
|
||||||
|
-->
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
### Project Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
├── cmd/ # Application entry points
|
||||||
|
├── data/ # Seed data
|
||||||
|
├── deploy/ # Deployment configuration (Pulumi)
|
||||||
|
├── docs/ # Technical documentation
|
||||||
|
│ ├── server-json/ # server.json specification & examples
|
||||||
|
│ └── server-registry-api/ # API specification
|
||||||
|
├── internal/ # Private application code
|
||||||
|
│ ├── api/ # HTTP handlers and routing
|
||||||
|
│ ├── auth/ # Authentication (GitHub OAuth, JWT)
|
||||||
|
│ ├── config/ # Configuration management
|
||||||
|
│ ├── database/ # Data persistence (PostgreSQL, in-memory)
|
||||||
|
│ ├── model/ # Data models and domain structures
|
||||||
|
│ ├── service/ # Business logic
|
||||||
|
│ └── telemetry/ # Metrics and monitoring
|
||||||
|
├── scripts/ # Development and testing scripts
|
||||||
|
├── tests/ # Integration tests
|
||||||
|
└── tools/ # CLI tools
|
||||||
|
├── publisher/ # Server publishing tool
|
||||||
|
└── validate-*.sh # Schema validation tools
|
||||||
|
```
|
||||||
|
|
||||||
|
### Authentication
|
||||||
|
|
||||||
|
Publishing supports multiple authentication methods:
|
||||||
|
- **GitHub OAuth** - For publishing by logging into GitHub
|
||||||
|
- **GitHub OIDC** - For publishing from GitHub Actions
|
||||||
|
- **DNS verification** - For proving ownership of a domain and its subdomains
|
||||||
|
- **HTTP verification** - For proving ownership of a domain
|
||||||
|
|
||||||
|
The registry validates namespace ownership when publishing. E.g. to publish...:
|
||||||
|
- `io.github.domdomegg/my-cool-mcp` you must login to GitHub as `domdomegg`, or be in a GitHub Action on domdomegg's repos
|
||||||
|
- `me.adamjones/my-cool-mcp` you must prove ownership of `adamjones.me` via DNS or HTTP challenge
|
||||||
|
|
||||||
|
## More documentation
|
||||||
|
|
||||||
|
See the [docs](./docs) folder for more details if your question has not been answered here!
|
||||||
|
|
|
||||||
|
|
@ -1,23 +1,18 @@
|
||||||
# Official Registry Documentation
|
# Official Registry Documentation
|
||||||
|
|
||||||
|
This extends [the main README](../README.md).
|
||||||
|
|
||||||
## Project Documentation
|
## Project Documentation
|
||||||
|
|
||||||
[`design_principles.md`](./design_principles.md) - Core constraints and principles guiding the registry design
|
- [`faq.md`](./faq.md) - Frequently asked questions about the MCP Registry
|
||||||
|
- [`design_principles.md`](./design_principles.md) - Core constraints and principles guiding the registry design
|
||||||
[`faq.md`](./faq.md) - Frequently asked questions about the MCP Registry
|
- [`roadmap.md`](./roadmap.md) - High-level roadmap for the MCP Registry development
|
||||||
|
- [`MCP Developers Summit 2025 - Registry Talk Slides.pdf`](./MCP%20Developers%20Summit%202025%20-%20Registry%20Talk%20Slides.pdf) - Slides from a talk given at the MCP Developers Summit on May 23, 2025, with an up-to-date vision of how we are thinking about the official registry.
|
||||||
[`roadmap.md`](./roadmap.md) - High-level roadmap for the MCP Registry development
|
|
||||||
|
|
||||||
[`MCP Developers Summit 2025 - Registry Talk Slides.pdf`](./MCP%20Developers%20Summit%202025%20-%20Registry%20Talk%20Slides.pdf) - Slides from a talk given at the MCP Developers Summit on May 23, 2025, with an up-to-date vision of how we are thinking about the official registry.
|
|
||||||
|
|
||||||
## API & Technical Specifications
|
## API & Technical Specifications
|
||||||
|
|
||||||
[`openapi.yaml`](./openapi.yaml) - OpenAPI specification for the official registry API
|
- [`openapi.yaml`](./openapi.yaml) - OpenAPI specification for the official registry API
|
||||||
|
- [`api_examples.md`](./api_examples.md) - Examples of what data will actually look like coming from the official registry API
|
||||||
[`api_examples.md`](./api_examples.md) - Examples of what data will actually look like coming from the official registry API
|
- [`architecture.md`](./architecture.md) - Technical architecture, deployment strategies, and data flows
|
||||||
|
- [`server.json` README](./server-json/README.md) - description of the `server.json` purpose and schema
|
||||||
[`architecture.md`](./architecture.md) - Technical architecture, deployment strategies, and data flows
|
- [`new_package_registry.md`](./new_package_registry.md) - steps to add a new package registry for local server packages
|
||||||
|
|
||||||
[`server.json` README](./server-json/README.md) - description of the `server.json` purpose and schema
|
|
||||||
|
|
||||||
[`new_package_registry.md`](./new_package_registry.md) - steps to add a new package registry for local server packages
|
|
||||||
|
|
|
||||||
13
docs/ecosystem-diagram.excalidraw.svg
Normal file
13
docs/ecosystem-diagram.excalidraw.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 2.7 MiB |
116
docs/faq.md
116
docs/faq.md
|
|
@ -33,26 +33,21 @@ The registry is designed for programmatic consumption by:
|
||||||
- Server aggregators (Smithery, PulseMCP, etc.)
|
- Server aggregators (Smithery, PulseMCP, etc.)
|
||||||
- NOT individual end-users (they should use MCP clients or aggregator UIs)
|
- NOT individual end-users (they should use MCP clients or aggregator UIs)
|
||||||
|
|
||||||
### Will there be a UI for browsing servers?
|
### Will there be feature X?
|
||||||
|
|
||||||
A UI is planned as a future milestone after the initial API launch, but is not part of the MVP.
|
See [roadmap.md](./roadmap.md).
|
||||||
|
|
||||||
## Publishing Servers
|
## Publishing Servers
|
||||||
|
|
||||||
### How do I publish my MCP server?
|
### How do I publish my MCP server?
|
||||||
|
|
||||||
Servers are published by submitting a `server.json` file through our CLI tool. The process requires:
|
See the [publisher README](../tools/publisher/README.md)
|
||||||
|
|
||||||
1. GitHub authentication
|
|
||||||
2. A public GitHub repository (even for closed-source servers - just for the metadata)
|
|
||||||
3. Your server package published to a supported registry (npm, PyPI, NuGet, Docker Hub, etc.)
|
|
||||||
4. Optional: DNS verification for custom namespacing
|
|
||||||
|
|
||||||
### What namespaces are available?
|
### What namespaces are available?
|
||||||
|
|
||||||
- **With DNS verification**: `com.yourcompany/server-name` (reverse DNS notation)
|
- **With GitHub verification**: `io.github.yourusername/server-name`, `io.github.yourorg/server-name`
|
||||||
- **Without DNS verification**: `io.github.yourusername/server-name`
|
- **With DNS verification**: `com.yourcompany.*`, `com.yourcompany.*/*`
|
||||||
- DNS verification is done via TXT records and enables authoritative namespacing
|
- **With HTTP verification**: `com.yourcompany/*`
|
||||||
|
|
||||||
### Is open source required?
|
### Is open source required?
|
||||||
|
|
||||||
|
|
@ -90,9 +85,21 @@ The registry accepts any version string up to 255 characters, but we recommend:
|
||||||
|
|
||||||
The registry attempts to parse versions as semantic versions for proper ordering. Non-semantic versions are allowed but will be ordered by publication timestamp. See the [versioning guide](./versioning.md) for detailed guidance.
|
The registry attempts to parse versions as semantic versions for proper ordering. Non-semantic versions are allowed but will be ordered by publication timestamp. See the [versioning guide](./versioning.md) for detailed guidance.
|
||||||
|
|
||||||
|
### Can I add custom metadata when publishing?
|
||||||
|
|
||||||
|
Yes, extensions under the `x-publisher` property are preserved when publishing to the registry. This allows you to include custom metadata specific to your publishing process.
|
||||||
|
|
||||||
### Can I delete/unpublish my server?
|
### Can I delete/unpublish my server?
|
||||||
|
|
||||||
A reverse-publication flow is planned to allow quick deletion of accidentally published data.
|
At time of last update, this was open for discussion in [#104](https://github.com/modelcontextprotocol/registry/issues/104).
|
||||||
|
|
||||||
|
### Can I publish a private server?
|
||||||
|
|
||||||
|
Private servers are those that are only accessible to a narrow set of users. For example, servers published on a private network (like `mcp.acme-corp.internal`) or on private package registries (e.g. `npx -y @acme/mcp --registry https://artifactory.acme-corp.internal/npm`).
|
||||||
|
|
||||||
|
These are generally not supported on the official MCP registry, which is designed for publicly accessible MCP servers.
|
||||||
|
|
||||||
|
If you want to publish private servers we recommend you host your own MCP subregistry, and add them there.
|
||||||
|
|
||||||
## Security & Trust
|
## Security & Trust
|
||||||
|
|
||||||
|
|
@ -101,27 +108,22 @@ A reverse-publication flow is planned to allow quick deletion of accidentally pu
|
||||||
DNS verification ensures namespace ownership. For example:
|
DNS verification ensures namespace ownership. For example:
|
||||||
|
|
||||||
- `com.microsoft/server` requires DNS verification of microsoft.com
|
- `com.microsoft/server` requires DNS verification of microsoft.com
|
||||||
- `io.github.username/server` is tied to a GitHub account or GitHub organization
|
- `io.github.name/server` is tied to a GitHub account or GitHub organization `name`
|
||||||
|
|
||||||
### What about typosquatting?
|
|
||||||
|
|
||||||
The registry implements (or is slated to soon implement):
|
|
||||||
|
|
||||||
- Automatic blocking of names within a certain edit distance of existing servers
|
|
||||||
- Community reporting mechanisms
|
|
||||||
|
|
||||||
### Is there security scanning?
|
### Is there security scanning?
|
||||||
|
|
||||||
The MVP delegates security to the underlying package registries. Future iterations may include:
|
The MVP delegates security scanning to:
|
||||||
|
- underlying package registries; and
|
||||||
- Vulnerability scanning
|
- subregistries
|
||||||
- Dependency analysis
|
|
||||||
|
|
||||||
### How is spam prevented?
|
### How is spam prevented?
|
||||||
|
|
||||||
- GitHub authentication requirement
|
- Namespace authentication requirements
|
||||||
- Rate limiting (e.g., 10 new servers per user per day)
|
|
||||||
- Character limits and regex validation on free-form fields
|
- Character limits and regex validation on free-form fields
|
||||||
|
- Manual takedown of spam or malicious servers
|
||||||
|
|
||||||
|
In future we might explore:
|
||||||
|
- Stricter rate limiting (e.g., 10 new servers per user per day)
|
||||||
- Potential AI-based spam detection
|
- Potential AI-based spam detection
|
||||||
- Community reporting and admin blacklisting capabilities
|
- Community reporting and admin blacklisting capabilities
|
||||||
|
|
||||||
|
|
@ -135,64 +137,42 @@ Recommended polling frequency:
|
||||||
- `/servers/:id` endpoint: once per version (results are immutable)
|
- `/servers/:id` endpoint: once per version (results are immutable)
|
||||||
- Design assumes CDN caching between registry and consumers
|
- Design assumes CDN caching between registry and consumers
|
||||||
|
|
||||||
|
Also see [#291](https://github.com/modelcontextprotocol/registry/issues/291), which might mean the above can be more regular.
|
||||||
|
|
||||||
### Will there be webhooks?
|
### Will there be webhooks?
|
||||||
|
|
||||||
Not in the initial MVP, but the architecture supports adding webhooks for update notifications in the future.
|
Not in the initial MVP, but the architecture supports adding webhooks for update notifications in the future.
|
||||||
|
|
||||||
### Can I run my own registry instance?
|
### Can I run my own registry instance?
|
||||||
|
|
||||||
While the API shapes and data formats are designed for reuse, the registry implementation itself is not designed for self-hosting. Organizations needing private registries should:
|
Yes! The API shapes and data formats are intentionally designed for reuse by subregistries. Organizations needing private registries should:
|
||||||
|
|
||||||
- Implement the same API shape
|
- Implement the same API shape
|
||||||
- Use the same `server.json` format
|
- Use the same `server.json` format
|
||||||
- Potentially mirror/filter the official registry data
|
- Potentially mirror/filter the official registry data
|
||||||
|
|
||||||
|
### Can I extend the registry API?
|
||||||
|
|
||||||
|
Yes, we support `x-com.example` style extensions in a bunch of places - see the official MCP registry API spec. This can be used to add annotations to many objects, e.g. add security scanning details, enrich package metadata, etc.
|
||||||
|
|
||||||
|
If you have a use case that can't be addressed here, raise a GitHub issue!
|
||||||
|
|
||||||
|
### Can I use the code here to run my own registry instance?
|
||||||
|
|
||||||
|
The registry implementation here is not designed for self-hosting, but you're welcome to try to use it/fork it as necessary. Note that this is not an intended use, and the registry maintainers cannot provide any support for this at this time.
|
||||||
|
|
||||||
## Operations & Maintenance
|
## Operations & Maintenance
|
||||||
|
|
||||||
### What's the expected reliability?
|
### What's the expected reliability?
|
||||||
|
|
||||||
- 24-hour+ downtime tolerance is acceptable, so you shouldn't rely on the registry being always available.
|
- This is a community maintained project without full time staffing. You should therefore expect downtime periods of up to 1 business day. No strict guarantees are provided. (Also see discussion in [#150](https://github.com/modelcontextprotocol/registry/issues/150))
|
||||||
- No direct end-user impact (consumers cache data)
|
- Ideally clients should use subregistries with higher availability guarantees, to avoid direct end-user impact (as subregistries can cache data).
|
||||||
- Relies on CDN for actual availability
|
|
||||||
- Volunteer maintainer model (no formal on-call)
|
|
||||||
|
|
||||||
### How are DNS records verified?
|
### What if I need to report a spam or malicious server?
|
||||||
|
|
||||||
- Initial verification via TXT records
|
1. Report it as abuse to the underlying package registry (e.g. NPM, PyPi, DockerHub, etc.); and
|
||||||
- Daily re-verification to catch domain transfers
|
2. Raise a GitHub issue on the registry repo with a title beginning `Abuse report: `
|
||||||
- Publishing blocked if verification fails
|
|
||||||
- Historical packages remain available with warnings
|
|
||||||
|
|
||||||
### What about GitHub repository transfers?
|
### What if I need to report a security vulnerability in the registry itself?
|
||||||
|
|
||||||
The registry tracks GitHub repository IDs (not just URLs) to detect transfers. Daily checks update metadata if repositories move.
|
Follow [the MCP community SECURITY.md](https://github.com/modelcontextprotocol/.github/blob/main/SECURITY.md).
|
||||||
|
|
||||||
### How is namespace transfer handled?
|
|
||||||
|
|
||||||
Namespace transfers (e.g., when someone leaves a company) are handled through the DNS verification system and GitHub organization membership.
|
|
||||||
|
|
||||||
## Future Considerations
|
|
||||||
|
|
||||||
### Will download counts be tracked?
|
|
||||||
|
|
||||||
Download count tracking is being considered as a quality signal, but must be designed carefully to not impact CDN caching.
|
|
||||||
|
|
||||||
### What about tags or categories?
|
|
||||||
|
|
||||||
Categorization and curation are intentionally left to consumers (MCP clients and aggregators) to avoid maintenance burden and subjective decisions.
|
|
||||||
|
|
||||||
### Will there be quality metrics?
|
|
||||||
|
|
||||||
Quality assessment is explicitly out of scope for the official registry. This is delegated to:
|
|
||||||
|
|
||||||
- MCP clients (for their specific use cases)
|
|
||||||
- Third-party aggregators
|
|
||||||
- Community reviews on external platforms
|
|
||||||
|
|
||||||
### What about internationalization?
|
|
||||||
|
|
||||||
Internationalization is a future consideration but not part of the MVP.
|
|
||||||
|
|
||||||
### Will private registries be supported?
|
|
||||||
|
|
||||||
The registry design (API shapes, data formats) is intended to be reusable for private deployments, but the official registry will only host public servers.
|
|
||||||
|
|
|
||||||
|
|
@ -10,19 +10,14 @@ The initial version of the MCP Registry is actively being developed. The initial
|
||||||
|
|
||||||
## Phase 1: MVP/Go-Live (Current Focus)
|
## Phase 1: MVP/Go-Live (Current Focus)
|
||||||
|
|
||||||
- [ ] Specification: OpenAPI definition for the official REST API
|
See the [go-live blocker issues](https://github.com/modelcontextprotocol/registry/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22go-live%20blocker%22).
|
||||||
- [ ] Specification: Extensible OpenAPI definition for marketplace/aggregator consumers to repurpose
|
|
||||||
- [ ] REST API: Publish workflow
|
|
||||||
- [ ] REST API: Read workflow
|
|
||||||
- [ ] CLI: Publish tool
|
|
||||||
- [ ] CLI/REST API: DNS verification system for namespacing
|
|
||||||
|
|
||||||
## Backlog (Future Work)
|
## Backlog (Future Work, may be moved to out of scope)
|
||||||
|
|
||||||
- [ ] UI implementation
|
- [ ] UI implementation
|
||||||
- [ ] Store and surface other data besides servers (e.g. [clients](https://modelcontextprotocol.io/clients), resources)
|
- [ ] Store and surface other data besides servers (e.g. [clients](https://modelcontextprotocol.io/clients), resources)
|
||||||
- [ ] Additional IdP support (beyond GitHub)
|
|
||||||
- [ ] Download count tracking
|
- [ ] Download count tracking
|
||||||
|
- [ ] Internationalization (i18n)
|
||||||
|
|
||||||
## Out of Scope (Not Planned)
|
## Out of Scope (Not Planned)
|
||||||
|
|
||||||
|
|
@ -32,9 +27,5 @@ The initial version of the MCP Registry is actively being developed. The initial
|
||||||
- **Unified runtime**: Not solving how servers are executed
|
- **Unified runtime**: Not solving how servers are executed
|
||||||
- **Server hosting**: The registry does not provide hosting for servers
|
- **Server hosting**: The registry does not provide hosting for servers
|
||||||
- **Search engine**: The registry will not provide a commercial grade search engine for servers
|
- **Search engine**: The registry will not provide a commercial grade search engine for servers
|
||||||
- **Server tagging**: The registry will not support server tagging
|
- **Server tags or categories**: Not supported, to reduce moderation burden
|
||||||
- **Server rankings**: The registry will not rank servers by subjective measures of quality
|
- **Server rankings**: The registry will not rank servers by subjective measures of quality
|
||||||
|
|
||||||
## Contributing
|
|
||||||
|
|
||||||
See [CONTRIBUTING.md](../CONTRIBUTING.md) for details on how to contribute to the MCP Registry project.
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue