mcp-code-indexer 1.2.3__py3-none-any.whl → 1.4.0__py3-none-any.whl

mcp_code_indexer/server/mcp_server.py

@@ -252,7 +252,7 @@ class MCPCodeIndexServer:
                 ),
                 types.Tool(
                     name="check_codebase_size",
-                    description="Checks the total token count of a codebase's file structure and descriptions. Returns whether the codebase is 'large' and recommends using search instead of the full overview.",
+                    description="Checks the total token count of a codebase's file structure and descriptions - if you're in a git repo be sure to run `git rev-parse --abbrev-ref HEAD` to see what branch you're on before running this tool. Returns whether the codebase is 'large' and recommends using search instead of the full overview.",
                     inputSchema={
                         "type": "object",
                         "properties": {
@@ -350,7 +350,7 @@ class MCPCodeIndexServer:
                 ),
                 types.Tool(
                     name="get_codebase_overview",
-                    description="Returns a condensed, interpretive overview of the entire codebase. This is a single comprehensive narrative that captures the architecture, key components, relationships, and design patterns. Unlike get_all_descriptions which lists every file, this provides a holistic view suitable for understanding the codebase's structure and purpose. If no overview exists, returns empty string.",
+                    description="Returns a condensed, interpretive overview of the entire codebase - if you're in a git repo be sure to run `git rev-parse --abbrev-ref HEAD` to see what branch you're on before running this tool. This is a single comprehensive narrative that captures the architecture, key components, relationships, and design patterns. Unlike get_all_descriptions which lists every file, this provides a holistic view suitable for understanding the codebase's structure and purpose. If no overview exists, returns empty string.",
                     inputSchema={
                         "type": "object",
                         "properties": {
@@ -417,7 +417,7 @@ src/
                 ),
                 types.Tool(
                     name="get_word_frequency",
-                    description="Analyzes all file descriptions to find the most frequently used technical terms. Filters out common English stop words and symbols, returning the top 200 meaningful terms. Useful for understanding the codebase's domain vocabulary and finding all functions/files related to specific concepts.",
+                    description="Analyzes all file descriptions to find the most frequently used technical terms - if you're in a git repo be sure to run `git rev-parse --abbrev-ref HEAD` to see what branch you're on before running this tool. Filters out common English stop words and symbols, returning the top 200 meaningful terms. Useful for understanding the codebase's domain vocabulary and finding all functions/files related to specific concepts.",
                     inputSchema={
                         "type": "object",
                         "properties": {
@@ -579,6 +579,15 @@ src/
                 score += 1
                 match_factors.append("folder_path")
             
+            # Enhanced matching: If name matches and no remote origins are provided,
+            # consider it a strong match to prevent duplicates
+            if (score == 1 and "name" in match_factors and 
+                not remote_origin and not project.remote_origin and
+                not upstream_origin and not project.upstream_origin):
+                logger.info(f"Name-only match with no remotes for project {project.name} - treating as strong match to prevent duplicates")
+                score = 2  # Boost score to strong match level
+                match_factors.append("no_remotes_boost")
+            
             # If we have 2+ matches, this is a strong candidate
             if score >= 2:
                 if score > best_score:

{mcp_code_indexer-1.2.3.dist-info → mcp_code_indexer-1.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-code-indexer
-Version: 1.2.3
+Version: 1.4.0
 Summary: MCP server that tracks file descriptions across codebases, enabling AI agents to efficiently navigate and understand code through searchable summaries and token-aware overviews.
 Author: MCP Code Indexer Contributors
 Maintainer: MCP Code Indexer Contributors
@@ -35,6 +35,8 @@ Requires-Dist: gitignore_parser==0.1.11
 Requires-Dist: pydantic>=2.8.0
 Requires-Dist: aiofiles==23.2.0
 Requires-Dist: aiosqlite==0.19.0
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: tenacity>=8.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
@@ -55,11 +57,11 @@ Dynamic: requires-python
 
 # MCP Code Indexer 🚀
 
-[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?1)](https://badge.fury.io/py/mcp-code-indexer)
-[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?1)](https://pypi.org/project/mcp-code-indexer/)
+[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?2)](https://badge.fury.io/py/mcp-code-indexer)
+[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?2)](https://pypi.org/project/mcp-code-indexer/)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-A production-ready **Model Context Protocol (MCP) server** that provides intelligent codebase navigation for AI agents through searchable file descriptions, token-aware overviews, and advanced merge capabilities.
+A production-ready **Model Context Protocol (MCP) server** that revolutionizes how AI agents navigate and understand codebases. Instead of repeatedly scanning files, agents get instant access to intelligent descriptions, semantic search, and context-aware recommendations.
 
 ## 🎯 What It Does
 
@@ -75,40 +77,107 @@ Perfect for AI-powered code review, refactoring tools, documentation generation,
 
 ## ⚡ Quick Start
 
-### Install from PyPI
+### 👨‍💻 For Developers
+
+Get started integrating MCP Code Indexer into your AI agent workflow:
 
 ```bash
 # Install the package
 pip install mcp-code-indexer
 
-# Run the server
-mcp-code-indexer --token-limit 32000
+# Start the MCP server
+mcp-code-indexer
+
+# Connect your MCP client and start using tools
+# See API Reference for complete tool documentation
+```
+
+### 🔧 For System Administrators
 
-# Check version
+Deploy and configure the server for your team:
+
+```bash
+# Production deployment with custom settings
+mcp-code-indexer \
+  --token-limit 64000 \
+  --db-path /data/mcp-index.db \
+  --cache-dir /var/cache/mcp \
+  --log-level INFO
+
+# Check installation
 mcp-code-indexer --version
 ```
 
-### Install from Source
+### 🎯 For Everyone
+
+**New to MCP Code Indexer?** Start here:
+
+1. **Install**: `pip install mcp-code-indexer`
+2. **Run**: `mcp-code-indexer --token-limit 32000`
+3. **Connect**: Use your favorite MCP client
+4. **Explore**: Try the `check_codebase_size` tool first
+
+**Development Setup**:
 
 ```bash
-# Clone and setup
-git clone https://github.com/your-username/mcp-code-indexer.git
+# Clone and setup for contributing
+git clone https://github.com/fluffypony/mcp-code-indexer.git
 cd mcp-code-indexer
 
-# Install in development mode
+# Install in development mode (required)
 pip install -e .
 
 # Run the server
 mcp-code-indexer --token-limit 32000
 ```
 
+## 🔗 Git Hook Integration
+
+🚀 **NEW Feature**: Automated code indexing with AI-powered analysis! Keep your file descriptions synchronized automatically as your codebase evolves.
+
+### 👤 For Users: Quick Setup
+
+```bash
+# Set your OpenRouter API key
+export OPENROUTER_API_KEY="sk-or-v1-your-api-key-here"
+
+# Test git hook functionality
+mcp-code-indexer --githook
+
+# Install post-commit hook
+cp examples/git-hooks/post-commit .git/hooks/
+chmod +x .git/hooks/post-commit
+```
+
+### 👨‍💻 For Developers: How It Works
+
+The git hook integration provides intelligent automation:
+
+- **📊 Git Analysis**: Automatically analyzes git diffs after commits/merges
+- **🤖 AI Processing**: Uses OpenRouter API with Anthropic's Claude Sonnet 4
+- **⚡ Smart Updates**: Only processes files that actually changed  
+- **🔄 Overview Maintenance**: Updates project overview when structure changes
+- **🛡️ Error Isolation**: Git operations continue even if indexing fails
+- **⏱️ Rate Limiting**: Built-in retry logic with exponential backoff
+
+### 🎯 Key Benefits
+
+💡 **Zero Manual Work**: Descriptions stay current without any effort  
+⚡ **Performance**: Only analyzes changed files, not entire codebase  
+🔒 **Reliability**: Robust error handling ensures git operations never fail  
+🎛️ **Configurable**: Support for custom models and timeout settings  
+
+**Learn More**: See [Git Hook Setup Guide](docs/git-hook-setup.md) for complete configuration options and troubleshooting.
+
 ## 🔧 Development Setup
 
-For development work, you **must** install the package in editable mode to ensure proper import resolution:
+### 👨‍💻 For Contributors
+
+Contributing to MCP Code Indexer? Follow these steps for a proper development environment:
 
 ```bash
 # Setup development environment
-git clone https://github.com/your-username/mcp-code-indexer.git
+git clone https://github.com/fluffypony/mcp-code-indexer.git
 cd mcp-code-indexer
 
 # Create and activate virtual environment
@@ -126,11 +195,9 @@ python main.py --help
 mcp-code-indexer --version
 ```
 
-### Why Editable Install is Required
-
-The project uses a proper PyPI package structure with absolute imports like `from mcp_code_indexer.database.database import DatabaseManager`. Without the editable installation (`pip install -e .`), Python cannot resolve these imports and you'll get `ModuleNotFoundError` exceptions.
+⚠️ **Important**: The editable install (`pip install -e .`) is **required** for development. The project uses proper PyPI package structure with absolute imports like `from mcp_code_indexer.database.database import DatabaseManager`. Without editable installation, you'll get `ModuleNotFoundError` exceptions.
 
-### Development Workflow
+### 🎯 Development Workflow
 
 ```bash
 # Activate virtual environment
@@ -158,27 +225,27 @@ mypy src/
 
 ## 🛠️ MCP Tools Available
 
-The server provides **11 powerful MCP tools** for intelligent codebase management:
+The server provides **11 powerful MCP tools** for intelligent codebase management. Whether you're an AI agent or human developer, these tools make navigating code effortless.
 
-### Core Operations
-- **`get_file_description`** - Retrieve stored file descriptions instantly
-- **`update_file_description`** - Store detailed file summaries and metadata
-- **`check_codebase_size`** - Get token count and size-based recommendations with automatic file cleanup
+### 🎯 For Everyone: Start Here
+- **`check_codebase_size`** - Get instant recommendations for how to navigate your codebase
+- **`search_descriptions`** - Find files by what they do, not just their names
+- **`get_codebase_overview`** - Get a high-level understanding of any project
 
-### Batch Operations
+### 👨‍💻 For Developers: Core Operations
+- **`get_file_description`** - Retrieve stored file descriptions instantly
+- **`update_file_description`** - Store detailed file summaries and metadata  
 - **`find_missing_descriptions`** - Scan projects for files without descriptions
 - **`update_missing_descriptions`** - Bulk update multiple file descriptions
 
-### Search & Discovery
-- **`search_descriptions`** - Fast full-text search across all descriptions
+### 🔍 For Advanced Users: Search & Discovery
 - **`get_all_descriptions`** - Complete hierarchical project structure
-- **`get_codebase_overview`** - Condensed narrative overview of entire codebase
 - **`get_word_frequency`** - Technical vocabulary analysis with stop-word filtering
-
-### Advanced Features
 - **`merge_branch_descriptions`** - Two-phase merge with conflict resolution
 - **`update_codebase_overview`** - Create comprehensive codebase documentation
 
+💡 **Pro Tip**: Always start with `check_codebase_size` to get personalized recommendations for navigating your specific codebase.
+
 ## 🏗️ Architecture Highlights
 
 ### Performance Optimized
@@ -202,10 +269,16 @@ The server provides **11 powerful MCP tools** for intelligent codebase managemen
 
 ## 📖 Documentation
 
-- **[API Reference](docs/api-reference.md)** - Complete MCP tool documentation
-- **[Configuration Guide](docs/configuration.md)** - Setup and tuning options
-- **[Architecture Overview](docs/architecture.md)** - Technical deep dive
-- **[Contributing Guide](docs/contributing.md)** - Development workflow
+### 👤 For Users
+- **[Git Hook Setup Guide](docs/git-hook-setup.md)** - Automated code indexing setup
+- **[Configuration Guide](docs/configuration.md)** - Production deployment and tuning
+
+### 👨‍💻 For Developers  
+- **[API Reference](docs/api-reference.md)** - Complete MCP tool documentation with examples
+- **[Architecture Overview](docs/architecture.md)** - Technical deep dive into system design
+
+### 🤝 For Contributors
+- **[Contributing Guide](docs/contributing.md)** - Development setup and workflow guidelines
 
 ## 🚦 System Requirements
 
@@ -329,6 +402,39 @@ The server provides structured JSON logs for monitoring:
 }
 ```
 
+## 📋 Command Line Options
+
+### Server Mode (Default)
+```bash
+mcp-code-indexer [OPTIONS]
+
+Options:
+  --token-limit INT     Maximum tokens before recommending search (default: 32000)
+  --db-path PATH        SQLite database path (default: ~/.mcp-code-index/tracker.db)
+  --cache-dir PATH      Cache directory path (default: ~/.mcp-code-index/cache)
+  --log-level LEVEL     Logging level: DEBUG|INFO|WARNING|ERROR|CRITICAL (default: INFO)
+```
+
+### Git Hook Mode
+```bash
+mcp-code-indexer --githook [OPTIONS]
+
+# Automated analysis of git changes using OpenRouter API
+# Requires: OPENROUTER_API_KEY environment variable
+```
+
+### Utility Commands
+```bash
+# List all projects and branches
+mcp-code-indexer --getprojects
+
+# Execute MCP tool directly
+mcp-code-indexer --runcommand '{"method": "tools/call", "params": {...}}'
+
+# Export descriptions for a project
+mcp-code-indexer --dumpdescriptions PROJECT_ID [BRANCH]
+```
+
 ## 🛡️ Security Features
 
 - **Input validation** on all MCP tool parameters
@@ -339,10 +445,20 @@ The server provides structured JSON logs for monitoring:
 
 ## 🚀 Next Steps
 
-1. **[Read the API docs](docs/api-reference.md)** to understand available tools
-2. **[Check the configuration guide](docs/configuration.md)** for advanced setup
-3. **[Review the architecture](docs/architecture.md)** for technical details  
-4. **[Contribute](docs/contributing.md)** to help improve the project
+Ready to supercharge your AI agents with intelligent codebase navigation?
+
+### 👤 Getting Started
+1. **[Install and run your first server](#-quick-start)** - Get up and running in 2 minutes
+2. **[Set up git hooks](docs/git-hook-setup.md)** - Automate your workflow
+3. **[Configure for production](docs/configuration.md)** - Deploy for your team
+
+### 👨‍💻 For Developers
+4. **[Explore the API tools](docs/api-reference.md)** - Master all 11 MCP tools
+5. **[Understand the architecture](docs/architecture.md)** - Deep dive into the technical design
+
+### 🤝 Join the Community
+6. **[Contribute to the project](docs/contributing.md)** - Help make it even better
+7. **[Report issues on GitHub](https://github.com/fluffypony/mcp-code-indexer/issues)** - Share feedback and suggestions
 
 ## 🤝 Contributing
 
@@ -361,8 +477,14 @@ MIT License - see **[LICENSE](LICENSE)** for details.
 - **[Model Context Protocol](https://github.com/modelcontextprotocol/python-sdk)** - The foundation for tool integration
 - **[tiktoken](https://pypi.org/project/tiktoken/)** - Fast BPE tokenization  
 - **[aiosqlite](https://pypi.org/project/aiosqlite/)** - Async SQLite operations
+- **[aiohttp](https://pypi.org/project/aiohttp/)** - Async HTTP client for OpenRouter API
+- **[tenacity](https://pypi.org/project/tenacity/)** - Robust retry logic and rate limiting
 - **[Pydantic](https://pydantic.dev/)** - Data validation and settings
 
 ---
 
-**Ready to supercharge your AI agents with intelligent codebase navigation?** 🚀 [Install from PyPI](#install-from-pypi) or [explore the API docs](docs/api-reference.md)!
+**Transform how your AI agents understand code!** 🚀  
+
+🎯 **New User?** [Get started in 2 minutes](#-quick-start)  
+👨‍💻 **Developer?** [Explore the complete API](docs/api-reference.md)  
+🔧 **Production?** [Deploy with confidence](docs/configuration.md)

{mcp_code_indexer-1.2.3.dist-info → mcp_code_indexer-1.4.0.dist-info}/RECORD

@@ -1,24 +1,25 @@
-mcp_code_indexer/__init__.py,sha256=DIRa9PMADE0REdFtjY6OkI0-1-f1aFpkKPqgUbbLjNI,473
+mcp_code_indexer/__init__.py,sha256=i4UXNO0XCAzlG7V66eUuKQ9GCtuMeKAjxqVpB9Is_cI,473
 mcp_code_indexer/__main__.py,sha256=4Edinoe0ug43hobuLYcjTmGp2YJnlFYN4_8iKvUBJ0Q,213
 mcp_code_indexer/error_handler.py,sha256=cNSUFFrGBMLDv4qa78c7495L1wSl_dXCRbzCJOidx-Q,11590
 mcp_code_indexer/file_scanner.py,sha256=ctXeZMROgDThEtjzsANTK9TbK-fhTScMBd4iyuleBT4,11734
-mcp_code_indexer/logging_config.py,sha256=5L1cYIG8IAX91yCjc5pzkbO_KPt0bvm_ABHB53LBZjI,5184
-mcp_code_indexer/main.py,sha256=eRc0Vl3DVDGS5XtuPCDBArgmqcBIi92O97LbE8HYGGA,13601
+mcp_code_indexer/git_hook_handler.py,sha256=kp58PZUEU52H3ReqT84SC-BftwOo9WCjsAM6QHoj9rg,19448
+mcp_code_indexer/logging_config.py,sha256=yCGQD-xx9oobS-YctOFcaE1Q3iiuOj2E6cTfKHbh_wc,7358
+mcp_code_indexer/main.py,sha256=F1Ym1bSyatLk3jr9D2utqYZvWF7zq-bgOWjcmMZkvb4,30193
 mcp_code_indexer/merge_handler.py,sha256=lJR8eVq2qSrF6MW9mR3Fy8UzrNAaQ7RsI2FMNXne3vQ,14692
 mcp_code_indexer/token_counter.py,sha256=WrifOkbF99nWWHlRlhCHAB2KN7qr83GOHl7apE-hJcE,8460
 mcp_code_indexer/data/stop_words_english.txt,sha256=7Zdd9ameVgA6tN_zuXROvHXD4hkWeELVywPhb7FJEkw,6343
 mcp_code_indexer/database/__init__.py,sha256=aPq_aaRp0aSwOBIq9GkuMNjmLxA411zg2vhdrAuHm-w,38
-mcp_code_indexer/database/database.py,sha256=BRdV6XOn4yySHviAyNKG1faV_rzvsajU0ZppRGcvakg,26607
+mcp_code_indexer/database/database.py,sha256=c7-rtj7ZM2w9HcKphSjNccygwnTwDCiret79xbP1Jtg,31000
 mcp_code_indexer/database/models.py,sha256=_vCmJnPXZSiInRzyvs4c7QUWuNNW8qsOoDlGX8J-Gnk,7124
 mcp_code_indexer/middleware/__init__.py,sha256=p-mP0pMsfiU2yajCPvokCUxUEkh_lu4XJP1LyyMW2ug,220
 mcp_code_indexer/middleware/error_middleware.py,sha256=v6jaHmPxf3qerYdb85X1tHIXLxgcbybpitKVakFLQTA,10109
 mcp_code_indexer/server/__init__.py,sha256=16xMcuriUOBlawRqWNBk6niwrvtv_JD5xvI36X1Vsmk,41
-mcp_code_indexer/server/mcp_server.py,sha256=tYL-VJXJO-H41uyz6lDdZ6e21-sk__QkWJWFhbHSd1o,60284
+mcp_code_indexer/server/mcp_server.py,sha256=bRl5JTFWlQ0MrIulkts6fDws6kPqfy6kKoQdenMOk04,61290
 mcp_code_indexer/tiktoken_cache/9b5ad71b2ce5302211f9c61530b329a4922fc6a4,sha256=Ijkht27pm96ZW3_3OFE-7xAPtR0YyTWXoRO8_-hlsqc,1681126
 mcp_code_indexer/tools/__init__.py,sha256=m01mxML2UdD7y5rih_XNhNSCMzQTz7WQ_T1TeOcYlnE,49
-mcp_code_indexer-1.2.3.dist-info/licenses/LICENSE,sha256=JN9dyPPgYwH9C-UjYM7FLNZjQ6BF7kAzpF3_4PwY4rY,1086
-mcp_code_indexer-1.2.3.dist-info/METADATA,sha256=ogWMe_BwsnkgYX49tVqZqCOJofET_LtyRMiwQWLfIpc,12205
-mcp_code_indexer-1.2.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-mcp_code_indexer-1.2.3.dist-info/entry_points.txt,sha256=8HqWOw1Is7jOP1bvIgaSwouvT9z_Boe-9hd4NzyJOhY,68
-mcp_code_indexer-1.2.3.dist-info/top_level.txt,sha256=yKYCM-gMGt-cnupGfAhnZaoEsROLB6DQ1KFUuyKx4rw,17
-mcp_code_indexer-1.2.3.dist-info/RECORD,,
+mcp_code_indexer-1.4.0.dist-info/licenses/LICENSE,sha256=JN9dyPPgYwH9C-UjYM7FLNZjQ6BF7kAzpF3_4PwY4rY,1086
+mcp_code_indexer-1.4.0.dist-info/METADATA,sha256=C4obIa-pLTBrTg0k6OnU5LT6eSKajLWcen6rc5cgJFA,16721
+mcp_code_indexer-1.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mcp_code_indexer-1.4.0.dist-info/entry_points.txt,sha256=8HqWOw1Is7jOP1bvIgaSwouvT9z_Boe-9hd4NzyJOhY,68
+mcp_code_indexer-1.4.0.dist-info/top_level.txt,sha256=yKYCM-gMGt-cnupGfAhnZaoEsROLB6DQ1KFUuyKx4rw,17
+mcp_code_indexer-1.4.0.dist-info/RECORD,,