# NPM Package Distribution Guide

Guide for publishing and distributing Project Mind MCP.

---

## Package Information

**Package Name:** `project-mind-mcp`  
**Current Version:** 1.0.0  
**License:** MIT  
**Registry:** npm (public)

---

## Publishing to NPM

### Prerequisites

1. **NPM Account**
   ```bash
   npm login
   ```

2. **Package Validation**
   ```bash
   npm run validate
   npm test
   npm run build
   ```

3. **Version Bump**
   ```bash
   # Patch: 1.0.0 → 1.0.1
   npm version patch

   # Minor: 1.0.0 → 1.1.0
   npm version minor

   # Major: 1.0.0 → 2.0.0
   npm version major
   ```

### Publishing

```bash
# Dry run (test without publishing)
npm publish --dry-run

# Publish to NPM
npm publish

# Publish with tag
npm publish --tag beta
```

---

## Package Structure

```
project-mind-mcp/
├── dist/              # Built JavaScript (published)
├── src/               # TypeScript source (not published)
├── tests/             # Test suite (not published)
├── docs/              # Documentation (published)
├── scripts/           # Helper scripts (published)
├── package.json       # Package manifest
├── tsconfig.json      # TypeScript config
├── vitest.config.ts   # Test config
├── README.md          # Main documentation
└── LICENSE            # MIT license
```

### Published Files

Controlled by `.npmignore`:
```
# Published
dist/
docs/
scripts/
README.md
LICENSE
package.json

# Not published
src/
tests/
*.test.ts
.git/
node_modules/
```

---

## Installation Methods

### Global Installation
```bash
npm install -g project-mind-mcp
```

**Benefits:**
- Single installation for all projects
- Automatic PATH configuration
- Easy upgrades

### Local Installation
```bash
npm install project-mind-mcp
```

**Benefits:**
- Project-specific version
- No global namespace pollution
- Easier for team projects

### Development Installation
```bash
git clone <repository>
npm install
npm link
```

---

## Version Strategy

### Semantic Versioning

**Format:** MAJOR.MINOR.PATCH

- **MAJOR:** Breaking changes (e.g., 1.0.0 → 2.0.0)
- **MINOR:** New features (e.g., 1.0.0 → 1.1.0)
- **PATCH:** Bug fixes (e.g., 1.0.0 → 1.0.1)

### Pre-release Versions

```bash
# Beta release
npm version 1.1.0-beta.1
npm publish --tag beta

# Alpha release
npm version 1.1.0-alpha.1
npm publish --tag alpha

# Install pre-release
npm install project-mind-mcp@beta
```

---

## Distribution Channels

### 1. NPM Registry (Primary)

**Installation:**
```bash
npm install -g project-mind-mcp
```

**Update:**
```bash
npm update -g project-mind-mcp
```

### 2. GitHub Releases

**Download:**
```bash
curl -L https://github.com/user/project-mind-mcp/releases/latest/download/project-mind-mcp.tgz
npm install -g project-mind-mcp.tgz
```

### 3. Direct from GitHub

**Installation:**
```bash
npm install -g https://github.com/user/project-mind-mcp
```

### 4. Docker Hub (Planned)

**Pull:**
```bash
docker pull projectmind/mcp-server:latest
```

---

## Package Scripts

All available via `npm run <script>`:

```json
{
  "build": "Compile TypeScript to JavaScript",
  "test": "Run test suite",
  "test:coverage": "Run tests with coverage",
  "validate": "Validate installation",
  "install:claude": "Auto-configure Claude Desktop",
  "dev": "Watch mode for development",
  "clean": "Remove dist/ directory",
  "lint": "ESLint check",
  "format": "Prettier format"
}
```

---

## Continuous Integration

### GitHub Actions Workflow

```yaml
name: Publish

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'
      - run: npm install
      - run: npm test
      - run: npm run build
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
```

---

## Package Dependencies

### Production Dependencies
- `@modelcontextprotocol/sdk` - MCP framework
- `better-sqlite3` - Database
- `chokidar` - File watching
- `file-type` - Format detection
- `sharp` - Image processing
- `exceljs` - Excel support
- `pdf-parse` - PDF extraction

### Development Dependencies
- `typescript` - TypeScript compiler
- `vitest` - Test framework
- `eslint` - Linting
- `prettier` - Formatting

---

## Security

### Security Best Practices

1. **Dependency Auditing**
   ```bash
   npm audit
   npm audit fix
   ```

2. **Security Scanning**
   ```bash
   npm install -g snyk
   snyk test
   ```

3. **Code Signing** (Planned)
   - GPG signatures for releases
   - Checksum verification

---

## Maintenance

### Regular Tasks

**Monthly:**
- Update dependencies: `npm update`
- Security audit: `npm audit`
- Test on all platforms

**Before Each Release:**
- Run full test suite
- Update CHANGELOG.md
- Bump version number
- Update documentation
- Create GitHub release

---

## Support & Updates

### Release Channels

- **Stable:** `npm install project-mind-mcp`
- **Beta:** `npm install project-mind-mcp@beta`
- **Latest:** `npm install project-mind-mcp@latest`

### Update Notifications

Users can check for updates:
```bash
npm outdated -g project-mind-mcp
```

---

## License & Legal

**License:** MIT  
**Copyright:** © 2026 Project Mind Contributors

See [LICENSE](../LICENSE) file for full terms.

---

**For installation instructions:** [INSTALLATION.md](INSTALLATION.md)  
**For quick start:** [QUICK_START.md](QUICK_START.md)