stravinsky 0.2.67__py3-none-any.whl → 0.4.18__py3-none-any.whl

mcp_bridge/update_manager_pypi.py

@@ -0,0 +1,299 @@
+"""
+PyPI Update Manager for Stravinsky MCP server.
+
+Checks PyPI for new versions with throttling to prevent excessive API calls.
+Logs all checks to ~/.stravinsky/update.log for debugging and monitoring.
+Non-blocking background update checks on server startup.
+"""
+
+import asyncio
+import logging
+import subprocess
+import sys
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Optional
+
+# Get the logger for this module
+logger = logging.getLogger(__name__)
+
+# Import version from main module
+from mcp_bridge import __version__
+
+
+def _get_stravinsky_home() -> Optional[Path]:
+    """Get or create ~/.stravinsky directory."""
+    home_dir = Path.home() / ".stravinsky"
+    try:
+        home_dir.mkdir(parents=True, exist_ok=True)
+        return home_dir
+    except Exception as e:
+        logger.warning(f"Failed to create ~/.stravinsky directory: {e}")
+        return None
+
+
+def _get_last_check_time() -> Optional[datetime]:
+    """
+    Read the last update check time from ~/.stravinsky/update.log.
+
+    Returns:
+        datetime of last check, or None if file doesn't exist or is invalid
+    """
+    try:
+        home_dir = _get_stravinsky_home()
+        if not home_dir:
+            return None
+
+        update_log = home_dir / "update.log"
+        if not update_log.exists():
+            return None
+
+        # Read the last line (most recent check)
+        with open(update_log, "r") as f:
+            lines = f.readlines()
+            if not lines:
+                return None
+
+            last_line = lines[-1].strip()
+            if not last_line:
+                return None
+
+            # Parse format: YYYY-MM-DD HH:MM:SS | VERSION_CHECK | ...
+            parts = last_line.split(" | ")
+            if len(parts) < 1:
+                return None
+
+            timestamp_str = parts[0]
+            last_check = datetime.strptime(timestamp_str, "%Y-%m-%d %H:%M:%S")
+            return last_check
+
+    except Exception as e:
+        logger.debug(f"Failed to read last check time: {e}")
+        return None
+
+
+def _should_check(last_check_time: Optional[datetime]) -> bool:
+    """
+    Determine if enough time has passed since the last check.
+
+    Args:
+        last_check_time: datetime of last check, or None
+
+    Returns:
+        True if 24+ hours have passed or no prior check exists
+    """
+    if last_check_time is None:
+        return True
+
+    now = datetime.now()
+    time_since_last_check = now - last_check_time
+
+    # Check if 24+ hours have passed
+    return time_since_last_check >= timedelta(hours=24)
+
+
+def _get_pypi_version() -> Optional[str]:
+    """
+    Fetch the latest version of stravinsky from PyPI.
+
+    Uses: pip index versions stravinsky
+
+    Returns:
+        Version string (e.g., "0.3.10"), or None if unable to fetch
+    """
+    try:
+        # Run: pip index versions stravinsky
+        result = subprocess.run(
+            [sys.executable, "-m", "pip", "index", "versions", "stravinsky"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+
+        if result.returncode != 0:
+            logger.debug(f"pip index versions failed: {result.stderr}")
+            return None
+
+        # Parse output: first line is "Available versions: X.Y.Z, A.B.C, ..."
+        output = result.stdout.strip()
+        if not output:
+            logger.debug("pip index versions returned empty output")
+            return None
+
+        # Extract available versions line
+        lines = output.split("\n")
+        for line in lines:
+            if line.startswith("Available versions:"):
+                # Format: "Available versions: 0.3.10, 0.3.9, 0.3.8, ..."
+                versions_part = line.replace("Available versions:", "").strip()
+                versions = [v.strip() for v in versions_part.split(",")]
+
+                if versions:
+                    latest = versions[0]
+                    logger.debug(f"Latest version on PyPI: {latest}")
+                    return latest
+
+        logger.debug(f"Could not parse pip output: {output}")
+        return None
+
+    except subprocess.TimeoutExpired:
+        logger.warning("pip index versions timed out after 10 seconds")
+        return None
+    except Exception as e:
+        logger.debug(f"Failed to fetch PyPI version: {e}")
+        return None
+
+
+def _compare_versions(current: str, latest: str) -> bool:
+    """
+    Compare semantic versions.
+
+    Args:
+        current: Current version string (e.g., "0.3.9")
+        latest: Latest version string (e.g., "0.3.10")
+
+    Returns:
+        True if latest > current, False otherwise
+    """
+    try:
+        # Parse versions as tuples of integers
+        current_parts = [int(x) for x in current.split(".")]
+        latest_parts = [int(x) for x in latest.split(".")]
+
+        # Pad shorter version with zeros
+        max_len = max(len(current_parts), len(latest_parts))
+        current_parts += [0] * (max_len - len(current_parts))
+        latest_parts += [0] * (max_len - len(latest_parts))
+
+        # Tuple comparison works element-by-element
+        return tuple(latest_parts) > tuple(current_parts)
+
+    except Exception as e:
+        logger.debug(f"Failed to compare versions '{current}' and '{latest}': {e}")
+        return False
+
+
+def _log_check(current: str, latest: Optional[str], status: str) -> None:
+    """
+    Log the update check to ~/.stravinsky/update.log.
+
+    Format: YYYY-MM-DD HH:MM:SS | VERSION_CHECK | current=X.Y.Z pypi=A.B.C | <status>
+
+    Args:
+        current: Current version
+        latest: Latest version from PyPI (or None)
+        status: Check status ("new_available", "up_to_date", "error", etc.)
+    """
+    try:
+        home_dir = _get_stravinsky_home()
+        if not home_dir:
+            return
+
+        update_log = home_dir / "update.log"
+        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+        if latest:
+            log_entry = f"{timestamp} | VERSION_CHECK | current={current} pypi={latest} | {status}"
+        else:
+            log_entry = f"{timestamp} | VERSION_CHECK | current={current} pypi=unknown | {status}"
+
+        with open(update_log, "a") as f:
+            f.write(log_entry + "\n")
+
+        logger.debug(f"Logged update check: {status}")
+
+    except Exception as e:
+        logger.warning(f"Failed to log update check: {e}")
+
+
+async def check_for_updates(skip_updates: bool = False) -> dict:
+    """
+    Check PyPI for new versions of stravinsky.
+
+    Implements 24-hour throttling to prevent excessive API calls.
+    All failures are handled gracefully without raising exceptions.
+    Non-blocking - safe to run via asyncio.create_task().
+
+    Args:
+        skip_updates: If True, skip the check entirely
+
+    Returns:
+        dict with keys:
+            - status: "checked" | "skipped" | "error"
+            - current: current version (e.g., "0.3.9")
+            - latest: latest version (e.g., "0.3.10") or None
+            - update_available: bool
+            - message: str (optional, for errors)
+    """
+    try:
+        # Get current version
+        current_version = __version__
+
+        # Return early if updates are skipped
+        if skip_updates:
+            logger.debug("Update check skipped (skip_updates=True)")
+            return {
+                "status": "skipped",
+                "current": current_version,
+                "latest": None,
+                "update_available": False,
+            }
+
+        # Check if enough time has passed since last check
+        last_check_time = _get_last_check_time()
+        if not _should_check(last_check_time):
+            logger.debug("Update check throttled (24-hour limit)")
+            return {
+                "status": "skipped",
+                "current": current_version,
+                "latest": None,
+                "update_available": False,
+            }
+
+        # Fetch latest version from PyPI
+        latest_version = _get_pypi_version()
+
+        if latest_version is None:
+            logger.warning("Failed to fetch latest version from PyPI")
+            _log_check(current_version, None, "error")
+            return {
+                "status": "error",
+                "current": current_version,
+                "latest": None,
+                "update_available": False,
+                "message": "Failed to fetch version from PyPI",
+            }
+
+        # Compare versions
+        update_available = _compare_versions(current_version, latest_version)
+
+        # Determine status
+        if update_available:
+            status = "new_available"
+            logger.info(
+                f"Update available: {current_version} -> {latest_version}. "
+                f"Install with: pip install --upgrade stravinsky"
+            )
+        else:
+            status = "up_to_date"
+            logger.debug(f"Stravinsky is up to date ({current_version})")
+
+        # Log the check
+        _log_check(current_version, latest_version, status)
+
+        return {
+            "status": "checked",
+            "current": current_version,
+            "latest": latest_version,
+            "update_available": update_available,
+        }
+
+    except Exception as e:
+        logger.error(f"Unexpected error during update check: {e}", exc_info=True)
+        return {
+            "status": "error",
+            "current": __version__,
+            "latest": None,
+            "update_available": False,
+            "message": f"Update check failed: {str(e)}",
+        }

{stravinsky-0.2.67.dist-info → stravinsky-0.4.18.dist-info}/METADATA

@@ -1,41 +1,50 @@
 Metadata-Version: 2.4
 Name: stravinsky
-Version: 0.2.67
+Version: 0.4.18
 Summary: MCP Bridge for Claude Code with Multi-Model Support. Install globally: claude mcp add --scope user stravinsky -- uvx stravinsky. Add to CLAUDE.md: See https://pypi.org/project/stravinsky/
 Project-URL: Repository, https://github.com/GratefulDave/stravinsky
 Project-URL: Issues, https://github.com/GratefulDave/stravinsky/issues
 Author: Stravinsky Team
 License: MIT
 Keywords: claude,gemini,mcp,oauth,openai
-Requires-Python: >=3.11
+Requires-Python: <3.14,>=3.11
 Requires-Dist: aiofiles>=23.1.0
+Requires-Dist: chromadb>=0.6.0
 Requires-Dist: cryptography>=41.0.0
 Requires-Dist: google-auth-oauthlib>=1.0.0
 Requires-Dist: google-auth>=2.20.0
 Requires-Dist: httpx>=0.24.0
+Requires-Dist: jedi-language-server>=0.41.0
 Requires-Dist: jedi>=0.19.2
 Requires-Dist: keyring>=25.7.0
+Requires-Dist: lsprotocol>=2023.0.0
 Requires-Dist: mcp>=1.2.1
+Requires-Dist: ollama>=0.6.1
 Requires-Dist: openai>=1.0.0
+Requires-Dist: pathspec>=0.12.0
+Requires-Dist: plyer>=2.1.0
 Requires-Dist: psutil>=5.9.0
 Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pygls>=1.3.0
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: ruff>=0.14.10
 Requires-Dist: tenacity>=8.5.0
+Requires-Dist: watchdog~=5.0.0
 Provides-Extra: dev
 Requires-Dist: mypy>=1.10.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: semantic
+Requires-Dist: chromadb>=0.5.0; extra == 'semantic'
 Description-Content-Type: text/markdown
 
-<div align="center">
-  <img src="https://raw.githubusercontent.com/GratefulDave/stravinsky/main/assets/logo.png" width="300" alt="Stravinsky Logo">
-  <h1>Stravinsky</h1>
-  <p><strong>The Avant-Garde MCP Bridge for Claude Code</strong></p>
-  <p><em>Movement • Rhythm • Precision</em></p>
-</div>
+# Stravinsky
+
+**The Avant-Garde MCP Bridge for Claude Code**
+
+*Movement • Rhythm • Precision*
 
 ---
 
@@ -48,33 +57,55 @@ Description-Content-Type: text/markdown
 - 🔐 **OAuth Authentication** - Secure browser-based auth for Google (Gemini) and OpenAI (ChatGPT)
 - 🤖 **Multi-Model Support** - Seamlessly invoke Gemini and GPT models from Claude
 - 🎯 **Native Subagent Orchestration** - Auto-delegating orchestrator with parallel execution (zero CLI overhead)
-- 🛠️ **31 MCP Tools** - Model invocation, code search, LSP integrations, session management, and more
-- 🧠 **7 Specialized Native Agents** - Stravinsky (orchestrator), Delphi (GPT-5.2 advisor), Dewey (documentation), Explore (code search), Frontend (Gemini 3 Pro High UI/UX), Code Reviewer, Debugger
+- 🛠️ **40 MCP Tools** - Model invocation, code search, semantic search, LSP refactoring, session management, and more
+- 🧠 **9 Specialized Native Agents** - Stravinsky (orchestrator), Research Lead, Implementation Lead, Delphi (GPT-5.2 advisor), Dewey (documentation), Explore (code search), Frontend (Gemini 3 Pro High UI/UX), Code Reviewer, Debugger
 - 🔄 **Hook-Based Delegation** - PreToolUse hooks enforce delegation patterns with hard boundaries (exit code 2)
-- 📝 **LSP Integration** - Full Language Server Protocol support for Python (jedi)
+- 📝 **LSP Integration** - Full Language Server Protocol support with persistent servers (35x speedup), code refactoring, and advanced navigation
 - 🔍 **AST-Aware Search** - Structural code search and refactoring with ast-grep
+- 🧠 **Semantic Code Search** - Natural language queries with local embeddings (ChromaDB + Ollama)
 - ⚡ **Cost-Optimized Routing** - Free/cheap agents (explore, dewey) always async, expensive (delphi) only when needed
 
 ## Quick Start
 
 ### Installation
 
-**From PyPI (Recommended):**
+**CRITICAL: Always use --scope user with @latest for auto-updates and Python 3.13**
 
 ```bash
-# One-shot with uvx - no installation needed!
-claude mcp add stravinsky -- uvx stravinsky
+# CORRECT: User-level installation with Python 3.13 and automatic updates
+claude mcp add --scope user stravinsky -- uvx --python python3.13 stravinsky@latest
+
+# Why this matters:
+# - --scope user: Works across all projects (stored in ~/.claude.json)
+# - @latest: Auto-checks PyPI on every Claude restart (no stale cache)
+# - --python python3.13: Required due to chromadb → onnxruntime dependency (no Python 3.14+ support)
+```
+
+**⚠️ Python 3.13 Required**: Stravinsky requires Python 3.13 or earlier. Python 3.14+ is not supported because chromadb depends on onnxruntime, which lacks wheels for Python 3.14+.
+
+**WRONG - Do NOT use these:**
+
+```bash
+# ❌ Missing --python python3.13 (will fail on system Python 3.14+)
+claude mcp add --global stravinsky -- uvx stravinsky@latest
+
+# ❌ Local scope (only works in one project)
+claude mcp add stravinsky -- uvx --python python3.13 stravinsky@latest
 
-# Or install globally first:
+# ❌ No @latest (cache never updates, stays on old version)
+claude mcp add --global stravinsky -- uvx --python python3.13 stravinsky
+
+# ❌ uv tool install (requires manual upgrades)
 uv tool install stravinsky
-claude mcp add stravinsky -- stravinsky
 ```
 
-**From Source (for development):**
+**Development (local editable install):**
 
 ```bash
-uv tool install --editable /path/to/stravinsky
-claude mcp add stravinsky -- stravinsky
+# ONLY for active development on stravinsky source code
+cd /path/to/stravinsky
+uv tool install --editable . --force
+claude mcp add --scope user stravinsky -- stravinsky
 ```
 
 ### Authentication
@@ -93,6 +124,38 @@ stravinsky-auth status
 stravinsky-auth logout gemini
 ```
 
+**Secure Token Storage:**
+
+OAuth tokens are stored securely with automatic fallback:
+- **Primary**: System keyring (macOS Keychain, Linux Secret Service, Windows Credential Locker)
+- **Fallback**: Encrypted files at `~/.stravinsky/tokens/` using Fernet symmetric encryption
+- **Encryption**: AES-128-CBC with keys stored at `~/.stravinsky/tokens/.key` (0o600 permissions)
+- **No password prompts**: Seamless authentication across all terminal sessions after initial login
+- **Global access**: Works everywhere after one-time authentication per provider
+
+#### Troubleshooting: Password Prompts (macOS)
+
+If you experience persistent password prompts when authenticating, configure keyring to bypass macOS Keychain:
+
+```bash
+# 1. Create keyring config directory
+mkdir -p ~/.config/python_keyring
+
+# 2. Configure keyring to use fail backend (bypasses Keychain entirely)
+cat <<EOT > ~/.config/python_keyring/keyringrc.cfg
+[backend]
+default-keyring = keyring.backends.fail.Keyring
+EOT
+
+# 3. Verify configuration
+cat ~/.config/python_keyring/keyringrc.cfg
+
+# 4. Re-authenticate (tokens will be stored in encrypted files only)
+stravinsky-auth login gemini
+```
+
+This configuration stores tokens in encrypted files at `~/.stravinsky/tokens/` instead of macOS Keychain, eliminating password prompts across terminal sessions. See [docs/KEYRING_AUTH_FIX.md](docs/KEYRING_AUTH_FIX.md) for detailed information.
+
 ### Slash Commands
 
 Slash commands are discovered from:
@@ -134,27 +197,107 @@ Stravinsky uses **native Claude Code subagents** (.claude/agents/) with automati
 
 - **ULTRATHINK**: Engage exhaustive deep reasoning with extended thinking budget (32k tokens)
 - **ULTRAWORK**: Maximum parallel execution - spawn all async agents immediately
-````
 
-## Tools (31)
+---
+
+## Tools (40)
 
 | Category         | Tools                                                                              |
 | ---------------- | ---------------------------------------------------------------------------------- |
 | **Model Invoke** | `invoke_gemini`, `invoke_openai`, `get_system_health`                              |
 | **Environment**  | `get_project_context`, `task_spawn`, `task_status`, `task_list`                    |
-| **Agents**       | `agent_spawn`, `agent_output`, `agent_cancel`, `agent_list`, `agent_progress`      |
+| **Agents**       | `agent_spawn`, `agent_output`, `agent_cancel`, `agent_list`, `agent_progress`, `agent_retry` |
 | **Code Search**  | `ast_grep_search`, `ast_grep_replace`, `grep_search`, `glob_files`                 |
-| **LSP**          | `lsp_diagnostics`, `lsp_hover`, `lsp_goto_definition`, `lsp_find_references`, etc. |
+| **Semantic**     | `semantic_search`, `semantic_index`, `semantic_stats`, `cancel_indexing`, `delete_index` |
+| **LSP**          | `lsp_diagnostics`, `lsp_hover`, `lsp_goto_definition`, `lsp_find_references`, `lsp_document_symbols`, `lsp_workspace_symbols`, `lsp_prepare_rename`, `lsp_rename`, `lsp_code_actions`, `lsp_code_action_resolve`, `lsp_extract_refactor`, `lsp_servers` (12 tools) |
 | **Sessions**     | `session_list`, `session_read`, `session_search`                                   |
 | **Skills**       | `skill_list`, `skill_get`                                                          |
 
-## Native Subagents (7)
+### LSP Performance & Refactoring
+
+The Phase 2 update introduced the `LSPManager`, which maintains persistent language server instances:
+
+- **35x Speedup**: Subsequent LSP calls are near-instant because the server no longer needs to re-initialize and re-index the codebase for every request
+- **Code Refactoring**: New support for `lsp_extract_refactor` allows automated code extraction (e.g., extracting a method or variable) with full symbol resolution
+- **Code Actions**: `lsp_code_action_resolve` enables complex, multi-step refactoring workflows with automatic fixes for diagnostics
+
+### Semantic Code Search
+
+Natural language code search powered by embeddings. Find code by meaning, not just keywords.
+
+**Prerequisites:**
+
+```bash
+# Install Ollama (default provider - free, local)
+brew install ollama
+
+# Pull the recommended lightweight embedding model (274MB)
+ollama pull nomic-embed-text
+
+# Or for better accuracy (670MB, slower):
+ollama pull mxbai-embed-large
+```
+
+**Recommended model:** `nomic-embed-text` is lightweight (274MB), fast, and works great for code search. It's the best choice for most users, especially on space-constrained systems like MacBooks.
+
+**Workflow:**
+
+```bash
+# STEP 1: Initial indexing (REQUIRED - run once per project)
+semantic_index(project_path=".", provider="ollama")
+
+# STEP 2: Enable auto-updates (OPTIONAL - recommended for active projects)
+start_file_watcher(".", provider="ollama", debounce_seconds=2.0)
+
+# STEP 3: Search your codebase with natural language
+semantic_search(query="OAuth authentication logic", n_results=5)
+semantic_stats()  # View index statistics
+
+# STEP 4: Stop watching when done (optional - watcher cleans up on exit)
+stop_file_watcher(".")
+
+# OPTIONAL: Cancel ongoing indexing (for large codebases)
+cancel_indexing(project_path=".", provider="ollama")
+
+# OPTIONAL: Delete indexes
+delete_index(project_path=".", provider="ollama")  # Delete ollama index for this project
+delete_index(project_path=".")  # Delete all provider indexes for this project
+delete_index(delete_all=True)  # Delete ALL indexes for ALL projects
+```
+
+**⚠️ Important:** You MUST run `semantic_index()` first before using semantic search or starting the FileWatcher. If you skip this step:
+- `semantic_search()` will return no results
+- `start_file_watcher()` will show a warning but still work (indexes on first file change)
+
+**Example queries:**
+- "find authentication logic"
+- "error handling in API endpoints"
+- "database connection pooling"
+
+**Providers:**
+
+| Provider | Model | Size | Cost | Setup |
+|----------|-------|------|------|-------|
+| `ollama` (default) | nomic-embed-text (recommended) | 274MB | Free/local | `ollama pull nomic-embed-text` |
+| `ollama` | mxbai-embed-large (advanced) | 670MB | Free/local | `ollama pull mxbai-embed-large` |
+| `gemini` | gemini-embedding-001 | N/A | OAuth/cloud | `stravinsky-auth login gemini` |
+| `openai` | text-embedding-3-small | N/A | OAuth/cloud | `stravinsky-auth login openai` |
+
+**Technical details:**
+- **AST-aware chunking**: Python files split by functions/classes for better semantic boundaries
+- **Persistent storage**: ChromaDB at `~/.stravinsky/vectordb/<project>_<provider>/`
+- **Async parallel embeddings**: 10 concurrent for fast indexing
+- **Automatic file watching**: Background reindexing on code changes with configurable debouncing (2s default)
+
+## Native Subagents (9)
 
 Configured in `.claude/agents/*.md`:
 
 | Agent            | Purpose                                                               | Location |
 | ---------------- | --------------------------------------------------------------------- | -------- |
 | `stravinsky`     | Task orchestration with 32k extended thinking (Sonnet 4.5)            | .claude/agents/stravinsky.md |
+| `research-lead`  | Research coordinator - spawns explore/dewey, synthesizes findings (Gemini Flash) | .claude/agents/research-lead.md |
+| `implementation-lead` | Implementation coordinator - spawns frontend/debugger/reviewer (Haiku) | .claude/agents/implementation-lead.md |
 | `explore`        | Codebase search and structural analysis (Gemini 3 Flash)              | .claude/agents/explore.md |
 | `dewey`          | Documentation research and web search (Gemini 3 Flash)                | .claude/agents/dewey.md |
 | `code-reviewer`  | Security, quality, and best practice analysis (Claude Sonnet)         | .claude/agents/code-reviewer.md |
@@ -187,7 +330,7 @@ stravinsky/
 │   │   ├── delphi.md             # Strategic advisor (GPT-5.2)
 │   │   └── HOOKS.md              # Hook architecture guide
 │   ├── commands/                 # Slash commands (skills)
-│   │   ├── stravinsky.md         # /stravinsky orchestrator
+│   │   ├── stravinsky.md         # /strav orchestrator
 │   │   ├── delphi.md             # /delphi strategic advisor
 │   │   ├── dewey.md              # /dewey documentation research
 │   │   ├── publish.md            # /publish PyPI release
@@ -222,6 +365,7 @@ stravinsky/
 │   │   ├── model_invoke.py       # invoke_gemini, invoke_openai
 │   │   ├── agent_manager.py      # agent_spawn, agent_output, etc.
 │   │   ├── code_search.py        # ast_grep, grep, glob
+│   │   ├── semantic_search.py    # semantic_search, semantic_index, semantic_stats
 │   │   ├── session_manager.py    # session_list, session_read, etc.
 │   │   ├── skill_loader.py       # skill_list, skill_get
 │   │   ├── project_context.py    # get_project_context
@@ -277,6 +421,46 @@ The Codex CLI uses the same port. Stop it with: `killall codex`
 - Ensure you have a ChatGPT Plus/Pro subscription
 - Tokens expire occasionally; run `stravinsky-auth login openai` to refresh
 
+### Claude Code Not Loading Latest Version After Update
+
+**Problem:** After deploying a new version to PyPI, Claude Code still uses the old cached version even after restart.
+
+**Root Cause:** `uvx` caches packages and doesn't automatically check for updates. This is a known uvx behavior that affects all packages, not just Stravinsky.
+
+**Solution - Force Reinstall:**
+
+```bash
+# Option 1: Run latest version with uvx (if using uvx in .mcp.json)
+uvx stravinsky@latest
+
+# Option 2: Upgrade with uv tool (if installed globally)
+uv tool install --upgrade --force stravinsky
+# or reinstall all tools:
+uv tool upgrade --all --reinstall
+
+# Option 3: Clear uvx cache entirely (nuclear option)
+uv cache prune
+
+# Option 4: Remove and re-add MCP server
+claude mcp remove stravinsky
+claude mcp add stravinsky -- uvx stravinsky@latest
+
+# After any option, restart Claude Code
+claude restart
+```
+
+**Verify Version:**
+
+```bash
+# Check installed version
+stravinsky --version
+# or
+python -c "import mcp_bridge; print(mcp_bridge.__version__)"
+
+# Check PyPI latest version
+curl -s https://pypi.org/pypi/stravinsky/json | python -c "import sys, json; print(json.load(sys.stdin)['info']['version'])"
+```
+
 ## License
 
 MIT