# Auto-Update System - Implementation Summary

## Overview

Implemented a comprehensive auto-update system for the QSV MCP Server that keeps skill definitions synchronized with qsv releases. This addresses qsv's fast release tempo while giving users control over update behavior.

## Components Implemented

### 1. UpdateChecker Class (`src/update-checker.ts`)

**Core functionality**:
- Detects qsv binary version via `qsv --version`
- Reads skill definition versions from JSON files
- Compares versions to detect mismatches
- Checks GitHub releases for new qsv versions
- Optionally auto-regenerates skills when outdated
- Stores version tracking history

**Key methods**:
- `getQsvBinaryVersion()` - Get current qsv version
- `getSkillsVersion()` - Get version skills were generated with
- `quickCheck()` - Fast local version comparison (no network)
- `checkForUpdates()` - Full check including GitHub API
- `autoRegenerateSkills()` - Auto-run `qsv --update-mcp-skills` if configured

### 2. Integration with MCP Server (`src/mcp-server.ts`)

**Startup flow**:
1. Load skills
2. **Quick check** - Compare qsv binary vs skills version (< 50ms)
   - If mismatch detected, show warning
   - Optionally auto-regenerate skills
3. **Background check** - Check GitHub for new releases (non-blocking)
4. Register tool handlers
5. Start serving requests

**Non-blocking**: Update checks don't delay MCP server startup

### 3. Configuration via Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `QSV_MCP_AUTO_REGENERATE_SKILLS` | `false` | Auto-regenerate when version changes |
| `QSV_MCP_CHECK_UPDATES_ON_STARTUP` | `true` | Check for updates on startup |
| `QSV_MCP_NOTIFY_UPDATES` | `true` | Show notifications in logs |
| `QSV_MCP_GITHUB_REPO` | `dathere/qsv` | GitHub repo for releases |

### 4. Version Tracking

**File**: `.qsv-mcp-versions.json` (gitignored)

**Contents**:
```json
{
  "qsvBinaryVersion": "16.1.0",
  "skillsGeneratedWithVersion": "16.1.0",
  "mcpServerVersion": "16.1.2",
  "lastChecked": "2026-02-22T14:56:35.979Z"
}
```

Tracks update history and last check time.

### 5. Documentation

Created comprehensive documentation:
- **AUTO_UPDATE.md** - Complete auto-update guide with workflows
- Updated **README-MCP.md** - Added env vars and link to guide
- Updated **README.md** - Added link to auto-update guide
- **examples/update-checker-demo.js** - Interactive demo

## Usage Scenarios

### Scenario 1: Conservative (Default)

**Configuration**: `QSV_MCP_AUTO_REGENERATE_SKILLS=false`

**What happens**:
1. User updates qsv: `qsv --update`
2. MCP server detects mismatch on next startup
3. Logs show clear instructions to regenerate
4. User runs: `qsv --update-mcp-skills`
5. Restart Claude Desktop

**Output example**:
```
⚠️  VERSION MISMATCH DETECTED ⚠️
   qsv binary: 0.133.0
   Skills generated with: 0.132.0

ℹ️  To update skills manually, run:
   qsv --update-mcp-skills
   Then restart the MCP server
```

### Scenario 2: Automatic

**Configuration**: `QSV_MCP_AUTO_REGENERATE_SKILLS=true`

**What happens**:
1. User updates qsv: `qsv --update`
2. MCP server detects mismatch on next startup
3. **Automatically** runs `qsv --update-mcp-skills` (takes ~5-10 seconds)
4. Logs show success message
5. User restarts Claude Desktop

**Output example**:
```
⚠️  VERSION MISMATCH DETECTED ⚠️
   qsv binary: 0.133.0
   Skills generated with: 0.132.0

[UpdateChecker] Auto-regenerating skills...
✅ Skills regenerated successfully
   Please restart the MCP server to load updated skills
```

### Scenario 3: GitHub Release Notification

**What happens** (background check):
```
📦 UPDATE CHECK RESULTS:
🆕 New qsv release available: 0.133.0 (you have 0.132.0)
   Update with: qsv --update
```

## Technical Design Decisions

### 1. Why Three-Tier Strategy?

