mcp-code-indexer 3.6.0__tar.gz → 4.0.1__tar.gz

{mcp_code_indexer-3.6.0 → mcp_code_indexer-4.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: mcp-code-indexer
-Version: 3.6.0
+Version: 4.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.
 License: MIT
 Keywords: mcp,model-context-protocol,code-indexer,ai-tools,codebase-navigation,file-descriptions,llm-tools
@@ -43,8 +43,8 @@ Description-Content-Type: text/markdown
 
 # MCP Code Indexer 🚀
 
-[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?42)](https://badge.fury.io/py/mcp-code-indexer)
-[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?42)](https://pypi.org/project/mcp-code-indexer/)
+[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?44)](https://badge.fury.io/py/mcp-code-indexer)
+[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?44)](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.
@@ -80,6 +80,43 @@ mcp-code-indexer
 # See API Reference for complete tool documentation
 ```
 
+### 🌐 For Web Applications
+
+Enable HTTP/REST API access for browser-based applications:
+
+```bash
+# Start HTTP server with authentication
+mcp-code-indexer --http --auth-token "your-secret-token"
+
+# Custom host and port
+mcp-code-indexer --http --host 0.0.0.0 --port 8080
+
+# CORS configuration for web apps
+mcp-code-indexer --http --cors-origins "https://localhost:3000" "https://myapp.com"
+```
+
+**🔗 [Complete HTTP API Reference →](docs/http-api.md)**
+
+### 🤖 For AI-Powered Q&A
+
+Ask questions about your codebase using natural language:
+
+```bash
+# Set OpenRouter API key for Claude access
+export OPENROUTER_API_KEY="your-openrouter-api-key"
+
+# Simple questions about project architecture
+mcp-code-indexer --ask "What does this project do?" my-project
+
+# Enhanced analysis with file search
+mcp-code-indexer --deepask "How is authentication implemented?" web-app
+
+# JSON output for programmatic use
+mcp-code-indexer --ask "List the main components" my-project --json
+```
+
+**🤖 [Complete Q&A Interface Guide →](docs/qa-interface.md)**
+
 ### 🔧 For System Administrators
 
 Deploy and configure the server for your team:
@@ -309,12 +346,16 @@ 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 |
-| **[Git Hook Setup](docs/git-hook-setup.md)** | Automate your workflow | 5 minutes |
 | **[API Reference](docs/api-reference.md)** | Master all 11 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 |
 
 ### 🏗️ Production Deployment (Teams & Admins)
 | Guide | Focus | Best For |
 |-------|-------|----------|
+| **[CLI Reference](docs/cli-reference.md)** | Complete command documentation | All users |
+| **[Administrative Commands](docs/admin-commands.md)** | Project & database management | System administrators |
 | **[Configuration Guide](docs/configuration.md)** | Production setup & tuning | System administrators |
 | **[Performance Tuning](docs/performance-tuning.md)** | High-concurrency optimization | DevOps teams |
 | **[Monitoring & Diagnostics](docs/monitoring.md)** | Production monitoring | Operations teams |
@@ -332,8 +373,10 @@ Comprehensive documentation organized by user journey and expertise level.
 - **[API Tools Summary](#🛠️-mcp-tools-available)** - All 11 tools at a glance
 
 **📚 Reading Paths:**
-- **New to MCP Code Indexer?** Quick Start → Git Hooks → API Reference
-- **Setting up for a team?** Configuration → Performance → Monitoring  
+- **New to MCP Code Indexer?** Quick Start → API Reference → HTTP API → Q&A Interface
+- **Web developers?** Quick Start → HTTP API Reference → Q&A Interface → Git Hooks
+- **AI/ML engineers?** Quick Start → Q&A Interface → API Reference → Git Hooks
+- **Setting up for a team?** CLI Reference → Configuration → Administrative Commands → Monitoring  
 - **Contributing to the project?** Architecture → Contributing → API Reference
 
 ## 🚦 System Requirements
@@ -518,7 +561,31 @@ mcp-code-indexer --githook [OPTIONS]
 # Requires: OPENROUTER_API_KEY environment variable
 ```
 
-### Utility Commands
+### HTTP Server Mode
+```bash
+# Start HTTP/REST API server
+mcp-code-indexer --http [OPTIONS]
+
+# HTTP server with authentication
+mcp-code-indexer --http --auth-token "your-secret-token"
+
+# Custom host and port configuration
+mcp-code-indexer --http --host 0.0.0.0 --port 8080
+```
+
+### Q&A Commands
+```bash
+# Simple AI-powered questions (requires OPENROUTER_API_KEY)
+mcp-code-indexer --ask "What does this project do?" PROJECT_NAME
+
+# Enhanced analysis with file search
+mcp-code-indexer --deepask "How is authentication implemented?" PROJECT_NAME
+
+# JSON output for programmatic use
+mcp-code-indexer --ask "Question" PROJECT_NAME --json
+```
+
+### Administrative Commands
 ```bash
 # List all projects
 mcp-code-indexer --getprojects
@@ -528,6 +595,12 @@ mcp-code-indexer --runcommand '{"method": "tools/call", "params": {...}}'
 
 # Export descriptions for a project
 mcp-code-indexer --dumpdescriptions PROJECT_ID
+
+# Create local database for a project
+mcp-code-indexer --makelocal /path/to/project
+
+# Generate project documentation map
+mcp-code-indexer --map PROJECT_NAME
 ```
 
 ## 🛡️ Security Features
@@ -546,8 +619,10 @@ mcp-code-indexer --dumpdescriptions PROJECT_ID
 |-------|-----------|------------|
 | **"No module named 'mcp_code_indexer'"** | `pip install -e .` (for development) | [Contributing Guide](docs/contributing.md#development-setup) |
 | **"OPENROUTER_API_KEY not found"** | `export OPENROUTER_API_KEY="your-key"` | [Git Hook Setup](docs/git-hook-setup.md#prerequisites) |
-| **"Database is locked"** | Enable WAL mode: `--enable-wal-mode` | [Performance Tuning](docs/performance-tuning.md#database-configuration) |
+| **"Database is locked"** | Enable WAL mode: `--enable-wal-mode` | [CLI Reference](docs/cli-reference.md#database-configuration) |
 | **"Large codebase - use search"** | Normal for 200+ files. Use `search_descriptions` | [API Reference](docs/api-reference.md#search_descriptions) |
+| **HTTP authentication failed** | Check `--auth-token` configuration | [HTTP API Reference](docs/http-api.md#authentication) |
+| **Q&A commands not working** | Set `OPENROUTER_API_KEY` environment variable | [Q&A Interface](docs/qa-interface.md#getting-started) |
 | **High memory usage** | Reduce token limit: `--token-limit 10000` | [Configuration Guide](docs/configuration.md#performance-tuning) |
 
 **💡 Not finding your issue?** Check the [complete troubleshooting guides](docs/monitoring.md#troubleshooting-runbook) in our documentation.
@@ -560,13 +635,17 @@ Ready to supercharge your AI agents with intelligent codebase navigation?
 
 **🆕 New to MCP Code Indexer?**
 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. **[Master the API tools](docs/api-reference.md)** - Learn all 11 tools with examples
+2. **[Master the API tools](docs/api-reference.md)** - Learn all 11 tools with examples
+3. **[Try HTTP API access](docs/http-api.md)** - REST API for web applications
+4. **[Explore AI-powered Q&A](docs/qa-interface.md)** - Ask questions about your code
+5. **[Set up git hooks](docs/git-hook-setup.md)** - Automate your workflow  
 
 **👥 Setting up for a team?**
-1. **[Configure for production](docs/configuration.md)** - Production deployment guide
-2. **[Performance optimization](docs/performance-tuning.md)** - High-concurrency setup
-3. **[Monitoring & alerts](docs/monitoring.md)** - Production monitoring
+1. **[Learn all CLI commands](docs/cli-reference.md)** - Complete command reference
+2. **[Configure for production](docs/configuration.md)** - Production deployment guide
+3. **[Set up administrative workflows](docs/admin-commands.md)** - Project & database management
+4. **[Performance optimization](docs/performance-tuning.md)** - High-concurrency setup
+5. **[Monitoring & alerts](docs/monitoring.md)** - Production monitoring
 
 **🔧 Want to contribute?**
 1. **[Understand the architecture](docs/architecture.md)** - Technical deep dive

{mcp_code_indexer-3.6.0 → mcp_code_indexer-4.0.1}/README.md

@@ -1,7 +1,7 @@
 # MCP Code Indexer 🚀
 
-[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?42)](https://badge.fury.io/py/mcp-code-indexer)
-[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?42)](https://pypi.org/project/mcp-code-indexer/)
+[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?44)](https://badge.fury.io/py/mcp-code-indexer)
+[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?44)](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.
@@ -37,6 +37,43 @@ mcp-code-indexer
 # See API Reference for complete tool documentation
 ```
 
+### 🌐 For Web Applications
+
+Enable HTTP/REST API access for browser-based applications:
+
+```bash
+# Start HTTP server with authentication
+mcp-code-indexer --http --auth-token "your-secret-token"
+
+# Custom host and port
+mcp-code-indexer --http --host 0.0.0.0 --port 8080
+
+# CORS configuration for web apps
+mcp-code-indexer --http --cors-origins "https://localhost:3000" "https://myapp.com"
+```
+
+**🔗 [Complete HTTP API Reference →](docs/http-api.md)**
+
+### 🤖 For AI-Powered Q&A
+
+Ask questions about your codebase using natural language:
+
+```bash
+# Set OpenRouter API key for Claude access
+export OPENROUTER_API_KEY="your-openrouter-api-key"
+
+# Simple questions about project architecture
+mcp-code-indexer --ask "What does this project do?" my-project
+
+# Enhanced analysis with file search
+mcp-code-indexer --deepask "How is authentication implemented?" web-app
+
+# JSON output for programmatic use
+mcp-code-indexer --ask "List the main components" my-project --json
+```
+
+**🤖 [Complete Q&A Interface Guide →](docs/qa-interface.md)**
+
 ### 🔧 For System Administrators
 
 Deploy and configure the server for your team:
@@ -266,12 +303,16 @@ 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 |
-| **[Git Hook Setup](docs/git-hook-setup.md)** | Automate your workflow | 5 minutes |
 | **[API Reference](docs/api-reference.md)** | Master all 11 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 |
 
 ### 🏗️ Production Deployment (Teams & Admins)
 | Guide | Focus | Best For |
 |-------|-------|----------|
+| **[CLI Reference](docs/cli-reference.md)** | Complete command documentation | All users |
+| **[Administrative Commands](docs/admin-commands.md)** | Project & database management | System administrators |
 | **[Configuration Guide](docs/configuration.md)** | Production setup & tuning | System administrators |
 | **[Performance Tuning](docs/performance-tuning.md)** | High-concurrency optimization | DevOps teams |
 | **[Monitoring & Diagnostics](docs/monitoring.md)** | Production monitoring | Operations teams |
@@ -289,8 +330,10 @@ Comprehensive documentation organized by user journey and expertise level.
 - **[API Tools Summary](#🛠️-mcp-tools-available)** - All 11 tools at a glance
 
 **📚 Reading Paths:**
-- **New to MCP Code Indexer?** Quick Start → Git Hooks → API Reference
-- **Setting up for a team?** Configuration → Performance → Monitoring  
+- **New to MCP Code Indexer?** Quick Start → API Reference → HTTP API → Q&A Interface
+- **Web developers?** Quick Start → HTTP API Reference → Q&A Interface → Git Hooks
+- **AI/ML engineers?** Quick Start → Q&A Interface → API Reference → Git Hooks
+- **Setting up for a team?** CLI Reference → Configuration → Administrative Commands → Monitoring  
 - **Contributing to the project?** Architecture → Contributing → API Reference
 
 ## 🚦 System Requirements
@@ -475,7 +518,31 @@ mcp-code-indexer --githook [OPTIONS]
 # Requires: OPENROUTER_API_KEY environment variable
 ```
 
-### Utility Commands
+### HTTP Server Mode
+```bash
+# Start HTTP/REST API server
+mcp-code-indexer --http [OPTIONS]
+
+# HTTP server with authentication
+mcp-code-indexer --http --auth-token "your-secret-token"
+
+# Custom host and port configuration
+mcp-code-indexer --http --host 0.0.0.0 --port 8080
+```
+
+### Q&A Commands
+```bash
+# Simple AI-powered questions (requires OPENROUTER_API_KEY)
+mcp-code-indexer --ask "What does this project do?" PROJECT_NAME
+
+# Enhanced analysis with file search
+mcp-code-indexer --deepask "How is authentication implemented?" PROJECT_NAME
+
+# JSON output for programmatic use
+mcp-code-indexer --ask "Question" PROJECT_NAME --json
+```
+
+### Administrative Commands
 ```bash
 # List all projects
 mcp-code-indexer --getprojects
@@ -485,6 +552,12 @@ mcp-code-indexer --runcommand '{"method": "tools/call", "params": {...}}'
 
 # Export descriptions for a project
 mcp-code-indexer --dumpdescriptions PROJECT_ID
+
+# Create local database for a project
+mcp-code-indexer --makelocal /path/to/project
+
+# Generate project documentation map
+mcp-code-indexer --map PROJECT_NAME
 ```
 
 ## 🛡️ Security Features
@@ -503,8 +576,10 @@ mcp-code-indexer --dumpdescriptions PROJECT_ID
 |-------|-----------|------------|
 | **"No module named 'mcp_code_indexer'"** | `pip install -e .` (for development) | [Contributing Guide](docs/contributing.md#development-setup) |
 | **"OPENROUTER_API_KEY not found"** | `export OPENROUTER_API_KEY="your-key"` | [Git Hook Setup](docs/git-hook-setup.md#prerequisites) |
-| **"Database is locked"** | Enable WAL mode: `--enable-wal-mode` | [Performance Tuning](docs/performance-tuning.md#database-configuration) |
+| **"Database is locked"** | Enable WAL mode: `--enable-wal-mode` | [CLI Reference](docs/cli-reference.md#database-configuration) |
 | **"Large codebase - use search"** | Normal for 200+ files. Use `search_descriptions` | [API Reference](docs/api-reference.md#search_descriptions) |
+| **HTTP authentication failed** | Check `--auth-token` configuration | [HTTP API Reference](docs/http-api.md#authentication) |
+| **Q&A commands not working** | Set `OPENROUTER_API_KEY` environment variable | [Q&A Interface](docs/qa-interface.md#getting-started) |
 | **High memory usage** | Reduce token limit: `--token-limit 10000` | [Configuration Guide](docs/configuration.md#performance-tuning) |
 
 **💡 Not finding your issue?** Check the [complete troubleshooting guides](docs/monitoring.md#troubleshooting-runbook) in our documentation.
@@ -517,13 +592,17 @@ Ready to supercharge your AI agents with intelligent codebase navigation?
 
 **🆕 New to MCP Code Indexer?**
 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. **[Master the API tools](docs/api-reference.md)** - Learn all 11 tools with examples
+2. **[Master the API tools](docs/api-reference.md)** - Learn all 11 tools with examples
+3. **[Try HTTP API access](docs/http-api.md)** - REST API for web applications
+4. **[Explore AI-powered Q&A](docs/qa-interface.md)** - Ask questions about your code
+5. **[Set up git hooks](docs/git-hook-setup.md)** - Automate your workflow  
 
 **👥 Setting up for a team?**
-1. **[Configure for production](docs/configuration.md)** - Production deployment guide
-2. **[Performance optimization](docs/performance-tuning.md)** - High-concurrency setup
-3. **[Monitoring & alerts](docs/monitoring.md)** - Production monitoring
+1. **[Learn all CLI commands](docs/cli-reference.md)** - Complete command reference
+2. **[Configure for production](docs/configuration.md)** - Production deployment guide
+3. **[Set up administrative workflows](docs/admin-commands.md)** - Project & database management
+4. **[Performance optimization](docs/performance-tuning.md)** - High-concurrency setup
+5. **[Monitoring & alerts](docs/monitoring.md)** - Production monitoring
 
 **🔧 Want to contribute?**
 1. **[Understand the architecture](docs/architecture.md)** - Technical deep dive

{mcp_code_indexer-3.6.0 → mcp_code_indexer-4.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "mcp-code-indexer"
-version = "3.6.0"
+version = "4.0.1"
 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"]

{mcp_code_indexer-3.6.0 → mcp_code_indexer-4.0.1}/src/mcp_code_indexer/server/mcp_server.py

@@ -1039,7 +1039,19 @@ class MCPCodeIndexServer:
 
         total_tokens = descriptions_tokens + overview_tokens
         is_large = total_tokens > token_limit
-        recommendation = "use_search" if is_large else "use_overview"
+        
+        # Smart recommendation logic:
+        # - If total is small, use overview
+        # - If total is large but overview is reasonable (< 8k tokens), recommend viewing overview + search
+        # - If both are large, use search only
+        overview_size_limit = 32000
+        
+        if not is_large:
+            recommendation = "use_overview"
+        elif overview_tokens > 0 and overview_tokens <= overview_size_limit:
+            recommendation = "view_overview_then_search"
+        else:
+            recommendation = "use_search"
 
         logger.info(
             f"Codebase analysis complete: {total_tokens} tokens total "