Package/server/manifest Version Bump

CLAUDE.md

@@ -90,23 +90,39 @@ When creating pull requests:
 
 When preparing a new release:
 
-```bash
-# Prepare CHANGELOG for release (replaces "Unreleased" with version and date)
-npm run changelog:prepare-release 1.0.0
-
-# Review changes, then commit and tag
-git add CHANGELOG.md
-git commit -m "Release v1.0.0"
-git tag v1.0.0
-git push && git push --tags
-```
+1. **Bump the version in `package.json`** to the new version (e.g., `1.0.0`)
+2. **Sync versions** across `manifest.json` and `server.json`:
+   ```bash
+   node scripts/sync-manifest-version.cjs
+   ```
+3. **Prepare the changelog** (replaces "Unreleased" with version and date):
+   ```bash
+   npm run changelog:prepare-release 1.0.0
+   ```
+4. **Commit, tag, and push:**
+   ```bash
+   git add package.json manifest.json server.json CHANGELOG.md
+   git commit -m "Release v1.0.0"
+   git tag v1.0.0
+   git push && git push --tags
+   ```
+5. **Publish via the [mcp-server-publisher](https://github.com/mapbox/mcp-server-publisher) workflow:**
+   - Go to Actions > "Manual Release MCP Server to NPM and MCP Registry"
+   - Select `mcp-devkit-server` from the repository dropdown
+   - Enter the version (must match `package.json` exactly)
+   - The workflow builds, tests, publishes to NPM (`@mapbox/mcp-devkit-server`), publishes to the MCP Registry, creates a DXT package, and creates a GitHub release
 
 The `changelog:prepare-release` script automatically:
 
 - Replaces "## Unreleased" with "## {version} - {date}"
 - Adds a new empty "## Unreleased" section at the top
 - Validates version format and CHANGELOG structure
 
+The `sync-manifest-version` script automatically:
+
+- Reads the version from `package.json`
+- Updates `manifest.json` and `server.json` (including `packages[0].version`) if they differ
+
 ## Important Constraints
 
 - **Tool naming:** Tool names (MCP identifiers) must be `snake_case_tool` (e.g., `list_styles_tool`). TypeScript class names follow `PascalCaseTool` convention (e.g., `ListStylesTool`)

README.md

@@ -45,6 +45,7 @@ https://github.com/user-attachments/assets/8b1b8ef2-9fba-4951-bc9a-beaed4f6aff6
     - [Environment Variables](#environment-variables-1)
       - [VERBOSE_ERRORS](#verbose_errors)
   - [Troubleshooting](#troubleshooting)
+  - [Release Process](#release-process)
   - [Contributing](#contributing)
 
 ## Quick Start
@@ -1337,6 +1338,64 @@ export CLIENT_NEEDS_RESOURCE_FALLBACK=true
 
 **Solution:** The GeoJSON preview tool may be slow with very large files. Consider simplifying geometries or using smaller datasets for preview purposes.
 
+## Release Process
+
+Follow these steps to publish a new release:
+
+1. **Bump the version in `package.json`** to the target version (e.g., `1.0.0`).
+
+2. **Sync versions** across `manifest.json` and `server.json`:
+
+   ```bash
+   node scripts/sync-manifest-version.cjs
+   ```
+
+   This reads the version from `package.json` and updates `manifest.json` and `server.json` (including `packages[0].version`) to match.
+
+3. **Prepare the changelog** — this replaces the "Unreleased" heading with the version and date:
+
+   ```bash
+   npm run changelog:prepare-release 1.0.0
+   ```
+
+4. **Commit, tag, and push:**
+
+   ```bash
+   git add package.json manifest.json server.json CHANGELOG.md
+   git commit -m "Release v1.0.0"
+   git tag v1.0.0
+   git push && git push --tags
+   ```
+
+5. **Publish via the [mcp-server-publisher](https://github.com/mapbox/mcp-server-publisher) workflow:**
+   - Go to the Actions tab in the `mcp-server-publisher` repo
+   - Select "Manual Release MCP Server to NPM and MCP Registry"
+   - Choose `mcp-devkit-server` from the repository dropdown
+   - Enter the version — it **must exactly match** the `package.json` version
+   - Leave the branch field empty for stable releases (or specify a branch for dev releases)
+   - The workflow will: build, test, publish to NPM (`@mapbox/mcp-devkit-server`), publish to the MCP Registry, create a DXT package, and create a GitHub Release
+
+### Version Files
+
+The following files must have matching versions before publishing:
+
+| File            | Fields                           |
+| --------------- | -------------------------------- |
+| `package.json`  | `version` (source of truth)      |
+| `manifest.json` | `version`                        |
+| `server.json`   | `version`, `packages[0].version` |
+
+The `sync-manifest-version.cjs` script handles syncing these automatically from `package.json`.
+
+### Dev Releases
+
+To publish a pre-release from a feature branch:
+
+1. Set the version in `package.json` with a pre-release suffix (e.g., `1.0.0-dev` or `1.0.0-beta`)
+2. Run `node scripts/sync-manifest-version.cjs`
+3. In the publisher workflow, enter the version and specify the branch name
+4. The package will be published to NPM under the `dev` tag (won't affect `latest`)
+
 ## Contributing
 
 We welcome contributions to the Mapbox Development MCP Server! Please review our documentation:

manifest.json

@@ -2,7 +2,7 @@
   "dxt_version": "0.1",
   "name": "@mapbox/mcp-devkit-server",
   "display_name": "Mapbox MCP DevKit Server",
-  "version": "0.4.7",
+  "version": "0.5.0",
   "description": "Mapbox MCP devkit server",
   "author": {
     "name": "Mapbox, Inc."

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapbox/mcp-devkit-server",
-  "version": "0.4.7",
+  "version": "0.5.0",
   "description": "Mapbox MCP devkit server",
   "mcpName": "io.github.mapbox/mcp-devkit-server",
   "main": "./dist/commonjs/index.js",

server.json

@@ -6,13 +6,13 @@
     "url": "https://github.com/mapbox/mcp-devkit-server",
     "source": "github"
   },
-  "version": "0.4.7",
+  "version": "0.5.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "runtimeHint": "npx",
-      "version": "0.4.7",
+      "version": "0.5.0",
       "identifier": "@mapbox/mcp-devkit-server",
       "transport": {
         "type": "stdio"