|
1 | | -# MCP Registry Publisher Tool |
| 1 | +# MCP Publisher Tool - Development |
2 | 2 |
|
3 | | -The MCP Registry Publisher Tool helps you publish Model Context Protocol (MCP) servers to the official registry. It follows a simple, npm-like workflow that's familiar to most developers. |
| 3 | +CLI tool for publishing MCP servers to the registry. |
4 | 4 |
|
5 | | -## Installation |
| 5 | +> These docs are for contributors. See the [Publisher User Guide](../../docs/publisher/guide.md) for end-user documentation. |
6 | 6 |
|
7 | | -```bash |
8 | | -# Build for current platform |
9 | | -./build.sh |
10 | | - |
11 | | -# Build for all supported platforms (optional) |
12 | | -./build.sh --all |
13 | | -``` |
14 | | - |
15 | | -The compiled binary will be placed in the `bin` directory. |
16 | | - |
17 | | -## Quick Start |
18 | | - |
19 | | -```bash |
20 | | -# 1. Create a template server.json file |
21 | | -mcp-publisher init |
22 | | - |
23 | | -# 2. Edit server.json with your server details |
24 | | - |
25 | | -# 3. Authenticate with the registry (one-time setup) |
26 | | -mcp-publisher login <method> |
27 | | - |
28 | | -# 4. Publish your server |
29 | | -mcp-publisher publish |
30 | | -``` |
31 | | - |
32 | | -## Commands |
33 | | - |
34 | | -### `mcp-publisher init` |
35 | | - |
36 | | -Creates a template `server.json` file with smart defaults. This command automatically detects values from your environment when possible. |
37 | | - |
38 | | -```bash |
39 | | -mcp-publisher init |
40 | | -``` |
41 | | - |
42 | | -Auto-detection sources: |
43 | | -- **Git remote origin** for repository URL and server name |
44 | | -- **package.json** for npm packages (name, description) |
45 | | -- **pyproject.toml** for Python packages |
46 | | -- **Current directory** for fallback naming |
47 | | - |
48 | | -The generated file includes placeholder values that you should update before publishing. |
49 | | - |
50 | | -### `mcp-publisher login <method>` |
51 | | - |
52 | | -Authenticates with the MCP registry. You'll only need to do this once - the tool saves your credentials locally. |
53 | | - |
54 | | -```bash |
55 | | -# GitHub interactive authentication |
56 | | -mcp-publisher login github |
57 | | - |
58 | | -# GitHub Actions OIDC (for CI/CD) |
59 | | -mcp-publisher login github-oidc |
60 | | - |
61 | | -# DNS-based authentication |
62 | | -mcp-publisher login dns --domain example.com --private-key abc123... |
63 | | - |
64 | | -# HTTP-based authentication |
65 | | -mcp-publisher login http --domain example.com --private-key abc123... |
66 | | -``` |
67 | | - |
68 | | -**Authentication Methods:** |
69 | | - |
70 | | -- **`github`**: Interactive GitHub OAuth flow. Opens browser for authentication. |
71 | | -- **`github-oidc`**: For GitHub Actions. Uses OIDC tokens automatically. |
72 | | -- **`dns`**: Domain-based auth using DNS TXT records. Requires `--domain` and `--private-key`. |
73 | | -- **`http`**: Domain-based auth using HTTPS endpoint. Requires `--domain` and `--private-key`. |
74 | | - |
75 | | -### `mcp-publisher publish` |
76 | | - |
77 | | -Publishes your `server.json` file to the registry. You must be logged in first. |
78 | | - |
79 | | -```bash |
80 | | -mcp-publisher publish |
81 | | -``` |
82 | | - |
83 | | -This command: |
84 | | -- Validates your `server.json` file |
85 | | -- Checks your authentication |
86 | | -- Uploads the server configuration to the registry |
87 | | - |
88 | | -### `mcp-publisher logout` |
89 | | - |
90 | | -Clears your saved authentication credentials. |
91 | | - |
92 | | -```bash |
93 | | -mcp-publisher logout |
94 | | -``` |
95 | | - |
96 | | -## GitHub Actions |
97 | | - |
98 | | -For automated publishing from GitHub Actions: |
99 | | - |
100 | | -```yaml |
101 | | -name: Publish to MCP Registry |
102 | | -on: |
103 | | - push: |
104 | | - tags: ['v*'] |
105 | | - |
106 | | -jobs: |
107 | | - publish: |
108 | | - runs-on: ubuntu-latest |
109 | | - permissions: |
110 | | - id-token: write # Required for OIDC |
111 | | - contents: read |
112 | | - steps: |
113 | | - - uses: actions/checkout@v4 |
114 | | - |
115 | | - - name: Setup MCP Publisher |
116 | | - run: | |
117 | | - curl -LO https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher-linux-amd64 |
118 | | - chmod +x mcp-publisher-linux-amd64 |
119 | | - |
120 | | - - name: Login to Registry |
121 | | - run: ./mcp-publisher-linux-amd64 login github-oidc |
122 | | - |
123 | | - - name: Publish to Registry |
124 | | - run: ./mcp-publisher-linux-amd64 publish |
125 | | -``` |
126 | | -
|
127 | | -The `login github-oidc` command uses GitHub's OIDC tokens for authentication in CI environments. |
128 | | - |
129 | | -## Examples |
130 | | - |
131 | | -### Publishing an NPM-based server |
132 | | - |
133 | | -```bash |
134 | | -# Create template server.json (auto-detects from package.json) |
135 | | -# Then edit server.json to add your specific details |
136 | | -mcp-publisher init |
137 | | -
|
138 | | -# Login (first time only) |
139 | | -mcp-publisher login github |
140 | | -
|
141 | | -# Publish |
142 | | -mcp-publisher publish |
143 | | -``` |
144 | | - |
145 | | -### Publishing a Python server |
| 7 | +## Quick Development Setup |
146 | 8 |
|
147 | 9 | ```bash |
148 | | -# Create template server.json (auto-detects from pyproject.toml) |
149 | | -# Then edit server.json to add your specific details |
150 | | -mcp-publisher init |
| 10 | +# Build the tool |
| 11 | +make publisher |
151 | 12 |
|
152 | | -# Publish (assuming already logged in) |
153 | | -mcp-publisher publish |
| 13 | +# Test locally |
| 14 | +make dev-compose # Start local registry |
| 15 | +./bin/mcp-publisher init |
| 16 | +./bin/mcp-publisher login none --registry=http://localhost:8080 |
| 17 | +./bin/mcp-publisher publish --registry=http://localhost:8080 |
154 | 18 | ``` |
155 | 19 |
|
156 | | -### Publishing with DNS authentication |
157 | | - |
158 | | -```bash |
159 | | -# Setup DNS TXT record first (see DNS Authentication section below) |
160 | | -
|
161 | | -# Login with DNS |
162 | | -mcp-publisher login dns --domain example.com --private-key YOUR_PRIVATE_KEY |
163 | | -
|
164 | | -# Publish |
165 | | -mcp-publisher publish |
166 | | -``` |
167 | | - |
168 | | -## Authentication Details |
169 | | - |
170 | | -### DNS Authentication |
171 | | - |
172 | | -For domain-based authentication using DNS: |
173 | | - |
174 | | -1. Generate an Ed25519 keypair: |
175 | | - ```bash |
176 | | - openssl genpkey -algorithm Ed25519 -out /tmp/key.pem && \ |
177 | | - echo "DNS TXT Record:" && \ |
178 | | - echo " v=MCPv1; k=ed25519; p=$(openssl pkey -in /tmp/key.pem -pubout -outform DER | tail -c 32 | base64)" && \ |
179 | | - echo "" && \ |
180 | | - echo "Private key for login:" && \ |
181 | | - echo " $(openssl pkey -in /tmp/key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n')" && \ |
182 | | - rm /tmp/key.pem |
183 | | - ``` |
184 | | - |
185 | | -2. Add the TXT record to your domain's DNS |
186 | | - |
187 | | -3. Login with: |
188 | | - ```bash |
189 | | - mcp-publisher login dns --domain example.com --private-key YOUR_PRIVATE_KEY |
190 | | - ``` |
191 | | - |
192 | | -This grants publishing rights for `example.com/*` and `*.example.com/*` namespaces. |
193 | | - |
194 | | -### HTTP Authentication |
195 | | - |
196 | | -For HTTP-based authentication: |
197 | | - |
198 | | -1. Generate an Ed25519 keypair (same as DNS) |
199 | | - |
200 | | -2. Host the public key at `https://yoursite.com/.well-known/mcp-registry-auth`: |
201 | | - ``` |
202 | | - v=MCPv1; k=ed25519; p=YOUR_PUBLIC_KEY_BASE64 |
203 | | - ``` |
204 | | - |
205 | | -3. Login with: |
206 | | - ```bash |
207 | | - mcp-publisher login http --domain example.com --private-key YOUR_PRIVATE_KEY |
208 | | - ``` |
209 | | - |
210 | | -This grants publishing rights for the `example.com/*` namespace. |
| 20 | +## Architecture |
211 | 21 |
|
212 | | -## Troubleshooting |
| 22 | +### Commands |
| 23 | +- **`init`** - Generate server.json templates with auto-detection |
| 24 | +- **`login`** - Handle authentication (github, dns, http, none) |
| 25 | +- **`publish`** - Validate and upload servers to registry |
| 26 | +- **`logout`** - Clear stored credentials |
213 | 27 |
|
214 | | -**"Not authenticated" error**: Run `mcp-publisher login <method>` to authenticate (e.g., `mcp-publisher login github`). |
| 28 | +### Authentication Providers |
| 29 | +- **`github`** - Interactive OAuth flow |
| 30 | +- **`github-oidc`** - CI/CD with GitHub Actions |
| 31 | +- **`dns`** - Domain verification via DNS TXT records |
| 32 | +- **`http`** - Domain verification via HTTPS endpoints |
| 33 | +- **`none`** - No auth (testing only) |
215 | 34 |
|
216 | | -**"Invalid server.json" error**: Ensure your `server.json` file is valid. You can recreate it with `mcp-publisher init`. |
| 35 | +## Key Files |
217 | 36 |
|
218 | | -**GitHub Actions failing**: Ensure your workflow has `id-token: write` permission and you're using `mcp-publisher login github-oidc`. |
| 37 | +- **`main.go`** - CLI setup and command routing |
| 38 | +- **`commands/`** - Command implementations with auto-detection logic |
| 39 | +- **`auth/`** - Authentication provider implementations |
| 40 | +- **`build.sh`** - Cross-platform build script |
0 commit comments