# Funplay Cocos MCP Release Workflow

This document records the release workflow for publishing Funplay MCP for Cocos to:

- Git tags
- GitHub Releases
- Downloadable Cocos Creator extension zip packages
- npm stdio wrapper package
- Official MCP Registry

## Published Identity

- GitHub repository: `https://github.com/FunplayAI/funplay-cocos-mcp`
- Git tag format: `v<version>`
- GitHub Release tag: `v<version>`
- Extension package asset: `Funplay.CocosMcp.v<version>.zip`
- Cocos extension folder name inside the zip: `funplay-cocos-mcp`
- npm package id: `funplay-cocos-mcp`
- npm command: `funplay-cocos-mcp`
- MCP Registry server name: `io.github.FunplayAI/funplay-cocos-mcp`
- Default local MCP endpoint: `http://127.0.0.1:8765/`

## Version Alignment Rule

Keep these versions aligned:

- `package.json` `version`
- `CHANGELOG.md` release section
- Git tag `v<version>`
- GitHub Release `v<version>`
- `releases/<version>/release-manifest.json` `version`
- Release zip filename `Funplay.CocosMcp.v<version>.zip`
- `server.json` top-level version
- `server.json` npm package version

Example:

- `package.json`: `0.3.1`
- Git tag: `v0.3.1`
- GitHub Release: `v0.3.1`
- Release asset: `Funplay.CocosMcp.v0.3.1.zip`
- npm package: `funplay-cocos-mcp@0.3.1`
- MCP Registry: `0.3.1`

## Files To Update For A New Release

Update:

1. `package.json`
   - `"version": "<version>"`
2. `CHANGELOG.md`
   - add a dated release notes block
3. `server.json`
   - top-level `"version"`
   - npm package `"version"`
4. `docs/TOOLS.md`
   - regenerate with `npm run docs:generate` after tool registry changes

Optional but recommended:

5. `README.md`
6. `README_CN.md`
7. GitHub Release notes text

## Release Steps

### 1. Verify Working Tree

```bash
git status --short --branch
```

The tree should contain only intentional release changes.

### 2. Update Versions And Notes

Update `package.json` and `CHANGELOG.md`.

Use semantic versions such as `0.3.1`, and keep release headings in this format:

```markdown
## [0.3.1] - 2026-05-20
```

When a release resolves a GitHub issue, reference it directly in the relevant
changelog bullet so the generated GitHub Release notes preserve traceability:

```markdown
- Fixed [#123](https://github.com/FunplayAI/funplay-cocos-mcp/issues/123): describe the resolved problem.
```

### 3. Run Release Verification

```bash
npm run release:verify
```

This runs:

- JavaScript syntax checks
- Node.js tests
- generated tool documentation validation
- release metadata validation
- npm package dry-run validation
- release package generation

The generated local artifacts are written to:

```text
releases/<version>/
```

Expected contents:

- `Funplay.CocosMcp.v<version>.zip`
- `release-manifest.json`
- `SHA256SUMS.txt`
- `README.md`

### 4. Inspect The Package

The release script validates that every archive path stays under:

```text
funplay-cocos-mcp/
```

The package must not contain local/build content such as:

- `.git/`
- `.github/`
- `.DS_Store`
- `node_modules/`
- `Library/`
- `Temp/`
- `dist/`
- `build/`
- `test/`
- `scripts/`

Verify checksums:

```bash
cd releases/<version>
shasum -a 256 -c SHA256SUMS.txt
```

### 4.5 Validate npm And MCP Registry Metadata

```bash
npm run pack:dry-run
npm run registry:validate
```

The npm package must include the stdio wrapper command:

```bash
npx --yes ./funplay-cocos-mcp-<version>.tgz --version
```

### 5. Commit, Tag, And Push

```bash
git add .
git commit -m "Release v<version>"
git tag v<version>
git push origin main
git push origin v<version>
```

### 6. Create GitHub Release

Regenerate the final release artifacts from the tagged clean commit:

```bash
npm run release:package -- --strict-tag
```

If creating a new release:

```bash
gh release create v<version> \
  -R FunplayAI/funplay-cocos-mcp \
  --title "v<version>" \
  --notes-file releases/<version>/RELEASE_NOTES.md \
  releases/<version>/Funplay.CocosMcp.v<version>.zip \
  releases/<version>/release-manifest.json \
  releases/<version>/RELEASE_NOTES.md \
  releases/<version>/SHA256SUMS.txt \
  releases/<version>/README.md
```

