Skip to content

PUBLISHING.md

Latest commit

 

History

History
253 lines (190 loc) · 5.26 KB

PUBLISHING.md

File metadata and controls

253 lines (190 loc) · 5.26 KB

Publishing Guide for PostgreSQL MCP Server

🚀 Publishing to npm

Prerequisites

  1. npm account: Create an account at npmjs.com
  2. Update package.json: Replace placeholders with your actual information: 
    {
  "name": "@your-username/postgres-mcp-server",
  "author": {
    "name": "Your Name",
    "email": "your.email@example.com",
    "url": "https://github.com/your-username"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/your-username/postgres-mcp-server.git"
  }
}

Step-by-Step Publishing

  1. Login to npm:

    npm login

  2. Build the project:

    npm run build

  3. Test the package locally (optional):

    npm pack
# This creates a .tgz file you can test with: npm install ./package.tgz

  4. Publish to npm:

    npm publish --access public

    Note: Use --access public for scoped packages (@your-username/package-name)

Alternative: Unscoped Publishing

If you prefer an unscoped package name (easier for users), change the package name to:

{
  "name": "postgres-mcp-server-cli",  // or another unique name
}

Then publish with:

npm publish

📦 Usage After Publishing

Global Installation

Users can install globally and run from anywhere:

# Install globally
npm install -g @your-username/postgres-mcp-server

# Run from anywhere
postgres-mcp --connection-string "postgresql://user:pass@localhost:5432/db"

Using with npx (No Installation)

Users can run directly without installing:

npx @your-username/postgres-mcp-server --connection-string "postgresql://user:pass@localhost:5432/db"

MCP Client Configuration

After publishing, users can configure their MCP clients:

{
  "mcpServers": {
    "postgresql-mcp": {
      "command": "npx",
      "args": [
        "@your-username/postgres-mcp-server",
        "--connection-string", "postgresql://user:password@host:port/database"
      ]
    }
  }
}

Or with global installation:

{
  "mcpServers": {
    "postgresql-mcp": {
      "command": "postgres-mcp",
      "args": [
        "--connection-string", "postgresql://user:password@host:port/database"
      ]
    }
  }
}

🔄 Updating the Package

Version Management

Update version in package.json and publish:

# Patch version (1.0.0 -> 1.0.1)
npm version patch

# Minor version (1.0.0 -> 1.1.0)
npm version minor

# Major version (1.0.0 -> 2.0.0)
npm version major

# Then publish
npm publish

Automated Publishing with GitHub Actions

Create .github/workflows/publish.yml:

name: Publish to npm

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'
      
      - run: npm ci
      - run: npm run build
      - run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

🧪 Testing the Package

Local Testing

Test the built package locally:

# Build
npm run build

# Test CLI directly
node build/index.js --help

# Test with sample connection (use your actual DB)
node build/index.js --connection-string "postgresql://localhost/test"

Test with MCP Client

  1. Install locally in test project:

    npm pack
npm install -g ./postgres-mcp-server-1.0.0.tgz

  2. Configure MCP client and test tools

  3. Uninstall test version:

    npm uninstall -g @your-username/postgres-mcp-server

📋 Checklist Before Publishing

  • Update package.json with your details
  • Ensure all placeholder names are replaced
  • Build succeeds without errors: npm run build
  • CLI works: node build/index.js --help
  • All dependencies are correct
  • README.md is updated
  • License is appropriate
  • Version number is correct

🚨 Security Considerations

  1. Never commit connection strings to git
  2. Review dependencies for security vulnerabilities: 
    npm audit
npm audit fix
  3. Use environment variables for sensitive data
  4. Consider scoped packages for namespace control

📈 Post-Publication

Monitor Usage

  • Check npm statistics: npm view @your-username/postgres-mcp-server
  • Monitor downloads and issues
  • Update documentation based on user feedback

Maintenance

  • Keep dependencies updated
  • Respond to GitHub issues
  • Follow semantic versioning for updates
  • Consider setting up automated security updates

🔗 Useful Commands

# Check what will be published
npm pack --dry-run

# View published package info
npm view @your-username/postgres-mcp-server

# Check package size
npm pack && du -h *.tgz

# Test installation
npm install -g @your-username/postgres-mcp-server

# Uninstall
npm uninstall -g @your-username/postgres-mcp-server

Happy publishing! 🎉