Skip to content

Update documentation structure and content #302

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
domdomegg merged 2 commits into from
Aug 26, 2025
Merged

Update documentation structure and content #302

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
99ba340
Update documentation structure and content
domdomegg Aug 26, 2025
dec6013
Add FAQ entry for custom metadata in publishing process
domdomegg Aug 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
302 changes: 104 additions & 198 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,214 +1,86 @@
# 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.

## 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.

### Contributing

Use [Discussions](https://github.com/modelcontextprotocol/registry/discussions) to propose and discuss product and/or technical **requirements**.

Use [Issues](https://github.com/modelcontextprotocol/registry/issues) to track **well-scoped technical work** that the community agrees should be done at some point.

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.

## Overview

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.
📖 **[API Documentation](https://staging.registry.modelcontextprotocol.io/docs)** | 📚 **[Technical Docs](./docs)**

## Features
## What is the registry?

- RESTful API for managing MCP registry entries (list, get, create, update, delete)
- Health check endpoint for service monitoring
- Support for various environment configurations
- 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
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.)

## Getting Started
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.

### Prerequisites
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.

- Go 1.24.x (required - check with `go version`)
- PostgreSQL
- Docker (optional, but recommended for development)
In time, we expect the ecosystem to look a bit like this:

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
```
![](./docs/ecosystem-diagram.excalidraw.svg)

## Running
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.

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.
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.

```bash
make dev-compose
```

This will start the MCP Registry service running at [`localhost:8080`](http://localhost:8080).
## Development Status

## Building
**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.

If you prefer to run the service locally without Docker, you can build and run it directly:
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)

```bash
# Build a registry executable
make build
```
This will create the `registry` binary in the current directory.
## Contributing

To run the service locally:
```bash
# Run registry locally
make dev-local
```
We use multiple channels for collaboration - see [modelcontextprotocol.io/community/communication](https://modelcontextprotocol.io/community/communication).

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.
Often (but not always) ideas flow through this pipeline:

To build the CLI tool for publishing MCP servers to the registry:
- **[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

```bash
# Build the publisher tool
make publisher
```
### Quick start:

## Development
#### Pre-requisites

### Available Make Targets
- **Docker**
- **Go 1.24.x**
- **golangci-lint v2.4.0**

To see all available make targets:
#### Running the server

```bash
make help
# Start full development environment
make dev-compose
```

Key development commands:
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.

```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
```
<details>
<summary>Alternative: Local setup without Docker</summary>

### Linting

The project uses golangci-lint with extensive checks. Always run linting before pushing:
**Prerequisites:**
- PostgreSQL running locally
- Go 1.24.x installed

```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
# Build and run locally
make build
make dev-local
```

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 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.

The service can be configured using environment variables. See [.env.example](./.env.example) for details.
</details>

## Pre-built Docker Images
<details>
<summary>Alternative: Running a pre-built Docker image</summary>

Pre-built Docker images are automatically published to GitHub Container Registry on each release and main branch commit:
Pre-built Docker images are automatically published to GitHub Container Registry:

```bash
# Run latest from main branch
Expand All @@ -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
```

**Available image tags:**
- `latest` - Latest commit from main branch
- `main-<date>-<sha>` - Specific commit builds
**Available tags:** `latest`, `main-<date>-<sha>`

**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
```
# Build the latest CLI
make publisher

**HTTP endpoints:**
```bash
MCP_REGISTRY_SEED_FROM=http://other-registry:8080 ./registry
# Use it!
./tools/publisher/bin/mcp-publisher --help
```

## Testing
See [the publisher README](./tools/publisher/README.md) for more details.

Run the test script to validate API endpoints:
#### Other commands

```bash
./scripts/test_endpoints.sh
# Run lint, unit tests and integration tests
make check
```

You can specify specific endpoints to test:
There are also a few more helpful commands for development. Run `make help` to learn more, or look in [Makefile](./Makefile).

```bash
./scripts/test_endpoints.sh --endpoint health
./scripts/test_endpoints.sh --endpoint servers
```
<!--
For Claude and other AI tools: Always prefer make targets over custom commands where possible.
-->

## License
## Architecture

See the [LICENSE](LICENSE) file for details.
### 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!
27 changes: 11 additions & 16 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,18 @@
# Official Registry Documentation

## Project Documentation

[`design_principles.md`](./design_principles.md) - Core constraints and principles guiding the registry design
This extends [the main README](../README.md).

[`faq.md`](./faq.md) - Frequently asked questions about the MCP Registry

[`roadmap.md`](./roadmap.md) - High-level roadmap for the MCP Registry development
## Project Documentation

[`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.
- [`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
- [`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

[`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

[`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

[`new_package_registry.md`](./new_package_registry.md) - steps to add a new package registry for local server packages
- [`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
- [`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
- [`new_package_registry.md`](./new_package_registry.md) - steps to add a new package registry for local server packages
13 changes: 13 additions & 0 deletions docs/ecosystem-diagram.excalidraw.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading