mcp-adr-analysis-server

# NPM Publishing Guide This document explains how to publish the MCP ADR Analysis Server to npmjs.com using the automated GitHub Actions workflow. ## 🚀 Quick Start ### Automatic Publishing (Recommended) 1. **Create a version tag:** ```bash git tag v1.0.1 git push origin v1.0.1 ``` 2. **The GitHub Actions workflow will automatically:** - Run all tests and linting - Build the project - Test MCP server functionality - Publish to npmjs.com - Create a GitHub release ### Manual Publishing 1. **Test the package locally:** ```bash npm run test:package ``` 2. **Publish manually:** ```bash npm publish ``` ## 📋 Prerequisites ### NPM Token Setup 1. **Create an NPM account** at https://www.npmjs.com/ 2. **Generate an access token:** - Go to https://www.npmjs.com/settings/tokens - Click "Generate New Token" - Choose "Automation" type - Copy the token 3. **Add token to GitHub Secrets:** - Go to your repository settings - Navigate to "Secrets and variables" → "Actions" - Add a new secret named `NPM_TOKEN` - Paste your NPM token as the value ## 🔧 Publishing Workflow Features ### Automated Quality Checks - ✅ ESLint code quality validation - ✅ Jest test suite execution - ✅ TypeScript compilation verification - ✅ MCP server functionality testing - ✅ Package structure validation ### Version Management - **Tag-based publishing**: Push a version tag to trigger publishing - **Manual versioning**: Use workflow dispatch with version input - **Automatic version updates**: Updates package.json version ### Package Optimization - **Selective file inclusion**: Only includes necessary files - **Size optimization**: ~173 KB optimized package - **Binary setup**: Includes CLI binary for global installation ## 📦 Package Information ### Installation ```bash # Global installation npm install -g mcp-adr-analysis-server # Local installation npm install mcp-adr-analysis-server ``` ### Usage ```bash # Run as CLI tool mcp-adr-analysis-server # Or use as Node.js module node node_modules/mcp-adr-analysis-server/dist/src/index.js ``` ### Package Contents - **Main entry**: `dist/src/index.js` - **Binary**: `mcp-adr-analysis-server` command - **Documentation**: README.md and ../../LICENSE - **Type definitions**: Full TypeScript support ## 🔄 Version Management ### Semantic Versioning - **Patch** (1.0.1): Bug fixes and minor updates - **Minor** (1.1.0): New features, backward compatible - **Major** (2.0.0): Breaking changes ### Publishing Commands ```bash # Patch version (1.0.0 → 1.0.1) git tag v1.0.1 && git push origin v1.0.1 # Minor version (1.0.0 → 1.1.0) git tag v1.1.0 && git push origin v1.1.0 # Major version (1.0.0 → 2.0.0) git tag v2.0.0 && git push origin v2.0.0 ``` ### Manual Workflow Dispatch You can also trigger publishing manually: 1. Go to GitHub Actions tab 2. Select "Publish to NPM" workflow 3. Click "Run workflow" 4. Choose version type (patch/minor/major/prerelease) ## 🛡️ Security & Best Practices ### Token Security - ✅ NPM token stored as GitHub secret - ✅ Token only accessible to authorized workflows - ✅ Automatic token rotation recommended ### Quality Gates - ✅ All tests must pass before publishing - ✅ Linting must pass before publishing - ✅ Build must succeed before publishing - ✅ MCP server functionality verified ### Package Integrity - ✅ Package contents verified before publishing - ✅ Main entry point validated - ✅ Binary accessibility confirmed - ✅ Size optimization applied ## 📊 Monitoring & Maintenance ### NPM Package Stats - **Package page**: https://www.npmjs.com/package/mcp-adr-analysis-server - **Download stats**: Available on NPM package page - **Version history**: Tracked in NPM registry ### GitHub Releases - **Automatic releases**: Created for each published version - **Release notes**: Generated with feature highlights - **Asset downloads**: Package tarballs available ## 🔧 Troubleshooting ### Common Issues 1. **NPM Token Invalid** - Regenerate token on npmjs.com - Update GitHub secret 2. **Tests Failing** - Check test output in GitHub Actions - Fix issues locally and push 3. **Package Size Too Large** - Review .npmignore file - Remove unnecessary files 4. **Binary Not Working** - Verify package.json bin configuration - Test locally with `npm run test:package` ### Support For issues with the publishing process, check: - GitHub Actions logs - NPM package page - Repository issues section