Supabase Coolify MCP Server

# NPM Publishing Guide Complete guide for publishing the Supabase Coolify MCP Server to NPM. ## 📋 Pre-Publishing Checklist ### ✅ Code Quality - [x] All features implemented - [x] Zero linter errors - [x] TypeScript type checking passes - [x] Input validation on all tools - [x] Health checks implemented - [x] Comprehensive error handling ### ✅ Documentation - [x] README.md complete - [x] QUICKSTART.md for easy setup - [x] CHANGELOG.md with version history - [x] docs/ folder with guides - [x] env.example with all variables - [x] LICENSE file (MIT) ### ✅ Package Configuration - [x] package.json properly configured - [x] Version set (1.2.0) - [x] Keywords added for discoverability - [x] Files field specifies what to include - [x] .npmignore excludes unnecessary files - [x] prepublishOnly script for safety ### ✅ Build & Test - [ ] Run full build - [ ] Test in clean environment - [ ] Verify dist/ contains all needed files - [ ] Test executable works ## 🚀 Publishing Steps ### Step 1: Update Repository URLs In `package.json`, update these fields with your actual GitHub repository: ```json { "repository": { "type": "git", "url": "https://github.com/YOUR_USERNAME/supabase-coolify-mcp-server.git" }, "bugs": { "url": "https://github.com/YOUR_USERNAME/supabase-coolify-mcp-server/issues" }, "homepage": "https://github.com/YOUR_USERNAME/supabase-coolify-mcp-server#readme" } ``` ### Step 2: Set Author Information Update the `author` field in `package.json`: ```json { "author": "Your Name <your.email@example.com>" } ``` Or more detailed: ```json { "author": { "name": "Your Name", "email": "your.email@example.com", "url": "https://yourwebsite.com" } } ``` ### Step 3: Clean Build ```bash # Remove any existing build artifacts Remove-Item -Recurse -Force dist -ErrorAction SilentlyContinue # Install dependencies fresh Remove-Item -Recurse -Force node_modules -ErrorAction SilentlyContinue npm install # Run checks npm run typecheck npm run lint # Build npm run build ``` ### Step 4: Test Locally Test the package works correctly: ```bash # Test the built version node dist/index.js # Or test as if installed globally npm link supabase-coolify-mcp --help npm unlink ``` ### Step 5: Verify Package Contents See what will be published: ```bash npm pack --dry-run ``` This shows all files that will be included in the package. ### Step 6: Test Installation Create a test directory and install from local: ```bash mkdir test-install cd test-install npm init -y npm install ../path/to/supabase-coolify-mcp-server ``` Test that it works: ```bash npx supabase-coolify-mcp ``` Clean up: ```bash cd .. Remove-Item -Recurse -Force test-install ``` ### Step 7: Login to NPM ```bash npm login ``` You'll need: - NPM username - Password - Email - 2FA code (if enabled) ### Step 8: Publish First publish (or if you've never published this package): ```bash # For first publish npm publish # For scoped packages (if using @yourusername/package-name) npm publish --access public ``` For subsequent versions: ```bash # Patch version (1.2.0 -> 1.2.1) npm version patch npm publish # Minor version (1.2.0 -> 1.3.0) npm version minor npm publish # Major version (1.2.0 -> 2.0.0) npm version major npm publish ``` ### Step 9: Verify Publication Check your package on NPM: ```bash # Open in browser start https://www.npmjs.com/package/supabase-coolify-mcp-server # Or install globally to test npm install -g supabase-coolify-mcp-server supabase-coolify-mcp --version ``` ### Step 10: Update GitHub ```bash # Tag the release git tag v1.2.0 git push origin v1.2.0 # Create GitHub release with changelog # Go to GitHub > Releases > Create new release ``` ## 📦 What Gets Published Based on the `files` field in package.json: ``` ✅ dist/ - Built JavaScript files ✅ docs/ - Documentation guides ✅ README.md - Main documentation ✅ QUICKSTART.md - Quick start guide ✅ CHANGELOG.md - Version history ✅ LICENSE - MIT license ✅ env.example - Configuration template ✅ package.json - Package metadata ``` **NOT included** (via .npmignore): ``` ❌ src/ - TypeScript source ❌ .archive/ - Internal files ❌ examples/ - Examples (on GitHub) ❌ ARCHITECTURE.md - Internal docs ❌ DEPLOYMENT_GUIDE.md - On GitHub ❌ CONTRIBUTING.md - On GitHub ❌ .env files - Environment configs ``` ## 🔄 Version Management ### Semantic Versioning Follow [semver](https://semver.org/): - **MAJOR** (1.0.0 → 2.0.0): Breaking changes - API changes that break existing usage - Removed features - Changed behavior that users depend on - **MINOR** (1.2.0 → 1.3.0): New features (backward compatible) - New tools added - New features that don't break existing code - Deprecations (with warnings) - **PATCH** (1.2.0 → 1.2.1): Bug fixes - Bug fixes - Documentation updates - Performance improvements - Security patches ### Our Version History - **1.0.0** - Initial release - **1.1.0** - Added CLI integration and rollback - **1.2.0** - Added validation, health checks, verification - **1.2.1** - Bug fixes (if needed) - **1.3.0** - Next minor features ## 🛡️ Security Considerations ### Before Publishing 1. **Review code for secrets** ```bash # Search for potential secrets git grep -i "password\|secret\|key\|token" src/ ``` 2. **Check .gitignore** - Ensure .env is ignored - No sensitive files tracked 3. **Review dependencies** ```bash npm audit ``` 4. **Test with minimal permissions** - Don't test with production credentials - Use test/development instances ### After Publishing 1. **Monitor for vulnerabilities** ```bash npm audit ``` 2. **Set up GitHub security alerts** - Enable Dependabot - Enable security advisories 3. **Document security policy** - How to report vulnerabilities - Response timeline ## 📊 Package Statistics Current package size (estimated): ``` dist/ ~100 KB (built JavaScript) docs/ ~50 KB (documentation) README.md ~20 KB Other files ~10 KB ----------------------------------- Total package ~180 KB ``` ## 🎯 Post-Publishing Tasks ### Update Documentation 1. Update README with NPM installation instructions 2. Update QUICKSTART with NPM usage 3. Create release notes on GitHub ### Announce 1. Tweet/post about the release 2. Share in relevant communities: - Supabase Discord - Coolify Discord - MCP community channels 3. Create example projects/tutorials ### Monitor 1. Watch for issues on GitHub 2. Monitor NPM downloads 3. Respond to questions/feedback ## 🔍 Troubleshooting ### "Package name already taken" ```bash # Use a scoped package # Change name in package.json to: "name": "@yourusername/supabase-coolify-mcp-server" # Publish with public access npm publish --access public ``` ### "Need to authenticate" ```bash npm login # Or if that fails: npm adduser ``` ### "No permission to publish" - Check you're logged in: `npm whoami` - Verify package name isn't taken: `npm view supabase-coolify-mcp-server` - For scoped packages, use `--access public` ### "Files not included in package" ```bash # Check what will be published npm pack --dry-run # Verify files field in package.json # Check .npmignore doesn't exclude needed files ``` ### "Build fails on publish" ```bash # The prepublishOnly script runs checks # Fix any errors it reports: npm run typecheck # Fix TypeScript errors npm run lint # Fix linting errors npm run build # Ensure build succeeds ``` ## 📝 Checklist Summary Before running `npm publish`: - [ ] Update repository URLs in package.json - [ ] Set author information - [ ] Clean build (`rm -rf dist && npm run build`) - [ ] Run all checks (`npm run typecheck && npm run lint`) - [ ] Test locally (`node dist/index.js`) - [ ] Verify package contents (`npm pack --dry-run`) - [ ] Test installation in clean directory - [ ] Login to NPM (`npm login`) - [ ] Review CHANGELOG.md - [ ] Commit all changes - [ ] Create git tag - [ ] Ready to publish! (`npm publish`) ## 🎉 Success! After successful publish: ```bash # Install your package npm install -g supabase-coolify-mcp-server # Use it supabase-coolify-mcp # View on NPM start https://www.npmjs.com/package/supabase-coolify-mcp-server ``` --- **Current Version:** 1.2.0 **Ready to Publish:** ✅ **Package Quality:** Enterprise Grade 🌟