Release Process

October 30, 2025 · View on GitHub

This document describes the release process for Token Optimizer MCP, including automated releases via semantic-release and manual procedures when needed.

Automated Release Process
Manual Release Steps
Registry Publishing
Post-Release Checklist
Rollback Procedures

Automated Release Process

Token Optimizer MCP uses semantic-release to automate version management and package publishing.

How It Works

Commit Analysis
- On merge to main branch, semantic-release analyzes commits
- Follows Conventional Commits specification
- Determines version bump based on commit messages

Version Determination

Commit Type	Version Bump	Example
`fix:`	Patch (0.0.x)	`fix(cache): resolve memory leak`
`feat:`	Minor (0.x.0)	`feat(tools): add smart compression`
`BREAKING CHANGE:`	Major (x.0.0)	`feat!: redesign cache API`
`perf:`	Patch (0.0.x)	`perf(token): optimize counting`
`docs:`, `chore:`	No release	Documentation/maintenance only

Release Workflow

Commit to main
→ CI/CD triggered
→ semantic-release runs
→ Version calculated
→ CHANGELOG.md updated
→ package.json version bumped
→ Git tag created
→ npm package published
→ GitHub release created
→ Docker image built (optional)

Commit Message Format

Standard Format:

<type>(<scope>): <short summary>

<body>

<footer>

Examples:

# Patch release (0.0.x)
fix(cache): prevent duplicate cache entries
docs(readme): fix installation instructions

# Minor release (0.x.0)
feat(tools): add sentiment analysis tool
feat(api): implement GraphQL optimization

# Major release (x.0.0)
feat(cache)!: redesign cache API

BREAKING CHANGE: Cache API now uses async/await instead of callbacks

Breaking Changes:

Add ! after type: feat!: or fix!:
Include BREAKING CHANGE: in footer
Clearly describe the breaking change

Triggering a Release

Merge PR to main

# After PR approval
git checkout main
git pull origin main

CI/CD automatically
- Runs all tests
- Checks code quality
- Analyzes commits
- Publishes if needed
Monitor Release
- Check GitHub Actions
- Verify npm publish succeeded
- Review generated CHANGELOG

Configuration Files

.releaserc.json - semantic-release configuration
package.json - Version and metadata
.github/workflows/release.yml - CI/CD workflow

Manual Release Steps

Use manual release only when automation fails or for special releases.

Prerequisites

Permissions
- Maintainer access to repository
- npm publish rights for @ooples scope
- GitHub release creation access

Environment Setup

# Verify npm authentication
npm whoami

# Ensure clean working directory
git status

# On main branch, up to date
git checkout main
git pull origin main

Manual Release Procedure

Version Bump

# Patch release (0.0.x)
npm version patch -m "chore(release): %s"

# Minor release (0.x.0)
npm version minor -m "chore(release): %s"

# Major release (x.0.0)
npm version major -m "chore(release): %s"

Update CHANGELOG

# Manually edit CHANGELOG.md
# Add version, date, and changes
# Follow Keep a Changelog format

Build Package

# Clean build
npm run clean
npm run build

# Run all tests
npm test

# Check package contents
npm pack --dry-run

Publish to npm

# Publish to npm
npm publish --access public

# Verify publication
npm view token-optimizer-mcp

Push Git Tags

# Push version commit and tag
git push origin main --follow-tags

Create GitHub Release

# Using GitHub CLI
gh release create v0.2.0 \
  --title "v0.2.0" \
  --notes-file CHANGELOG.md

# Or manually via GitHub web interface

Emergency Hotfix Release

For critical bug fixes:

Create Hotfix Branch

git checkout -b hotfix/critical-bug main

Make Fix

# Fix the bug
# Add tests
# Commit with fix: prefix
git commit -m "fix: critical security vulnerability"

Version Bump
```
npm version patch
```
Publish
```
npm run build
npm test
npm publish
```

Merge Back

git checkout main
git merge hotfix/critical-bug
git push origin main

Registry Publishing

After npm publication, update MCP registries.

Official MCP Registry

Create Registry Entry
- Navigate to MCP Registry
- Fork the repository
- Add entry in registry/servers.json

Registry Format

