Skip to content

Commit d663406

Browse files
domdomeggdomdomegg
authored
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
1 parent 60c75b6 commit d663406

File tree

5 files changed

+177
-292
lines changed

5 files changed

+177
-292
lines changed

‎README.md

Lines changed: 104 additions & 198 deletions
Original file line numberDiff line numberDiff line change
@@ -1,214 +1,86 @@
11
# MCP Registry
22

3-
A community driven registry service for Model Context Protocol (MCP) servers.
3+
> [!WARNING]
4+
> 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.
45
5-
## Development Status
6-
7-
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.
8-
9-
### Contributing
10-
11-
Use [Discussions](https://github.com/modelcontextprotocol/registry/discussions) to propose and discuss product and/or technical **requirements**.
12-
13-
Use [Issues](https://github.com/modelcontextprotocol/registry/issues) to track **well-scoped technical work** that the community agrees should be done at some point.
14-
15-
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.
16-
17-
## Overview
18-
19-
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.
6+
📖 **[API Documentation](https://staging.registry.modelcontextprotocol.io/docs)** | 📚 **[Technical Docs](./docs)**
207

21-
## Features
8+
## What is the registry?
229

23-
- RESTful API for managing MCP registry entries (list, get, create, update, delete)
24-
- Health check endpoint for service monitoring
25-
- Support for various environment configurations
26-
- Graceful shutdown handling
27-
- PostgreSQL and in-memory database support
28-
- Comprehensive API documentation
29-
- Pagination support for listing registry entries
30-
- Seed data export/import composability with HTTP support
31-
- Registry instance data sharing via HTTP endpoints
10+
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.)
3211

33-
## Getting Started
12+
There are two parts to the registry project:
13+
1. 🟦 **The MCP registry spec**: An [API specification](./docs/server-registry-api/) that allows anyone to implement a registry.
14+
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.
3415

35-
### Prerequisites
16+
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.
3617

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

41-
For development:
42-
- golangci-lint v2.4.0 - Install with:
43-
```bash
44-
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.4.0
45-
```
20+
![](./docs/ecosystem-diagram.excalidraw.svg)
4621

47-
## Running
22+
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.
4823

49-
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.
24+
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.
5025

51-
```bash
52-
make dev-compose
53-
```
54-
55-
This will start the MCP Registry service running at [`localhost:8080`](http://localhost:8080).
26+
## Development Status
5627

57-
## Building
28+
**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.
5829

59-
If you prefer to run the service locally without Docker, you can build and run it directly:
30+
Current key maintainers:
31+
- **Adam Jones** (Anthropic) [@domdomegg](https://github.com/domdomegg)
32+
- **Tadas Antanavicius** (PulseMCP) [@tadasant](https://github.com/tadasant)
33+
- **Toby Padilla** (GitHub) [@toby](https://github.com/toby)
6034

61-
```bash
62-
# Build a registry executable
63-
make build
64-
```
65-
This will create the `registry` binary in the current directory.
35+
## Contributing
6636

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

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

75-
To build the CLI tool for publishing MCP servers to the registry:
41+
- **[Discord](https://modelcontextprotocol.io/community/communication)** - Real-time community discussions
42+
- **[Discussions](https://github.com/modelcontextprotocol/registry/discussions)** - Propose and discuss product/technical requirements
43+
- **[Issues](https://github.com/modelcontextprotocol/registry/issues)** - Track well-scoped technical work
44+
- **[Pull Requests](https://github.com/modelcontextprotocol/registry/pulls)** - Contribute work towards issues
7645

77-
```bash
78-
# Build the publisher tool
79-
make publisher
80-
```
46+
### Quick start:
8147

82-
## Development
48+
#### Pre-requisites
8349

84-
### Available Make Targets
50+
- **Docker**
51+
- **Go 1.24.x**
52+
- **golangci-lint v2.4.0**
8553

86-
To see all available make targets:
54+
#### Running the server
8755

8856
```bash
89-
make help
57+
# Start full development environment
58+
make dev-compose
9059
```
9160

92-
Key development commands:
61+
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.
9362

94-
```bash
95-
# Development
96-
make dev-compose # Start development environment with Docker Compose
97-
make dev-local # Run registry locally
98-
99-
# Build targets
100-
make build # Build the registry application
101-
make publisher # Build the publisher tool
102-
make migrate # Build the database migration tool
103-
104-
# Testing
105-
make test-unit # Run unit tests with coverage report
106-
make test-integration # Run integration tests
107-
make test-endpoints # Test API endpoints (requires running server)
108-
make test-publish # Test publish endpoint (requires BEARER_TOKEN)
109-
make test-all # Run all tests
110-
111-
# Code quality
112-
make lint # Run linter (same as CI)
113-
make lint-fix # Run linter with auto-fix
114-
115-
# Validation
116-
make validate-schemas # Validate JSON schemas
117-
make validate-examples # Validate examples against schemas
118-
make validate # Run all validation checks
119-
120-
# Combined workflows
121-
make check # Run all checks (lint, validate, unit tests)
122-
123-
# Utilities
124-
make clean # Clean build artifacts and coverage files
125-
```
63+
<details>
64+
<summary>Alternative: Local setup without Docker</summary>
12665

127-
### Linting
128-
129-
The project uses golangci-lint with extensive checks. Always run linting before pushing:
66+
**Prerequisites:**
67+
- PostgreSQL running locally
68+
- Go 1.24.x installed
13069

13170
```bash
132-
# Run all linters (same as CI)
133-
make lint
134-
135-
# Run linter with auto-fix
136-
make lint-fix
137-
```
138-
139-
### Git Hooks (Optional)
140-
141-
To automatically run linting before commits:
142-
143-
```bash
144-
git config core.hooksPath .githooks
145-
```
146-
147-
This will prevent commits that fail linting or have formatting issues.
148-
149-
### Project Structure
150-
151-
```
152-
├── api/ # OpenApi specification
153-
├── cmd/ # Application entry points
154-
├── config/ # Configuration files
155-
├── internal/ # Private application code
156-
│ ├── api/ # HTTP server and request handlers (routing)
157-
│ ├── auth/ # GitHub OAuth integration
158-
│ ├── config/ # Configuration management
159-
│ ├── database/ # Data persistence abstraction
160-
│ ├── model/ # Data models and domain structures
161-
│ └── service/ # Business logic implementation
162-
├── pkg/ # Public libraries
163-
├── scripts/ # Utility scripts
164-
└── tools/ # Command line tools
165-
└── publisher/ # Tool to publish MCP servers to the registry
166-
```
167-
168-
### Architecture Overview
169-
170-
### Request Flow
171-
1. HTTP requests enter through router (`internal/api/router/`)
172-
2. Handlers in `internal/api/handlers/v0/` validate and process requests
173-
3. Service layer executes business logic
174-
4. Database interface handles persistence
175-
5. JSON responses returned to clients
176-
177-
### Key Interfaces
178-
- **Database Interface** (`internal/database/database.go`) - Abstracts data persistence with PostgreSQL and in-memory implementations
179-
- **RegistryService** (`internal/service/service.go`) - Business logic abstraction over database
180-
- **Auth Service** (`internal/auth/jwt.go`) - Registry token creation and validation
181-
182-
### Authentication Flow
183-
Publishing requires GitHub OAuth validation:
184-
1. Extract bearer token from Authorization header
185-
2. Validate token with GitHub API
186-
3. Verify repository ownership matches token owner
187-
4. Check organization membership if applicable
188-
189-
### Design Patterns
190-
- **Factory Pattern** for service creation with dependency injection
191-
- **Repository Pattern** for database abstraction
192-
- **Context Pattern** for timeout management (5-second DB operations)
193-
- **Cursor-based Pagination** using UUIDs for stateless pagination
194-
195-
## API Endpoints
196-
197-
### API Documentation
198-
199-
```
200-
GET /docs
71+
# Build and run locally
72+
make build
73+
make dev-local
20174
```
20275

203-
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.
204-
205-
## Configuration
76+
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.
20677

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

209-
## Pre-built Docker Images
80+
<details>
81+
<summary>Alternative: Running a pre-built Docker image</summary>
21082

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

21385
```bash
21486
# Run latest from main branch
@@ -218,41 +90,75 @@ docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:latest
21890
docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main-20250806-a1b2c3d
21991
```
22092

221-
**Available image tags:**
222-
- `latest` - Latest commit from main branch
223-
- `main-<date>-<sha>` - Specific commit builds
93+
**Available tags:** `latest`, `main-<date>-<sha>`
22494

225-
**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.
95+
</details>
22696

227-
### Import Seed Data
97+
#### Publishing a server
22898

229-
Registry instances can import data from:
99+
To publish a server, we've built a simple CLI. You can use it with:
230100

231-
**Local files:**
232101
```bash
233-
MCP_REGISTRY_SEED_FROM=data/seed.json ./registry
234-
```
102+
# Build the latest CLI
103+
make publisher
235104

236-
**HTTP endpoints:**
237-
```bash
238-
MCP_REGISTRY_SEED_FROM=http://other-registry:8080 ./registry
105+
# Use it!
106+
./tools/publisher/bin/mcp-publisher --help
239107
```
240108

241-
## Testing
109+
See [the publisher README](./tools/publisher/README.md) for more details.
242110

243-
Run the test script to validate API endpoints:
111+
#### Other commands
244112

245113
```bash
246-
./scripts/test_endpoints.sh
114+
# Run lint, unit tests and integration tests
115+
make check
247116
```
248117

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

251-
```bash
252-
./scripts/test_endpoints.sh --endpoint health
253-
./scripts/test_endpoints.sh --endpoint servers
254-
```
120+
<!--
121+
For Claude and other AI tools: Always prefer make targets over custom commands where possible.
122+
-->
255123

256-
## License
124+
## Architecture
257125

258-
See the [LICENSE](LICENSE) file for details.
126+
### Project Structure
127+
128+
```
129+
├── cmd/ # Application entry points
130+
├── data/ # Seed data
131+
├── deploy/ # Deployment configuration (Pulumi)
132+
├── docs/ # Technical documentation
133+
│ ├── server-json/ # server.json specification & examples
134+
│ └── server-registry-api/ # API specification
135+
├── internal/ # Private application code
136+
│ ├── api/ # HTTP handlers and routing
137+
│ ├── auth/ # Authentication (GitHub OAuth, JWT)
138+
│ ├── config/ # Configuration management
139+
│ ├── database/ # Data persistence (PostgreSQL, in-memory)
140+
│ ├── model/ # Data models and domain structures
141+
│ ├── service/ # Business logic
142+
│ └── telemetry/ # Metrics and monitoring
143+
├── scripts/ # Development and testing scripts
144+
├── tests/ # Integration tests
145+
└── tools/ # CLI tools
146+
├── publisher/ # Server publishing tool
147+
└── validate-*.sh # Schema validation tools
148+
```
149+
150+
### Authentication
151+
152+
Publishing supports multiple authentication methods:
153+
- **GitHub OAuth** - For publishing by logging into GitHub
154+
- **GitHub OIDC** - For publishing from GitHub Actions
155+
- **DNS verification** - For proving ownership of a domain and its subdomains
156+
- **HTTP verification** - For proving ownership of a domain
157+
158+
The registry validates namespace ownership when publishing. E.g. to publish...:
159+
- `io.github.domdomegg/my-cool-mcp` you must login to GitHub as `domdomegg`, or be in a GitHub Action on domdomegg's repos
160+
- `me.adamjones/my-cool-mcp` you must prove ownership of `adamjones.me` via DNS or HTTP challenge
161+
162+
## More documentation
163+
164+
See the [docs](./docs) folder for more details if your question has not been answered here!

‎docs/README.md

Lines changed: 11 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,18 @@
11
# Official Registry Documentation
22

3-
## Project Documentation
4-
5-
[`design_principles.md`](./design_principles.md) - Core constraints and principles guiding the registry design
3+
This extends [the main README](../README.md).
64

7-
[`faq.md`](./faq.md) - Frequently asked questions about the MCP Registry
8-
9-
[`roadmap.md`](./roadmap.md) - High-level roadmap for the MCP Registry development
5+
## Project Documentation
106

11-
[`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.
7+
- [`faq.md`](./faq.md) - Frequently asked questions about the MCP Registry
8+
- [`design_principles.md`](./design_principles.md) - Core constraints and principles guiding the registry design
9+
- [`roadmap.md`](./roadmap.md) - High-level roadmap for the MCP Registry development
10+
- [`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.
1211

1312
## API & Technical Specifications
1413

15-
[`openapi.yaml`](./openapi.yaml) - OpenAPI specification for the official registry API
16-
17-
[`api_examples.md`](./api_examples.md) - Examples of what data will actually look like coming from the official registry API
18-
19-
[`architecture.md`](./architecture.md) - Technical architecture, deployment strategies, and data flows
20-
21-
[`server.json` README](./server-json/README.md) - description of the `server.json` purpose and schema
22-
23-
[`new_package_registry.md`](./new_package_registry.md) - steps to add a new package registry for local server packages
14+
- [`openapi.yaml`](./openapi.yaml) - OpenAPI specification for the official registry API
15+
- [`api_examples.md`](./api_examples.md) - Examples of what data will actually look like coming from the official registry API
16+
- [`architecture.md`](./architecture.md) - Technical architecture, deployment strategies, and data flows
17+
- [`server.json` README](./server-json/README.md) - description of the `server.json` purpose and schema
18+
- [`new_package_registry.md`](./new_package_registry.md) - steps to add a new package registry for local server packages

‎docs/ecosystem-diagram.excalidraw.svg

Lines changed: 13 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)