# Publishing to npm
Maintainer guide for publishing new versions of `remnote-mcp-server` to npm.
## Automated Publishing (Recommended)
The `npm-publish.sh` script automates the complete publishing workflow with proper error checking:
```bash
./npm-publish.sh
```
**What it does:**
1. Pre-flight checks (git clean, npm auth, package.json exists)
2. Runs full code quality suite (`./code-quality.sh`)
3. Verifies package contents (`npm pack --dry-run`)
4. Runs publish dry-run for review
5. Prompts for confirmation before actual publish
6. Publishes to npm
7. Verifies publication succeeded
8. Creates and pushes git tag (`vX.Y.Z`)
9. Displays next steps (GitHub release, CHANGELOG update)
**Note:** The script assumes version has already been bumped in `package.json` and `CHANGELOG.md` has been updated. See
"Pre-Publication Checklist" below.
## Manual Publishing
The following manual workflow is documented for reference and advanced use cases. For standard releases, use
`./npm-publish.sh` instead.
## Prerequisites
- npm account with publish permissions for `remnote-mcp-server`
- Authenticated via `npm login`
- Clean working directory (all changes committed)
## Pre-Publication Checklist
1. **Update version in package.json**
```bash
npm version [major|minor|patch]
```
- `major` - Breaking changes (e.g., 1.0.0 → 2.0.0)
- `minor` - New features, backwards compatible (e.g., 0.1.0 → 0.2.0)
- `patch` - Bug fixes, backwards compatible (e.g., 0.1.0 → 0.1.1)
2. **Document changes in CHANGELOG.md**
- Move items from `[Unreleased]` to new version section
- Add release date: `## [0.1.0] - 2026-02-07`
- Ensure changes are categorized (Added, Changed, Fixed, etc.)
3. **Verify package contents**
```bash
npm pack --dry-run
```
- Check included files list
- Verify `dist/` is built (runs automatically via `prepublishOnly`)
- Ensure no sensitive files are included
4. **Run type checks**
```bash
npm run typecheck
```
5. **Manual verification**
- Start server: `npm start`
- Verify WebSocket port listening: `lsof -i :3002`
- Test MCP tools in Claude Code CLI (e.g., `remnote_status`)
## Publishing Workflow
1. **Dry run**
```bash
npm publish --dry-run
```
- Review output for any warnings
- Verify package size is reasonable
2. **Publish**
```bash
npm publish
```
- For pre-release versions: `npm publish --tag beta`
3. **Verify publication**
```bash
npm view remnote-mcp-server
```
- Check version, description, repository links
- Visit: https://www.npmjs.com/package/remnote-mcp-server
## Post-Publication
1. **Create git tag**
```bash
git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0
```
2. **Create GitHub release**
- Navigate to repository releases page
- Create release from tag
- Copy CHANGELOG.md section for release notes
3. **Update CHANGELOG.md**
- Add new `[Unreleased]` section at top
- Commit and push
## Common Issues
**Port 3002 already in use during testing:**
```bash
lsof -i :3002
kill -9 <PID>
```
**Build fails during prepublishOnly:**
- Check TypeScript errors: `npm run typecheck`
- Ensure all dependencies installed: `npm install`
**Package version already exists:**
- Increment version: `npm version patch`
- Republish
## Version Guidelines
Follow [Semantic Versioning](https://semver.org/):
- **0.x.y** - Initial development (API may change)
- **1.0.0** - First stable release (public API contract)
- **Major (x.0.0)** - Breaking changes to public API
- **Minor (0.x.0)** - New features, backwards compatible
- **Patch (0.0.x)** - Bug fixes, backwards compatible
