Big docs tidy up in preparation for launch (#364)
## Motivation and Context Docs currently don't have very clear organisation, and don't explain core flows. This fixes #89 (although we still might want to push these to `https://modelcontextprotocol.io/docs/`), based on the plan there. One minor change from that plan is that I merged tutorials and guides, because they ended up basically being duplicates which I thought would be annoying for us to keep in sync. Additionally in the Diátaxis framework, tutorials and guides are separated by whether they are focused on acquisition of skills (e.g. in a learning environment) or application of skills (e.g. in a work environment). I expect the registry to be something that will be used occasionally in a work environment, rather than a fundamental 'learnable' skill so I think it's reasonable not to have tutorials and fold these into guides. ## How Has This Been Tested? - Read through all these updated docs - Unit and integration tests (that previously used examples.md and use the schema) working - Ran `npx markdown-link-check .` to check all the links work ## Breaking Changes Links to old docs will break, but I don't think there are any. All internal links have been checked and updated. ## 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
This commit is contained in:
adam jones
GitHub
parent
e9884c1d7b
commit
2e7108d366
2 changed files with 1200 additions and 376 deletions
331
docs/guides/publishing/github-actions.md
Normal file
331
docs/guides/publishing/github-actions.md
Normal file
|
|
@ -0,0 +1,331 @@
|
|||
# Automate Publishing with GitHub Actions
|
||||
|
||||
Set up automated MCP server publishing using GitHub Actions.
|
||||
|
||||
## What You'll Learn
|
||||
|
||||
By the end of this tutorial, you'll have:
|
||||
- A GitHub Actions workflow that automatically publishes your server
|
||||
- Understanding of GitHub OIDC authentication
|
||||
- Knowledge of best practices for automated publishing
|
||||
- Working examples for Node.js, Python, and Docker projects
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Already published your server manually (complete [Publishing Tutorial](publish-server.md) first)
|
||||
- GitHub repository with your MCP server code
|
||||
- Basic understanding of CI/CD concepts
|
||||
- 20-30 minutes
|
||||
|
||||
## GitHub Actions Setup
|
||||
|
||||
### Step 1: Create Workflow File
|
||||
|
||||
Create `.github/workflows/publish-mcp.yml` in your repository:
|
||||
|
||||
```yaml
|
||||
name: Publish to MCP Registry
|
||||
|
||||
on:
|
||||
push:
|
||||
tags: ['v*'] # Triggers on version tags like v1.0.0
|
||||
|
||||
jobs:
|
||||
publish:
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
id-token: write # Required for OIDC authentication
|
||||
contents: read
|
||||
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js # Adjust for your language
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20'
|
||||
registry-url: 'https://registry.npmjs.org'
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Run tests
|
||||
run: npm test
|
||||
|
||||
- name: Build package
|
||||
run: npm run build
|
||||
|
||||
- name: Publish to npm
|
||||
run: npm publish
|
||||
env:
|
||||
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
||||
|
||||
- name: Install MCP Publisher
|
||||
run: |
|
||||
# Build publisher from source (requires Go)
|
||||
git clone https://github.com/modelcontextprotocol/registry publisher-repo
|
||||
cd publisher-repo
|
||||
make publisher
|
||||
cp cmd/publisher/bin/mcp-publisher ../mcp-publisher
|
||||
cd ..
|
||||
chmod +x mcp-publisher
|
||||
|
||||
- name: Login to MCP Registry
|
||||
run: ./mcp-publisher login github-oidc
|
||||
|
||||
- name: Publish to MCP Registry
|
||||
run: ./mcp-publisher publish
|
||||
```
|
||||
|
||||
### Step 2: Configure Secrets
|
||||
|
||||
For npm publishing, add your NPM token to repository secrets:
|
||||
|
||||
1. Go to repository Settings → Secrets and variables → Actions
|
||||
2. Add `NPM_TOKEN` with your npm access token
|
||||
|
||||
**Note:** GitHub OIDC authentication requires no additional secrets for MCP Registry publishing.
|
||||
|
||||
### Step 3: Tag and Release
|
||||
|
||||
Create a version tag to trigger the workflow:
|
||||
|
||||
```bash
|
||||
git tag v1.0.0
|
||||
git push origin v1.0.0
|
||||
```
|
||||
|
||||
The workflow will:
|
||||
1. Run tests
|
||||
2. Build your package
|
||||
3. Publish to npm
|
||||
4. Automatically authenticate with the MCP Registry
|
||||
5. Publish updated server.json
|
||||
|
||||
## Authentication Methods by CI Platform
|
||||
|
||||
### GitHub Actions - OIDC (Recommended)
|
||||
|
||||
```yaml
|
||||
- name: Login to MCP Registry
|
||||
run: mcp-publisher login github-oidc
|
||||
```
|
||||
|
||||
**Advantages:**
|
||||
- No secrets to manage
|
||||
- Automatically scoped to your repository
|
||||
- Most secure option
|
||||
|
||||
### GitHub Actions - Personal Access Token
|
||||
|
||||
```yaml
|
||||
- name: Login to MCP Registry
|
||||
run: mcp-publisher login github --token ${{ secrets.GITHUB_TOKEN }}
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.MCP_GITHUB_TOKEN }}
|
||||
```
|
||||
|
||||
Add `MCP_GITHUB_TOKEN` secret with a GitHub PAT that has repo access.
|
||||
|
||||
### DNS Authentication (Any CI)
|
||||
|
||||
For custom domain namespaces (`com.yourcompany/*`):
|
||||
|
||||
```yaml
|
||||
- name: Login to MCP Registry
|
||||
run: |
|
||||
echo "${{ secrets.MCP_PRIVATE_KEY }}" > key.pem
|
||||
mcp-publisher login dns --domain yourcompany.com --private-key-file key.pem
|
||||
```
|
||||
|
||||
Add your Ed25519 private key as `MCP_PRIVATE_KEY` secret.
|
||||
|
||||
## Language-Specific Examples
|
||||
|
||||
### Python Project
|
||||
|
||||
```yaml
|
||||
name: Publish Python MCP Server
|
||||
|
||||
on:
|
||||
push:
|
||||
tags: ['v*']
|
||||
|
||||
jobs:
|
||||
publish:
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
id-token: write
|
||||
contents: read
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Python
|
||||
uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: '3.11'
|
||||
|
||||
- name: Install Poetry
|
||||
run: pipx install poetry
|
||||
|
||||
- name: Build package
|
||||
run: poetry build
|
||||
|
||||
- name: Publish to PyPI
|
||||
run: poetry publish
|
||||
env:
|
||||
POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_TOKEN }}
|
||||
|
||||
- name: Install MCP Publisher
|
||||
run: |
|
||||
git clone https://github.com/modelcontextprotocol/registry publisher-repo
|
||||
cd publisher-repo && make publisher && cd ..
|
||||
cp publisher-repo/cmd/publisher/bin/mcp-publisher mcp-publisher
|
||||
|
||||
- name: Publish to MCP Registry
|
||||
run: |
|
||||
./mcp-publisher login github-oidc
|
||||
./mcp-publisher publish
|
||||
```
|
||||
|
||||
### Docker Project
|
||||
|
||||
```yaml
|
||||
name: Publish Docker MCP Server
|
||||
|
||||
on:
|
||||
push:
|
||||
tags: ['v*']
|
||||
|
||||
jobs:
|
||||
publish:
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
id-token: write
|
||||
contents: read
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Docker Buildx
|
||||
uses: docker/setup-buildx-action@v3
|
||||
|
||||
- name: Login to Docker Hub
|
||||
uses: docker/login-action@v3
|
||||
with:
|
||||
username: ${{ secrets.DOCKER_USERNAME }}
|
||||
password: ${{ secrets.DOCKER_PASSWORD }}
|
||||
|
||||
- name: Extract version
|
||||
id: version
|
||||
run: echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
|
||||
|
||||
- name: Build and push
|
||||
uses: docker/build-push-action@v5
|
||||
with:
|
||||
context: .
|
||||
push: true
|
||||
tags: yourname/your-server:${{ steps.version.outputs.version }}
|
||||
labels: |
|
||||
io.modelcontextprotocol.server.name=io.github.yourname/your-server
|
||||
|
||||
- name: Install MCP Publisher
|
||||
run: |
|
||||
git clone https://github.com/modelcontextprotocol/registry publisher-repo
|
||||
cd publisher-repo && make publisher && cd ..
|
||||
cp publisher-repo/cmd/publisher/bin/mcp-publisher mcp-publisher
|
||||
|
||||
- name: Publish to MCP Registry
|
||||
run: |
|
||||
./mcp-publisher login github-oidc
|
||||
./mcp-publisher publish
|
||||
```
|
||||
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Version Alignment
|
||||
|
||||
Keep your package version and server.json version in sync:
|
||||
|
||||
```yaml
|
||||
- name: Update server.json version
|
||||
run: |
|
||||
VERSION=${GITHUB_REF#refs/tags/v}
|
||||
jq --arg version "$VERSION" '.version_detail.version = $version' server.json > tmp.json
|
||||
mv tmp.json server.json
|
||||
```
|
||||
|
||||
### 2. Conditional Publishing
|
||||
|
||||
Only publish to registry after package publishing succeeds:
|
||||
|
||||
```yaml
|
||||
- name: Publish to npm
|
||||
run: npm publish
|
||||
id: npm-publish
|
||||
|
||||
- name: Publish to MCP Registry
|
||||
if: steps.npm-publish.outcome == 'success'
|
||||
run: ./mcp-publisher publish
|
||||
```
|
||||
|
||||
### 3. Test Before Publishing
|
||||
|
||||
Include validation in your workflow:
|
||||
|
||||
```yaml
|
||||
- name: Validate server.json
|
||||
run: |
|
||||
# Validate against schema
|
||||
curl -s https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json | \
|
||||
jq . > schema.json
|
||||
npx ajv-cli validate -s schema.json -d server.json
|
||||
|
||||
# Test with publisher
|
||||
./mcp-publisher init --validate-only
|
||||
```
|
||||
|
||||
### 4. Notification Setup
|
||||
|
||||
Get notified of publishing status:
|
||||
|
||||
```yaml
|
||||
- name: Notify on success
|
||||
if: success()
|
||||
run: |
|
||||
curl -X POST "${{ secrets.WEBHOOK_URL }}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"text": "✅ MCP server ${{ github.repository }} published successfully"}'
|
||||
|
||||
- name: Notify on failure
|
||||
if: failure()
|
||||
run: |
|
||||
curl -X POST "${{ secrets.WEBHOOK_URL }}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"text": "❌ MCP server ${{ github.repository }} publishing failed"}'
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**"Publisher binary not found"** - Ensure you download the correct binary for your CI platform (linux/mac/windows).
|
||||
|
||||
**"Authentication failed"** - For GitHub OIDC, verify `id-token: write` permission is set. For other methods, check secret configuration.
|
||||
|
||||
**"Package validation failed"** - Ensure your package was published successfully before MCP Registry publishing runs.
|
||||
|
||||
**"Version already exists"** - Each server.json version must be unique. Consider using build numbers: `1.0.0-build.123`.
|
||||
|
||||
## What You've Accomplished
|
||||
|
||||
You now have automated MCP server publishing that:
|
||||
- Triggers on version tags
|
||||
- Runs tests before publishing
|
||||
- Publishes to package registry first
|
||||
- Automatically publishes to MCP Registry
|
||||
- Handles authentication securely
|
||||
- Provides failure notifications
|
||||
|
||||
Your MCP server publishing is now fully automated - just tag a release and everything happens automatically!
|
||||
309
docs/guides/publishing/publish-server.md
Normal file
309
docs/guides/publishing/publish-server.md
Normal file
|
|
@ -0,0 +1,309 @@
|
|||
# Publish Your MCP Server
|
||||
|
||||
Complete guide to publishing an MCP server to the registry.
|
||||
|
||||
## What You'll Learn
|
||||
|
||||
By the end of this tutorial, you'll have:
|
||||
- Created a server.json file for your MCP server
|
||||
- Authenticated with the registry
|
||||
- Successfully published your server
|
||||
- Verified your server appears in the registry
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- An MCP server you've already built ([follow this guide if you don't have one already](https://modelcontextprotocol.io/quickstart/server))
|
||||
- Your server published to a package registry (npm, PyPI, Docker Hub, etc.)
|
||||
|
||||
## Step 1: Install the Publisher CLI
|
||||
|
||||
<!-- TODO: update once #358 solved -->
|
||||
|
||||
Download and build the MCP publisher tool:
|
||||
|
||||
```bash
|
||||
# Clone the registry repository (requires Go 1.24+)
|
||||
git clone https://github.com/modelcontextprotocol/registry
|
||||
cd registry
|
||||
make publisher
|
||||
|
||||
# The binary will be at cmd/publisher/bin/mcp-publisher
|
||||
export PATH=$PATH:$(pwd)/cmd/publisher/bin
|
||||
```
|
||||
|
||||
## Step 2: Initialize Your server.json
|
||||
|
||||
Navigate to your server's directory and create a template:
|
||||
|
||||
```bash
|
||||
cd /path/to/your/mcp-server
|
||||
mcp-publisher init
|
||||
```
|
||||
|
||||
This creates a `server.json` with auto-detected values. You'll see something like:
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
|
||||
"name": "io.github.yourname/your-server",
|
||||
"description": "A description of your MCP server",
|
||||
"version_detail": {
|
||||
"version": "1.0.0"
|
||||
},
|
||||
"packages": [
|
||||
{
|
||||
"registry_type": "npm",
|
||||
"identifier": "your-package-name",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Step 3: Configure Your Server Details
|
||||
|
||||
Edit the generated `server.json`:
|
||||
|
||||
### Choose Your Namespace
|
||||
|
||||
The `name` field determines authentication requirements:
|
||||
|
||||
- **`io.github.yourname/*`** - Requires GitHub authentication
|
||||
- **`com.yourcompany/*`** - Requires DNS or HTTP domain verification
|
||||
|
||||
### Add Package Validation
|
||||
|
||||
Your package must include validation metadata to prove ownership.
|
||||
|
||||
|
||||
<details>
|
||||
<summary><strong>📦 NPM Packages</strong></summary>
|
||||
|
||||
### Requirements
|
||||
Add an `mcpName` field to your `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "your-npm-package",
|
||||
"version": "1.0.0",
|
||||
"mcpName": "io.github.username/server-name"
|
||||
}
|
||||
```
|
||||
|
||||
### How It Works
|
||||
- Registry fetches `https://registry.npmjs.org/your-npm-package`
|
||||
- Checks that `mcpName` field matches your server name
|
||||
- Fails if field is missing or doesn't match
|
||||
|
||||
### Example server.json
|
||||
```json
|
||||
{
|
||||
"name": "io.github.username/server-name",
|
||||
"packages": [
|
||||
{
|
||||
"registry_type": "npm",
|
||||
"identifier": "your-npm-package",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The official MCP registry currently only supports the NPM public registry (`https://registry.npmjs.org`).
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>🐍 PyPI Packages</strong></summary>
|
||||
|
||||
### Requirements
|
||||
Include your server name in your package README file using this format:
|
||||
|
||||
**MCP name format**: `mcp-name: io.github.username/server-name`
|
||||
|
||||
Add it to your README.md file (which becomes the package description on PyPI).
|
||||
|
||||
### How It Works
|
||||
- Registry fetches `https://pypi.org/pypi/your-package/json`
|
||||
- Passes if `mcp-name: server-name` is in the README content
|
||||
|
||||
### Example server.json
|
||||
```json
|
||||
{
|
||||
"name": "io.github.username/server-name",
|
||||
"packages": [
|
||||
{
|
||||
"registry_type": "pypi",
|
||||
"identifier": "your-pypi-package",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The official MCP registry currently only supports the official PyPI registry (`https://pypi.org`).
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>📋 NuGet Packages</strong></summary>
|
||||
|
||||
### Requirements
|
||||
Include your server name in your package's README using this format:
|
||||
|
||||
**MCP name format**: `mcp-name: io.github.username/server-name`
|
||||
|
||||
Add a README file to your NuGet package that includes the server name.
|
||||
|
||||
### How It Works
|
||||
- Registry fetches README from `https://api.nuget.org/v3-flatcontainer/{id}/{version}/readme`
|
||||
- Passes if `mcp-name: server-name` is found in the README content
|
||||
|
||||
### Example server.json
|
||||
```json
|
||||
{
|
||||
"name": "io.github.username/server-name",
|
||||
"packages": [
|
||||
{
|
||||
"registry_type": "nuget",
|
||||
"identifier": "Your.NuGet.Package",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The official MCP registry currently only supports the official NuGet registry (`https://api.nuget.org`).
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>🐳 Docker/OCI Images</strong></summary>
|
||||
|
||||
### Requirements
|
||||
Add an annotation to your Docker image:
|
||||
|
||||
```dockerfile
|
||||
LABEL io.modelcontextprotocol.server.name="io.github.username/server-name"
|
||||
```
|
||||
|
||||
### How It Works
|
||||
- Registry authenticates with Docker Hub using public token
|
||||
- Fetches image manifest using Docker Registry v2 API
|
||||
- Checks that `io.modelcontextprotocol.server.name` annotation matches your server name
|
||||
- Fails if annotation is missing or doesn't match
|
||||
|
||||
### Example server.json
|
||||
```json
|
||||
{
|
||||
"name": "io.github.username/server-name",
|
||||
"packages": [
|
||||
{
|
||||
"registry_type": "oci",
|
||||
"identifier": "yourusername/your-mcp-server",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The identifier is `namespace/repository`, and version is the tag and optionally digest.
|
||||
|
||||
The official MCP registry currently only supports the official Docker registry (`https://docker.io`).
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>📁 MCPB Packages</strong></summary>
|
||||
|
||||
### Requirements
|
||||
**MCP reference** - MCPB package URLs must contain "mcp" somewhere within them, to ensure the correct artifact has been uploaded. This may be with the `.mcpb` extension or in the name of your repository.
|
||||
|
||||
### Example server.json
|
||||
```json
|
||||
{
|
||||
"name": "io.github.username/server-name",
|
||||
"packages": [
|
||||
{
|
||||
"registry_type": "mcpb",
|
||||
"identifier": "https://github.com/you/your-repo/releases/download/v1.0.0/server.mcpb"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The official MCP registry currently only supports artifacts hosted on GitHub or GitLab releases.
|
||||
|
||||
</details>
|
||||
|
||||
## Step 4: Authenticate
|
||||
|
||||
Choose your authentication method based on your namespace:
|
||||
|
||||
### GitHub Authentication (for io.github.* namespaces)
|
||||
|
||||
```bash
|
||||
mcp-publisher login github
|
||||
```
|
||||
|
||||
This opens your browser for OAuth authentication.
|
||||
|
||||
### DNS Authentication (for custom domains)
|
||||
|
||||
```bash
|
||||
# Generate keypair
|
||||
openssl genpkey -algorithm Ed25519 -out key.pem
|
||||
|
||||
# Get public key for DNS record
|
||||
echo "_mcp-registry.yourcompany.com. IN TXT \"v=MCPv1; k=ed25519; p=$(openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64)\""
|
||||
|
||||
# Add the TXT record to your DNS, then login
|
||||
mcp-publisher login dns --domain yourcompany.com --private-key $(openssl pkey -in key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n')
|
||||
```
|
||||
|
||||
## Step 5: Publish Your Server
|
||||
|
||||
With authentication complete, publish your server:
|
||||
|
||||
```bash
|
||||
mcp-publisher publish
|
||||
```
|
||||
|
||||
You'll see output like:
|
||||
```
|
||||
✓ Validating server.json
|
||||
✓ Checking package ownership
|
||||
✓ Publishing to registry
|
||||
✓ Server published successfully!
|
||||
|
||||
Your server is now available at:
|
||||
https://registry.modelcontextprotocol.io/servers/io.github.yourname/weather-server
|
||||
```
|
||||
|
||||
## Step 6: Verify Publication
|
||||
|
||||
Check that your server appears in the registry:
|
||||
|
||||
```bash
|
||||
curl https://registry.modelcontextprotocol.io/servers/io.github.yourname/weather-server
|
||||
```
|
||||
|
||||
You should see your server metadata returned as JSON.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**"Package validation failed"** - Ensure your package includes the required validation metadata (mcpName field, README mention, or Docker label).
|
||||
|
||||
**"Authentication failed"** - Verify you've correctly set up DNS records or are logged into the right GitHub account.
|
||||
|
||||
**"Namespace not authorized"** - Your authentication method doesn't match your chosen namespace format.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- **Update your server**: Publish new versions with updated server.json files
|
||||
- **Set up CI/CD**: Automate publishing with [GitHub Actions](github-actions.md)
|
||||
- **Learn more**: Understand [server.json format](../../reference/server-json/generic-server-json.md) in depth
|
||||
|
||||
## What You've Accomplished
|
||||
|
||||
You've successfully published your first MCP server to the registry! Your server is now discoverable by MCP clients and can be installed by users worldwide.
|
||||
Loading…
Reference in a new issue