npm-deploy
Publish the @magnet-ai/magnet-mcp-server package to NPM with version bumping and git tagging. Use when user says "publish to npm", "npm publish", "deploy to npm", "release to npm", "publish package", "bump version and publish", or "release new version".
When & Why to Use This Skill
This Claude skill automates the end-to-end NPM deployment workflow for the @magnet-ai/magnet-mcp-server package. It streamlines version management, git tagging, and package publishing while ensuring code quality through automated build verification, environment checks, and git synchronization.
Use Cases
- Automating routine patch releases to NPM after bug fixes with synchronized git tagging and version bumping.
- Managing minor or major version upgrades for new feature releases while maintaining a clean and consistent git history.
- Ensuring deployment safety by automatically verifying git status, branch synchronization, and build success before pushing to the NPM registry.
- Recovering from interrupted or failed deployment processes by auditing the current state of the NPM registry and local repository to resume the release safely.
| name | npm-deploy |
|---|---|
| description | Publish the @magnet-ai/magnet-mcp-server package to NPM with version bumping and git tagging. Use when user says "publish to npm", "npm publish", "deploy to npm", "release to npm", "publish package", "bump version and publish", or "release new version". |
NPM Deployment Skill
This skill guides users through correctly publishing the @magnet-ai/magnet-mcp-server package to NPM, including version management and git operations.
When to Use This Skill
Use this skill when the user requests:
- Publishing the package to NPM
- Releasing a new version
- Bumping the version and deploying
- Creating a new NPM release
Instructions
Step 1: Verify Git Status
Check that the working directory is clean and on the correct branch:
git status
git branch --show-current
Requirements:
- Working directory must be clean (no uncommitted changes)
- Should typically be on
mainbranch for releases
If there are uncommitted changes, inform the user and ask them to commit or stash changes first.
Step 2: Sync with Remote
Ensure local branch is up to date:
git fetch origin
git status
If behind remote, pull the latest changes:
git pull origin main
Step 3: Install Dependencies
Ensure dependencies are current:
pnpm install
Step 4: Run Build and Validation
Build the TypeScript project and verify:
pnpm build
Run type checking:
pnpm tsc --noEmit
Verify the build output exists:
ls -la dist/index.js
If the build fails, stop and inform the user about the errors.
Step 5: Check Current Version
Read the current version from package.json:
node -p "require('./package.json').version"
Display the current version to the user.
Step 6: Select Version Bump Type
Use AskUserQuestion to determine the version bump type:
Question: "What type of version bump is this release?" Options:
- "Patch (x.x.X)" - Bug fixes, documentation updates
- "Minor (x.X.0)" - New features, backwards compatible changes
- "Major (X.0.0)" - Breaking changes
Calculate the new version based on current version and selected bump type.
Step 7: Update package.json Version
Update the version in package.json:
npm version <patch|minor|major> --no-git-tag-version
Note: We use --no-git-tag-version because we'll handle git operations ourselves for more control.
Verify the new version:
node -p "require('./package.json').version"
Step 8: Verify NPM Authentication
Check that the user is logged into NPM:
npm whoami
If not logged in, inform the user:
- "You need to log in to NPM first. Run
npm loginand authenticate." - They should be logged into an account with publish access to
@magnet-aiscope
Step 9: Confirm Before Publishing
Use AskUserQuestion for final confirmation:
Question: "Ready to publish version {new_version} to NPM?" Options:
- "Yes, publish now" - Proceed with publishing
- "No, abort" - Cancel the release
Step 10: Publish to NPM
Publish the package:
pnpm publish --access public
The prepublishOnly script will automatically run pnpm build before publishing.
Verify the publish succeeded by checking the npm registry:
npm view @magnet-ai/magnet-mcp-server version
Step 11: Commit Version Bump
Commit the version change to git:
git add package.json
git commit -m "v{version}"
Step 12: Create Git Tag
Create a git tag for the release:
git tag v{version}
Step 13: Push to Remote
Push the commit and tag to the remote repository:
git push origin main
git push origin v{version}
Step 14: Display Success Summary
Inform the user of the successful release:
- New version:
{version} - NPM package URL: https://www.npmjs.com/package/@magnet-ai/magnet-mcp-server
- Git tag:
v{version} - Commit pushed to:
main
Error Handling
Dirty Git Working Directory
If git status shows uncommitted changes:
- Inform the user they have uncommitted changes
- Suggest:
git stashto temporarily save changes, orgit committo commit them - Do not proceed until working directory is clean
Build Failures
If pnpm build fails:
- Display the error output
- Common issues:
- TypeScript errors in source files
- Missing dependencies (run
pnpm install)
- Do not proceed until build succeeds
NPM Not Logged In
If npm whoami fails:
- Inform user they need to authenticate
- Run
npm login - Ensure they use an account with
@magnet-aiscope access - Verify with
npm whoamibefore proceeding
Publish Fails - 403 Forbidden
If publish returns 403:
- User may not have publish permissions for
@magnet-aiscope - Check:
npm access ls-collaborators @magnet-ai/magnet-mcp-server - Contact a maintainer (nico-pal, zachcaceres, juliankrispel) for access
Tag Already Exists
If git tag fails because tag exists:
- Verify the tag:
git tag -l v{version} - If it exists from a failed previous attempt, delete it:
- Local:
git tag -d v{version} - Remote (if pushed):
git push origin :refs/tags/v{version}
- Local:
- Re-run the tag creation
Push Rejected
If git push is rejected:
- Someone may have pushed to main since you started
- Run
git pull --rebase origin main - Resolve any conflicts
- Re-push
Examples
Example 1: Standard Patch Release
User: "Publish the latest bug fixes to npm"
Actions:
- Verify git status is clean and on main
- Pull latest changes
- Run
pnpm buildand type check - Show current version (e.g., 0.2.7)
- Ask for version type → User selects "Patch"
- Bump to 0.2.8
- Verify npm login
- Confirm publishing
- Run
pnpm publish --access public - Commit: "v0.2.8"
- Tag: v0.2.8
- Push commit and tag
- Display success with NPM URL
Example 2: Minor Release with New Features
User: "We added new tools, let's release a new version"
Actions:
- Verify git status and sync with remote
- Build and validate
- Show current version (e.g., 0.2.8)
- Ask for version type → User selects "Minor"
- Bump to 0.3.0
- Verify npm login
- Confirm publishing
- Publish to npm
- Commit, tag, push
- Display success
Example 3: Recovering from Failed Publish
User: "The last publish failed halfway, can you help?"
Actions:
- Check git status for any partial changes
- Check if version was bumped:
node -p "require('./package.json').version" - Check if tag exists:
git tag -l v{version} - Check npm registry:
npm view @magnet-ai/magnet-mcp-server version - Based on state:
- If npm has the version but git doesn't: just commit, tag, and push
- If git has changes but npm doesn't: publish first, then commit/tag/push
- If nothing was done: start fresh
Notes
- Always verify build before publishing - the
prepublishOnlyscript runs build automatically, but checking first catches errors early - Scoped package -
@magnet-ai/magnet-mcp-serverrequires--access publicfor public visibility - Version format - Uses semantic versioning (MAJOR.MINOR.PATCH)
- Git tags - Always prefixed with
v(e.g.,v0.2.8) - Maintainers - Current npm maintainers: nico-pal, zachcaceres, juliankrispel
- No automated CI/CD - Publishing is manual via this skill