**qsv binary**: Users manage via their preferred method (package manager, qsv --update, GitHub releases)
**Skill definitions**: MCP server can regenerate by calling `qsv --update-mcp-skills` (uses prebuilt qsv binary, no Rust toolchain needed)
**MCP server code**: Standard npm package updates

### 2. Why Quick Check + Background Check?

- **Quick check** is instant (< 50ms), no network delay
- Catches most common case (qsv updated, skills stale)
- **Background check** doesn't block server startup
- Provides additional info (GitHub releases) without delay

### 3. Why Conservative Default?

- `QSV_MCP_AUTO_REGENERATE_SKILLS=false` by default
- Automatic regeneration requires:
  - qsv binary with "mcp" feature enabled
  - 5-10 seconds added to startup time
- Better to notify users than fail unexpectedly
- Much simpler than previous approach (no Rust toolchain required)

### 4. Why Store Version Info?

- Tracks history of version changes
- Enables future features (update frequency analysis, rollback support)
- Useful for debugging version mismatch issues

## Testing

### Demo Script

Run the interactive demo:
```bash
npm run test-update-checker
```

### Manual Testing

1. **Test version detection**:
   ```bash
   node examples/update-checker-demo.js
   ```

2. **Test with version mismatch**:
   - Modify a skill JSON file to change version
   - Run `npm run mcp:start`
   - Should see version mismatch warning

3. **Test auto-regeneration** (requires qsv binary with "mcp" feature):
   ```bash
   export QSV_MCP_AUTO_REGENERATE_SKILLS=true
   # Modify skill version to trigger mismatch
   npm run mcp:start
   # Should auto-regenerate
   ```

## Performance

- **Quick check**: < 50ms (just reading files and running qsv --version)
- **Full check**: < 500ms (includes GitHub API call)
- **Auto-regeneration**: ~5-10 seconds (only when needed)
- **Impact on startup**: Minimal (< 100ms in normal case)

## Future Enhancements

Potential improvements for future versions:

1. **Rollback support**: Keep previous skill versions for quick rollback
2. **Update frequency analysis**: Track how often qsv releases
3. **Smart scheduling**: Check for updates based on release frequency
4. **Version pinning**: Allow users to pin specific qsv versions
5. **Notification webhooks**: Send notifications via Slack, Discord, etc.
6. **CI/CD integration**: GitHub Actions workflow template
7. **Multi-version support**: Support multiple qsv versions simultaneously

## Files Modified/Created

### New Files
- `src/update-checker.ts` - Update checker implementation
- `AUTO_UPDATE.md` - Comprehensive documentation
- `examples/update-checker-demo.js` - Interactive demo
- `UPDATE_SYSTEM.md` - This file (formerly UPDATE_SYSTEM_SUMMARY.md)

### Modified Files
- `src/mcp-server.ts` - Integrated update checker
- `README-MCP.md` - Added env vars and documentation link
- `README.md` - Added documentation link
- `package.json` - Added test-update-checker script
- `.gitignore` - Added .qsv-mcp-versions.json

## Dependencies

Uses Node.js built-ins plus two npm dependencies:
- `child_process` - For spawning qsv
- `fs` - For reading version files
- `fetch` - For GitHub API (Node 18+ built-in)
- `wink-bm25-text-search` - BM25 search index for tool discovery
- `wink-nlp-utils` - NLP utilities for search tokenization

## Compatibility

- **Node.js**: >= 20.0.0 (matches package.json engines; pulled forward by @modelcontextprotocol/ext-apps ≥ 1.7 which requires Node ≥ 20)
- **qsv**: All versions (uses --version flag)
- **Rust**: Not required (auto-regeneration uses the prebuilt qsv binary's `--update-mcp-skills` flag)
- **OS**: macOS, Linux, Windows

## Related Documentation

- [AUTO_UPDATE.md](./AUTO_UPDATE.md) - User guide
- [README-MCP.md](../../README-MCP.md) - MCP server guide
- [qsv self-update](https://github.com/dathere/qsv#self-update) - qsv's update mechanism

---

**Implemented**: 2026-01-07
**Version**: 18.0.5
**Status**: ✅ Production Ready
