mcp-code-indexer 4.2.14__tar.gz → 4.2.16__tar.gz

{mcp_code_indexer-4.2.14 → mcp_code_indexer-4.2.16}/PKG-INFO

@@ -1,8 +1,9 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: mcp-code-indexer
-Version: 4.2.14
+Version: 4.2.16
 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.
 License: MIT
+License-File: LICENSE
 Keywords: mcp,model-context-protocol,code-indexer,ai-tools,codebase-navigation,file-descriptions,llm-tools
 Author: MCP Code Indexer Contributors
 Maintainer: MCP Code Indexer Contributors
@@ -36,11 +37,11 @@ Requires-Dist: pyyaml (>=6.0)
 Requires-Dist: tenacity (>=8.0.0)
 Requires-Dist: tiktoken (>=0.9.0)
 Requires-Dist: tomli (>=1.2.0) ; python_version < "3.11"
-Requires-Dist: tree-sitter (>=0.25.0)
+Requires-Dist: tree-sitter (>=0.21.0)
 Requires-Dist: turbopuffer (>=0.6.0)
 Requires-Dist: uvicorn (>=0.24.0)
 Requires-Dist: voyageai (>=0.3.0)
-Requires-Dist: watchdog (>=6.0.0)
+Requires-Dist: watchdog (>=4.0.0)
 Project-URL: Documentation, https://github.com/fluffypony/mcp-code-indexer/blob/main/README.md
 Project-URL: Homepage, https://github.com/fluffypony/mcp-code-indexer
 Project-URL: Repository, https://github.com/fluffypony/mcp-code-indexer
@@ -48,8 +49,8 @@ Description-Content-Type: text/markdown
 
 # MCP Code Indexer 🚀
 
