# Publishing Guide
This guide explains how to publish the Marble MCP Server to npm.
## Prerequisites
1. **Create an npm account**: If you don't have one, sign up at [npmjs.com](https://www.npmjs.com/signup)
2. **Login to npm**: Run this command and enter your credentials:
```bash
npm login
```
3. **Verify you're logged in**:
```bash
npm whoami
```
## Pre-publish Checklist
Before publishing, ensure:
- [ ] All tests pass (if applicable)
- [ ] Version number is updated in `package.json`
- [ ] README.md is up to date
- [ ] CHANGELOG.md is updated (if you have one)
- [ ] All code is committed to git
- [ ] You're on the correct branch (usually `main` or `master`)
## Publishing Steps
### 1. Update Version Number
Follow [semantic versioning](https://semver.org/):
```bash
# For bug fixes (1.0.0 -> 1.0.1)
npm version patch
# For new features (1.0.0 -> 1.1.0)
npm version minor
# For breaking changes (1.0.0 -> 2.0.0)
npm version major
```
This automatically updates `package.json` and creates a git tag.
### 2. Preview the Package
See what files will be published:
```bash
npm pack --dry-run
```
Or create an actual tarball to inspect:
```bash
npm pack
tar -xzf marble-mcp-server-1.0.0.tgz
ls -la package/
```
### 3. Publish to npm
For the first publish:
```bash
npm publish
```
For subsequent publishes with a specific version:
```bash
npm publish --access public
```
**Note**: If this is a scoped package (e.g., `@marble/mcp-server`), you may need `--access public` to make it publicly available.
### 4. Verify the Publish
1. Visit your package page: `https://www.npmjs.com/package/marble-mcp-server`
2. Test installing it:
```bash
npm install -g marble-mcp-server
marble-mcp-server --help
```
## Publishing a Beta/Pre-release
To publish a pre-release version:
```bash
# Update version to beta (e.g., 1.1.0-beta.0)
npm version prerelease --preid=beta
# Publish with beta tag
npm publish --tag beta
```
Users can install it with:
```bash
npm install -g marble-mcp-server@beta
```
## Updating the Package
When you need to publish an update:
1. Make your changes
2. Commit to git
3. Update version: `npm version patch/minor/major`
4. Publish: `npm publish`
5. Push to git: `git push && git push --tags`
## Package Ownership
To add collaborators to the npm package:
```bash
npm owner add <username> marble-mcp-server
```
To transfer ownership:
```bash
npm owner add <new-owner> marble-mcp-server
npm owner rm <old-owner> marble-mcp-server
```
## Unpublishing (Use with Caution!)
You can only unpublish within 72 hours of publishing:
```bash
npm unpublish marble-mcp-server@1.0.0
```
**Warning**: Unpublishing can break projects that depend on your package. Consider deprecating instead:
```bash
npm deprecate marble-mcp-server@1.0.0 "This version has been deprecated"
```
## Troubleshooting
### "You do not have permission to publish"
Make sure you're logged in to the correct npm account:
```bash
npm logout
npm login
```
### "Package name already exists"
The package name `marble-mcp-server` might be taken. Either:
1. Choose a different name (update in `package.json`)
2. Use a scoped package: `@yourorg/marble-mcp-server`
### Build fails before publish
The `prepublishOnly` script runs `npm run build` automatically. If it fails:
```bash
# Check TypeScript errors
npm run build
# Fix any errors, then try publishing again
```
## Best Practices
1. **Always test locally first** using `npm link`
2. **Use semantic versioning** consistently
3. **Keep a CHANGELOG** to document changes
4. **Tag releases in git** (done automatically by `npm version`)
5. **Test installation** after publishing
6. **Monitor issues** on npm and GitHub
## Resources
- [npm Publishing Guide](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry)
- [Semantic Versioning](https://semver.org/)
- [npm version command](https://docs.npmjs.com/cli/v10/commands/npm-version)
