docs(scripts): add comprehensive README for template maintenance scripts

Add detailed documentation for all template maintenance scripts including
installation instructions, usage examples, and common workflows.

Covers:
- merge-template-updates.sh usage and options
- analyze-template-diff.sh output formats
- install-scripts.sh for distribution
- mcp-status.sh for multi-repo management
- Common workflows and troubleshooting

Author: Mearman

scripts/README.md

@@ -0,0 +1,386 @@
+# MCP Template Scripts
+
+This directory contains utility scripts for managing MCP server repositories derived from the mcp-template.
+
+## merge-template-updates.sh
+
+A sophisticated script for merging updates from the mcp-template repository into derived MCP server repositories while preserving project-specific customizations.
+
+### Features
+
+- **Selective merging**: Automatically excludes project-specific files from being overwritten
+- **Dry run mode**: Preview changes before applying them
+- **Local template support**: Can merge from a local copy of the template for testing
+- **Project-aware**: Knows about specific MCP projects and their unique files
+- **Safe operation**: Validates repository state before merging
+- **Detailed feedback**: Shows exactly what files changed and how
+
+### Installation
+
+Copy this script to your derived MCP repository:
+
+```bash
+# From your derived repository (e.g., mcp-wayback-machine)
+mkdir -p scripts
+curl -o scripts/merge-template-updates.sh \
+  https://raw.githubusercontent.com/Mearman/mcp-template/main/scripts/merge-template-updates.sh
+chmod +x scripts/merge-template-updates.sh
+```
+
+### Usage
+
+Basic usage from the root of your derived MCP repository:
+
+```bash
+./scripts/merge-template-updates.sh
+```
+
+With options:
+
+```bash
+# Preview what would happen without making changes
+./scripts/merge-template-updates.sh --dry-run
+
+# Merge from a specific branch
+./scripts/merge-template-updates.sh --branch feature/new-updates
+
+# Merge from a local template repository
+./scripts/merge-template-updates.sh --template-path ../mcp-template
+
+# Show help
+./scripts/merge-template-updates.sh --help
+```
+
+### What Files Are Preserved
+
+The script automatically preserves these repository-specific files:
+
+**Always preserved:**
+- `package.json` - Your project name, version, description
+- `README.md` - Your project documentation
+- `CHANGELOG.md` - Your project's changelog
+- `LICENSE` - Your project's license
+- `.github/workflows/release.yml` - Release configuration
+- `.github/workflows/semantic-release.yml` - Semantic release config
+- `src/tools/*` - All your custom tools
+- `src/index.ts` - Your main server implementation
+- `src/cli.ts` - Your CLI implementation
+- `scripts/merge-template-updates.sh` - This script itself
+- `scripts/README.md` - Scripts documentation
+
+**Project-specific preservations:**
+- **mcp-wayback-machine**: `RELEASING.md`, integration tests, package tests
+- **mcp-openalex**: Type definitions, OpenAlex client utilities
+
+### Example Workflow
+
+#### 1. Standard Update Flow
+
+```bash
+# Ensure clean working directory
+git status
+# Should show: nothing to commit, working tree clean
+
+# Run the merge
+./scripts/merge-template-updates.sh
+
+# Review what changed
+git diff HEAD~1
+
+# Run tests
+yarn test
+
+# If all looks good, push and create PR
+git push origin merge-template-YYYYMMDD-HHMMSS
+```
+
+#### 2. Testing with Dry Run
+
+```bash
+# See what would happen without making changes
+./scripts/merge-template-updates.sh --dry-run
+
+# If satisfied, run for real
+./scripts/merge-template-updates.sh
+```
+
+#### 3. Testing with Local Template
+
+```bash
+# Clone template locally and make experimental changes
+git clone https://github.com/Mearman/mcp-template.git ../mcp-template-test
+cd ../mcp-template-test
+# Make your changes...
+
+# Test merge from local template
+cd ../mcp-wayback-machine
+./scripts/merge-template-updates.sh --template-path ../mcp-template-test --dry-run
+```
+
+### Handling Merge Conflicts
+
+If conflicts occur, the script will:
+
+1. List all conflicting files
+2. Provide resolution tips based on file type
+3. Exit with clear instructions
+
+To resolve conflicts:
+
+```bash
+# 1. Review conflicts
+git status
+
+# 2. Edit conflicting files
+# Look for conflict markers: <<<<<<< HEAD
+
+# 3. Common resolution strategies:
+#    - Configuration files: Usually keep your version
+#    - Shared utilities: Carefully merge both versions
+#    - Test files: Ensure they match your project structure
+
+# 4. Stage resolved files
+git add <resolved-files>
+
+# 5. Complete the merge
+git commit
+
+# 6. Continue with PR workflow
+git push origin merge-template-YYYYMMDD-HHMMSS
+```
+
+### Aborting a Merge
+
+If you need to abort and start over:
+
+```bash
+# Return to original branch
+git checkout main  # or your original branch
+
+# Delete the merge branch
+git branch -D merge-template-YYYYMMDD-HHMMSS
+
+# Remove the template remote (optional)
+git remote remove mcp-template
+```
+
+### Understanding the Merge Process
+
+1. **Validation Phase**
+   - Checks you're in a valid MCP repository
+   - Ensures no uncommitted changes
+   - Validates project structure
+
+2. **Setup Phase**
+   - Adds mcp-template as a git remote
+   - Fetches latest changes
+   - Creates a new branch for the merge
+
+3. **Configuration Phase**
+   - Sets up git attributes to exclude specific files
+   - Configures merge strategy to preserve your files
+   - Identifies project-specific exclusions
+
+4. **Merge Phase**
+   - Performs the actual merge
+   - Handles unrelated histories (first-time merges)
+   - Reports conflicts if any
+
+5. **Cleanup Phase**
+   - Shows what changed
+   - Provides next steps
+   - Cleans up temporary git configuration
+
+### Best Practices
+
+1. **Always review changes**: Use `git diff HEAD~1` to see exactly what changed
+2. **Run tests**: Ensure `yarn test` passes before creating a PR
+3. **Test locally**: Run `yarn dev` to verify everything works
+4. **Use dry run first**: Especially when merging after a long time
+5. **Create PRs**: Don't merge directly to main, use pull requests for review
+
+### Customizing for New Projects
+
+If you're creating a new MCP server not yet known to the script:
+
+1. The script will still work, using the default exclusion list
+2. To add project-specific exclusions, edit the script and add a case in the switch statement:
+
+```bash
+case "$REPO_NAME" in
+    "mcp-your-project")
+        EXCLUDE_FILES+=("your-special-file.ts" "another-file.md")
+        ;;
+```
+
+3. Consider submitting a PR to update the template script with your project
+
+### Troubleshooting
+
+**"Not in a git repository"**
+- Ensure you're in the root directory of your MCP project
+- Check that `.git` directory exists
+
+**"You have uncommitted changes"**
+- Commit or stash your changes: `git stash`
+- After merging, restore with: `git stash pop`
+
+**"This doesn't appear to be a valid MCP repository"**
+- Ensure you have `package.json` and `src/` directory
+- You might be in the wrong directory
+
+**Merge conflicts in files that should be excluded**
+- The exclusion might not be working for wildcard patterns
+- Manually resolve and report the issue
+
+**"fatal: refusing to merge unrelated histories"**
+- This is handled automatically by the script
+- If it still occurs, you might need to update git
+
+### Contributing
+
+To improve this script:
+
+1. Test your changes with `--dry-run` first
+2. Ensure it works with all known MCP projects
+3. Update this README with any new features
+4. Submit a PR to the mcp-template repository
+
+## analyze-template-diff.sh
+
+A utility script for analyzing differences between your MCP server and the template. Useful for understanding what has diverged before merging updates.
+
+### Features
+
+- **Multiple output formats**: Summary, detailed diff, or file listing
+- **Comprehensive analysis**: Checks files, directories, and dependencies
+- **Local template support**: Can analyze against a local template copy
+- **Package.json insights**: Shows dependency count differences
+
+### Usage
+
+Basic usage from the root of your derived MCP repository:
+
+```bash
+# Show summary of differences
+./scripts/analyze-template-diff.sh
+
+# Show detailed diffs for modified files
+./scripts/analyze-template-diff.sh --output detailed
+
+# List files that exist in only one repository
+./scripts/analyze-template-diff.sh --output files
+
+# Analyze against a local template
+./scripts/analyze-template-diff.sh --template-path ../mcp-template
+```
+
+### Output Formats
+
+#### Summary (default)
+
+Shows a high-level overview:
+- ✓ Identical files
+- ↻ Modified files
+- + Files only in your repository
+- - Files missing from your repository
+- Directory file counts
+- Dependency analysis
+
+#### Detailed
+
+Shows full unified diffs for all modified files. Useful for understanding exactly what changed.
+
+#### Files
+
+Lists all files that exist in only one repository. Helpful for identifying:
+- Custom files you've added
+- Template files you haven't adopted
+
+### Example Output
+
+```
+Analysis Results:
+==================
+
+File Differences:
+  ✓ tsconfig.json (identical)
+  ↻ package.json (modified)
+  + RELEASING.md (only in mcp-wayback-machine)
+  - src/tools/fetch-example.ts (missing from mcp-wayback-machine)
+
+Directory Differences:
+  ↻ src/tools (4 files vs 2 in template)
+  ✓ src/utils (3 files)
+
+Package.json Analysis:
+  Dependencies: 5 (vs 3 in template)
+  Dev Dependencies: 15 (vs 15 in template)
+  Version: 1.0.0 (template: 1.1.1)
+```
+
+### When to Use
+
+Run this script:
+- **Before merging**: Understand what will change
+- **After development**: See how far you've diverged
+- **During planning**: Identify reusable patterns to contribute back
+- **For documentation**: Track customizations in your project
+
+## mcp-status.sh
+
+A utility script for getting a quick overview of all MCP servers in a directory. Useful for managing multiple MCP server projects.
+
+### Features
+
+- **Auto-discovery**: Finds all MCP servers by checking for @modelcontextprotocol dependency
+- **Git status**: Shows branch, uncommitted changes, and unpushed commits
+- **Script availability**: Indicates which servers have merge scripts installed
+- **Project metrics**: Shows tool count and last modification time
+
+### Usage
+
+From the mcp-template directory:
+
+```bash
+# Check all MCP servers in parent directory (default)
+./scripts/mcp-status.sh
+
+# Check MCP servers in a specific directory
+./scripts/mcp-status.sh /path/to/mcp-servers
+```
+
+### Example Output
+
+```
+MCP Server Status Report
+========================
+
+Searching in: ..
+
+━━━ mcp-wayback-machine ━━━
+  Package: [email protected]
+  Description: MCP server for Internet Archive Wayback Machine
+  Scripts: ✓ (2 scripts found)
+  Git Branch: main
+  Git Status: ✓ Clean
+  Last Modified: 2024-01-15 14:32
+  Tools: 4
+
+━━━ mcp-openalex ━━━
+  Package: [email protected]
+  Description: MCP server for OpenAlex scholarly data
+  Scripts: ✗ (no scripts directory)
+  Git Branch: feature/new-tool
+  Git Status: ⚠ 3 uncommitted changes
+  Unpushed: ⚠ 2 commits ahead
+  Last Modified: 2024-01-15 16:45
+  Tools: 6
+```
+
+### When to Use
+
+- **Project overview**: Get a quick status of all your MCP servers
+- **Maintenance planning**: Identify which servers need script updates
+- **Git hygiene**: Find servers with uncommitted or unpushed changes
+- **Development tracking**: See which servers were recently modified