multi-database-mcp/DEPLOYMENT.md

A comprehensive multi-database MCP server that provides unified access to multiple databases through a single interface

# Deployment Guide

This guide explains how to deploy, publish, and maintain the Multi-Database MCP Server as an npm package.

## 📦 Prerequisites

Before deploying, ensure you have:

- **Node.js** 18.0.0 or higher
- **npm account** with publishing permissions
- **Git repository** with proper remote origin
- **All tests passing** locally

## 🚀 Initial Setup

### 1. Create npm Account

If you don't have an npm account:
```bash
npm adduser
```

### 2. Login to npm

```bash
npm login
```

### 3. Verify Package Configuration

Check your `package.json` has all required fields:
```json
{
  "name": "multi-database-mcp",
  "version": "1.0.0",
  "description": "A comprehensive multi-database MCP server...",
  "main": "server.js",
  "bin": {
    "multi-database-mcp": "server.js"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/shivanandham/multi-database-mcp.git"
  },
  "files": [
    "server.js",
    "databases.json",
    "databases.example.json",
    "test.js",
    "cursor-mcp-config-example.json",
    "README.md"
  ]
}
```

## 📋 Pre-Deployment Checklist

Before publishing, run through this checklist:

- [ ] **Version number updated** in `package.json`
- [ ] **README.md updated** with latest features
- [ ] **All tests passing** (`npm test`)
- [ ] **Package builds successfully** (`npm pack`)
- [ ] **No sensitive data** in published files
- [ ] **Git repository clean** (commit all changes)
- [ ] **Git tag created** for the version

## 🔄 Publishing Process

### 1. Update Version

```bash
# For patch updates (bug fixes)
npm version patch

# For minor updates (new features)
npm version minor

# For major updates (breaking changes)
npm version major
```

This automatically:
- Updates `package.json` version
- Creates a git commit
- Creates a git tag

### 2. Test Package Locally

```bash
# Create a tarball to test
npm pack

# Test the package structure
tar -tzf multi-database-mcp-*.tgz
```

### 3. Publish to npm

```bash
# Publish to npm registry
npm publish

# For first-time publishing (public package)
npm publish --access public
```

### 4. Push to Git

```bash
# Push commits and tags
git push origin main
git push origin --tags
```

## 🧪 Testing the Published Package

After publishing, test that users can install it:

### 1. Test with npx

```bash
# Test the npx command (should download and run)
npx -y multi-database-mcp --help
```

### 2. Test MCP Configuration

Create a test `mcp.json`:
```json
{
  "mcpServers": {
    "multi-database": {
      "command": "npx",
      "args": ["-y", "multi-database-mcp"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

### 3. Verify in Cursor

1. Add the configuration to `.cursor/mcp.json`
2. Restart Cursor
3. Verify the MCP server loads correctly

## 📊 Package Information

### Package Size
- **Compressed**: ~12.7 kB
- **Uncompressed**: ~49.0 kB
- **Files included**: 8 files

### Dependencies
- `@modelcontextprotocol/sdk`: ^1.20.0
- `pg`: ^8.16.3

### Node.js Compatibility
- **Minimum**: Node.js 18.0.0
- **Recommended**: Node.js 20.x or higher

## 🔄 Update Workflow

### For Bug Fixes (Patch Updates)

1. Fix the bug
2. Update tests if needed
3. Run `npm version patch`
4. Run `npm publish`
5. Push to git: `git push origin main --tags`

### For New Features (Minor Updates)

1. Implement the feature
2. Update documentation
3. Add tests
4. Run `npm version minor`
5. Run `npm publish`
6. Push to git: `git push origin main --tags`

### For Breaking Changes (Major Updates)

1. Implement breaking changes
2. Update documentation
3. Update migration guide
4. Run `npm version major`
5. Run `npm publish`
6. Push to git: `git push origin main --tags`

## 🛠️ Maintenance Tasks

### Regular Maintenance

- **Monthly**: Check for dependency updates
- **Quarterly**: Review and update documentation
- **As needed**: Address security vulnerabilities

### Dependency Updates

```bash
# Check for outdated packages
npm outdated

# Update dependencies
npm update

# Update specific package
npm install package-name@latest
```

### Security Audits

```bash
# Run security audit
npm audit

# Fix vulnerabilities
npm audit fix

# Fix with breaking changes
npm audit fix --force
```

## 📈 Monitoring

### npm Package Stats

Monitor your package on:
- [npmjs.com](https://www.npmjs.com/package/multi-database-mcp)
- [npm-stat.com](https://npm-stat.com/charts.html?package=multi-database-mcp)

### Key Metrics to Track

- **Downloads per day/week/month**
- **Version adoption rate**
- **GitHub stars and forks**
- **Issue reports and bug reports**

## 🚨 Troubleshooting

### Common Issues

**"Package name already exists"**
- Check if the package name is available
- Consider using a scoped package: `@your-org/multi-database-mcp`

**"Authentication failed"**
- Run `npm login` again
- Check your npm credentials

**"Version already exists"**
- The version number is already published
- Use `npm version` to increment the version

**"Package too large"**
- Check the `files` array in `package.json`
- Remove unnecessary files from the package

### Rollback Process

If you need to rollback a version:

```bash
# Unpublish a version (within 24 hours)
npm unpublish multi-database-mcp@1.0.1

# Or deprecate a version
npm deprecate multi-database-mcp@1.0.1 "This version has critical bugs"
```

## 🔐 Security Considerations

### Before Publishing

- [ ] **No API keys** in the code
- [ ] **No passwords** in configuration examples
- [ ] **No sensitive URLs** in examples
- [ ] **Use environment variables** for sensitive data

### Package Security

- **Use exact versions** for critical dependencies
- **Regular security audits** with `npm audit`
- **Keep dependencies updated**
- **Use `npm ci`** in CI/CD pipelines

## 📝 Release Notes Template

When publishing updates, include release notes:

```markdown
## Version 1.1.0

### New Features
- Added support for MySQL databases
- Implemented connection pooling
- Added database health checks

### Bug Fixes
- Fixed memory leak in long-running connections
- Resolved issue with special characters in passwords

### Breaking Changes
- Changed default port from 5432 to 3306 for MySQL

### Migration Guide
- Update your database URLs to use the new format
- Run `npm update` to get the latest version
```

## 🎯 Best Practices

### Version Management
- **Semantic versioning** (semver)
- **Clear commit messages**
- **Automated testing** before publishing
- **Documentation updates** with each release

### Package Quality
- **Small package size**
- **Minimal dependencies**
- **Clear documentation**
- **Comprehensive tests**

### User Experience
- **Backward compatibility** when possible
- **Clear migration guides** for breaking changes
- **Responsive issue handling**
- **Regular updates** and bug fixes

## 📞 Support

For deployment issues:
- **GitHub Issues**: [Create an issue](https://github.com/shivanandham/multi-database-mcp/issues)
- **npm Support**: [npm support](https://npmjs.com/support)
- **Documentation**: Check this guide and README.md

---

**Happy Deploying! 🚀**