-[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?61)](https://badge.fury.io/py/mcp-code-indexer)
-[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?61)](https://pypi.org/project/mcp-code-indexer/)
+[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?63)](https://badge.fury.io/py/mcp-code-indexer)
+[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?63)](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 revolutionizes how AI agents navigate and understand codebases. Built for high-concurrency environments with advanced database resilience, the server provides instant access to intelligent descriptions, semantic search, and context-aware recommendations while maintaining 800+ writes/sec throughput.
@@ -256,6 +257,7 @@ mcp-code-indexer --vector --http --port 8080
 
 Vector Mode adds powerful new MCP tools:
 - `vector_search` - Semantic code search across projects
+- `find_similar_code` - Find code similar to a given snippet or file section
 - `similarity_search` - Find similar code patterns  
 - `dependency_search` - Discover code relationships
 - `vector_status` - Monitor indexing progress
@@ -316,7 +318,7 @@ mypy src/
 
 ## 🛠️ MCP Tools Available
 
-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.
+The server provides **13 powerful MCP tools** for intelligent codebase management. Whether you're an AI agent or human developer, these tools make navigating code effortless.
 
 ### 🎯 Essential Tools (Start Here)
 | Tool | Purpose | When to Use |
@@ -339,6 +341,7 @@ The server provides **11 powerful MCP tools** for intelligent codebase managemen
 | **`get_word_frequency`** | Technical vocabulary analysis | Domain understanding |
 | **`update_codebase_overview`** | Create project documentation | Architecture documentation |
 | **`search_codebase_overview`** | Search in project overviews | Finding specific topics |
+| **`find_similar_code`** | Find code similar to snippet/section | Code pattern discovery (Vector Mode) |
 
 ### 🏥 System Health
 | Tool | Purpose | For |
@@ -347,7 +350,7 @@ The server provides **11 powerful MCP tools** for intelligent codebase managemen
 
 💡 **Pro Tip**: Always start with `check_codebase_size` to get personalized recommendations for navigating your specific codebase.
 
-**📖 Complete API Documentation**: [View all 11 tools with examples →](docs/api-reference.md)
+**📖 Complete API Documentation**: [View all 13 tools with examples →](docs/api-reference.md)
 
 ## 🔗 Git Hook Integration
 
@@ -411,7 +414,7 @@ Comprehensive documentation organized by user journey and expertise level.
 | Guide | Purpose | Time Investment |
 |-------|---------|-----------------|
 | **[Quick Start](#-quick-start)** | Install and run your first server | 2 minutes |
-| **[API Reference](docs/api-reference.md)** | Master all 11 MCP tools | 15 minutes |
+| **[API Reference](docs/api-reference.md)** | Master all 13 MCP tools | 15 minutes |
 | **[HTTP API Reference](docs/http-api.md)** | REST API for web applications | 10 minutes |
 | **[Q&A Interface](docs/qa-interface.md)** | AI-powered codebase analysis | 8 minutes |
 | **[Git Hook Setup](docs/git-hook-setup.md)** | Automate your workflow | 5 minutes |
@@ -435,7 +438,7 @@ Comprehensive documentation organized by user journey and expertise level.
 ### 📋 Quick References
 - **[Examples & Integrations](examples/)** - Ready-to-use configurations
 - **[Troubleshooting](#🚨-troubleshooting)** - Common issues & solutions
-- **[API Tools Summary](#🛠️-mcp-tools-available)** - All 11 tools at a glance
+- **[API Tools Summary](#🛠️-mcp-tools-available)** - All 13 tools at a glance
 
 **📚 Reading Paths:**
 - **New to MCP Code Indexer?** Quick Start → API Reference → HTTP API → Q&A Interface

{mcp_code_indexer-4.2.14 → mcp_code_indexer-4.2.16}/README.md

@@ -1,7 +1,7 @@
 # MCP Code Indexer 🚀
 
-[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?61)](https://badge.fury.io/py/mcp-code-indexer)
-[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?61)](https://pypi.org/project/mcp-code-indexer/)
+[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?63)](https://badge.fury.io/py/mcp-code-indexer)
+[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?63)](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 revolutionizes how AI agents navigate and understand codebases. Built for high-concurrency environments with advanced database resilience, the server provides instant access to intelligent descriptions, semantic search, and context-aware recommendations while maintaining 800+ writes/sec throughput.
@@ -208,6 +208,7 @@ mcp-code-indexer --vector --http --port 8080
 
 Vector Mode adds powerful new MCP tools:
 - `vector_search` - Semantic code search across projects
+- `find_similar_code` - Find code similar to a given snippet or file section
 - `similarity_search` - Find similar code patterns  
 - `dependency_search` - Discover code relationships
 - `vector_status` - Monitor indexing progress
@@ -268,7 +269,7 @@ mypy src/
 
 ## 🛠️ MCP Tools Available
 
-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.
+The server provides **13 powerful MCP tools** for intelligent codebase management. Whether you're an AI agent or human developer, these tools make navigating code effortless.
 
 ### 🎯 Essential Tools (Start Here)
 | Tool | Purpose | When to Use |
@@ -291,6 +292,7 @@ The server provides **11 powerful MCP tools** for intelligent codebase managemen
 | **`get_word_frequency`** | Technical vocabulary analysis | Domain understanding |
 | **`update_codebase_overview`** | Create project documentation | Architecture documentation |
 | **`search_codebase_overview`** | Search in project overviews | Finding specific topics |
+| **`find_similar_code`** | Find code similar to snippet/section | Code pattern discovery (Vector Mode) |
 
 ### 🏥 System Health
 | Tool | Purpose | For |
@@ -299,7 +301,7 @@ The server provides **11 powerful MCP tools** for intelligent codebase managemen
 
 💡 **Pro Tip**: Always start with `check_codebase_size` to get personalized recommendations for navigating your specific codebase.
 
-**📖 Complete API Documentation**: [View all 11 tools with examples →](docs/api-reference.md)
+**📖 Complete API Documentation**: [View all 13 tools with examples →](docs/api-reference.md)
 
 ## 🔗 Git Hook Integration
 
@@ -363,7 +365,7 @@ Comprehensive documentation organized by user journey and expertise level.
 | Guide | Purpose | Time Investment |
 |-------|---------|-----------------|
 | **[Quick Start](#-quick-start)** | Install and run your first server | 2 minutes |
-| **[API Reference](docs/api-reference.md)** | Master all 11 MCP tools | 15 minutes |
+| **[API Reference](docs/api-reference.md)** | Master all 13 MCP tools | 15 minutes |
 | **[HTTP API Reference](docs/http-api.md)** | REST API for web applications | 10 minutes |
 | **[Q&A Interface](docs/qa-interface.md)** | AI-powered codebase analysis | 8 minutes |
 | **[Git Hook Setup](docs/git-hook-setup.md)** | Automate your workflow | 5 minutes |
@@ -387,7 +389,7 @@ Comprehensive documentation organized by user journey and expertise level.
 ### 📋 Quick References
 - **[Examples & Integrations](examples/)** - Ready-to-use configurations
 - **[Troubleshooting](#🚨-troubleshooting)** - Common issues & solutions
-- **[API Tools Summary](#🛠️-mcp-tools-available)** - All 11 tools at a glance
+- **[API Tools Summary](#🛠️-mcp-tools-available)** - All 13 tools at a glance
 
 **📚 Reading Paths:**
 - **New to MCP Code Indexer?** Quick Start → API Reference → HTTP API → Q&A Interface

{mcp_code_indexer-4.2.14 → mcp_code_indexer-4.2.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "mcp-code-indexer"
-version = "4.2.14"
+version = "4.2.16"
 description = "MCP server that tracks file descriptions across codebases, enabling AI agents to efficiently navigate and understand code through searchable summaries and token-aware overviews."
 authors = ["MCP Code Indexer Contributors"]
 maintainers = ["MCP Code Indexer Contributors"]
@@ -61,8 +61,8 @@ python-multipart = ">=0.0.6"
 # Vector mode dependencies (always included)
 voyageai = ">=0.3.0"
 turbopuffer = ">=0.6.0"
-tree-sitter = ">=0.25.0"
-watchdog = ">=6.0.0"
+tree-sitter = ">=0.21.0"
+watchdog = ">=4.0.0"
 pyyaml = ">=6.0"
 
 [tool.poetry.group.dev.dependencies]

{mcp_code_indexer-4.2.14 → mcp_code_indexer-4.2.16}/src/mcp_code_indexer/database/database.py

@@ -27,9 +27,11 @@ from mcp_code_indexer.database.exceptions import (
 )
 from mcp_code_indexer.database.models import (
     FileDescription,
+    IndexMeta,
     Project,
     ProjectOverview,
     SearchResult,
+    SyncStatus,
     WordFrequencyResult,
     WordFrequencyTerm,
 )
@@ -315,12 +317,10 @@ class DatabaseManager:
         self, operation_name: str = "write_operation"
     ) -> AsyncIterator[aiosqlite.Connection]:
         """
-        Get a database connection with write serialization and automatic
-        retry logic.
+        Get a database connection with write serialization.
 
-        This uses the new RetryExecutor to properly handle retry logic
-        without the broken yield-in-retry-loop pattern that caused
-        generator errors.
+        Ensures the write lock is held throughout the duration of the context
+        to prevent race conditions and database locking errors.
 
         Args:
             operation_name: Name of the operation for logging and
@@ -331,43 +331,10 @@ class DatabaseManager:
                 "DatabaseManager not initialized - call initialize() first"
             )
 
-        async def get_write_connection() -> aiosqlite.Connection:
-            """Inner function to get connection - retried by executor."""
-            if self._write_lock is None:
-                raise RuntimeError("Write lock not initialized")
-            async with self._write_lock:
-                async with self.get_connection() as conn:
-                    return conn
-
-        try:
-            # Use retry executor to handle connection acquisition with retries
-            connection = await self._retry_executor.execute_with_retry(
-                get_write_connection, operation_name
-            )
-
-            try:
-                yield connection
-
-                # Success - retry executor handles all failure tracking
-
-            except Exception:
-                # Error handling is managed by the retry executor
-                raise
-
-        except DatabaseError:
-            # Re-raise our custom database errors as-is
-            raise
-        except Exception as e:
-            # Classify and wrap other exceptions
-            classified_error = classify_sqlite_error(e, operation_name)
-            logger.error(
-                (
-                    f"Database operation '{operation_name}' failed: "
-                    f"{classified_error.message}"
-                ),
-                extra={"structured_data": classified_error.to_dict()},
-            )
-            raise classified_error
+        # Acquire lock for exclusive write access - hold it for entire context
+        async with self._write_lock:
+            async with self.get_connection() as conn:
+                yield conn
 
     def get_database_stats(self) -> Dict[str, Any]:
         """
@@ -740,6 +707,25 @@ class DatabaseManager:
             await db.commit()
             logger.debug(f"Updated project: {project.id}")
 
+    async def set_project_vector_mode(self, project_id: str, enabled: bool) -> None:
+        """Set the vector_mode for a specific project."""
+        async with self.get_write_connection_with_retry(
+            "set_project_vector_mode"
+        ) as db:
+            await db.execute(
+                "UPDATE projects SET vector_mode = ? WHERE id = ?",
+                (int(enabled), project_id),
+            )
+
+            # Check if the project was actually updated
+            cursor = await db.execute("SELECT changes()")
+            changes = await cursor.fetchone()
+            if changes[0] == 0:
+                raise ValueError(f"Project not found: {project_id}")
+
+            await db.commit()
+            logger.debug(f"Set vector_mode={enabled} for project: {project_id}")
+
     async def get_all_projects(self) -> List[Project]:
         """Get all projects in the database."""
         async with self.get_connection() as db:
@@ -795,12 +781,19 @@ class DatabaseManager:
         ) as db:
             await db.execute(
                 """
-                INSERT OR REPLACE INTO file_descriptions
+                INSERT INTO file_descriptions
                 (
                     project_id, file_path, description, file_hash, last_modified,
                     version, source_project_id, to_be_cleaned
                 )
                 VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT(project_id, file_path) DO UPDATE SET
+                    description=excluded.description,
+                    file_hash=excluded.file_hash,
+                    last_modified=excluded.last_modified,
+                    version=excluded.version,
+                    source_project_id=excluded.source_project_id,
+                    to_be_cleaned=excluded.to_be_cleaned
                 """,
                 (
                     file_desc.project_id,
@@ -898,12 +891,19 @@ class DatabaseManager:
 
             await conn.executemany(
                 """
-                INSERT OR REPLACE INTO file_descriptions
+                INSERT INTO file_descriptions
                 (
                     project_id, file_path, description, file_hash, last_modified,
                     version, source_project_id, to_be_cleaned
                 )
                 VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT(project_id, file_path) DO UPDATE SET
+                    description=excluded.description,
+                    file_hash=excluded.file_hash,
+                    last_modified=excluded.last_modified,
+                    version=excluded.version,
+                    source_project_id=excluded.source_project_id,
+                    to_be_cleaned=excluded.to_be_cleaned
                 """,
                 data,
             )
@@ -1067,10 +1067,8 @@ class DatabaseManager:
         Returns:
             List of file paths that were marked for cleanup
         """
-        removed_files: List[str] = []
-
-        async def cleanup_operation(conn: aiosqlite.Connection) -> List[str]:
-            # Get all active file descriptions for this project
+        # 1. Get all active file paths (fast DB read)
+        async with self.get_connection() as conn:
             cursor = await conn.execute(
                 (
                     "SELECT file_path FROM file_descriptions WHERE "
@@ -1078,46 +1076,29 @@ class DatabaseManager:
                 ),
                 (project_id,),
             )
-
             rows = await cursor.fetchall()
+            file_paths = [row["file_path"] for row in rows]
 
-            # Check which files no longer exist
-            to_remove = []
-            for row in rows:
-                file_path = row["file_path"]
+        # 2. Check existence on disk (blocking IO - run in executor)
+        def find_removed_files() -> List[str]:
+            missing = []
+            for file_path in file_paths:
                 full_path = project_root / file_path
-
                 if not full_path.exists():
-                    to_remove.append(file_path)
-
-            # Mark descriptions for cleanup instead of deleting
-            if to_remove:
-                import time
-
-                cleanup_timestamp = int(time.time())
-                await conn.executemany(
-                    (
-                        "UPDATE file_descriptions SET to_be_cleaned = ? WHERE "
-                        "project_id = ? AND file_path = ?"
-                    ),
-                    [(cleanup_timestamp, project_id, path) for path in to_remove],
-                )
-                logger.info(
-                    (
-                        f"Marked {len(to_remove)} missing files for cleanup "
-                        f"from {project_id}"
-                    )
-                )
+                    missing.append(file_path)
+            return missing
 
-            return to_remove
+        loop = asyncio.get_running_loop()
+        to_remove = await loop.run_in_executor(None, find_removed_files)
 
-        removed_files = await self.execute_transaction_with_retry(
-            cleanup_operation,
-            f"cleanup_missing_files_{project_id}",
-            timeout_seconds=60.0,  # Longer timeout for file system operations
-        )
+        # 3. Mark for cleanup (fast DB write)
+        if to_remove:
+            await self.cleanup_manager.mark_files_for_cleanup(project_id, to_remove)
+            logger.info(
+                f"Marked {len(to_remove)} missing files for cleanup from {project_id}"
+            )
 
-        return removed_files
+        return to_remove
 
     async def analyze_word_frequency(
         self, project_id: str, limit: int = 200
@@ -1139,7 +1120,7 @@ class DatabaseManager:
         stop_words_path = (
             Path(__file__).parent.parent / "data" / "stop_words_english.txt"
         )
-        stop_words = set()
+        stop_words: set = set()
 
         if stop_words_path.exists():
             with open(stop_words_path, "r", encoding="utf-8") as f:
@@ -1186,8 +1167,8 @@ class DatabaseManager:
         }
         stop_words.update(programming_keywords)
 
+        # Get all descriptions for this project (fast DB read)
         async with self.get_connection() as db:
-            # Get all descriptions for this project
             cursor = await db.execute(
                 (
                     "SELECT description FROM file_descriptions WHERE "
@@ -1195,11 +1176,13 @@ class DatabaseManager:
                 ),
                 (project_id,),
             )
-
             rows = await cursor.fetchall()
+            descriptions = [row["description"] for row in rows]
 
+        # Process word frequency in executor (CPU-bound work)
+        def process_word_frequency() -> WordFrequencyResult:
             # Combine all descriptions
-            all_text = " ".join(row["description"] for row in rows)
+            all_text = " ".join(descriptions)
 
             # Tokenize and filter
             words = re.findall(r"\b[a-zA-Z]{2,}\b", all_text.lower())
@@ -1220,6 +1203,9 @@ class DatabaseManager:
                 total_unique_terms=len(word_counts),
             )
 
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, process_word_frequency)
+
     async def cleanup_empty_projects(self) -> int:
         """
         Remove projects that have no file descriptions and no project overview.
@@ -1320,6 +1306,186 @@ class DatabaseManager:
                 "files": file_descriptions,
             }
 
+    # IndexMeta operations
+    async def create_index_meta(self, index_meta: IndexMeta) -> None:
+        """Create or update index metadata for a project."""
+        async with self.get_write_connection_with_retry("create_index_meta") as db:
+            await db.execute(
+                """
+                INSERT OR REPLACE INTO index_meta (
+                    project_id, total_chunks, indexed_chunks, total_files, indexed_files,
+                    last_sync, sync_status, error_message, queue_depth, processing_rate,
+                    estimated_completion, metadata, created, last_modified
+                )
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    index_meta.project_id,
+                    index_meta.total_chunks,
+                    index_meta.indexed_chunks,
+                    index_meta.total_files,
+                    index_meta.indexed_files,
+                    index_meta.last_sync,
+                    index_meta.sync_status.value,
+                    index_meta.error_message,
+                    index_meta.queue_depth,
+                    index_meta.processing_rate,
+                    index_meta.estimated_completion,
+                    json.dumps(index_meta.metadata),
+                    index_meta.created,
+                    index_meta.last_modified,
+                ),
+            )
+            await db.commit()
+            logger.debug(
+                f"Created/updated index metadata for project: {index_meta.project_id}"
+            )
+
+    async def update_index_meta(self, index_meta: IndexMeta) -> None:
+        """Update existing index metadata for a project."""
+        async with self.get_write_connection_with_retry("update_index_meta") as db:
+            await db.execute(
+                """
+                UPDATE index_meta
+                SET total_chunks = ?, indexed_chunks = ?, total_files = ?, indexed_files = ?,
+                    last_sync = ?, sync_status = ?, error_message = ?, queue_depth = ?,
+                    processing_rate = ?, estimated_completion = ?, metadata = ?, last_modified = ?
+                WHERE project_id = ?
+                """,
+                (
+                    index_meta.total_chunks,
+                    index_meta.indexed_chunks,
+                    index_meta.total_files,
+                    index_meta.indexed_files,
+                    index_meta.last_sync,
+                    index_meta.sync_status.value,
+                    index_meta.error_message,
+                    index_meta.queue_depth,
+                    index_meta.processing_rate,
+                    index_meta.estimated_completion,
+                    json.dumps(index_meta.metadata),
+                    index_meta.last_modified,
+                    index_meta.project_id,
+                ),
+            )
+
+            # Check if the project was actually updated
+            cursor = await db.execute("SELECT changes()")
+            changes = await cursor.fetchone()
+            if changes[0] == 0:
+                raise ValueError(
+                    f"Index metadata not found for project: {index_meta.project_id}"
+                )
+
+            await db.commit()
+            logger.debug(f"Updated index metadata for project: {index_meta.project_id}")
+
+    async def get_index_meta(self, project_id: str) -> Optional[IndexMeta]:
+        """Retrieve index metadata for a project."""
+        async with self.get_connection() as db:
+            cursor = await db.execute(
+                "SELECT * FROM index_meta WHERE project_id = ?", (project_id,)
+            )
+            row = await cursor.fetchone()
+
+            if row:
+                # Convert row to dict for easier field access
+                row_dict = dict(row)
+
+                # Parse JSON metadata field
+                metadata = (
+                    json.loads(row_dict["metadata"]) if row_dict["metadata"] else {}
+                )
+
+                # Parse datetime fields
+                created = (
+                    datetime.fromisoformat(row_dict["created"])
+                    if row_dict["created"]
+                    else datetime.utcnow()
+                )
+                last_modified = (
+                    datetime.fromisoformat(row_dict["last_modified"])
+                    if row_dict["last_modified"]
+                    else datetime.utcnow()
+                )
+                last_sync = (
+                    datetime.fromisoformat(row_dict["last_sync"])
+                    if row_dict["last_sync"]
+                    else None
+                )
+                estimated_completion = (
+                    datetime.fromisoformat(row_dict["estimated_completion"])
+                    if row_dict["estimated_completion"]
+                    else None
+                )
+
+                return IndexMeta(
+                    id=row_dict["id"],
+                    project_id=row_dict["project_id"],
+                    total_chunks=row_dict["total_chunks"],
+                    indexed_chunks=row_dict["indexed_chunks"],
+                    total_files=row_dict["total_files"],
+                    indexed_files=row_dict["indexed_files"],
+                    last_sync=last_sync,
+                    sync_status=row_dict["sync_status"],
+                    error_message=row_dict["error_message"],
+                    queue_depth=row_dict["queue_depth"],
+                    processing_rate=row_dict["processing_rate"],
+                    estimated_completion=estimated_completion,
+                    metadata=metadata,
+                    created=created,
+                    last_modified=last_modified,
+                )
+            return None
+
+    async def get_or_create_index_meta(self, project_id: str, **kwargs) -> IndexMeta:
+        """
+        Get existing index metadata or create new one with default values.
+        
+        Args:
+            project_id: Project identifier
+            **kwargs: Optional fields to override defaults when creating new metadata
+            
+        Returns:
+            IndexMeta object (existing or newly created)
+        """
+        # Try to get existing metadata first
+        existing_meta = await self.get_index_meta(project_id)
+        if existing_meta:
+            return existing_meta
+        
+        # Create new metadata with defaults, allowing kwargs to override
+        default_metadata = {
+            "project_id": project_id,
+            "total_chunks": 0,
+            "indexed_chunks": 0,
+            "total_files": 0,
+            "indexed_files": 0,
+            "last_sync": None,
+            "sync_status": SyncStatus.PENDING,
+            "error_message": None,
+            "queue_depth": 0,
+            "processing_rate": 0.0,
+            "estimated_completion": None,
+            "metadata": {},
+        }
+        
+        # Override defaults with provided kwargs
+        default_metadata.update(kwargs)
+        
+        # Create the IndexMeta object
+        new_meta = IndexMeta(**default_metadata)
+        
+        # Store it in the database
+        await self.create_index_meta(new_meta)
+        
+        # Return the created metadata (fetch it back to get the assigned ID)
+        result = await self.get_index_meta(project_id)
+        if result is None:
+            raise DatabaseError(f"Failed to create index metadata for project: {project_id}")
+        
+        return result
+
     # Cleanup operations
 
     @property