mcp-code-indexer 2.1.0__tar.gz → 2.2.1__tar.gz

{mcp_code_indexer-2.1.0/src/mcp_code_indexer.egg-info → mcp_code_indexer-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-code-indexer
-Version: 2.1.0
+Version: 2.2.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,8 +59,8 @@ Dynamic: requires-python
 
 # MCP Code Indexer 🚀
 
-[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?14)](https://badge.fury.io/py/mcp-code-indexer)
-[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?14)](https://pypi.org/project/mcp-code-indexer/)
+[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?16)](https://badge.fury.io/py/mcp-code-indexer)
+[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?16)](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.

{mcp_code_indexer-2.1.0 → mcp_code_indexer-2.2.1}/README.md

@@ -1,7 +1,7 @@
 # MCP Code Indexer 🚀
 
-[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?14)](https://badge.fury.io/py/mcp-code-indexer)
-[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?14)](https://pypi.org/project/mcp-code-indexer/)
+[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?16)](https://badge.fury.io/py/mcp-code-indexer)
+[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?16)](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.

{mcp_code_indexer-2.1.0 → mcp_code_indexer-2.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mcp-code-indexer"
-version = "2.1.0"
+version = "2.2.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."
 readme = "README.md"
 license = {text = "MIT"}

mcp_code_indexer-2.2.1/src/mcp_code_indexer/ask_handler.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""
+Ask Handler for MCP Code Indexer
+
+Handles simple question-answering by combining project overview with user questions
+and sending them to Claude via OpenRouter API for direct responses.
+"""
+
+import logging
+from pathlib import Path
+from typing import Dict, Optional, Any
+
+from .claude_api_handler import ClaudeAPIHandler, ClaudeAPIError
+from .database.database import DatabaseManager
+
+
+class AskError(ClaudeAPIError):
+    """Exception specific to Ask operations."""
+    pass
+
+
+class AskHandler(ClaudeAPIHandler):
+    """
+    Handler for simple Q&A operations using Claude API.
+    
+    Provides functionality to:
+    - Combine project overview with user questions
+    - Send combined prompt to Claude for analysis
+    - Return formatted responses for CLI consumption
+    """
+    
+    def __init__(self, db_manager: DatabaseManager, cache_dir: Path, logger: Optional[logging.Logger] = None):
+        """
+        Initialize AskHandler.
+        
+        Args:
+            db_manager: Database manager instance
+            cache_dir: Cache directory for temporary files
+            logger: Logger instance to use (optional, creates default if not provided)
+        """
+        super().__init__(db_manager, cache_dir, logger)
+        self.logger = logger if logger is not None else logging.getLogger(__name__)
+    
+    async def ask_question(
+        self, 
+        project_info: Dict[str, str], 
+        question: str,
+        include_overview: bool = True
+    ) -> Dict[str, Any]:
+        """
+        Ask a question about the project using Claude API.
+        
+        Args:
+            project_info: Project information dict with projectName, folderPath, branch, etc.
+            question: User's question about the project
+            include_overview: Whether to include project overview in context
+            
+        Returns:
+            Dict containing response and metadata
+        """
+        try:
+            self.logger.info(f"Processing ask question for project: {project_info['projectName']}")
+            self.logger.info(f"Question: {question}")
+            
+            # Validate inputs
+            if not question or not question.strip():
+                raise AskError("Question cannot be empty")
+            
+            if not project_info.get("projectName"):
+                raise AskError("Project name is required")
+            
+            # Get project overview if requested
+            overview = ""
+            if include_overview:
+                overview = await self.get_project_overview(project_info)
+                if not overview:
+                    self.logger.warning(f"No project overview found for {project_info['projectName']}")
+                    overview = "No project overview available."
+            
+            # Build the prompt
+            prompt = self._build_ask_prompt(project_info, question, overview)
+            
+            # Validate token limits
+            if not self.validate_token_limit(prompt):
+                raise AskError(
+                    f"Question and project context exceed token limit of {self.config.token_limit}. "
+                    "Please ask a more specific question or use --deepask for enhanced search."
+                )
+            
+            # Get token counts for reporting
+            overview_tokens = self.get_token_count(overview) if overview else 0
+            question_tokens = self.get_token_count(question)
+            total_prompt_tokens = self.get_token_count(prompt)
+            
+            self.logger.info(f"Token usage: overview={overview_tokens}, question={question_tokens}, total={total_prompt_tokens}")
+            
+            # Call Claude API
+            system_prompt = self._get_system_prompt()
+            response = await self._call_claude_api(prompt, system_prompt)
+            
+            # Format response
+            result = {
+                "answer": response.content,
+                "project_name": project_info["projectName"],
+                "question": question,
+                "metadata": {
+                    "model": response.model or self.config.model,
+                    "token_usage": {
+                        "overview_tokens": overview_tokens,
+                        "question_tokens": question_tokens,
+                        "total_prompt_tokens": total_prompt_tokens,
+                        "response_tokens": response.usage.get("completion_tokens") if response.usage else None,
+                        "total_tokens": response.usage.get("total_tokens") if response.usage else None
+                    },
+                    "include_overview": include_overview,
+                    "branch": project_info.get("branch", "unknown")
+                }
+            }
+            
+            self.logger.info(f"Ask question completed successfully")
+            return result
+            
+        except Exception as e:
+            error_msg = f"Failed to process ask question: {str(e)}"
+            self.logger.error(error_msg)
+            if isinstance(e, (ClaudeAPIError, AskError)):
+                raise
+            else:
+                raise AskError(error_msg)
+    
+    def _build_ask_prompt(self, project_info: Dict[str, str], question: str, overview: str) -> str:
+        """
+        Build the prompt for Claude API.
+        
+        Args:
+            project_info: Project information
+            question: User's question
+            overview: Project overview (may be empty)
+            
+        Returns:
+            Formatted prompt string
+        """
+        project_name = project_info["projectName"]
+        branch = project_info.get("branch", "unknown")
+        
+        if overview.strip():
+            prompt = f"""Please answer the following question about the codebase "{project_name}" (branch: {branch}).
+
+PROJECT OVERVIEW:
+{overview}
+
+QUESTION:
+{question}
+
+Please provide a clear, detailed answer based on the project overview above. If the overview doesn't contain enough information to fully answer the question, please say so and suggest what additional information might be needed."""
+        else:
+            prompt = f"""Please answer the following question about the codebase "{project_name}" (branch: {branch}).
+
+Note: No project overview is available for this codebase.
+
+QUESTION:
+{question}
+
+Please provide the best answer you can based on the project name and general software development knowledge. If you need more specific information about this codebase to provide a complete answer, please mention what would be helpful."""
+        
+        return prompt
+    
+    def _get_system_prompt(self) -> str:
+        """Get system prompt for Claude API."""
+        return """You are a helpful software engineering assistant that analyzes codebases and answers questions about them.
+
+When answering questions:
+1. Be specific and technical when appropriate
+2. Reference the project overview when available
+3. If information is missing, clearly state what you don't know
+4. Provide actionable suggestions when possible
+5. Use clear, professional language
+6. Focus on the specific question asked
+
+If the project overview is insufficient to answer the question completely, explain what additional information would be needed and suggest using --deepask for more detailed analysis."""
+    
+    def format_response(self, result: Dict[str, Any], format_type: str = "text") -> str:
+        """
+        Format response for CLI output.
+        
+        Args:
+            result: Result from ask_question
+            format_type: Output format ("text" or "json")
+            
+        Returns:
+            Formatted response string
+        """
+        if format_type == "json":
+            import json
+            return json.dumps(result, indent=2)
+        
+        # Text format
+        answer = result["answer"]
+        metadata = result["metadata"]
+        
+        output = []
+        output.append(f"Question: {result['question']}")
+        output.append(f"Project: {result['project_name']} (branch: {metadata['branch']})")
+        output.append("")
+        output.append("Answer:")
+        output.append(answer)
+        output.append("")
+        output.append("Metadata:")
+        output.append(f"  Model: {metadata['model']}")
+        output.append(f"  Overview included: {metadata['include_overview']}")
+        
+        if metadata['token_usage']['total_tokens']:
+            output.append(f"  Total tokens: {metadata['token_usage']['total_tokens']}")
+        else:
+            output.append(f"  Prompt tokens: {metadata['token_usage']['total_prompt_tokens']}")
+        
+        return "\n".join(output)

mcp_code_indexer-2.2.1/src/mcp_code_indexer/claude_api_handler.py

@@ -0,0 +1,355 @@
+#!/usr/bin/env python3
+"""
+Base Claude API Handler for MCP Code Indexer
+
+Provides shared functionality for interacting with Claude via OpenRouter API,
+including token management, retry logic, and response validation.
+"""
+
+import asyncio
+import json
+import logging
+import os
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Any
+from pathlib import Path
+
+import aiohttp
+from tenacity import retry, wait_exponential, stop_after_attempt, retry_if_exception_type
+
+from .database.database import DatabaseManager
+from .token_counter import TokenCounter
+
+
+class ClaudeAPIError(Exception):
+    """Base exception for Claude API operations."""
+    pass
+
+
+class ClaudeRateLimitError(ClaudeAPIError):
+    """Exception for rate limiting scenarios."""
+    def __init__(self, message: str, retry_after: int = 60):
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class ClaudeValidationError(ClaudeAPIError):
+    """Exception for response validation failures."""
+    pass
+
+
+@dataclass
+class ClaudeConfig:
+    """Configuration for Claude API calls."""
+    model: str = "anthropic/claude-sonnet-4"
+    max_tokens: int = 24000
+    temperature: float = 0.3
+    timeout: int = 300
+    token_limit: int = 180000
+
+
+@dataclass
+class ClaudeResponse:
+    """Structured response from Claude API."""
+    content: str
+    usage: Optional[Dict[str, Any]] = None
+    model: Optional[str] = None
+
+
+class ClaudeAPIHandler:
+    """
+    Base handler for Claude API interactions via OpenRouter.
+    
+    Provides shared functionality for:
+    - Token counting and limit validation
+    - API request/response handling with retry logic
+    - Response validation and parsing
+    - Error handling and logging
+    """
+    
+    OPENROUTER_API_URL = "https://openrouter.ai/api/v1/chat/completions"
+    
+    def __init__(self, db_manager: DatabaseManager, cache_dir: Path, logger: Optional[logging.Logger] = None):
+        """
+        Initialize Claude API Handler.
+        
+        Args:
+            db_manager: Database manager instance
+            cache_dir: Cache directory for temporary files
+            logger: Logger instance to use (optional, creates default if not provided)
+        """
+        self.db_manager = db_manager
+        self.cache_dir = cache_dir
+        self.logger = logger if logger is not None else logging.getLogger(__name__)
+        self.token_counter = TokenCounter()
+        
+        # Initialize configuration
+        self.config = ClaudeConfig(
+            model=os.getenv("MCP_CLAUDE_MODEL", "anthropic/claude-sonnet-4"),
+            max_tokens=int(os.getenv("MCP_CLAUDE_MAX_TOKENS", "24000")),
+            temperature=float(os.getenv("MCP_CLAUDE_TEMPERATURE", "0.3")),
+            timeout=int(os.getenv("MCP_CLAUDE_TIMEOUT", "600")),  # 10 minutes
+            token_limit=int(os.getenv("MCP_CLAUDE_TOKEN_LIMIT", "180000"))
+        )
+        
+        # Validate API key
+        self.api_key = os.getenv("OPENROUTER_API_KEY")
+        if not self.api_key:
+            raise ClaudeAPIError("OPENROUTER_API_KEY environment variable is required")
+    
+    def validate_token_limit(self, prompt: str, context: str = "") -> bool:
+        """
+        Validate that prompt + context fits within token limit.
+        
+        Args:
+            prompt: Main prompt text
+            context: Additional context (project overview, file descriptions, etc.)
+            
+        Returns:
+            True if within limits, False otherwise
+        """
+        combined_text = f"{prompt}\n\n{context}"
+        token_count = self.token_counter.count_tokens(combined_text)
+        
+        self.logger.debug(f"Token count validation: {token_count}/{self.config.token_limit}")
+        
+        if token_count > self.config.token_limit:
+            self.logger.warning(
+                f"Token limit exceeded: {token_count} > {self.config.token_limit}. "
+                f"Consider using shorter context or ask for a more specific question."
+            )
+            return False
+        
+        return True
+    
+    def get_token_count(self, text: str) -> int:
+        """Get token count for given text."""
+        return self.token_counter.count_tokens(text)
+    
+    @retry(
+        wait=wait_exponential(multiplier=1, min=1, max=60),
+        stop=stop_after_attempt(5),
+        retry=retry_if_exception_type(ClaudeRateLimitError),
+        reraise=True
+    )
+    async def _call_claude_api(self, prompt: str, system_prompt: Optional[str] = None) -> ClaudeResponse:
+        """
+        Make API call to Claude via OpenRouter with retry logic.
+        
+        Args:
+            prompt: User prompt
+            system_prompt: Optional system prompt
+            
+        Returns:
+            ClaudeResponse with parsed response data
+        """
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "HTTP-Referer": "https://github.com/fluffypony/mcp-code-indexer",
+            "X-Title": "MCP Code Indexer",
+            "Content-Type": "application/json"
+        }
+        
+        messages = []
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        messages.append({"role": "user", "content": prompt})
+        
+        payload = {
+            "model": self.config.model,
+            "messages": messages,
+            "temperature": self.config.temperature,
+            "max_tokens": self.config.max_tokens,
+        }
+        
+        timeout = aiohttp.ClientTimeout(total=self.config.timeout)
+        
+        self.logger.info(f"Sending request to Claude API via OpenRouter...")
+        self.logger.info(f"  Model: {self.config.model}")
+        self.logger.info(f"  Temperature: {self.config.temperature}")
+        self.logger.info(f"  Max tokens: {self.config.max_tokens}")
+        self.logger.info(f"  Timeout: {self.config.timeout}s")
+        
+        try:
+            async with aiohttp.ClientSession(timeout=timeout) as session:
+                async with session.post(
+                    self.OPENROUTER_API_URL,
+                    headers=headers,
+                    json=payload
+                ) as response:
+                    
+                    self.logger.info(f"Claude API response status: {response.status}")
+                    
+                    if response.status == 429:
+                        retry_after = int(response.headers.get("Retry-After", 60))
+                        self.logger.warning(f"Rate limited by OpenRouter, retry after {retry_after}s")
+                        raise ClaudeRateLimitError(f"Rate limited. Retry after {retry_after}s", retry_after)
+                    
+                    response.raise_for_status()
+                    
+                    response_data = await response.json()
+                    
+                    if "choices" not in response_data:
+                        self.logger.error(f"Invalid API response format: {response_data}")
+                        raise ClaudeAPIError(f"Invalid API response format: {response_data}")
+                    
+                    content = response_data["choices"][0]["message"]["content"]
+                    usage = response_data.get("usage")
+                    model = response_data.get("model")
+                    
+                    self.logger.info(f"Claude response content length: {len(content)} characters")
+                    if usage:
+                        self.logger.info(f"Token usage: {usage}")
+                    
+                    return ClaudeResponse(content=content, usage=usage, model=model)
+                    
+        except aiohttp.ClientError as e:
+            self.logger.error(f"Claude API request failed: {e}")
+            raise ClaudeAPIError(f"Claude API request failed: {e}")
+        except asyncio.TimeoutError as e:
+            self.logger.error(f"Claude API request timed out after {self.config.timeout}s")
+            raise ClaudeAPIError("Claude API request timed out")
+    
+    def validate_json_response(self, response_text: str, required_keys: List[str] = None) -> Dict[str, Any]:
+        """
+        Validate and parse JSON response from Claude.
+        
+        Args:
+            response_text: Raw response content
+            required_keys: List of required keys in the JSON response
+            
+        Returns:
+            Validated JSON data
+        """
+        def extract_json_from_response(text: str) -> str:
+            """Extract JSON from response that might have extra text before/after."""
+            text = text.strip()
+            
+            # Try to find JSON in the response
+            json_start = -1
+            json_end = -1
+            
+            # Look for opening brace
+            for i, char in enumerate(text):
+                if char == '{':
+                    json_start = i
+                    break
+            
+            if json_start == -1:
+                return text  # No JSON found, return original
+            
+            # Find matching closing brace
+            brace_count = 0
+            for i in range(json_start, len(text)):
+                if text[i] == '{':
+                    brace_count += 1
+                elif text[i] == '}':
+                    brace_count -= 1
+                    if brace_count == 0:
+                        json_end = i + 1
+                        break
+            
+            if json_end == -1:
+                return text  # No matching brace found, return original
+            
+            return text[json_start:json_end]
+        
+        try:
+            # First try parsing as-is
+            try:
+                data = json.loads(response_text.strip())
+            except json.JSONDecodeError:
+                # Try extracting JSON from response
+                extracted_json = extract_json_from_response(response_text)
+                if extracted_json != response_text.strip():
+                    self.logger.debug(f"Extracted JSON from response: {extracted_json}")
+                data = json.loads(extracted_json)
+            
+            # Validate required keys if specified
+            if required_keys:
+                missing_keys = [key for key in required_keys if key not in data]
+                if missing_keys:
+                    raise ClaudeValidationError(f"Missing required keys in response: {missing_keys}")
+            
+            return data
+            
+        except json.JSONDecodeError as e:
+            self.logger.error(f"Failed to parse JSON response: {e}")
+            self.logger.error(f"Response text: {response_text}")
+            raise ClaudeValidationError(f"Invalid JSON response: {e}")
+        except Exception as e:
+            self.logger.error(f"Response validation failed: {e}")
+            raise ClaudeValidationError(f"Response validation failed: {e}")
+    
+    def format_error_response(self, error: Exception, context: str = "") -> str:
+        """
+        Format error for user-friendly display.
+        
+        Args:
+            error: The exception that occurred
+            context: Additional context about the operation
+            
+        Returns:
+            Formatted error message
+        """
+        if isinstance(error, ClaudeRateLimitError):
+            return f"Rate limited by Claude API. Please wait {error.retry_after} seconds and try again."
+        elif isinstance(error, ClaudeValidationError):
+            return f"Invalid response from Claude API: {str(error)}"
+        elif isinstance(error, ClaudeAPIError):
+            return f"Claude API error: {str(error)}"
+        else:
+            return f"Unexpected error during {context}: {str(error)}"
+    
+    async def find_existing_project_by_name(self, project_name: str) -> Optional[Any]:
+        """
+        Find existing project by name for CLI usage.
+        
+        Args:
+            project_name: Name of the project to find
+            
+        Returns:
+            Project object if found, None otherwise
+        """
+        try:
+            all_projects = await self.db_manager.get_all_projects()
+            normalized_name = project_name.lower()
+            
+            for project in all_projects:
+                if project.name.lower() == normalized_name:
+                    self.logger.info(f"Found existing project: {project.name} (ID: {project.id})")
+                    return project
+            
+            self.logger.warning(f"No existing project found with name: {project_name}")
+            return None
+        except Exception as e:
+            self.logger.error(f"Error finding project by name: {e}")
+            return None
+
+    async def get_project_overview(self, project_info: Dict[str, str]) -> str:
+        """
+        Get project overview from database.
+        
+        Args:
+            project_info: Project information dict with projectName, folderPath, branch, etc.
+            
+        Returns:
+            Project overview text or empty string if not found
+        """
+        try:
+            # Try to find existing project by name first
+            project = await self.find_existing_project_by_name(project_info["projectName"])
+            
+            if not project:
+                self.logger.warning(f"Project '{project_info['projectName']}' not found in database")
+                return ""
+            
+            # Get overview for the project using project.id
+            overview_result = await self.db_manager.get_project_overview(project.id, project_info["branch"])
+            if overview_result:
+                return overview_result.overview
+            else:
+                return ""
+        except Exception as e:
+            self.logger.warning(f"Failed to get project overview: {e}")
+            return ""

mcp_code_indexer-2.2.1/src/mcp_code_indexer/deepask_handler.py

@@ -0,0 +1,465 @@
+#!/usr/bin/env python3
+"""
+DeepAsk Handler for MCP Code Indexer
+
+Handles enhanced question-answering with two-stage processing:
+1. Extract search terms and compress overview
+2. Search file descriptions and provide enhanced answer
+"""
+
+import logging
+from pathlib import Path
+from typing import Dict, List, Optional, Any, Tuple
+
+from .claude_api_handler import ClaudeAPIHandler, ClaudeAPIError
+from .database.database import DatabaseManager
+
+
+class DeepAskError(ClaudeAPIError):
+    """Exception specific to DeepAsk operations."""
+    pass
+
+
+class DeepAskHandler(ClaudeAPIHandler):
+    """
+    Handler for enhanced Q&A operations using two-stage Claude API processing.
+    
+    Stage 1: Extract search terms and compress project overview
+    Stage 2: Search file descriptions and provide enhanced answer with context
+    """
+    
+    def __init__(self, db_manager: DatabaseManager, cache_dir: Path, logger: Optional[logging.Logger] = None):
+        """
+        Initialize DeepAskHandler.
+        
+        Args:
+            db_manager: Database manager instance
+            cache_dir: Cache directory for temporary files
+            logger: Logger instance to use (optional, creates default if not provided)
+        """
+        super().__init__(db_manager, cache_dir, logger)
+        self.logger = logger if logger is not None else logging.getLogger(__name__)
+    
+    async def find_existing_project_by_name(self, project_name: str) -> Optional[Any]:
+        """
+        Find existing project by name for CLI usage.
+        
+        Args:
+            project_name: Name of the project to find
+            
+        Returns:
+            Project object if found, None otherwise
+        """
+        try:
+            all_projects = await self.db_manager.get_all_projects()
+            normalized_name = project_name.lower()
+            
+            for project in all_projects:
+                if project.name.lower() == normalized_name:
+                    self.logger.info(f"Found existing project: {project.name} (ID: {project.id})")
+                    return project
+            
+            self.logger.warning(f"No existing project found with name: {project_name}")
+            return None
+        except Exception as e:
+            self.logger.error(f"Error finding project by name: {e}")
+            return None
+
+    async def deepask_question(
+        self, 
+        project_info: Dict[str, str], 
+        question: str,
+        max_file_results: int = 10
+    ) -> Dict[str, Any]:
+        """
+        Ask an enhanced question about the project using two-stage Claude API processing.
+        
+        Args:
+            project_info: Project information dict with projectName, folderPath, branch, etc.
+            question: User's question about the project
+            max_file_results: Maximum number of file descriptions to include
+            
+        Returns:
+            Dict containing enhanced response and metadata
+        """
+        try:
+            self.logger.info(f"Processing deepask question for project: {project_info['projectName']}")
+            self.logger.info(f"Question: {question}")
+            
+            # Validate inputs
+            if not question or not question.strip():
+                raise DeepAskError("Question cannot be empty")
+            
+            if not project_info.get("projectName"):
+                raise DeepAskError("Project name is required")
+            
+            # Stage 1: Extract search terms and compress overview
+            stage1_result = await self._stage1_extract_search_terms(project_info, question)
+            
+            # Stage 2: Search files and provide enhanced answer
+            stage2_result = await self._stage2_enhanced_answer(
+                project_info, 
+                question, 
+                stage1_result["search_terms"],
+                stage1_result["compressed_overview"],
+                max_file_results
+            )
+            
+            # Combine results
+            result = {
+                "answer": stage2_result["answer"],
+                "project_name": project_info["projectName"],
+                "question": question,
+                "search_terms": stage1_result["search_terms"],
+                "compressed_overview": stage1_result["compressed_overview"],
+                "relevant_files": stage2_result["relevant_files"],
+                "metadata": {
+                    "model": self.config.model,
+                    "stage1_tokens": stage1_result["token_usage"],
+                    "stage2_tokens": stage2_result["token_usage"],
+                    "total_files_found": stage2_result["total_files_found"],
+                    "files_included": len(stage2_result["relevant_files"]),
+                    "branch": project_info.get("branch", "unknown")
+                }
+            }
+            
+            self.logger.info(f"DeepAsk question completed successfully")
+            self.logger.info(f"Search terms: {stage1_result['search_terms']}")
+            self.logger.info(f"Files found: {stage2_result['total_files_found']}")
+            self.logger.info(f"Files included: {len(stage2_result['relevant_files'])}")
+            
+            return result
+            
+        except Exception as e:
+            error_msg = f"Failed to process deepask question: {str(e)}"
+            self.logger.error(error_msg)
+            if isinstance(e, (ClaudeAPIError, DeepAskError)):
+                raise
+            else:
+                raise DeepAskError(error_msg)
+    
+    async def _stage1_extract_search_terms(
+        self, 
+        project_info: Dict[str, str], 
+        question: str
+    ) -> Dict[str, Any]:
+        """
+        Stage 1: Extract search terms and compress project overview.
+        
+        Args:
+            project_info: Project information
+            question: User's question
+            
+        Returns:
+            Dict with search_terms, compressed_overview, and token_usage
+        """
+        self.logger.info("Stage 1: Extracting search terms and compressing overview")
+        
+        # Get project overview
+        overview = await self.get_project_overview(project_info)
+        if not overview:
+            overview = "No project overview available."
+        
+        # Build stage 1 prompt
+        prompt = self._build_stage1_prompt(project_info, question, overview)
+        
+        # Validate token limits for stage 1
+        if not self.validate_token_limit(prompt):
+            raise DeepAskError(
+                f"Stage 1 prompt exceeds token limit of {self.config.token_limit}. "
+                "Project overview may be too large."
+            )
+        
+        # Call Claude API for stage 1
+        system_prompt = self._get_stage1_system_prompt()
+        response = await self._call_claude_api(prompt, system_prompt)
+        
+        # Parse and validate response
+        response_data = self.validate_json_response(
+            response.content, 
+            required_keys=["search_terms", "compressed_overview"]
+        )
+        
+        token_usage = {
+            "prompt_tokens": self.get_token_count(prompt),
+            "response_tokens": response.usage.get("completion_tokens") if response.usage else None,
+            "total_tokens": response.usage.get("total_tokens") if response.usage else None
+        }
+        
+        return {
+            "search_terms": response_data["search_terms"],
+            "compressed_overview": response_data["compressed_overview"],
+            "token_usage": token_usage
+        }
+    
+    async def _stage2_enhanced_answer(
+        self,
+        project_info: Dict[str, str],
+        question: str,
+        search_terms: List[str],
+        compressed_overview: str,
+        max_file_results: int
+    ) -> Dict[str, Any]:
+        """
+        Stage 2: Search file descriptions and provide enhanced answer.
+        
+        Args:
+            project_info: Project information
+            question: User's question
+            search_terms: Search terms from stage 1
+            compressed_overview: Compressed overview from stage 1
+            max_file_results: Maximum number of files to include
+            
+        Returns:
+            Dict with answer, relevant_files, total_files_found, and token_usage
+        """
+        self.logger.info(f"Stage 2: Searching files and generating enhanced answer")
+        self.logger.info(f"Search terms: {search_terms}")
+        
+        # Search for relevant files
+        relevant_files = []
+        total_files_found = 0
+        
+        try:
+            # Find existing project by name only (don't create new ones for Q&A)
+            project = await self.find_existing_project_by_name(project_info["projectName"])
+            
+            if not project:
+                self.logger.warning(f"Project '{project_info['projectName']}' not found in database")
+                return {
+                    "answer": f"Project '{project_info['projectName']}' not found in database. Please check the project name.",
+                    "relevant_files": [],
+                    "total_files_found": 0,
+                    "token_usage": {"prompt_tokens": 0, "response_tokens": 0, "total_tokens": 0}
+                }
+            
+            for search_term in search_terms:
+                try:
+                    search_results = await self.db_manager.search_file_descriptions(
+                        project_id=project.id,
+                        branch=project_info["branch"],
+                        query=search_term,
+                        max_results=max_file_results
+                    )
+                    
+                    total_files_found += len(search_results)
+                    
+                    # Add unique files to relevant_files
+                    for result in search_results:
+                        if not any(f["filePath"] == result.file_path for f in relevant_files):
+                            relevant_files.append({
+                                "filePath": result.file_path,
+                                "description": result.description,
+                                "search_term": search_term,
+                                "relevance_score": result.relevance_score
+                            })
+                            
+                            # Stop if we have enough files
+                            if len(relevant_files) >= max_file_results:
+                                break
+                    
+                    if len(relevant_files) >= max_file_results:
+                        break
+                        
+                except Exception as e:
+                    self.logger.warning(f"Search failed for term '{search_term}': {e}")
+                    continue
+                    
+        except Exception as e:
+            self.logger.warning(f"Failed to search files: {e}")
+            # Continue with empty relevant_files list
+        
+        # Build stage 2 prompt with file context
+        prompt = self._build_stage2_prompt(
+            project_info, 
+            question, 
+            compressed_overview, 
+            relevant_files
+        )
+        
+        # Validate token limits for stage 2
+        if not self.validate_token_limit(prompt):
+            # Try reducing file context
+            self.logger.warning("Stage 2 prompt exceeds token limit, reducing file context")
+            reduced_files = relevant_files[:max_file_results//2]
+            prompt = self._build_stage2_prompt(
+                project_info, 
+                question, 
+                compressed_overview, 
+                reduced_files
+            )
+            
+            if not self.validate_token_limit(prompt):
+                raise DeepAskError(
+                    f"Stage 2 prompt still exceeds token limit even with reduced context. "
+                    "Try a more specific question."
+                )
+            
+            relevant_files = reduced_files
+        
+        # Call Claude API for stage 2
+        system_prompt = self._get_stage2_system_prompt()
+        response = await self._call_claude_api(prompt, system_prompt)
+        
+        token_usage = {
+            "prompt_tokens": self.get_token_count(prompt),
+            "response_tokens": response.usage.get("completion_tokens") if response.usage else None,
+            "total_tokens": response.usage.get("total_tokens") if response.usage else None
+        }
+        
+        return {
+            "answer": response.content,
+            "relevant_files": relevant_files,
+            "total_files_found": total_files_found,
+            "token_usage": token_usage
+        }
+    
+    def _build_stage1_prompt(
+        self, 
+        project_info: Dict[str, str], 
+        question: str, 
+        overview: str
+    ) -> str:
+        """Build stage 1 prompt for extracting search terms."""
+        project_name = project_info["projectName"]
+        branch = project_info.get("branch", "unknown")
+        
+        return f"""I need to answer a question about the codebase "{project_name}" (branch: {branch}). To provide the best answer, I need to search for relevant files and then answer the question.
+
+PROJECT OVERVIEW:
+{overview}
+
+QUESTION:
+{question}
+
+Please analyze the question and project overview, then provide:
+
+1. A list of 3-5 search terms that would help find relevant files to answer this question
+2. A compressed version of the project overview (2-3 sentences max) that captures the most relevant information for this question
+
+Respond with valid JSON in this format:
+{{
+  "search_terms": ["term1", "term2", "term3"],
+  "compressed_overview": "Brief summary focusing on aspects relevant to the question..."
+}}"""
+    
+    def _build_stage2_prompt(
+        self,
+        project_info: Dict[str, str],
+        question: str,
+        compressed_overview: str,
+        relevant_files: List[Dict[str, Any]]
+    ) -> str:
+        """Build stage 2 prompt for enhanced answer."""
+        project_name = project_info["projectName"]
+        branch = project_info.get("branch", "unknown")
+        
+        # Format file descriptions
+        file_context = ""
+        if relevant_files:
+            file_context = "\n\nRELEVANT FILES:\n"
+            for i, file_info in enumerate(relevant_files, 1):
+                file_context += f"\n{i}. {file_info['filePath']}\n"
+                file_context += f"   Description: {file_info['description']}\n"
+                file_context += f"   Found via search: {file_info['search_term']}\n"
+        else:
+            file_context = "\n\nNo relevant files found in the search."
+        
+        return f"""Please answer the following question about the codebase "{project_name}" (branch: {branch}).
+
+PROJECT OVERVIEW (COMPRESSED):
+{compressed_overview}
+{file_context}
+
+QUESTION:
+{question}
+
+Please provide a comprehensive answer based on the project overview and relevant file descriptions above. Reference specific files when appropriate and explain how they relate to the question. If the available information is insufficient, clearly state what additional details would be needed."""
+    
+    def _get_stage1_system_prompt(self) -> str:
+        """Get system prompt for stage 1."""
+        return """You are a technical assistant that analyzes software projects to extract relevant search terms and compress information.
+
+Your task:
+1. Analyze the user's question about a codebase
+2. Extract 3-5 search terms that would help find relevant files to answer the question
+3. Compress the project overview to focus on information relevant to the question
+
+Search terms should be:
+- Technical keywords (function names, class names, concepts)
+- File types or directory names if relevant
+- Domain-specific terminology from the question
+
+The compressed overview should:
+- Be 2-3 sentences maximum
+- Focus only on aspects relevant to answering the question
+- Preserve the most important architectural or functional details
+
+Always respond with valid JSON matching the requested format."""
+    
+    def _get_stage2_system_prompt(self) -> str:
+        """Get system prompt for stage 2."""
+        return """You are a software engineering expert that provides detailed answers about codebases using available context.
+
+When answering:
+1. Use the compressed project overview for high-level context
+2. Reference specific files from the relevant files list when they relate to the question
+3. Explain how different files work together if relevant
+4. Be specific and technical when appropriate
+5. If information is incomplete, clearly state what's missing and suggest next steps
+6. Provide actionable insights when possible
+
+Your answer should be comprehensive but focused on the specific question asked."""
+    
+    def format_response(self, result: Dict[str, Any], format_type: str = "text") -> str:
+        """
+        Format response for CLI output.
+        
+        Args:
+            result: Result from deepask_question
+            format_type: Output format ("text" or "json")
+            
+        Returns:
+            Formatted response string
+        """
+        if format_type == "json":
+            import json
+            return json.dumps(result, indent=2)
+        
+        # Text format
+        answer = result["answer"]
+        metadata = result["metadata"]
+        
+        output = []
+        output.append(f"Question: {result['question']}")
+        output.append(f"Project: {result['project_name']} (branch: {metadata['branch']})")
+        output.append("")
+        output.append("Answer:")
+        output.append(answer)
+        output.append("")
+        
+        # Show search terms used
+        output.append(f"Search terms: {', '.join(result['search_terms'])}")
+        output.append("")
+        
+        # Show relevant files
+        if result["relevant_files"]:
+            output.append("Relevant files analyzed:")
+            for i, file_info in enumerate(result["relevant_files"], 1):
+                output.append(f"  {i}. {file_info['filePath']}")
+        else:
+            output.append("No relevant files found.")
+        output.append("")
+        
+        # Show metadata
+        output.append("Metadata:")
+        output.append(f"  Model: {metadata['model']}")
+        output.append(f"  Total files found: {metadata['total_files_found']}")
+        output.append(f"  Files included: {metadata['files_included']}")
+        
+        stage1_tokens = metadata['stage1_tokens']['total_tokens']
+        stage2_tokens = metadata['stage2_tokens']['total_tokens']
+        if stage1_tokens and stage2_tokens:
+            output.append(f"  Total tokens: {stage1_tokens + stage2_tokens} (Stage 1: {stage1_tokens}, Stage 2: {stage2_tokens})")
+        
+        return "\n".join(output)

{mcp_code_indexer-2.1.0 → mcp_code_indexer-2.2.1}/src/mcp_code_indexer/server/mcp_server.py

@@ -324,7 +324,7 @@ class MCPCodeIndexServer:
                 ),
                 types.Tool(
                     name="search_descriptions",
-                    description="Searches through all file descriptions in a project to find files related to specific functionality. Use this for large codebases instead of loading the entire structure. Always start with the fewest terms possible; if the tool returns a lot of results (more than 20) or the results are not relevant, then narrow it down by increasing the number of search terms. Start broad, then narrow the focus only if needed!",
+                    description="Searches through all file descriptions in a project to find files related to specific functionality. Use this for large codebases instead of loading the entire structure. Always start with the fewest terms possible (1 to 3 words AT MOST); if the tool returns a lot of results (more than 20) or the results are not relevant, then narrow it down by increasing the number of search words one at a time and calling the tool again. Start VERY broad, then narrow the focus only if needed!",
                     inputSchema={
                         "type": "object",
                         "properties": {

{mcp_code_indexer-2.1.0 → mcp_code_indexer-2.2.1/src/mcp_code_indexer.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-code-indexer
-Version: 2.1.0
+Version: 2.2.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,8 +59,8 @@ Dynamic: requires-python
 
 # MCP Code Indexer 🚀
 
-[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?14)](https://badge.fury.io/py/mcp-code-indexer)
-[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?14)](https://pypi.org/project/mcp-code-indexer/)
+[![PyPI version](https://badge.fury.io/py/mcp-code-indexer.svg?16)](https://badge.fury.io/py/mcp-code-indexer)
+[![Python](https://img.shields.io/pypi/pyversions/mcp-code-indexer.svg?16)](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.

{mcp_code_indexer-2.1.0 → mcp_code_indexer-2.2.1}/src/mcp_code_indexer.egg-info/SOURCES.txt

@@ -17,6 +17,9 @@ migrations/002_performance_indexes.sql
 migrations/003_project_overviews.sql
 src/mcp_code_indexer/__init__.py
 src/mcp_code_indexer/__main__.py
+src/mcp_code_indexer/ask_handler.py
+src/mcp_code_indexer/claude_api_handler.py
+src/mcp_code_indexer/deepask_handler.py
 src/mcp_code_indexer/error_handler.py
 src/mcp_code_indexer/file_scanner.py
 src/mcp_code_indexer/git_hook_handler.py