funplay-cocos-mcp/RELEASE_WORKFLOW.md

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

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
• 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

Example:

• package.json: 0.3.1
• Git tag: v0.3.1
• GitHub Release: v0.3.1
• Release asset: Funplay.CocosMcp.v0.3.1.zip

Files To Update For A New Release

Update:

1. package.json
   • "version": "<version>"
2. CHANGELOG.md
   • add a dated release notes block

Optional but recommended:

3. README.md
4. README_CN.md
5. GitHub Release notes text

Release Steps

1. Verify Working Tree

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:

## [0.3.1] - 2026-05-20

3. Run Release Verification

npm run release:verify

This runs:

• JavaScript syntax checks
• Node.js tests
• release metadata validation
• release package generation

The generated local artifacts are written to:

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:

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:

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

5. Commit, Tag, And Push

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:

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

If creating a new release:

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

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

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>/SHA256SUMS.txt \
  releases/<version>/README.md

7. Verify GitHub Release

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

Confirm the release has all four assets.

8. 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.

Current Verification Commands

npm run release:verify
gh release view v<version> -R FunplayAI/funplay-cocos-mcp --json url,assets

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>.