kuzu-mcp-server/.topos/NPM-PUBLISHING.md

A Model Context Protocol (MCP) server for Kuzu graph databases. Enables LLMs like Claude to execute Cypher queries and analyze graph data with path invariance support.

# NPM Publishing Instructions for Kuzu MCP Server

This document provides step-by-step instructions for publishing the Kuzu MCP Server to npm, making it available for global installation via `npx kuzu-mcp-server`.

## Prerequisites

1. **npm Account**: You need an npm account with publishing permissions
2. **Two-Factor Authentication**: Recommended for security
3. **npm CLI**: Ensure npm is installed and up to date

## Pre-Publishing Checklist

### 1. Verify Package Configuration

Ensure `package.json` contains:
- ✅ Correct package name: `kuzu-mcp-server`
- ✅ Valid version: `0.1.0`
- ✅ Author information: `freemorphism@gmail.com`
- ✅ Bin configuration for npx usage
- ✅ Repository and homepage URLs
- ✅ Proper keywords for discoverability

### 2. Test Package Locally

```bash
# Test all functionality
npm run test
node bin/kuzu-mcp-server.js --test
node bin/kuzu-mcp-server.js --setup ./test-db
node bin/kuzu-mcp-server.js --health ./test-db

# Test package creation
npm pack --dry-run
```

### 3. Verify File Inclusion

Check what files will be included in the package:
```bash
npm pack --dry-run
```

Expected files:
- `index.js` (main server)
- `bin/kuzu-mcp-server.js` (CLI executable)
- `package.json`
- `README.md`
- `LICENSE`
- Documentation and examples
- Test scripts

## Publishing Steps

### Step 1: Login to npm

```bash
npm login
```

Enter your npm credentials:
- Username
- Password
- Email: `freemorphism@gmail.com`
- Two-factor authentication code (if enabled)

### Step 2: Verify Login

```bash
npm whoami
```

Should return your npm username.

### Step 3: Run Pre-publish Tests

```bash
npm run prepublishOnly
```

This will run the test suite automatically.

### Step 4: Publish to npm

For first-time publishing:
```bash
npm publish --access public
```

The package will be published as a public package since it's specified in `package.json`.

### Step 5: Verify Publication

After publishing, verify the package is available:

```bash
# Check package info
npm info kuzu-mcp-server

# Test installation
npx kuzu-mcp-server --version
npx kuzu-mcp-server --help
```

## Post-Publishing Verification

### Test Global Installation

```bash
# Test npx usage (no installation required)
npx kuzu-mcp-server --version
npx kuzu-mcp-server --setup ./test-publish-db
npx kuzu-mcp-server --health ./test-publish-db

# Test global installation
npm install -g kuzu-mcp-server
kuzu-mcp-server --version

# Clean up
npm uninstall -g kuzu-mcp-server
rm -rf ./test-publish-db
```

### Verify Package Page

Visit the npm package page:
https://www.npmjs.com/package/kuzu-mcp-server

Check that:
- ✅ README displays correctly
- ✅ Version is correct
- ✅ Keywords are present
- ✅ Author information is displayed
- ✅ Repository link works

## Version Management

### For Future Updates

1. **Update Version Number**:
   ```bash
   # Patch version (0.1.0 → 0.1.1)
   npm version patch
   
   # Minor version (0.1.0 → 0.2.0)
   npm version minor
   
   # Major version (0.1.0 → 1.0.0)
   npm version major
   ```

2. **Commit and Push**:
   ```bash
   git push origin main --tags
   ```

3. **Publish Update**:
   ```bash
   npm publish
   ```

## Troubleshooting

### Common Issues

1. **Package Name Already Exists**:
   - Error: `403 Forbidden - PUT https://registry.npmjs.org/kuzu-mcp-server`
   - Solution: The name might be taken. Check on npmjs.com

2. **Authentication Issues**:
   - Error: `ENEEDAUTH`
   - Solution: Run `npm login` again

3. **Permission Denied**:
   - Error: `EACCES`
   - Solution: Ensure you have publish permissions for the package

4. **Two-Factor Authentication**:
   - Error: `EOTP`
   - Solution: Include OTP with `npm publish --otp=123456`

### Package Size Issues

If the package is too large:
```bash
# Check what's included
npm pack --dry-run

# Update .npmignore to exclude large files
echo "large-file.dat" >> .npmignore
```

## Testing Installation

After publishing, test the package works correctly:

```bash
# Create a temporary directory
mkdir /tmp/test-kuzu-mcp
cd /tmp/test-kuzu-mcp

# Test npx usage
npx kuzu-mcp-server --version
npx kuzu-mcp-server --setup ./test-db
npx kuzu-mcp-server --health ./test-db

# Test starting server
timeout 5s npx kuzu-mcp-server ./test-db

# Clean up
cd /
rm -rf /tmp/test-kuzu-mcp
```

## Success Criteria

The package is successfully published when:

- ✅ `npx kuzu-mcp-server --version` returns version 0.1.0
- ✅ `npx kuzu-mcp-server --help` shows usage instructions
- ✅ `npx kuzu-mcp-server --setup ./db` creates a working database
- ✅ `npx kuzu-mcp-server --health ./db` reports healthy status
- ✅ `npx kuzu-mcp-server --test` passes all tests
- ✅ Package appears on npmjs.com with correct metadata
- ✅ MCP server starts without errors

## Package Statistics

After publication, monitor:
- Download count
- GitHub stars
- Issues and feedback
- Usage in Claude Desktop configurations

## Security Considerations

- ✅ No secrets or API keys in published package
- ✅ .npmignore excludes sensitive files
- ✅ Package only includes necessary files
- ✅ Two-factor authentication enabled on npm account

## Support and Maintenance

After publishing:
1. Monitor for issues and feedback
2. Respond to GitHub issues
3. Update documentation as needed
4. Release patches for bugs
5. Consider feature requests for minor/major releases

---

**Ready to Publish**: Once all checks pass, run `npm publish --access public` to make the Kuzu MCP Server available worldwide via npx!