# Scripts Directory

Shell scripts for plugin setup, diagnostics, and MCP server.

---

## MCP Wrapper (`mcp-wrapper.sh`)

Entry point for MCP server. Called by Claude Code when starting the plugin.

**CRITICAL:** Uses `sort -V -r` to get LATEST cached version, not first alphabetically.
- Bug: Alphabetical sort put 0.20.0 before 0.22.x
- Fix: Version sort ensures latest cached version with all fixes

**Flow:**
1. Check `installed_plugins.json` for explicit path
2. Fallback: Scan cache dirs, sort by version (descending), use first valid
3. Run `bootstrap.js` which handles deps and starts MCP

---

## Setup (`setup.sh`)

Manual and auto setup script. Installs dependencies.

**CRITICAL:** Uses `npm install --legacy-peer-deps`
- Required because tree-sitter-go@0.25 and tree-sitter-rust@0.24 have incompatible peer deps
- Without this flag, npm fails even though tree-sitter is optional

**Installs:**
- MCP wrapper to `~/.local/bin/bluera-knowledge-mcp`
- node_modules (bun or npm)
- Playwright Chromium browser

---

## Auto-Setup (`auto-setup.sh`)

Runs on SessionStart (async, non-blocking). Calls setup.sh if needed.

**Fast exit:** If node_modules AND wrapper exist, exits immediately.

---

## Doctor (`doctor.sh`)

Diagnostic tool for MCP failures. **Use this first when MCP breaks.**

Invoked via: `/bluera-knowledge:doctor`

**Checks:**
- Build tools (make) - REQUIRED for native modules
- Node.js version - WARNS on v24+ (native module issues)
- node_modules - installation status
- MCP wrapper - installation status
- Python 3 - optional, for embeddings
- Playwright - optional, for web crawling

---

## Check-Ready (`check-ready.sh`)

Fast validation on SessionStart (sync, blocking with timeout).

Verifies prerequisites without full setup. Exits 2 for blocking errors.