mcp-code-indexer 1.9.1__tar.gz → 2.0.1__tar.gz

{mcp_code_indexer-1.9.1/src/mcp_code_indexer.egg-info → mcp_code_indexer-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-code-indexer
-Version: 1.9.1
+Version: 2.0.1
 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
@@ -59,11 +59,11 @@ Dynamic: requires-python
 
 # MCP Code Indexer 🚀
 
-[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?10)](https://badge.fury.io/py/mcp-code-indexer)
-[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?10)](https://pypi.org/project/mcp-code-indexer/)
+[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?12)](https://badge.fury.io/py/mcp-code-indexer)
+[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?12)](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. Instead of repeatedly scanning files, agents get instant access to intelligent descriptions, semantic search, and context-aware recommendations.
+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.
 
 ## 🎯 What It Does
 
@@ -227,7 +227,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 **12 powerful MCP tools** for intelligent codebase management. Whether you're an AI agent or human developer, these tools make navigating code effortless.
 
 ### 🎯 For Everyone: Start Here
 - **`check_codebase_size`** - Get instant recommendations for how to navigate your codebase
@@ -246,6 +246,9 @@ The server provides **11 powerful MCP tools** for intelligent codebase managemen
 - **`merge_branch_descriptions`** - Two-phase merge with conflict resolution
 - **`update_codebase_overview`** - Create comprehensive codebase documentation
 
+### 🏥 For System Monitoring: Health & Performance
+- **`check_database_health`** - Real-time database health monitoring and diagnostics
+
 💡 **Pro Tip**: Always start with `check_codebase_size` to get personalized recommendations for navigating your specific codebase.
 
 ## 🔗 Git Hook Integration
@@ -272,24 +275,29 @@ See the **[Git Hook Setup Guide](docs/git-hook-setup.md)** for complete installa
 
 ## 🏗️ Architecture Highlights
 
-### Performance Optimized
-- **SQLite with WAL mode** for high-concurrency access
-- **Connection pooling** for efficient database operations
-- **FTS5 full-text search** with prefix indexing
+### 🚀 Performance Optimized
+- **SQLite with WAL mode** for high-concurrency access (800+ writes/sec)
+- **Smart connection pooling** with optimized pool size (3 connections default)
+- **FTS5 full-text search** with prefix indexing for sub-100ms queries
 - **Token-aware caching** to minimize expensive operations
+- **Write operation serialization** to eliminate database lock conflicts
 
-### Production Ready
-- **Comprehensive error handling** with structured JSON logging
+### 🛡️ Production Ready
+- **Database resilience features** with <2% error rate under high load
+- **Exponential backoff retry logic** with intelligent failure recovery
+- **Comprehensive health monitoring** with automatic pool refresh
+- **Structured JSON logging** with performance metrics tracking
 - **Async-first design** with proper resource cleanup
 - **MCP protocol compliant** with clean stdio streams
 - **Upstream inheritance** for fork workflows
 - **Git integration** with .gitignore support
 
-### Developer Friendly
-- **95%+ test coverage** with async support
-- **Integration tests** for complete workflows
-- **Performance benchmarks** for large codebases
+### 👨‍💻 Developer Friendly
+- **95%+ test coverage** with async support and concurrent access tests
+- **Integration tests** for complete workflows including database stress testing
+- **Performance benchmarks** for large codebases with resilience validation
 - **Clear error messages** with MCP protocol compliance
+- **Comprehensive configuration options** for production tuning
 
 ## 📖 Documentation
 
@@ -300,6 +308,11 @@ See the **[Git Hook Setup Guide](docs/git-hook-setup.md)** for complete installa
 ### 👨‍💻 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
+- **[Database Resilience Guide](docs/database-resilience.md)** - Advanced database optimization and monitoring
+
+### 🔧 For System Administrators
+- **[Performance Tuning Guide](docs/performance-tuning.md)** - High-concurrency deployment optimization
+- **[Monitoring & Diagnostics](docs/monitoring.md)** - Production monitoring setup and troubleshooting
 
 ### 🤝 For Contributors
 - **[Contributing Guide](docs/contributing.md)** - Development setup and workflow guidelines
@@ -321,6 +334,8 @@ Tested with codebases up to **10,000 files**:
 
 ## 🔧 Advanced Configuration
 
+### 👨‍💻 For Developers: Basic Configuration
+
 ```bash
 # Production setup with custom limits
 mcp-code-indexer \
@@ -334,6 +349,44 @@ export MCP_LOG_FORMAT=json
 mcp-code-indexer
 ```
 
+### 🔧 For System Administrators: Database Resilience Tuning
+
+Configure advanced database resilience features for high-concurrency environments:
+
+```bash
+# High-performance production deployment
+mcp-code-indexer \
+  --token-limit 64000 \
+  --db-path /data/mcp-index.db \
+  --cache-dir /var/cache/mcp \
+  --log-level INFO \
+  --db-pool-size 5 \
+  --db-retry-count 7 \
+  --db-timeout 15.0 \
+  --enable-wal-mode \
+  --health-check-interval 20.0
+
+# Environment variable configuration
+export DB_POOL_SIZE=5
+export DB_RETRY_COUNT=7
+export DB_TIMEOUT=15.0
+export DB_WAL_MODE=true
+export DB_HEALTH_CHECK_INTERVAL=20.0
+mcp-code-indexer --token-limit 64000
+```
+
+#### Configuration Options
+
+| Parameter | Default | Description | Use Case |
+|-----------|---------|-------------|----------|
+| `--db-pool-size` | 3 | Database connection pool size | Higher for more concurrent clients |
+| `--db-retry-count` | 5 | Max retry attempts for failed operations | Increase for unstable environments |
+| `--db-timeout` | 10.0 | Transaction timeout (seconds) | Increase for large operations |
+| `--enable-wal-mode` | true | Enable WAL mode for concurrency | Always enable for production |
+| `--health-check-interval` | 30.0 | Health monitoring interval (seconds) | Lower for faster issue detection |
+
+💡 **Performance Tip**: For environments with 10+ concurrent clients, use `--db-pool-size 5` and `--health-check-interval 15.0` for optimal throughput.
+
 ## 🤝 Integration Examples
 
 ### With AI Agents

{mcp_code_indexer-1.9.1 → mcp_code_indexer-2.0.1}/README.md

@@ -1,10 +1,10 @@
 # MCP Code Indexer 🚀
 
-[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?10)](https://badge.fury.io/py/mcp-code-indexer)
-[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?10)](https://pypi.org/project/mcp-code-indexer/)
+[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?12)](https://badge.fury.io/py/mcp-code-indexer)
+[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?12)](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. Instead of repeatedly scanning files, agents get instant access to intelligent descriptions, semantic search, and context-aware recommendations.
+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.
 
 ## 🎯 What It Does
 
@@ -168,7 +168,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 **12 powerful MCP tools** for intelligent codebase management. Whether you're an AI agent or human developer, these tools make navigating code effortless.
 
 ### 🎯 For Everyone: Start Here
 - **`check_codebase_size`** - Get instant recommendations for how to navigate your codebase
@@ -187,6 +187,9 @@ The server provides **11 powerful MCP tools** for intelligent codebase managemen
 - **`merge_branch_descriptions`** - Two-phase merge with conflict resolution
 - **`update_codebase_overview`** - Create comprehensive codebase documentation
 
+### 🏥 For System Monitoring: Health & Performance
+- **`check_database_health`** - Real-time database health monitoring and diagnostics
+
 💡 **Pro Tip**: Always start with `check_codebase_size` to get personalized recommendations for navigating your specific codebase.
 
 ## 🔗 Git Hook Integration
@@ -213,24 +216,29 @@ See the **[Git Hook Setup Guide](docs/git-hook-setup.md)** for complete installa
 
 ## 🏗️ Architecture Highlights
 
-### Performance Optimized
-- **SQLite with WAL mode** for high-concurrency access
-- **Connection pooling** for efficient database operations
-- **FTS5 full-text search** with prefix indexing
+### 🚀 Performance Optimized
+- **SQLite with WAL mode** for high-concurrency access (800+ writes/sec)
+- **Smart connection pooling** with optimized pool size (3 connections default)
+- **FTS5 full-text search** with prefix indexing for sub-100ms queries
 - **Token-aware caching** to minimize expensive operations
+- **Write operation serialization** to eliminate database lock conflicts
 
-### Production Ready
-- **Comprehensive error handling** with structured JSON logging
+### 🛡️ Production Ready
+- **Database resilience features** with <2% error rate under high load
+- **Exponential backoff retry logic** with intelligent failure recovery
+- **Comprehensive health monitoring** with automatic pool refresh
+- **Structured JSON logging** with performance metrics tracking
 - **Async-first design** with proper resource cleanup
 - **MCP protocol compliant** with clean stdio streams
 - **Upstream inheritance** for fork workflows
 - **Git integration** with .gitignore support
 
-### Developer Friendly
-- **95%+ test coverage** with async support
-- **Integration tests** for complete workflows
-- **Performance benchmarks** for large codebases
+### 👨‍💻 Developer Friendly
+- **95%+ test coverage** with async support and concurrent access tests
+- **Integration tests** for complete workflows including database stress testing
+- **Performance benchmarks** for large codebases with resilience validation
 - **Clear error messages** with MCP protocol compliance
+- **Comprehensive configuration options** for production tuning
 
 ## 📖 Documentation
 
@@ -241,6 +249,11 @@ See the **[Git Hook Setup Guide](docs/git-hook-setup.md)** for complete installa
 ### 👨‍💻 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
+- **[Database Resilience Guide](docs/database-resilience.md)** - Advanced database optimization and monitoring
+
+### 🔧 For System Administrators
+- **[Performance Tuning Guide](docs/performance-tuning.md)** - High-concurrency deployment optimization
+- **[Monitoring & Diagnostics](docs/monitoring.md)** - Production monitoring setup and troubleshooting
 
 ### 🤝 For Contributors
 - **[Contributing Guide](docs/contributing.md)** - Development setup and workflow guidelines
@@ -262,6 +275,8 @@ Tested with codebases up to **10,000 files**:
 
 ## 🔧 Advanced Configuration
 
+### 👨‍💻 For Developers: Basic Configuration
+
 ```bash
 # Production setup with custom limits
 mcp-code-indexer \
@@ -275,6 +290,44 @@ export MCP_LOG_FORMAT=json
 mcp-code-indexer
 ```
 
+### 🔧 For System Administrators: Database Resilience Tuning
+
+Configure advanced database resilience features for high-concurrency environments:
+
+```bash
+# High-performance production deployment
+mcp-code-indexer \
+  --token-limit 64000 \
+  --db-path /data/mcp-index.db \
+  --cache-dir /var/cache/mcp \
+  --log-level INFO \
+  --db-pool-size 5 \
+  --db-retry-count 7 \
+  --db-timeout 15.0 \
+  --enable-wal-mode \
+  --health-check-interval 20.0
+
+# Environment variable configuration
+export DB_POOL_SIZE=5
+export DB_RETRY_COUNT=7
+export DB_TIMEOUT=15.0
+export DB_WAL_MODE=true
+export DB_HEALTH_CHECK_INTERVAL=20.0
+mcp-code-indexer --token-limit 64000
+```
+
+#### Configuration Options
+
+| Parameter | Default | Description | Use Case |
+|-----------|---------|-------------|----------|
+| `--db-pool-size` | 3 | Database connection pool size | Higher for more concurrent clients |
+| `--db-retry-count` | 5 | Max retry attempts for failed operations | Increase for unstable environments |
+| `--db-timeout` | 10.0 | Transaction timeout (seconds) | Increase for large operations |
+| `--enable-wal-mode` | true | Enable WAL mode for concurrency | Always enable for production |
+| `--health-check-interval` | 30.0 | Health monitoring interval (seconds) | Lower for faster issue detection |
+
+💡 **Performance Tip**: For environments with 10+ concurrent clients, use `--db-pool-size 5` and `--health-check-interval 15.0` for optimal throughput.
+
 ## 🤝 Integration Examples
 
 ### With AI Agents

{mcp_code_indexer-1.9.1 → mcp_code_indexer-2.0.1}/docs/api-reference.md

@@ -21,6 +21,8 @@ Complete reference for all 11 MCP tools provided by the Code Indexer server. Whe
 - [Advanced Features](#advanced-features)
   - [merge_branch_descriptions](#merge_branch_descriptions)
   - [update_codebase_overview](#update_codebase_overview)
+- [System Monitoring](#system-monitoring)
+  - [check_database_health](#check_database_health)
 - [Common Parameters](#common-parameters)
 - [Error Handling](#error-handling)
 
@@ -638,6 +640,135 @@ const result = await mcp.callTool("merge_branch_descriptions", {
 
 ---
 
+## System Monitoring
+
+### check_database_health
+
+🏥 **Real-time database health monitoring and diagnostics**
+
+Monitor database performance, connection pool status, and system health in production environments. Essential for maintaining high-availability deployments and troubleshooting performance issues.
+
+#### Parameters
+
+```typescript
+interface CheckDatabaseHealthParams {
+  // No parameters required
+}
+```
+
+#### Response
+
+```typescript
+interface CheckDatabaseHealthResponse {
+  health_status: {
+    overall_health: 'healthy' | 'degraded' | 'unhealthy';
+    database: {
+      pool_healthy: boolean;
+      active_connections: number;
+      total_connections: number;
+      failed_connections: number;
+      avg_response_time_ms: number;
+      wal_size_mb: number;
+    };
+    performance: {
+      current_throughput: number;
+      target_throughput: number;
+      p95_latency_ms: number;
+      error_rate: number;
+      operations_last_minute: number;
+    };
+    system: {
+      memory_usage_mb: number;
+      cpu_usage_percent: number;
+      disk_usage_percent: number;
+      uptime_seconds: number;
+    };
+  };
+  recommendations: string[];
+  last_check: string;  // ISO timestamp
+}
+```
+
+#### Usage Examples
+
+##### 👨‍💻 Basic Health Check
+
+```python
+# Check current system health
+health_result = await mcp_client.call_tool("check_database_health", {})
+
+if health_result["health_status"]["overall_health"] != "healthy":
+    print("⚠️ System health issue detected!")
+    for rec in health_result["recommendations"]:
+        print(f"💡 {rec}")
+```
+
+##### 🔧 Production Monitoring
+
+```python
+# Automated health monitoring
+async def monitor_health():
+    while True:
+        health = await mcp_client.call_tool("check_database_health", {})
+        
+        # Check critical metrics
+        db_status = health["health_status"]["database"]
+        if db_status["failed_connections"] > 2:
+            send_alert("Database connection failures detected")
+        
+        perf_status = health["health_status"]["performance"]
+        if perf_status["error_rate"] > 0.05:
+            send_alert(f"High error rate: {perf_status['error_rate']:.2%}")
+        
+        await asyncio.sleep(30)  # Check every 30 seconds
+```
+
+##### 📊 Performance Dashboard
+
+```python
+# Gather metrics for dashboard
+health_data = await mcp_client.call_tool("check_database_health", {})
+
+metrics = {
+    'throughput': health_data["health_status"]["performance"]["current_throughput"],
+    'latency_p95': health_data["health_status"]["performance"]["p95_latency_ms"],
+    'error_rate': health_data["health_status"]["performance"]["error_rate"],
+    'pool_utilization': (
+        health_data["health_status"]["database"]["active_connections"] /
+        health_data["health_status"]["database"]["total_connections"]
+    )
+}
+
+# Send to monitoring system
+await send_metrics_to_grafana(metrics)
+```
+
+#### 🎯 Use Cases
+
+- **Production Monitoring**: Continuous health checks in production deployments
+- **Performance Debugging**: Identify bottlenecks and optimization opportunities  
+- **Capacity Planning**: Monitor resource utilization trends
+- **Incident Response**: Quick diagnostics during performance issues
+- **Load Testing**: Validate system behavior under stress
+
+#### 🔍 Health Status Indicators
+
+| Status | Database | Performance | System | Action Required |
+|--------|----------|-------------|--------|-----------------|
+| `healthy` | All connections working | <2% error rate | <80% resource usage | None |
+| `degraded` | Some connection issues | 2-5% error rate | 80-90% resource usage | Monitor closely |
+| `unhealthy` | Pool failures | >5% error rate | >90% resource usage | Immediate action |
+
+#### 🚨 Common Issues & Recommendations
+
+The tool provides intelligent recommendations based on current system state:
+
+- **"Increase connection pool size"** - When pool utilization >90%
+- **"Enable WAL mode for better concurrency"** - When lock contention detected
+- **"Consider scaling resources"** - When system resources >85%
+- **"Check for database corruption"** - When integrity issues found
+- **"Review recent configuration changes"** - When performance regression detected
+
 ## Common Parameters
 
 All tools support these optional parameters for project identification: