PUBLISHING.md

Publishing to NPM

This document explains how to publish this package to NPM automatically when you create a GitHub release.

Setup (One-time)

1. Create an NPM Account

If you don't have one already:

1. Go to https://www.npmjs.com/signup
2. Create an account
3. Verify your email

2. Generate an NPM Access Token

1. Log in to https://www.npmjs.com
2. Click your profile picture → Access Tokens
3. Click "Generate New Token" → "Granular Access Token"
4. Configure the token:
   • Token name: bible-ko-mcp-github-actions
   • Expiration: 1 year (or your preference)
   • Packages and scopes:
     • Select "Read and write"
     • For "Packages", select "All packages" or specifically allow bible-ko-mcp
5. Click "Generate Token"
6. Copy the token immediately (you won't be able to see it again)

3. Add NPM Token to GitHub

1. Go to your GitHub repository: https://github.com/oksure/bible-ko-mcp
2. Click Settings → Secrets and variables → Actions
3. Click New repository secret
4. Name: NPM_TOKEN
5. Value: Paste the token you copied from NPM
6. Click Add secret

4. Verify Package Name is Available

Check if the package name is available on NPM:

npm view bible-ko-mcp

If you get "404 Not Found", the name is available. If not, you'll need to:

• Choose a different name in package.json
• Or use a scoped package: @oksure/bible-ko-mcp

Publishing a New Version

Method 1: Using GitHub Releases (Recommended)

This triggers automatic publishing via GitHub Actions.

1. Update version in package.json:

   npm version patch  # For bug fixes (0.1.0 → 0.1.1)
   npm version minor  # For new features (0.1.0 → 0.2.0)
   npm version major  # For breaking changes (0.1.0 → 1.0.0)

2. Push the version commit and tag:

   git push && git push --tags

3. Create a GitHub Release:

   • Go to https://github.com/oksure/bible-ko-mcp/releases
   • Click "Create a new release"
   • Choose the tag you just pushed (e.g., v0.1.1)
   • Title: v0.1.1 (match the tag)
   • Description: Write release notes (features, fixes, changes)
   • Click "Publish release"

4. Wait for GitHub Actions:

   • Go to the Actions tab: https://github.com/oksure/bible-ko-mcp/actions
   • Watch the "Publish to NPM" workflow run
   • If successful, your package is now live on NPM!

Method 2: Manual Publishing

If you prefer to publish manually:

# Make sure you're logged in to NPM
npm login

# Verify package.json version is updated
npm version patch  # or minor/major

# Run tests and build
npm test
npm run build

# Publish to NPM
npm publish --access public

Verifying Publication

After publishing, verify your package:

1. View on NPM:

   • https://www.npmjs.com/package/bible-ko-mcp

2. Test installation:

   npm install -g bible-ko-mcp
   bible-ko-mcp

3. Check version:

   npm view bible-ko-mcp version

Troubleshooting

"You must be logged in to publish packages"

• Your NPM_TOKEN might be invalid or expired
• Regenerate the token and update the GitHub secret

"Package name already taken"

• Change the name in package.json
• Or use a scoped package: @oksure/bible-ko-mcp

"Tests failed"

• Fix the failing tests before publishing
• The prepublishOnly script will prevent publishing if tests fail

"403 Forbidden"

• Your NPM token doesn't have write permissions
• Generate a new token with "Read and write" permissions

Version Guidelines

Follow Semantic Versioning:

• MAJOR version (1.0.0 → 2.0.0): Breaking changes

  • Changed API, removed features, incompatible changes

• MINOR version (0.1.0 → 0.2.0): New features

  • Added new tools, enhanced functionality
  • Backward compatible

• PATCH version (0.1.0 → 0.1.1): Bug fixes

  • Fixed bugs, improved parsing
  • No new features, backward compatible

Release Checklist

Before creating a release:

• All tests pass: npm test
• Build succeeds: npm run build
• README.md is up to date
• CHANGELOG or release notes prepared
• Version bumped in package.json
• Git tag created and pushed
• GitHub release created with detailed notes

CI/CD Workflow

This project has two automated workflows:

1. CI (Continuous Integration) - .github/workflows/ci.yml

   • Runs on every push and pull request
   • Tests on Node.js 18 and 20
   • Ensures tests pass and build succeeds

2. Publish - .github/workflows/npm-publish.yml

   • Runs when you create a GitHub release
   • Runs tests, builds, and publishes to NPM
   • Uses provenance for supply chain security

First-time Publication

For the very first publication (v0.1.0):

# Make sure you're ready
npm test
npm run build

# Login to NPM (if not already)
npm login

# Publish for the first time
npm publish --access public

# After successful publication, set up the GitHub workflow
# for future automated releases

Support

If you encounter issues:

• Check GitHub Actions logs
• Verify NPM token is valid
• Ensure package name is available
• Test locally with npm pack before publishing