5a584b86f4<!-- Provide a brief summary of your changes --> ## Motivation and Context <!-- Why is this change needed? What problem does it solve? --> The following adds a doc to reference community projects. ## 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) - [x] 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 --> Signed-off-by: Radoslav Dimitrov <radoslav@stacklok.com>
145 lines
6.1 KiB
Markdown
145 lines
6.1 KiB
Markdown
# MCP Registry
|
|
|
|
The MCP registry provides MCP clients with a list of MCP servers, like an app store for MCP servers.
|
|
|
|
[**📤 Publish my MCP server**](docs/guides/publishing/publish-server.md) | [**⚡️ Live API docs**](https://registry.modelcontextprotocol.io/docs) | [**👀 Ecosystem vision**](docs/explanations/ecosystem-vision.md) | 📖 **[Full documentation](./docs)**
|
|
|
|
## Development Status
|
|
|
|
**2025-09-08 update**: The registry has launched in preview 🎉 ([announcement blog post](https://blog.modelcontextprotocol.io/posts/2025-09-08-mcp-registry-preview/)). While the system is now more stable, this is still a preview release and breaking changes or data resets may occur. A general availability (GA) release will follow later. We'd love your feedback in [GitHub discussions](https://github.com/modelcontextprotocol/registry/discussions/new?category=ideas) or in the [#registry-dev Discord](https://discord.com/channels/1358869848138059966/1369487942862504016) ([joining details here](https://modelcontextprotocol.io/community/communication)).
|
|
|
|
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)
|
|
|
|
## Contributing
|
|
|
|
We use multiple channels for collaboration - see [modelcontextprotocol.io/community/communication](https://modelcontextprotocol.io/community/communication).
|
|
|
|
Often (but not always) ideas flow through this pipeline:
|
|
|
|
- **[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
|
|
|
|
### Quick start:
|
|
|
|
#### Pre-requisites
|
|
|
|
- **Docker**
|
|
- **Go 1.24.x**
|
|
- **golangci-lint v2.4.0**
|
|
|
|
#### Running the server
|
|
|
|
```bash
|
|
# Start full development environment
|
|
make dev-compose
|
|
```
|
|
|
|
This starts the registry at [`localhost:8080`](http://localhost:8080) with PostgreSQL and seed data. The database uses ephemeral storage and is reset each time you restart the containers, ensuring a clean state for development and testing.
|
|
|
|
The setup can be configured with environment variables in [docker-compose.yml](./docker-compose.yml) - see [.env.example](./.env.example) for a reference.
|
|
|
|
<details>
|
|
<summary>Alternative: Running a pre-built Docker image</summary>
|
|
|
|
Pre-built Docker images are automatically published to GitHub Container Registry:
|
|
|
|
```bash
|
|
# Run latest stable release
|
|
docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:latest
|
|
|
|
# Run latest from main branch (continuous deployment)
|
|
docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main
|
|
|
|
# Run specific release version
|
|
docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:v1.0.0
|
|
|
|
# Run development build from main branch
|
|
docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main-20250906-abc123d
|
|
```
|
|
|
|
**Available tags:**
|
|
- **Releases**: `latest`, `v1.0.0`, `v1.1.0`, etc.
|
|
- **Continuous**: `main` (latest main branch build)
|
|
- **Development**: `main-<date>-<sha>` (specific commit builds)
|
|
|
|
</details>
|
|
|
|
#### Publishing a server
|
|
|
|
To publish a server, we've built a simple CLI. You can use it with:
|
|
|
|
```bash
|
|
# Build the latest CLI
|
|
make publisher
|
|
|
|
# Use it!
|
|
./bin/mcp-publisher --help
|
|
```
|
|
|
|
See [the publisher guide](./docs/guides/publishing/publish-server.md) for more details.
|
|
|
|
#### Other commands
|
|
|
|
```bash
|
|
# Run lint, unit tests and integration tests
|
|
make check
|
|
```
|
|
|
|
There are also a few more helpful commands for development. Run `make help` to learn more, or look in [Makefile](./Makefile).
|
|
|
|
<!--
|
|
For Claude and other AI tools: Always prefer make targets over custom commands where possible.
|
|
-->
|
|
|
|
## Architecture
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
├── cmd/ # Application entry points
|
|
│ └── publisher/ # Server publishing tool
|
|
├── data/ # Seed data
|
|
├── deploy/ # Deployment configuration (Pulumi)
|
|
├── docs/ # Documentation
|
|
├── internal/ # Private application code
|
|
│ ├── api/ # HTTP handlers and routing
|
|
│ ├── auth/ # Authentication (GitHub OAuth, JWT, namespace blocking)
|
|
│ ├── config/ # Configuration management
|
|
│ ├── database/ # Data persistence (PostgreSQL)
|
|
│ ├── service/ # Business logic
|
|
│ ├── telemetry/ # Metrics and monitoring
|
|
│ └── validators/ # Input validation
|
|
├── pkg/ # Public packages
|
|
│ ├── api/ # API types and structures
|
|
│ │ └── v0/ # Version 0 API types
|
|
│ └── model/ # Data models for server.json
|
|
├── scripts/ # Development and testing scripts
|
|
├── tests/ # Integration tests
|
|
└── tools/ # CLI tools and utilities
|
|
└── 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
|
|
|
|
## Community Projects
|
|
|
|
Check out [community projects](docs/community-projects.md) to explore notable registry-related work created by the community.
|
|
|
|
## More documentation
|
|
|
|
See the [documentation](./docs) for more details if your question has not been answered here!
|