cicada-mcp 0.1.5__tar.gz → 0.2.0__tar.gz

{cicada_mcp-0.1.5 → cicada_mcp-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cicada-mcp
-Version: 0.1.5
+Version: 0.2.0
 Summary: An Elixir module search MCP server
 Author-email: wende <wende@hey.com>
 Maintainer-email: wende <wende@hey.com>
@@ -31,15 +31,12 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: tree-sitter>=0.20.0
 Requires-Dist: tree-sitter-elixir>=0.1.0
 Requires-Dist: gitpython>=3.1.0
+Requires-Dist: keybert>=0.8.0
 Requires-Dist: lemminflect>=0.2.3
 Requires-Dist: rank-bm25>=0.2.2
+Requires-Dist: simple-term-menu>=1.6.0
 Requires-Dist: tomli>=2.0.0; python_version < "3.11"
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0.0; extra == "dev"
-Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
-Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
-Requires-Dist: black>=24.0.0; extra == "dev"
-Requires-Dist: pyrefly>=0.1.0; extra == "dev"
+Requires-Dist: gensim>=4.4.0
 Dynamic: license-file
 
 <div align="center">
@@ -60,7 +57,9 @@ Dynamic: license-file
 [![Elixir](https://img.shields.io/badge/Elixir-Support-purple.svg)](https://elixir-lang.org/)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
 
-[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=cicada&config=eyJjb21tYW5kIjoidXZ4IC0tZnJvbSBnaXQraHR0cHM6Ly9naXRodWIuY29tL3dlbmRlL2NpY2FkYS5naXRAbGF0ZXN0IGNpY2FkYS1zZXJ2ZXIgLiJ9)
+> 🎉 **Version 0.2.0 Released!** Enhanced AI-powered keyword search with **15-25x faster** incremental indexing. [What's New →](#whats-new-in-v020)
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=cicada&config=eyJjb21tYW5kIjoidXZ4IGNpY2FkYS1tY3AgLiJ9)
 
 [Installation](#installation) •
 [Quick Start](#quick-start) •
@@ -96,6 +95,78 @@ CICADA is a Model Context Protocol (MCP) server that provides AI coding assistan
   </table>
 </div>
 
+## What's New in v0.2.0
+
+### 🤖 Enhanced AI Keyword Extraction
+
+AI-powered semantic search is now production-ready with advanced NLP capabilities:
+
+- **BERT Integration**: KeyBERT-based keyword extraction for superior semantic understanding
+- **Configurable Model Tiers**: Choose between `fast`, `regular`, or `large` models to balance speed and accuracy
+- **Smart Wildcard Search**: Use patterns like `create*` or `*_user` to find related concepts
+- **Improved Relevance Scoring**: Better ranking of search results by semantic relevance
+
+```bash
+# Index with enhanced AI keyword extraction
+cicada index --nlp --fast
+
+# Search by concept, not just exact names
+# AI will find: create_user, user_creation, new_user_account, etc.
+```
+
+### ⚡ Incremental Indexing - Lightning Fast Updates
+
+Say goodbye to slow reindexing! v0.2.0 introduces intelligent change detection that makes reindexing **15-25x faster**:
+
+- **🚀 15-25x Speedup**: Only processes files that actually changed (MD5 hash-based detection)
+- **💾 Interrupt Safety**: Ctrl-C gracefully saves progress - resume anytime without data loss
+- **🎯 Perfect for AI Search**: Keyword extraction drops from 48.7s to 2.1s for typical updates
+- **🔄 Zero Configuration**: Works automatically out of the box
+
+```bash
+# First run: full index + hash computation (~12s for 200 files)
+cicada index --nlp
+
+# Subsequent runs: lightning fast incremental updates
+# Changed 5 files? Only 2.1s instead of 48.7s!
+cicada index --nlp
+```
+
+**Performance Benchmark** (200-file Phoenix app, 5 files changed):
+
+| Operation | Before v0.2.0 | v0.2.0 Incremental | Speedup |
+|-----------|---------------|-------------------|---------|
+| Code indexing only | 12.3s | 0.8s | **15.4x faster** |
+| With AI keyword extraction | 48.7s | 2.1s | **23.2x faster** |
+
+### 🛡️ Production-Ready Features
+
+- **Graceful Interruption**: Press Ctrl-C to cleanly save progress mid-indexing
+- **Resume Capability**: Interrupted? Just run the same command again to continue
+- **Smart Merging**: Automatically merges incremental changes with existing index
+- **Backward Compatible**: Seamlessly upgrades from v0.1.x with no breaking changes
+
+### Migration from v0.1.x
+
+✅ **Zero Breaking Changes** - v0.2.0 is fully backward compatible
+✅ **Automatic Upgrade** - Just install and run `cicada index` as usual
+✅ **Graceful Fallback** - Missing hashes? Performs full index once automatically
+
+```bash
+# Update to v0.2.0
+uv tool install git+https://github.com/wende/cicada.git@latest --force
+
+# Run indexer - automatically enables incremental mode
+cicada index --nlp
+
+# Need to switch keyword extraction methods? Use --full for consistency
+cicada index --rag --fast --full
+```
+
+**[Read the complete incremental indexing guide →](docs/INCREMENTAL_INDEXING.md)**
+
+---
+
 ### Key Features
 
 - **AST-aware code search** - Find function definitions with full signatures, types, and documentation—no implementation bloat
@@ -119,7 +190,7 @@ curl -LsSf https://astral.sh/uv/install.sh | sh
 
 ```bash
 # Step 1: Install once
-uv tool install git+https://github.com/wende/cicada.git@latest
+uv tool install cicada-mcp
 
 # Step 2: Setup in each project (one command per project)
 cd /path/to/your/elixir/project
@@ -139,9 +210,9 @@ cicada claude  # or: cicada cursor, cicada vs
 **Available commands after installation:**
 - `cicada [claude|cursor|vs]` - One-command setup per project
 - `cicada-mcp` - MCP server (auto-started by editor)
-- `cicada-index` - Re-index code with custom options (medium/large spaCy models)
-- `cicada-index-pr` - Index pull requests for PR attribution
-- `cicada-install` - Legacy setup (creates `.cicada/` in repo)
+- `cicada index` - Re-index code with custom options (--nlp or --rag)
+- `cicada index-pr` - Index pull requests for PR attribution
+- `cicada find-dead-code` - Find potentially unused functions
 
 ### Try Before Installing
 
@@ -151,19 +222,19 @@ Want to test Cicada first? Use `uvx` for a quick trial:
 cd /path/to/your/elixir/project
 
 # For Claude Code
-uvx --from git+https://github.com/wende/cicada.git@latest cicada claude
+uvx --from cicada-mcp cicada claude
 
 # For Cursor
-uvx --from git+https://github.com/wende/cicada.git@latest cicada cursor
+uvx --from cicada-mcp cicada cursor
 
 # For VS Code
-uvx --from git+https://github.com/wende/cicada.git@latest cicada vs
+uvx --from cicada-mcp cicada vs
 ```
 
 **Note:** `uvx` is perfect for trying Cicada, but **permanent installation is recommended** because:
 - ✅ Faster MCP server startup (no temporary environment creation)
-- ✅ Access to all CLI commands (`cicada-index`, `cicada-index-pr`)
-- ✅ Fine-tuned keyword extraction with medium/large spaCy models
+- ✅ Access to all CLI commands (`cicada index`, `cicada index-pr`)
+- ✅ Fine-tuned keyword extraction with lemminflect or BERT models
 - ✅ PR indexing features
 - ✅ Custom re-indexing options
 
@@ -174,26 +245,26 @@ Once you're convinced, install permanently with `uv tool install` above!
 **For Cursor:**
 
 Click the install button at the top of this README or visit:
-[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=cicada&config=eyJjb21tYW5kIjoidXZ4IC0tZnJvbSBnaXQraHR0cHM6Ly9naXRodWIuY29tL3dlbmRlL2NpY2FkYS5naXRAbGF0ZXN0IGNpY2FkYS1zZXJ2ZXIgLiJ9)
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=cicada&config=eyJjb21tYW5kIjoidXZ4IGNpY2FkYS1tY3AgLiJ9)
 
 **For Claude Code:**
 
 ```bash
 # Option 1: Using claude mcp add command
-claude mcp add cicada -- uvx --from git+https://github.com/wende/cicada.git@latest cicada-mcp ./path/to/your/codebase
+claude mcp add cicada -- uvx cicada-mcp ./path/to/your/codebase
 
 # Option 2: Using setup script
-uvx --from git+https://github.com/wende/cicada.git@latest cicada claude
+uvx --from cicada-mcp cicada claude
 ```
 
 **Then for both editors,** run these commands in your codebase to generate keyword lookup and GitHub PR lookup databases:
 
 ```bash
 # Generate keyword lookup database
-uvx --from git+https://github.com/wende/cicada.git@latest cicada-index .
+uvx --from cicada-mcp cicada-index .
 
 # Generate GitHub PR lookup database
-uvx --from git+https://github.com/wende/cicada.git@latest cicada-index-pr .
+uvx --from cicada-mcp cicada-index-pr .
 ```
 
 ---
@@ -213,7 +284,7 @@ After installation, ask your AI coding assistant:
 
 **For PR features**, first run:
 ```bash
-cicada-index-pr .
+cicada index-pr .
 ```
 
 ---
@@ -258,13 +329,21 @@ your-project/
 }
 ```
 
+✅ Fast startup, no paths, portable!
+
+**Migration tip from v0.1.x:** If you have the old Python-based config, run:
+```bash
+uv tool install git+https://github.com/wende/cicada.git@v0.2.0 --force
+cicada claude  # Re-run to get optimized config
+```
+
 ### Re-indexing
 
 After code changes, re-run the setup command:
 
 ```bash
 # Re-index for Claude Code
-uvx --from git+https://github.com/wende/cicada.git@latest cicada claude
+uvx --from cicada-mcp cicada claude
 
 # Or if permanently installed
 cicada claude
@@ -281,19 +360,14 @@ Index pull requests for PR-related features:
 
 ```bash
 # After permanent installation
-cicada-index-pr .
+cicada index-pr .
 
 # Or with uvx
-uvx --from git+https://github.com/wende/cicada.git@latest cicada-index-pr .
+uvx --from cicada-mcp cicada-index-pr .
 ```
 
-### Legacy Installation
-
-If you prefer the old setup (stores files in `.cicada/` directory in your repo):
-
-```bash
-# Only available after permanent installation
-cicada-install
+# Clean rebuild (re-index everything from scratch)
+cicada index-pr . --clean
 ```
 
 **See also:** [PR Indexing Documentation](docs/PR_INDEXING.md)
@@ -356,7 +430,7 @@ CICADA provides 9 specialized tools for AI assistants to understand and navigate
 - Wildcard pattern matching (`create*`, `*_user`)
 - NLP-extracted keywords from docs
 - Relevance scoring
-- Requires: Index built with `--extract-keywords`
+- Requires: Index built with `--nlp` or `--rag`
 
 **`find_dead_code`** - Identify potentially unused functions
 - Three confidence levels (high, medium, low)
@@ -380,7 +454,6 @@ CICADA provides several command-line tools for setup, indexing, and analysis:
 **`cicada`** - Initialize CICADA in your project
 ```bash
 cicada                           # Setup in current directory
-cicada --skip-install           # Skip dependency installation
 cicada /path/to/other/project   # Setup in different directory
 ```
 - Generates `.mcp.json` configuration
@@ -390,21 +463,21 @@ cicada /path/to/other/project   # Setup in different directory
 
 ### Indexing Tools
 
-**`cicada-index`** - Index Elixir codebase
+**`cicada index`** - Index Elixir codebase
 ```bash
-cicada-index                         # Index current directory
-cicada-index --output .cicada/index.json
-cicada-index --extract-keywords      # Include NLP keyword extraction
+cicada index                         # Index current directory
+cicada index --nlp                   # Use NLP keyword extraction (lemminflect)
+cicada index --rag                   # Use BERT-based keyword extraction
 ```
 - Parses all Elixir files using tree-sitter
 - Extracts modules, functions, and call sites
 - Resolves aliases for accurate tracking
 - Optional keyword extraction for semantic search
 
-**`cicada-index-pr`** - Index GitHub pull requests
+**`cicada index-pr`** - Index GitHub pull requests
 ```bash
-cicada-index-pr .              # Index PRs for current repo
-cicada-index-pr . --clean      # Full rebuild from scratch
+cicada index-pr .              # Index PRs for current repo
+cicada index-pr . --clean      # Full rebuild from scratch
 ```
 - Requires GitHub CLI (`gh`) authenticated
 - Indexes PR metadata and review comments
@@ -413,12 +486,12 @@ cicada-index-pr . --clean      # Full rebuild from scratch
 
 ### Analysis Tools
 
-**`cicada-find-dead-code`** - Find unused functions (CLI version)
+**`cicada find-dead-code`** - Find unused functions (CLI version)
 ```bash
-cicada-find-dead-code                      # Show high confidence only
-cicada-find-dead-code --min-confidence low # Show all candidates
-cicada-find-dead-code --format json        # JSON output
-cicada-find-dead-code --index path/to/index.json
+cicada find-dead-code                      # Show high confidence only
+cicada find-dead-code --min-confidence low # Show all candidates
+cicada find-dead-code --format json        # JSON output
+cicada find-dead-code --index path/to/index.json
 ```
 - Analyzes function usage across codebase
 - Categorizes by confidence level
@@ -428,6 +501,22 @@ cicada-find-dead-code --index path/to/index.json
 
 ## Roadmap
 
+### v0.2.0 (Released - October 2025) ✅
+- **Enhanced AI Keyword Extraction** - Production-ready semantic search
+  - BERT integration with KeyBERT for superior keyword extraction
+  - Configurable model tiers (fast, regular, large)
+  - Wildcard pattern support (`create*`, `*_user`)
+  - Improved relevance scoring
+- **Incremental Indexing** - 15-25x faster reindexing
+  - MD5-based change detection
+  - Processes only modified files
+  - Interrupt-safe with graceful Ctrl-C handling
+  - Resume capability for interrupted indexes
+- **Production Hardening**
+  - Signal handlers (SIGINT, SIGTERM)
+  - Partial progress saving
+  - Automatic hash storage and management
+
 ### v0.1.1 (Released - October 2025) ✅
 - Module and function search
 - Call site tracking with alias resolution
@@ -444,12 +533,12 @@ cicada-find-dead-code --index path/to/index.json
 - Intelligent .mcp.json auto-configuration
 - `uv tool install` support
 - **Automatic version update checking** - Notifies users when newer versions are available
-- **NLP Keyword search** (EXPERIMENTAL) - Semantic search across documentation with wildcard support
+- **NLP Keyword search** (EXPERIMENTAL) - Basic semantic search across documentation
 
-### v0.2 (Potential Future Enhancements)
-- Incremental code re-indexing
+### v0.3 (Potential Future Enhancements)
 - Enhanced keyword search with BM25 ranking
-- RAG with KeyBERT option (??)
+- Directory tree hashing for faster change detection
+- Caching optimizations for large codebases
 
 ### Long Term (Stretch Goals)
 - Multi-language support (Python, TypeScript)
@@ -564,7 +653,7 @@ When reporting bugs or requesting features:
 
 Run the indexer first:
 ```bash
-cicada-index /path/to/project
+cicada index /path/to/project
 ```
 
 ### "Module not found"
@@ -592,14 +681,14 @@ brew install gh  # macOS
 gh auth login
 
 # Index PRs (first time or after new PRs)
-cicada-index-pr .
+cicada index-pr .
 
 # Clean rebuild (re-index everything from scratch)
-cicada-index-pr . --clean
+cicada index-pr . --clean
 ```
 
 **Common issues:**
-- "No PR index found" → Run `cicada-index-pr .`
+- "No PR index found" → Run `cicada index-pr .`
 - "Not a GitHub repository" → Ensure repo has GitHub remote
 - Slow indexing → Incremental updates are used by default