If the release already exists and only assets need to be replaced:

```bash
gh release upload v<version> \
  -R FunplayAI/funplay-cocos-mcp \
  --clobber \
  releases/<version>/Funplay.CocosMcp.v<version>.zip \
  releases/<version>/release-manifest.json \
  releases/<version>/RELEASE_NOTES.md \
  releases/<version>/SHA256SUMS.txt \
  releases/<version>/README.md
```

If the release body needs to be refreshed without replacing assets:

```bash
gh release edit v<version> \
  -R FunplayAI/funplay-cocos-mcp \
  --notes-file releases/<version>/RELEASE_NOTES.md
```

### 7. Verify GitHub Release

```bash
gh release view v<version> \
  -R FunplayAI/funplay-cocos-mcp \
  --json url,assets,isDraft,isPrerelease,publishedAt
```

Confirm the release has all five assets and the public release body is organized by change type. Download all five assets together and run `shasum -a 256 -c SHA256SUMS.txt` to verify the public files.

### 8. Publish To npm

```bash
npm publish
```

Verify the published package:

```bash
npm view funplay-cocos-mcp@<version> version bin mcpName
```

Notes:

- `package.json` `mcpName` must match `server.json` `name`.
- If `npm publish` returns `ENEEDAUTH`, run `npm adduser` with a publishing account and retry.
- If the package name already exists under another owner, choose a scoped package name and update both `package.json` and `server.json`.

### 9. Publish To MCP Registry

The preferred organization-safe path is the GitHub Actions OIDC workflow. It
uses the repository identity and does not require a saved Registry token:

```bash
gh workflow run publish-mcp-registry.yml \
  -R FunplayAI/funplay-cocos-mcp \
  -f release_ref=v<version>
```

Wait for the workflow and verify it succeeds:

```bash
gh run watch \
  -R FunplayAI/funplay-cocos-mcp \
  "$(gh run list -R FunplayAI/funplay-cocos-mcp \
    --workflow publish-mcp-registry.yml --limit 1 --json databaseId --jq '.[0].databaseId')"
```

Verify latest:

```bash
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.FunplayAI/funplay-cocos-mcp&version=latest"
```

Check a specific version:

```bash
curl "https://registry.modelcontextprotocol.io/v0.1/servers/io.github.FunplayAI%2Ffunplay-cocos-mcp/versions/<version>"
```

### 10. Post-Release Smoke Test

Test the package from the public GitHub Release:

1. Download `Funplay.CocosMcp.v<version>.zip`.
2. Unzip it.
3. Move `funplay-cocos-mcp` into a Cocos project `extensions/` directory.
4. Restart Cocos Creator or reload extensions.
5. Open `Funplay > MCP Server`.
6. Start the MCP server.
7. Connect an MCP client and call `get_project_info`.
8. Install the npm wrapper with `npm install -g funplay-cocos-mcp`.
9. Connect an MCP client through the `funplay-cocos-mcp` command and call `tools/list`.

## Current Verification Commands

```bash
npm run release:verify
npm run registry:validate
gh release view v<version> -R FunplayAI/funplay-cocos-mcp --json url,assets
npm view funplay-cocos-mcp@<version> version bin mcpName
```

## Common Failure Cases

### Release validation says the changelog section is missing

Cause:

- `CHANGELOG.md` does not contain `## [<version>] - YYYY-MM-DD`.

Fix:

- Add a dated release section before packaging.

### `zip` command is missing

Cause:

- The local environment does not have the `zip` CLI installed.

Fix:

- Install `zip`, then rerun `npm run release:package`.

### GitHub Release upload replaces the wrong assets

Cause:

- The version directory or release tag does not match `package.json` version.

Fix:

- Rerun `npm run release:check`.
- Confirm the command uses `releases/<version>/` and `v<version>`.

### npm `ENEEDAUTH`

Cause:

- The local machine is not logged in to npm.

Fix:

```bash
npm adduser
npm publish
```

### MCP Registry `Package validation failed`

Cause:

- npm package has not been published yet.
- `package.json` `mcpName` does not match `server.json` `name`.
- `server.json` package version does not match the npm package version.

Fix:

- Publish the npm package first.
- Rerun `npm run release:check`.
- Rerun `npm run registry:validate`.