{
  "name": "token-optimizer-mcp",
  "version": "0.2.0",
  "repository": "https://github.com/ooples/token-optimizer-mcp",
  "npm": "token-optimizer-mcp",
  "description": "Intelligent token optimization achieving 95%+ reduction",
  "categories": ["optimization", "caching", "compression"]
}

Submit PR
- Create PR to MCP registry
- Wait for review and merge

Smithery

Login to Smithery
- Visit Smithery
- Sign in with GitHub
Submit Server
- Click "Add Server"
- Fill form with package details
- Upload screenshots/demo
- Submit for review

MCP Hub (Community)

Create Listing
- Visit MCP Hub
- Submit new server listing
- Include installation guide
Update Documentation
- Link to GitHub repo
- Add usage examples
- Include configuration snippets

Docker Hub (Optional)

If Docker images are published:

# Build image
docker build -t ooples/token-optimizer-mcp:0.2.0 .
docker build -t ooples/token-optimizer-mcp:latest .

# Push to Docker Hub
docker push ooples/token-optimizer-mcp:0.2.0
docker push ooples/token-optimizer-mcp:latest

Post-Release Checklist

After publishing a release:

Verification

npm package available

npm view token-optimizer-mcp
npm install -g token-optimizer-mcp

Test installation

npx token-optimizer-mcp --version
# Test basic functionality

GitHub release created
- Check Releases page
- Verify release notes
- Check attached assets
CHANGELOG updated
- Review CHANGELOG.md
- Ensure all changes listed
- Verify formatting

Registry Updates

MCP Registry
- PR submitted or merged
- Server listed on official registry
Smithery
- Server approved
- Listing visible
Documentation Updated
- README.md reflects new version
- Migration guide (if breaking changes)
- API documentation current

Communication

Announce Release
- GitHub Discussions (if used)
- Social media (optional)
- Relevant communities
Update Examples
- README examples work with new version
- Code snippets updated
- Configuration examples current

Monitoring

Check npm downloads
- Monitor download stats
- Watch for error reports
Monitor Issues
- Watch for bug reports
- Respond to questions
- Track feedback

Rollback Procedures

If a release has critical issues:

npm Deprecation

# Deprecate specific version
npm deprecate token-optimizer-mcp@0.2.0 "Critical bug - use 0.1.9 instead"

# Deprecate and redirect
npm deprecate token-optimizer-mcp@0.2.0 "Please upgrade to 0.2.1"

Publish Patch Release

# Fix the issue
git checkout -b fix/critical-issue

# Make changes, test
npm version patch
npm publish

# Announce fix
gh release create v0.2.1 --notes "Hotfix for critical issue in 0.2.0"

Unpublish (Last Resort)

Warning: Only use within 72 hours of publish, and only for severe security issues.

# Unpublish specific version (avoid if possible)
npm unpublish token-optimizer-mcp@0.2.0

# Note: This breaks existing installations

Communication Template

## Critical Issue in v0.2.0

We've identified a critical issue in version 0.2.0 that affects [describe impact].

**Action Required:**
- If using v0.2.0, upgrade to v0.2.1 immediately
- Run: `npm install token-optimizer-mcp@latest`

**Details:**
[Explain the issue and fix]

**Timeline:**
- v0.2.0 released: [date]
- Issue discovered: [date]
- v0.2.1 hotfix released: [date]

We apologize for any inconvenience.

Versioning Strategy

We follow Semantic Versioning 2.0.0:

Major (x.0.0): Breaking changes, API redesigns
Minor (0.x.0): New features, backward compatible
Patch (0.0.x): Bug fixes, backward compatible

Pre-releases

For testing before stable release:

# Alpha release
npm version prerelease --preid=alpha
# Results in: 0.2.0-alpha.0

# Beta release
npm version prerelease --preid=beta
# Results in: 0.2.0-beta.0

# Publish with tag
npm publish --tag beta

Version Lifecycle

Alpha: Internal testing, unstable
Beta: Public testing, feature complete
RC (Release Candidate): Final testing before stable
Stable: Production-ready release

Additional Resources

Support

For release-related questions:

Open an issue: GitHub Issues
Contact maintainers: See CONTRIBUTING.md