nia-mcp-server 1.0.18__py3-none-any.whl → 1.0.20__py3-none-any.whl

nia_mcp_server/server.py

@@ -186,34 +186,22 @@ async def search_codebase(
     try:
         client = await ensure_api_client()
         
-        # Get all indexed repositories if not specified
+        # Require explicit repository selection
         if not repositories:
-            all_repos = await client.list_repositories()
-            
-            # Ensure all_repos is a list and contains dictionaries
-            if not isinstance(all_repos, list):
-                logger.error(f"Unexpected type for all_repos: {type(all_repos)}")
-                return [TextContent(
-                    type="text",
-                    text="❌ Error retrieving repositories. The API returned an unexpected response."
-                )]
-            
-            repositories = []
-            for repo in all_repos:
-                if isinstance(repo, dict) and repo.get("status") == "completed":
-                    repo_name = repo.get("repository")
-                    if repo_name:
-                        repositories.append(repo_name)
-                    else:
-                        logger.warning(f"Repository missing 'repository' field: {repo}")
-                else:
-                    logger.warning(f"Unexpected repository format: {type(repo)}, value: {repo}")
-            
-            if not repositories:
-                return [TextContent(
-                    type="text",
-                    text="❌ No indexed repositories found. Use `index_repository` to index a codebase first."
-                )]
+            return [TextContent(
+                type="text",
+                text="🔍 **Please specify which repositories to search:**\n\n"
+                     "1. Use `list_repositories` to see available repositories\n"
+                     "2. Then call `search_codebase(\"your query\", [\"owner/repo1\", \"owner/repo2\"])`\n\n"
+                     "**Example:**\n"
+                     "```\n"
+                     "search_codebase(\"How does auth work?\", [\"facebook/react\"])\n"
+                     "```\n\n"
+                     "**📌 Tip:** You can search specific folders using the exact format from `list_repositories`:\n"
+                     "```\n"
+                     "search_codebase(\"query\", [\"owner/repo/tree/branch/folder\"])\n"
+                     "```"
+            )]
         
         # Build messages for the query
         messages = [
@@ -343,31 +331,46 @@ async def search_documentation(
     include_sources: bool = True
 ) -> List[TextContent]:
     """
-    Search indexed documentation using natural language. 
-    
+    Search indexed documentation using natural language.
+
     Args:
         query: Natural language search query. Don't just use keywords or unstrctured query, make a comprehensive question to get the best results possible.
-        sources: List of documentation source IDs to search. Use it based on user's query.
+        sources: List of documentation identifiers to search. Can be:
+            - Display names (e.g., "Vercel AI SDK - Core")
+            - URLs (e.g., "https://sdk.vercel.ai/docs")
+            - Source IDs (UUID format for backwards compatibility)
         include_sources: Whether to include source references in results
-        
+
     Returns:
         Search results with relevant documentation excerpts
 
     Important:
-        - Always use Source ID. If you don't have it, use `list_documentation` tool to get it.
+        - You can now use friendly names instead of UUIDs! Try display names or URLs.
+        - If you don't know the identifiers, use `list_documentation` tool to see available options.
     """
     try:
         client = await ensure_api_client()
         
-        # Get all indexed documentation sources if not specified
+        # Require explicit source selection
         if not sources:
-            all_sources = await client.list_data_sources()
-            sources = [source["id"] for source in all_sources if source.get("status") == "completed"]
-            if not sources:
-                return [TextContent(
-                    type="text",
-                    text="❌ No indexed documentation found. Use `index_documentation` to index documentation first."
-                )]
+            return [TextContent(
+                type="text",
+                text="📚 **Please specify which documentation sources to search:**\n\n"
+                     "1. Use `list_documentation` to see available sources\n"
+                     "2. Then call `search_documentation(\"your query\", [\"source1\", \"source2\"])`\n\n"
+                     "**You can use any of these identifier formats:**\n"
+                     "- Display names: `\"Vercel AI SDK - Core\"`\n"
+                     "- URLs: `\"https://docs.trynia.ai/\"`\n"
+                     "- UUIDs: `\"550e8400-e29b-41d4-a716-446655440000\"`\n\n"
+                     "**Example:**\n"
+                     "```\n"
+                     "search_documentation(\"API reference\", [\"Vercel AI SDK - Core\"])\n"
+                     "```\n\n"
+                     "**📌 Tip:** Mix different identifier types in the same search:\n"
+                     "```\n"
+                     "search_documentation(\"query\", [\"Display Name\", \"https://docs.example.com/\"])\n"
+                     "```"
+            )]
         
         # Build messages for the query
         messages = [
@@ -471,8 +474,8 @@ async def search_documentation(
             text=f"❌ Error searching documentation: {str(e)}"
         )]
 
-@mcp.tool()
-async def list_repositories() -> List[TextContent]:
+# @mcp.tool()
+# async def list_repositories() -> List[TextContent]:
     """
     List all indexed repositories.
     
@@ -555,8 +558,8 @@ async def list_repositories() -> List[TextContent]:
             text=f"❌ Error listing repositories: {error_msg}"
         )]
 
-@mcp.tool()
-async def check_repository_status(repository: str) -> List[TextContent]:
+# @mcp.tool()
+# async def check_repository_status(repository: str) -> List[TextContent]:
     """
     Check the indexing status of a repository.
     
@@ -704,8 +707,8 @@ async def index_documentation(
             text=f"❌ Error indexing documentation: {str(e)}"
         )]
 
-@mcp.tool()
-async def list_documentation() -> List[TextContent]:
+# @mcp.tool()
+# async def list_documentation() -> List[TextContent]:
     """
     List all indexed documentation sources.
     
@@ -763,8 +766,8 @@ async def list_documentation() -> List[TextContent]:
             text=f"❌ Error listing documentation: {str(e)}"
         )]
 
-@mcp.tool()
-async def check_documentation_status(source_id: str) -> List[TextContent]:
+# @mcp.tool()
+# async def check_documentation_status(source_id: str) -> List[TextContent]:
     """
     Check the indexing status of a documentation source.
     
@@ -829,8 +832,390 @@ async def check_documentation_status(source_id: str) -> List[TextContent]:
             text=f"❌ Error checking documentation status: {str(e)}"
         )]
 
+# Combined Resource Management Tools
+
+@mcp.tool()
+async def rename_resource(
+    resource_type: str,
+    identifier: str,
+    new_name: str
+) -> List[TextContent]:
+    """
+    Rename a resource (repository or documentation) for better organization.
+
+    Args:
+        resource_type: Type of resource - "repository" or "documentation"
+        identifier:
+            - For repository: Repository in owner/repo format (e.g., "facebook/react")
+            - For documentation: Can be display name, URL, or UUID (e.g., "Vercel AI SDK - Core", "https://docs.trynia.ai/", or "doc-id-123")
+        new_name: New display name for the resource (1-100 characters)
+
+    Returns:
+        Confirmation of rename operation
+
+    Examples:
+        - rename_resource("repository", "facebook/react", "React Framework")
+        - rename_resource("documentation", "Vercel AI SDK - Core", "Python Official Docs")
+        - rename_resource("documentation", "https://docs.trynia.ai/", "NIA Documentation")
+    """
+    try:
+        # Validate resource type
+        if resource_type not in ["repository", "documentation"]:
+            return [TextContent(
+                type="text",
+                text=f"❌ Invalid resource_type: '{resource_type}'. Must be 'repository' or 'documentation'."
+            )]
+
+        # Validate name length
+        if not new_name or len(new_name) > 100:
+            return [TextContent(
+                type="text",
+                text="❌ Display name must be between 1 and 100 characters."
+            )]
+
+        client = await ensure_api_client()
+
+        if resource_type == "repository":
+            result = await client.rename_repository(identifier, new_name)
+            resource_desc = f"repository '{identifier}'"
+        else:  # documentation
+            result = await client.rename_data_source(identifier, new_name)
+            resource_desc = f"documentation source"
+
+        if result.get("success"):
+            return [TextContent(
+                type="text",
+                text=f"✅ Successfully renamed {resource_desc} to '{new_name}'"
+            )]
+        else:
+            return [TextContent(
+                type="text",
+                text=f"❌ Failed to rename {resource_type}: {result.get('message', 'Unknown error')}"
+            )]
+
+    except APIError as e:
+        logger.error(f"API Error renaming {resource_type}: {e}")
+        error_msg = f"❌ {str(e)}"
+        if e.status_code == 403 and "lifetime limit" in str(e).lower():
+            error_msg += "\n\n💡 Tip: You've reached the free tier limit. Upgrade to Pro for unlimited access."
+        return [TextContent(type="text", text=error_msg)]
+    except Exception as e:
+        logger.error(f"Error renaming {resource_type}: {e}")
+        return [TextContent(
+            type="text",
+            text=f"❌ Error renaming {resource_type}: {str(e)}"
+        )]
+
+@mcp.tool()
+async def delete_resource(
+    resource_type: str,
+    identifier: str
+) -> List[TextContent]:
+    """
+    Delete an indexed resource (repository or documentation).
+
+    Args:
+        resource_type: Type of resource - "repository" or "documentation"
+        identifier:
+            - For repository: Repository in owner/repo format (e.g., "facebook/react")
+            - For documentation: Can be display name, URL, or UUID (e.g., "Vercel AI SDK - Core", "https://docs.trynia.ai/", or "doc-id-123")
+
+    Returns:
+        Confirmation of deletion
+
+    Examples:
+        - delete_resource("repository", "facebook/react")
+        - delete_resource("documentation", "Vercel AI SDK - Core")
+        - delete_resource("documentation", "https://docs.trynia.ai/")
+    """
+    try:
+        # Validate resource type
+        if resource_type not in ["repository", "documentation"]:
+            return [TextContent(
+                type="text",
+                text=f"❌ Invalid resource_type: '{resource_type}'. Must be 'repository' or 'documentation'."
+            )]
+
+        client = await ensure_api_client()
+
+        if resource_type == "repository":
+            success = await client.delete_repository(identifier)
+            resource_desc = f"repository: {identifier}"
+        else:  # documentation
+            success = await client.delete_data_source(identifier)
+            resource_desc = f"documentation source: {identifier}"
+
+        if success:
+            return [TextContent(
+                type="text",
+                text=f"✅ Successfully deleted {resource_desc}"
+            )]
+        else:
+            return [TextContent(
+                type="text",
+                text=f"❌ Failed to delete {resource_desc}"
+            )]
+
+    except APIError as e:
+        logger.error(f"API Error deleting {resource_type}: {e}")
+        error_msg = f"❌ {str(e)}"
+        if e.status_code == 403 and "lifetime limit" in str(e).lower():
+            error_msg += "\n\n💡 Tip: You've reached the free tier limit of 3 indexing operations. Upgrade to Pro for unlimited access."
+        return [TextContent(type="text", text=error_msg)]
+    except Exception as e:
+        logger.error(f"Error deleting {resource_type}: {e}")
+        return [TextContent(
+            type="text",
+            text=f"❌ Error deleting {resource_type}: {str(e)}"
+        )]
+
+@mcp.tool()
+async def check_resource_status(
+    resource_type: str,
+    identifier: str
+) -> List[TextContent]:
+    """
+    Check the indexing status of a resource (repository or documentation).
+
+    Args:
+        resource_type: Type of resource - "repository" or "documentation"
+        identifier:
+            - For repository: Repository in owner/repo format (e.g., "facebook/react")
+            - For documentation: Source ID (UUID format only) - use list_resources to get the UUID
+
+    Returns:
+        Current status of the resource
+
+    Examples:
+        - check_resource_status("repository", "facebook/react")
+        - check_resource_status("documentation", "550e8400-e29b-41d4-a716-446655440000")
+
+    Note:
+        - Documentation status checking requires UUID identifiers only
+        - Use list_resources("documentation") to find the UUID for a documentation source
+    """
+    try:
+        # Validate resource type
+        if resource_type not in ["repository", "documentation"]:
+            return [TextContent(
+                type="text",
+                text=f"❌ Invalid resource_type: '{resource_type}'. Must be 'repository' or 'documentation'."
+            )]
+
+        client = await ensure_api_client()
+
+        if resource_type == "repository":
+            status = await client.get_repository_status(identifier)
+            if not status:
+                return [TextContent(
+                    type="text",
+                    text=f"❌ Repository '{identifier}' not found."
+                )]
+            title = f"Repository Status: {identifier}"
+            status_key = "status"
+        else:  # documentation
+            status = await client.get_data_source_status(identifier)
+            if not status:
+                return [TextContent(
+                    type="text",
+                    text=f"❌ Documentation source '{identifier}' not found."
+                )]
+            title = f"Documentation Status: {status.get('url', 'Unknown URL')}"
+            status_key = "status"
+
+        # Format status with appropriate icon
+        status_text = status.get(status_key, "unknown")
+        status_icon = {
+            "completed": "✅",
+            "indexing": "⏳",
+            "processing": "⏳",
+            "failed": "❌",
+            "pending": "🔄",
+            "error": "❌"
+        }.get(status_text, "❓")
+
+        lines = [
+            f"# {title}\n",
+            f"{status_icon} **Status:** {status_text}"
+        ]
+
+        # Add resource-specific fields
+        if resource_type == "repository":
+            lines.append(f"**Branch:** {status.get('branch', 'main')}")
+            if status.get("progress"):
+                progress = status["progress"]
+                if isinstance(progress, dict):
+                    lines.append(f"**Progress:** {progress.get('percentage', 0)}%")
+                    if progress.get("stage"):
+                        lines.append(f"**Stage:** {progress['stage']}")
+        else:  # documentation
+            lines.append(f"**Source ID:** {identifier}")
+            if status.get("page_count", 0) > 0:
+                lines.append(f"**Pages Indexed:** {status['page_count']}")
+            if status.get("details"):
+                details = status["details"]
+                if details.get("progress"):
+                    lines.append(f"**Progress:** {details['progress']}%")
+                if details.get("stage"):
+                    lines.append(f"**Stage:** {details['stage']}")
+
+        # Common fields
+        if status.get("indexed_at"):
+            lines.append(f"**Indexed:** {status['indexed_at']}")
+        elif status.get("created_at"):
+            lines.append(f"**Created:** {status['created_at']}")
+
+        if status.get("error"):
+            lines.append(f"**Error:** {status['error']}")
+
+        return [TextContent(type="text", text="\n".join(lines))]
+
+    except APIError as e:
+        logger.error(f"API Error checking {resource_type} status: {e}")
+        error_msg = f"❌ {str(e)}"
+        if e.status_code == 403 and "lifetime limit" in str(e).lower():
+            error_msg += "\n\n💡 Tip: You've reached the free tier limit of 3 indexing operations. Upgrade to Pro for unlimited access."
+        return [TextContent(type="text", text=error_msg)]
+    except Exception as e:
+        logger.error(f"Error checking {resource_type} status: {e}")
+        return [TextContent(
+            type="text",
+            text=f"❌ Error checking {resource_type} status: {str(e)}"
+        )]
+
 @mcp.tool()
-async def delete_documentation(source_id: str) -> List[TextContent]:
+async def list_resources(
+    resource_type: Optional[str] = None
+) -> List[TextContent]:
+    """
+    List indexed resources (repositories and/or documentation).
+
+    Args:
+        resource_type: Optional filter - "repository", "documentation", or None for all
+
+    Returns:
+        List of indexed resources with their status
+
+    Examples:
+        - list_resources() - List all resources
+        - list_resources("repository") - List only repositories
+        - list_resources("documentation") - List only documentation
+    """
+    try:
+        # Validate resource type if provided
+        if resource_type and resource_type not in ["repository", "documentation"]:
+            return [TextContent(
+                type="text",
+                text=f"❌ Invalid resource_type: '{resource_type}'. Must be 'repository', 'documentation', or None for all."
+            )]
+
+        client = await ensure_api_client()
+        lines = []
+
+        # Determine what to list
+        list_repos = resource_type in [None, "repository"]
+        list_docs = resource_type in [None, "documentation"]
+
+        if list_repos:
+            repositories = await client.list_repositories()
+
+            if repositories:
+                lines.append("# Indexed Repositories\n")
+                for repo in repositories:
+                    status_icon = "✅" if repo.get("status") == "completed" else "⏳"
+
+                    # Show display name if available, otherwise show repository
+                    display_name = repo.get("display_name")
+                    repo_name = repo['repository']
+
+                    if display_name:
+                        lines.append(f"\n## {status_icon} {display_name}")
+                        lines.append(f"- **Repository:** {repo_name}")
+                    else:
+                        lines.append(f"\n## {status_icon} {repo_name}")
+
+                    lines.append(f"- **Branch:** {repo.get('branch', 'main')}")
+                    lines.append(f"- **Status:** {repo.get('status', 'unknown')}")
+                    if repo.get("indexed_at"):
+                        lines.append(f"- **Indexed:** {repo['indexed_at']}")
+                    if repo.get("error"):
+                        lines.append(f"- **Error:** {repo['error']}")
+
+                    # Add usage hint for completed repositories
+                    if repo.get("status") == "completed":
+                        lines.append(f"- **Usage:** `search_codebase(query, [\"{repo_name}\"])`")
+            elif resource_type == "repository":
+                lines.append("No indexed repositories found.\n\n")
+                lines.append("Get started by indexing a repository:\n")
+                lines.append("Use `index_repository` with a GitHub URL.")
+
+        if list_docs:
+            sources = await client.list_data_sources()
+
+            if sources:
+                if lines:  # Add separator if we already have repositories
+                    lines.append("\n---\n")
+                lines.append("# Indexed Documentation\n")
+
+                for source in sources:
+                    status_icon = "✅" if source.get("status") == "completed" else "⏳"
+
+                    # Show display name if available, otherwise show URL
+                    display_name = source.get("display_name")
+                    url = source.get('url', 'Unknown URL')
+
+                    if display_name:
+                        lines.append(f"\n## {status_icon} {display_name}")
+                        lines.append(f"- **URL:** {url}")
+                    else:
+                        lines.append(f"\n## {status_icon} {url}")
+
+                    lines.append(f"- **ID:** {source['id']}")
+                    lines.append(f"- **Status:** {source.get('status', 'unknown')}")
+                    lines.append(f"- **Type:** {source.get('source_type', 'web')}")
+                    if source.get("page_count", 0) > 0:
+                        lines.append(f"- **Pages:** {source['page_count']}")
+                    if source.get("created_at"):
+                        lines.append(f"- **Created:** {source['created_at']}")
+            elif resource_type == "documentation":
+                lines.append("No indexed documentation found.\n\n")
+                lines.append("Get started by indexing documentation:\n")
+                lines.append("Use `index_documentation` with a URL.")
+
+        if not lines:
+            lines.append("No indexed resources found.\n\n")
+            lines.append("Get started by indexing:\n")
+            lines.append("- Use `index_repository` for GitHub repositories\n")
+            lines.append("- Use `index_documentation` for documentation sites")
+
+        return [TextContent(type="text", text="\n".join(lines))]
+
+    except APIError as e:
+        logger.error(f"API Error listing resources: {e}")
+        error_msg = f"❌ {str(e)}"
+        if e.status_code == 403 or "free tier limit" in str(e).lower():
+            if e.detail and "3 free indexing operations" in e.detail:
+                error_msg = f"❌ {e.detail}\n\n💡 Tip: Upgrade to Pro at https://trynia.ai/billing for unlimited indexing."
+            else:
+                error_msg += "\n\n💡 Tip: You've reached the free tier limit. Upgrade to Pro for unlimited access."
+        return [TextContent(type="text", text=error_msg)]
+    except Exception as e:
+        logger.error(f"Unexpected error listing resources: {e}")
+        error_msg = str(e)
+        if "indexing operations" in error_msg.lower() or "lifetime limit" in error_msg.lower():
+            return [TextContent(
+                type="text",
+                text=f"❌ {error_msg}\n\n💡 Tip: Upgrade to Pro at https://trynia.ai/billing for unlimited indexing."
+            )]
+        return [TextContent(
+            type="text",
+            text=f"❌ Error listing resources: {error_msg}"
+        )]
+
+# Old individual tools (to be commented out after testing)
+
+# @mcp.tool()
+# async def delete_documentation(source_id: str) -> List[TextContent]:
     """
     Delete an indexed documentation source.
     
@@ -868,8 +1253,8 @@ async def delete_documentation(source_id: str) -> List[TextContent]:
             text=f"❌ Error deleting documentation: {str(e)}"
         )]
 
-@mcp.tool()
-async def delete_repository(repository: str) -> List[TextContent]:
+# @mcp.tool()
+# async def delete_repository(repository: str) -> List[TextContent]:
     """
     Delete an indexed repository.
     
@@ -907,8 +1292,8 @@ async def delete_repository(repository: str) -> List[TextContent]:
             text=f"❌ Error deleting repository: {str(e)}"
         )]
 
-@mcp.tool()
-async def rename_repository(repository: str, new_name: str) -> List[TextContent]:
+# @mcp.tool()
+# async def rename_repository(repository: str, new_name: str) -> List[TextContent]:
     """
     Rename an indexed repository for better organization.
     
@@ -954,8 +1339,8 @@ async def rename_repository(repository: str, new_name: str) -> List[TextContent]
             text=f"❌ Error renaming repository: {str(e)}"
         )]
 
-@mcp.tool()
-async def rename_documentation(source_id: str, new_name: str) -> List[TextContent]:
+# @mcp.tool()
+# async def rename_documentation(source_id: str, new_name: str) -> List[TextContent]:
     """
     Rename a documentation source for better organization.
     
@@ -1633,406 +2018,814 @@ async def read_source_content(
             text=f"❌ Error reading source content: {str(e)}"
         )]
 
+# @mcp.tool()
+# async def index_local_filesystem(
+#     directory_path: str,
+#     inclusion_patterns: Optional[List[str]] = None,
+#     exclusion_patterns: Optional[List[str]] = None,
+#     max_file_size_mb: int = 50
+# ) -> List[TextContent]:
+#     """
+#     Index a local filesystem directory for intelligent search.
+#
+#     Args:
+#         directory_path: Absolute path to the directory to index
+#         inclusion_patterns: Optional list of patterns to include (e.g., ["ext:.py", "dir:src"])
+#         exclusion_patterns: Optional list of patterns to exclude (e.g., ["dir:node_modules", "ext:.log"])
+#         max_file_size_mb: Maximum file size in MB to process (default: 50)
+#
+#     Returns:
+#         Status of the indexing operation
+#
+#     Important:
+#         - Path must be absolute (e.g., /Users/username/projects/myproject)
+#         - When indexing starts, use check_local_filesystem_status tool to monitor progress
+#     """
+#     try:
+#         # Validate absolute path
+#         if not os.path.isabs(directory_path):
+#             return [TextContent(
+#                 type="text",
+#                 text=f"❌ Error: directory_path must be an absolute path. Got: {directory_path}\n\n"
+#                      f"Example: /Users/username/projects/myproject"
+#             )]
+#
+#         client = await ensure_api_client()
+#
+#         # Start indexing
+#         logger.info(f"Starting to index local directory: {directory_path}")
+#         result = await client.index_local_filesystem(
+#             directory_path=directory_path,
+#             inclusion_patterns=inclusion_patterns or [],
+#             exclusion_patterns=exclusion_patterns or [],
+#             max_file_size_mb=max_file_size_mb
+#         )
+#
+#         if result.get("success"):
+#             source_id = result["data"]["source_id"]
+#             status_url = result["data"]["status_url"]
+#
+#             return [TextContent(
+#                 type="text",
+#                 text=(
+#                     f"✅ Successfully started indexing local directory!\n\n"
+#                     f"📁 **Directory:** `{directory_path}`\n"
+#                     f"🆔 **Source ID:** `{source_id}`\n"
+#                     f"📊 **Status:** Processing\n\n"
+#                     f"**What happens next:**\n"
+#                     f"• NIA is scanning and indexing your files in the background\n"
+#                     f"• This process typically takes a few minutes depending on directory size\n"
+#                     f"• Use `check_local_filesystem_status` with source ID `{source_id}` to monitor progress\n"
+#                     f"• Once indexed, use `search_codebase` or `search_documentation` to search your files\n\n"
+#                     f"📌 **Tip:** You can check the status at any time or visit [app.trynia.ai](https://app.trynia.ai) to monitor progress."
+#                 )
+#             )]
+#         else:
+#             return [TextContent(
+#                 type="text",
+#                 text=f"❌ Failed to start indexing: {result.get('detail', 'Unknown error')}"
+#             )]
+#
+#     except APIError as e:
+#         logger.error(f"API error indexing local filesystem: {e}")
+#         return [TextContent(
+#             type="text",
+#             text=f"❌ API Error: {str(e)}\n\nStatus Code: {e.status_code}\nDetails: {e.detail}"
+#         )]
+#     except Exception as e:
+#         logger.error(f"Unexpected error indexing local filesystem: {e}")
+#         return [TextContent(
+#             type="text",
+#             text=f"❌ Error: An unexpected error occurred while indexing the directory: {str(e)}"
+#         )]
+
+# @mcp.tool()
+# async def scan_local_filesystem(
+#     directory_path: str,
+#     inclusion_patterns: Optional[List[str]] = None,
+#     exclusion_patterns: Optional[List[str]] = None,
+#     max_file_size_mb: int = 50
+# ) -> List[TextContent]:
+#     """
+#     Scan a local filesystem directory to preview what files would be indexed.
+#
+#     This tool helps you understand what files will be processed before actually indexing.
+#
+#     Args:
+#         directory_path: Absolute path to the directory to scan
+#         inclusion_patterns: Optional list of patterns to include (e.g., ["ext:.py", "dir:src"])
+#         exclusion_patterns: Optional list of patterns to exclude (e.g., ["dir:node_modules", "ext:.log"])
+#         max_file_size_mb: Maximum file size in MB to process (default: 50)
+#
+#     Returns:
+#         Summary of files that would be indexed including count, size, and file types
+#     """
+#     try:
+#         # Validate absolute path
+#         if not os.path.isabs(directory_path):
+#             return [TextContent(
+#                 type="text",
+#                 text=f"❌ Error: directory_path must be an absolute path. Got: {directory_path}\n\n"
+#                      f"Example: /Users/username/projects/myproject"
+#             )]
+#
+#         client = await ensure_api_client()
+#
+#         logger.info(f"Scanning local directory: {directory_path}")
+#         result = await client.scan_local_filesystem(
+#             directory_path=directory_path,
+#             inclusion_patterns=inclusion_patterns or [],
+#             exclusion_patterns=exclusion_patterns or [],
+#             max_file_size_mb=max_file_size_mb
+#         )
+#
+#         # Format the scan results
+#         total_files = result.get("total_files", 0)
+#         total_size_mb = result.get("total_size_mb", 0)
+#         file_types = result.get("file_types", {})
+#         files = result.get("files", [])
+#         truncated = result.get("truncated", False)
+#
+#         response = f"📊 **Local Directory Scan Results**\n\n"
+#         response += f"📁 **Directory:** `{directory_path}`\n"
+#         response += f"📄 **Total Files:** {total_files:,}\n"
+#         response += f"💾 **Total Size:** {total_size_mb:.2f} MB\n\n"
+#
+#         if file_types:
+#             response += "**File Types:**\n"
+#             # Sort by count descending
+#             sorted_types = sorted(file_types.items(), key=lambda x: x[1], reverse=True)
+#             for ext, count in sorted_types[:10]:  # Show top 10
+#                 response += f"• `{ext}`: {count:,} files\n"
+#             if len(sorted_types) > 10:
+#                 response += f"• ... and {len(sorted_types) - 10} more types\n"
+#             response += "\n"
+#
+#         if files:
+#             response += f"**Largest Files (showing {min(len(files), 10)}):**\n"
+#             for i, file_info in enumerate(files[:10]):
+#                 size_mb = file_info["size"] / (1024 * 1024)
+#                 response += f"{i+1}. `{file_info['path']}` ({size_mb:.2f} MB)\n"
+#
+#             if truncated:
+#                 response += f"\n*Note: Showing first 100 files out of {total_files:,} total*\n"
+#
+#         if inclusion_patterns:
+#             response += f"\n**Inclusion Patterns:** {', '.join(f'`{p}`' for p in inclusion_patterns)}\n"
+#         if exclusion_patterns:
+#             response += f"**Exclusion Patterns:** {', '.join(f'`{p}`' for p in exclusion_patterns)}\n"
+#
+#         response += "\n💡 **Next Step:** Use `index_local_filesystem` to index these files."
+#
+#         return [TextContent(type="text", text=response)]
+#
+#     except APIError as e:
+#         logger.error(f"API error scanning local filesystem: {e}")
+#         return [TextContent(
+#             type="text",
+#             text=f"❌ API Error: {str(e)}\n\nStatus Code: {e.status_code}\nDetails: {e.detail}"
+#         )]
+#     except Exception as e:
+#         logger.error(f"Unexpected error scanning local filesystem: {e}")
+#         return [TextContent(
+#             type="text",
+#             text=f"❌ Error: An unexpected error occurred while scanning: {str(e)}"
+#         )]
+
+# @mcp.tool()
+# async def check_local_filesystem_status(source_id: str) -> List[TextContent]:
+#     """
+#     Check the indexing status of a local filesystem source.
+#
+#     Args:
+#         source_id: The source ID returned when indexing was started
+#
+#     Returns:
+#         Current status of the local filesystem indexing
+#     """
+#     try:
+#         client = await ensure_api_client()
+#         status = await client.check_local_filesystem_status(source_id)
+#
+#         # Format status response
+#         status_text = status.get("status", "unknown")
+#         progress = status.get("progress", 0)
+#         message = status.get("message", "")
+#         error = status.get("error")
+#         directory_path = status.get("directory_path", "Unknown")
+#         page_count = status.get("page_count", 0)  # Number of files
+#         chunk_count = status.get("chunk_count", 0)
+#
+#         # Status emoji
+#         status_emoji = {
+#             "pending": "⏳",
+#             "processing": "🔄",
+#             "completed": "✅",
+#             "failed": "❌",
+#             "error": "❌"
+#         }.get(status_text, "❓")
+#
+#         response = f"{status_emoji} **Local Filesystem Status**\n\n"
+#         response += f"🆔 **Source ID:** `{source_id}`\n"
+#         response += f"📁 **Directory:** `{directory_path}`\n"
+#         response += f"📊 **Status:** {status_text.capitalize()}\n"
+#
+#         if progress > 0:
+#             response += f"📈 **Progress:** {progress}%\n"
+#
+#         if message:
+#             response += f"💬 **Message:** {message}\n"
+#
+#         if status_text == "completed":
+#             response += f"\n✨ **Indexing Complete!**\n"
+#             response += f"• **Files Indexed:** {page_count:,}\n"
+#             response += f"• **Chunks Created:** {chunk_count:,}\n"
+#             response += f"\nYou can now search this directory using `search_codebase` or the unified search!"
+#         elif status_text in ["failed", "error"]:
+#             response += f"\n❌ **Indexing Failed**\n"
+#             if error:
+#                 response += f"**Error:** {error}\n"
+#             response += "\nPlease check your directory path and try again."
+#         elif status_text == "processing":
+#             response += f"\n🔄 Indexing is in progress...\n"
+#             response += "Check back in a few moments or monitor at [app.trynia.ai](https://app.trynia.ai)"
+#
+#         return [TextContent(type="text", text=response)]
+#
+#     except APIError as e:
+#         logger.error(f"API error checking local filesystem status: {e}")
+#         if e.status_code == 404:
+#             return [TextContent(
+#                 type="text",
+#                 text=f"❌ Source ID `{source_id}` not found. Please check the ID and try again."
+#             )]
+#         return [TextContent(
+#             type="text",
+#             text=f"❌ API Error: {str(e)}\n\nStatus Code: {e.status_code}\nDetails: {e.detail}"
+#         )]
+#     except Exception as e:
+#         logger.error(f"Unexpected error checking local filesystem status: {e}")
+#         return [TextContent(
+#             type="text",
+#             text=f"❌ Error: An unexpected error occurred: {str(e)}"
+#         )]
+
+# @mcp.tool()
+# async def search_local_filesystem(
+#     source_id: str,
+#     query: str,
+#     include_sources: bool = True
+# ) -> List[TextContent]:
+#     """
+#     Search an indexed local filesystem directory using its source ID.
+#
+#     To search local files:
+#     1. First index a directory using `index_local_filesystem` - this will return a source_id
+#     2. Use that source_id with this tool to search the indexed content
+#
+#     Args:
+#         source_id: The source ID returned when the directory was indexed (required)
+#         query: Your search query in natural language (required)
+#         include_sources: Whether to include source code snippets in results (default: True)
+#
+#     Returns:
+#         Search results with relevant file snippets and explanations
+#
+#     Example:
+#         # After indexing returns source_id "abc123-def456"
+#         search_local_filesystem(
+#             source_id="abc123-def456",
+#             query="configuration settings"
+#         )
+#
+#     Note: To find your source IDs, use `list_documentation` and look for
+#     sources with source_type="local_filesystem"
+#     """
+#     try:
+#         # Validate inputs
+#         if not source_id:
+#             return [TextContent(
+#                 type="text",
+#                 text="❌ Error: 'source_id' parameter is required. Use the ID returned from index_local_filesystem."
+#             )]
+#
+#         if not query:
+#             return [TextContent(
+#                 type="text",
+#                 text="❌ Error: 'query' parameter is required"
+#             )]
+#
+#         client = await ensure_api_client()
+#
+#         # Check if the source exists and is ready
+#         logger.info(f"Checking status of source {source_id}")
+#         try:
+#             status = await client.get_data_source_status(source_id)
+#             if not status:
+#                 return [TextContent(
+#                     type="text",
+#                     text=f"❌ Source ID '{source_id}' not found. Please check the ID and try again."
+#                 )]
+#
+#             source_status = status.get("status", "unknown")
+#             if source_status == "processing":
+#                 progress = status.get("progress", 0)
+#                 return [TextContent(
+#                     type="text",
+#                     text=f"⏳ This source is still being indexed ({progress}% complete).\n\n"
+#                          f"Use `check_local_filesystem_status(\"{source_id}\")` to check progress."
+#                 )]
+#             elif source_status == "failed":
+#                 error = status.get("error", "Unknown error")
+#                 return [TextContent(
+#                     type="text",
+#                     text=f"❌ This source failed to index.\n\nError: {error}"
+#                 )]
+#             elif source_status != "completed":
+#                 return [TextContent(
+#                     type="text",
+#                     text=f"❌ Source is not ready for search. Status: {source_status}"
+#                 )]
+#         except Exception as e:
+#             logger.warning(f"Could not check source status: {e}")
+#             # Continue anyway in case it's just a status check issue
+#
+#         # Perform the search
+#         logger.info(f"Searching local filesystem source {source_id} with query: {query}")
+#
+#         # Use the unified query endpoint with data_sources parameter
+#         result = client.query_unified(
+#             messages=[{"role": "user", "content": query}],
+#             data_sources=[source_id],
+#             include_sources=include_sources,
+#             stream=False
+#         )
+#
+#         # Parse the response
+#         response_text = ""
+#         async for chunk in result:
+#             data = json.loads(chunk)
+#             if "content" in data:
+#                 response_text = data["content"]
+#                 sources = data.get("sources", [])
+#                 break
+#
+#         # Format the response nicely for local filesystem results
+#         if response_text:
+#             # Extract the local filesystem results section if present
+#             if "**Local filesystem results" in response_text:
+#                 # Keep the original response
+#                 formatted_response = response_text
+#             else:
+#                 # Create our own formatted response
+#                 formatted_response = f"🔍 **Search Results for Local Directory**\n"
+#                 formatted_response += f"🔎 Query: \"{query}\"\n\n"
+#                 formatted_response += response_text
+#
+#             # Add sources if available and requested
+#             if include_sources and sources:
+#                 formatted_response += "\n\n**📄 Source Details:**\n"
+#                 for i, source in enumerate(sources[:5], 1):
+#                     metadata = source.get("metadata", {})
+#                     file_path = metadata.get("file_path", "Unknown file")
+#                     formatted_response += f"\n{i}. `{file_path}`\n"
+#
+#                     # Add snippet of content
+#                     content = source.get("content", "")
+#                     if content:
+#                         # Truncate to reasonable length
+#                         lines = content.split('\n')[:10]
+#                         snippet = '\n'.join(lines)
+#                         if len(lines) > 10:
+#                             snippet += "\n..."
+#                         formatted_response += f"```\n{snippet}\n```\n"
+#
+#             return [TextContent(type="text", text=formatted_response)]
+#         else:
+#             return [TextContent(
+#                 type="text",
+#                 text=f"No results found for query: \"{query}\" in the indexed directory."
+#             )]
+#
+#     except APIError as e:
+#         logger.error(f"API error searching local filesystem: {e}")
+#         return [TextContent(
+#             type="text",
+#             text=f"❌ API Error: {str(e)}\n\nStatus Code: {e.status_code}\nDetails: {e.detail}"
+#         )]
+#     except Exception as e:
+#         logger.error(f"Unexpected error searching local filesystem: {e}")
+#         return [TextContent(
+#             type="text",
+#             text=f"❌ Error: An unexpected error occurred: {str(e)}"
+#         )]
+
+# ===============================================================================
+# CHROMA PACKAGE SEARCH INTEGRATION
+# ===============================================================================
+#
+# Provides access to Chroma's Package Search MCP tools for searching actual
+# source code from 3,000+ packages across multiple package registries.
+# This integration enables AI assistants to search ground-truth code instead
+# of relying on training data or hallucinations.
+#
+# Available Registries:
+#   - py_pi: Python Package Index (PyPI) packages
+#   - npm: Node.js packages from NPM registry
+#   - crates_io: Rust packages from crates.io
+#   - golang_proxy: Go modules from Go proxy
+#
+# Authentication:
+#   - Requires CHROMA_API_KEY environment variable
+#   - Uses x-chroma-token header for API authentication
+#
+# Tools:
+#   1. nia_package_search_grep: Regex-based code search
+#   2. nia_package_search_hybrid: Semantic/AI-powered search
+#   3. nia_package_search_read_file: Direct file content retrieval
+#
+# ===============================================================================
+
 @mcp.tool()
-async def index_local_filesystem(
-    directory_path: str,
-    inclusion_patterns: Optional[List[str]] = None,
-    exclusion_patterns: Optional[List[str]] = None,
-    max_file_size_mb: int = 50
+async def nia_package_search_grep(
+    registry: str,
+    package_name: str,
+    pattern: str,
+    version: Optional[str] = None,
+    language: Optional[str] = None,
+    filename_sha256: Optional[str] = None,
+    a: Optional[int] = None,
+    b: Optional[int] = None,
+    c: Optional[int] = None,
+    head_limit: Optional[int] = None,
+    output_mode: str = "content"
 ) -> List[TextContent]:
     """
-    Index a local filesystem directory for intelligent search.
-    
-    Args:
-        directory_path: Absolute path to the directory to index
-        inclusion_patterns: Optional list of patterns to include (e.g., ["ext:.py", "dir:src"])
-        exclusion_patterns: Optional list of patterns to exclude (e.g., ["dir:node_modules", "ext:.log"])
-        max_file_size_mb: Maximum file size in MB to process (default: 50)
-        
-    Returns:
-        Status of the indexing operation
-    
-    Important:
-        - Path must be absolute (e.g., /Users/username/projects/myproject)
-        - When indexing starts, use check_local_filesystem_status tool to monitor progress
+    Executes a grep over the source code of a public package. This tool is useful for deterministically
+    finding code in a package using regex. Use this tool before implementing solutions that use external
+    packages. The regex pattern should be restrictive enough to only match code you're looking for, to limit
+    overfetching.
+
+    Required Args: "registry", "package_name", "pattern" Optional Args: "version", "language",
+    "filename_sha256", "a", "b", "c", "head_limit", "output_mode"
+
+    Best for: Deterministic code search, finding specific code patterns, or exploring code structure.
+
+    Parameters:
+        a: The number of lines after a grep match to include
+        b: The number of lines before a grep match to include
+        c: The number of lines before and after a grep match to include
+        filename_sha256: The sha256 hash of the file to filter for
+        head_limit: Limits number of results returned. If the number of results returned is less than the
+            head limit, all results have been returned.
+        language: The languages to filter for. If not provided, all languages will be searched. Valid
+            options: "Rust", "Go", "Python", "JavaScript", "JSX", "TypeScript", "TSX", "HTML", "Markdown",
+            "YAML", "Bash", "SQL", "JSON", "Text", "Dockerfile", "HCL", "Protobuf", "Make", "Toml", "Jupyter Notebook"
+        output_mode: Controls the shape of the grep output. Accepted values:
+            "content" (default): return content snippets with line ranges
+            "files_with_matches": return unique files (path and sha256) that match
+            "count": return files with the count of matches per file
+        package_name: The name of the requested package. Pass the name as it appears in the package
+            manager. For Go packages, use the GitHub organization and repository name in the format
+            {org}/{repo}, if unsure check the GitHub URL for the package and use {org}/{repo} from that URL.
+        pattern: The regex pattern for exact text matching in the codebase. Must be a valid regex.
+            Example: "func\\s+\\(get_repository\\|getRepository\\)\\s*\\(.*?\\)\\s\\{"
+        registry: The name of the registry containing the requested package. Must be one of:
+            "crates_io", "golang_proxy", "npm", or "py_pi".
+        version: Optionally, the specific version of the package whose source code to search.
+            If provided, must be in semver format: {major}.{minor}.{patch}. Otherwise, the latest indexed
+            version of the package available will be used.
     """
     try:
-        # Validate absolute path
-        if not os.path.isabs(directory_path):
-            return [TextContent(
-                type="text",
-                text=f"❌ Error: directory_path must be an absolute path. Got: {directory_path}\n\n"
-                     f"Example: /Users/username/projects/myproject"
-            )]
-        
+        # Use API client for backend routing
         client = await ensure_api_client()
-        
-        # Start indexing
-        logger.info(f"Starting to index local directory: {directory_path}")
-        result = await client.index_local_filesystem(
-            directory_path=directory_path,
-            inclusion_patterns=inclusion_patterns or [],
-            exclusion_patterns=exclusion_patterns or [],
-            max_file_size_mb=max_file_size_mb
+        logger.info(f"Searching package {package_name} from {registry} with pattern: {pattern}")
+
+        # Execute grep search through backend
+        result = await client.package_search_grep(
+            registry=registry,
+            package_name=package_name,
+            pattern=pattern,
+            version=version,
+            language=language,
+            filename_sha256=filename_sha256,
+            a=a,
+            b=b,
+            c=c,
+            head_limit=head_limit,
+            output_mode=output_mode
         )
-        
-        if result.get("success"):
-            source_id = result["data"]["source_id"]
-            status_url = result["data"]["status_url"]
-            
+
+        # Handle raw Chroma JSON response
+        if not result or not isinstance(result, dict):
             return [TextContent(
                 type="text",
-                text=(
-                    f"✅ Successfully started indexing local directory!\n\n"
-                    f"📁 **Directory:** `{directory_path}`\n"
-                    f"🆔 **Source ID:** `{source_id}`\n"
-                    f"📊 **Status:** Processing\n\n"
-                    f"**What happens next:**\n"
-                    f"• NIA is scanning and indexing your files in the background\n"
-                    f"• This process typically takes a few minutes depending on directory size\n"
-                    f"• Use `check_local_filesystem_status` with source ID `{source_id}` to monitor progress\n"
-                    f"• Once indexed, use `search_codebase` or `search_documentation` to search your files\n\n"
-                    f"📌 **Tip:** You can check the status at any time or visit [app.trynia.ai](https://app.trynia.ai) to monitor progress."
-                )
+                text=f"No response from Chroma for pattern '{pattern}' in {package_name} ({registry})"
             )]
-        else:
+
+        # Extract results and version from raw Chroma response
+        results = result.get("results", [])
+        version_used = result.get("version_used")
+
+        if not results:
             return [TextContent(
                 type="text",
-                text=f"❌ Failed to start indexing: {result.get('detail', 'Unknown error')}"
+                text=f"No matches found for pattern '{pattern}' in {package_name} ({registry})"
             )]
-            
-    except APIError as e:
-        logger.error(f"API error indexing local filesystem: {e}")
-        return [TextContent(
-            type="text",
-            text=f"❌ API Error: {str(e)}\n\nStatus Code: {e.status_code}\nDetails: {e.detail}"
-        )]
+
+        response_lines = [
+            f"# 🔍 Package Search Results: {package_name} ({registry})",
+            f"**Pattern:** `{pattern}`",
+            ""
+        ]
+
+        if version_used:
+            response_lines.append(f"**Version:** {version_used}")
+        elif version:
+            response_lines.append(f"**Version:** {version}")
+
+        response_lines.append(f"**Found {len(results)} matches**\n")
+
+        # Handle grep result format: {output_mode: "content", result: {content, file_path, start_line, etc}}
+        for i, item in enumerate(results, 1):
+            response_lines.append(f"## Match {i}")
+
+            # Extract data from Chroma grep format
+            if "result" in item:
+                result_data = item["result"]
+                if result_data.get("file_path"):
+                    response_lines.append(f"**File:** `{result_data['file_path']}`")
+
+                # Show SHA256 for read_file tool usage
+                if result_data.get("filename_sha256"):
+                    response_lines.append(f"**SHA256:** `{result_data['filename_sha256']}`")
+
+                if result_data.get("start_line") and result_data.get("end_line"):
+                    response_lines.append(f"**Lines:** {result_data['start_line']}-{result_data['end_line']}")
+                if result_data.get("language"):
+                    response_lines.append(f"**Language:** {result_data['language']}")
+
+                response_lines.append("```")
+                response_lines.append(result_data.get("content", ""))
+                response_lines.append("```\n")
+            else:
+                # Fallback for other formats
+                response_lines.append("```")
+                response_lines.append(str(item))
+                response_lines.append("```\n")
+
+        # Add truncation message if present
+        if result.get("truncation_message"):
+            response_lines.append(f"⚠️ **Note:** {result['truncation_message']}")
+
+        # Add usage hint for read_file workflow (grep tool)
+        response_lines.append("\n💡 **To read full file content:**")
+        response_lines.append("Copy a SHA256 above and use: `nia_package_search_read_file(registry=..., package_name=..., filename_sha256=\"...\", start_line=1, end_line=100)`")
+
+        return [TextContent(type="text", text="\n".join(response_lines))]
+
     except Exception as e:
-        logger.error(f"Unexpected error indexing local filesystem: {e}")
+        logger.error(f"Error in package search grep: {e}")
         return [TextContent(
             type="text",
-            text=f"❌ Error: An unexpected error occurred while indexing the directory: {str(e)}"
+            text=f"❌ Error searching package: {str(e)}\n\n"
+                 f"Make sure:\n"
+                 f"- The registry is one of: crates_io, golang_proxy, npm, py_pi\n"
+                 f"- The package name is correct\n"
+                 f"- The pattern is a valid regex"
         )]
 
 @mcp.tool()
-async def scan_local_filesystem(
-    directory_path: str,
-    inclusion_patterns: Optional[List[str]] = None,
-    exclusion_patterns: Optional[List[str]] = None,
-    max_file_size_mb: int = 50
+async def nia_package_search_hybrid(
+    registry: str,
+    package_name: str,
+    semantic_queries: List[str],
+    version: Optional[str] = None,
+    filename_sha256: Optional[str] = None,
+    pattern: Optional[str] = None,
+    language: Optional[str] = None
 ) -> List[TextContent]:
     """
-    Scan a local filesystem directory to preview what files would be indexed.
-    
-    This tool helps you understand what files will be processed before actually indexing.
-    
-    Args:
-        directory_path: Absolute path to the directory to scan
-        inclusion_patterns: Optional list of patterns to include (e.g., ["ext:.py", "dir:src"])
-        exclusion_patterns: Optional list of patterns to exclude (e.g., ["dir:node_modules", "ext:.log"])
-        max_file_size_mb: Maximum file size in MB to process (default: 50)
-        
-    Returns:
-        Summary of files that would be indexed including count, size, and file types
+    Searches package source code using semantic understanding AND optionally regex patterns. This
+    allows for hybrid search, allowing for prefiltering with regex, and semantic ranking.
+
+    Required Args: "registry", "package_name", "semantic_queries"
+
+    Optional Args: "version", "filename_sha256", "pattern", "language"
+
+    Best for: Understanding how packages implement specific features, finding usage patterns, or
+    exploring code structure.
+
+    Parameters:
+        filename_sha256: The sha256 hash of the file to filter for
+        language: The languages to filter for. If not provided, all languages will be searched. Valid
+            options: "Rust", "Go", "Python", "JavaScript", "JSX", "TypeScript", "TSX", "HTML", "Markdown",
+            "YAML", "Bash", "SQL", "JSON", "Text", "Dockerfile", "HCL", "Protobuf", "Make", "Toml", "Jupyter Notebook"
+        package_name: The name of the requested package. Pass the name as it appears in the package
+            manager. For Go packages, use the GitHub organization and repository name in the format
+            {org}/{repo}, if unsure check the GitHub URL for the package and use {org}/{repo} from that URL.
+        pattern: The regex pattern for exact text matching in the codebase. Must be a valid regex.
+            Example: "func\\s+\\(get_repository\\|getRepository\\)\\s*\\(.*?\\)\\s\\{"
+        registry: The name of the registry containing the requested package. Must be one of:
+            "crates_io", "golang_proxy", "npm", or "py_pi".
+        semantic_queries: Array of 1-5 plain English questions about the codebase. Example: ["how is
+            argmax implemented in numpy?", "what testing patterns does axum use?"]
+        version: Optionally, the specific version of the package whose source code to search.
+            If provided, must be in semver format: {major}.{minor}.{patch}. Otherwise, the latest indexed
+            version of the package available will be used.
     """
     try:
-        # Validate absolute path
-        if not os.path.isabs(directory_path):
+        # Use API client for backend routing
+        client = await ensure_api_client()
+        logger.info(f"Hybrid search in {package_name} from {registry} with queries: {semantic_queries}")
+
+        # Execute hybrid search through backend
+        result = await client.package_search_hybrid(
+            registry=registry,
+            package_name=package_name,
+            semantic_queries=semantic_queries,
+            version=version,
+            filename_sha256=filename_sha256,
+            pattern=pattern,
+            language=language
+        )
+
+        # Handle raw Chroma JSON response
+        if not result or not isinstance(result, dict):
+            queries_str = "\n".join(f"- {q}" for q in semantic_queries)
             return [TextContent(
                 type="text",
-                text=f"❌ Error: directory_path must be an absolute path. Got: {directory_path}\n\n"
-                     f"Example: /Users/username/projects/myproject"
+                text=f"No response from Chroma for queries:\n{queries_str}\n\nin {package_name} ({registry})"
             )]
-        
-        client = await ensure_api_client()
-        
-        logger.info(f"Scanning local directory: {directory_path}")
-        result = await client.scan_local_filesystem(
-            directory_path=directory_path,
-            inclusion_patterns=inclusion_patterns or [],
-            exclusion_patterns=exclusion_patterns or [],
-            max_file_size_mb=max_file_size_mb
-        )
-        
-        # Format the scan results
-        total_files = result.get("total_files", 0)
-        total_size_mb = result.get("total_size_mb", 0)
-        file_types = result.get("file_types", {})
-        files = result.get("files", [])
-        truncated = result.get("truncated", False)
-        
-        response = f"📊 **Local Directory Scan Results**\n\n"
-        response += f"📁 **Directory:** `{directory_path}`\n"
-        response += f"📄 **Total Files:** {total_files:,}\n"
-        response += f"💾 **Total Size:** {total_size_mb:.2f} MB\n\n"
-        
-        if file_types:
-            response += "**File Types:**\n"
-            # Sort by count descending
-            sorted_types = sorted(file_types.items(), key=lambda x: x[1], reverse=True)
-            for ext, count in sorted_types[:10]:  # Show top 10
-                response += f"• `{ext}`: {count:,} files\n"
-            if len(sorted_types) > 10:
-                response += f"• ... and {len(sorted_types) - 10} more types\n"
-            response += "\n"
-        
-        if files:
-            response += f"**Largest Files (showing {min(len(files), 10)}):**\n"
-            for i, file_info in enumerate(files[:10]):
-                size_mb = file_info["size"] / (1024 * 1024)
-                response += f"{i+1}. `{file_info['path']}` ({size_mb:.2f} MB)\n"
-            
-            if truncated:
-                response += f"\n*Note: Showing first 100 files out of {total_files:,} total*\n"
-        
-        if inclusion_patterns:
-            response += f"\n**Inclusion Patterns:** {', '.join(f'`{p}`' for p in inclusion_patterns)}\n"
-        if exclusion_patterns:
-            response += f"**Exclusion Patterns:** {', '.join(f'`{p}`' for p in exclusion_patterns)}\n"
-        
-        response += "\n💡 **Next Step:** Use `index_local_filesystem` to index these files."
-        
-        return [TextContent(type="text", text=response)]
-        
-    except APIError as e:
-        logger.error(f"API error scanning local filesystem: {e}")
-        return [TextContent(
-            type="text",
-            text=f"❌ API Error: {str(e)}\n\nStatus Code: {e.status_code}\nDetails: {e.detail}"
-        )]
-    except Exception as e:
-        logger.error(f"Unexpected error scanning local filesystem: {e}")
-        return [TextContent(
-            type="text",
-            text=f"❌ Error: An unexpected error occurred while scanning: {str(e)}"
-        )]
 
-@mcp.tool()
-async def check_local_filesystem_status(source_id: str) -> List[TextContent]:
-    """
-    Check the indexing status of a local filesystem source.
-    
-    Args:
-        source_id: The source ID returned when indexing was started
-        
-    Returns:
-        Current status of the local filesystem indexing
-    """
-    try:
-        client = await ensure_api_client()
-        status = await client.check_local_filesystem_status(source_id)
-        
-        # Format status response
-        status_text = status.get("status", "unknown")
-        progress = status.get("progress", 0)
-        message = status.get("message", "")
-        error = status.get("error")
-        directory_path = status.get("directory_path", "Unknown")
-        page_count = status.get("page_count", 0)  # Number of files
-        chunk_count = status.get("chunk_count", 0)
-        
-        # Status emoji
-        status_emoji = {
-            "pending": "⏳",
-            "processing": "🔄",
-            "completed": "✅",
-            "failed": "❌",
-            "error": "❌"
-        }.get(status_text, "❓")
-        
-        response = f"{status_emoji} **Local Filesystem Status**\n\n"
-        response += f"🆔 **Source ID:** `{source_id}`\n"
-        response += f"📁 **Directory:** `{directory_path}`\n"
-        response += f"📊 **Status:** {status_text.capitalize()}\n"
-        
-        if progress > 0:
-            response += f"📈 **Progress:** {progress}%\n"
-        
-        if message:
-            response += f"💬 **Message:** {message}\n"
-        
-        if status_text == "completed":
-            response += f"\n✨ **Indexing Complete!**\n"
-            response += f"• **Files Indexed:** {page_count:,}\n"
-            response += f"• **Chunks Created:** {chunk_count:,}\n"
-            response += f"\nYou can now search this directory using `search_codebase` or the unified search!"
-        elif status_text in ["failed", "error"]:
-            response += f"\n❌ **Indexing Failed**\n"
-            if error:
-                response += f"**Error:** {error}\n"
-            response += "\nPlease check your directory path and try again."
-        elif status_text == "processing":
-            response += f"\n🔄 Indexing is in progress...\n"
-            response += "Check back in a few moments or monitor at [app.trynia.ai](https://app.trynia.ai)"
-        
-        return [TextContent(type="text", text=response)]
-        
-    except APIError as e:
-        logger.error(f"API error checking local filesystem status: {e}")
-        if e.status_code == 404:
+        # Extract results and version from raw Chroma response
+        results = result.get("results", [])
+        version_used = result.get("version_used")
+
+        if not results:
+            queries_str = "\n".join(f"- {q}" for q in semantic_queries)
             return [TextContent(
                 type="text",
-                text=f"❌ Source ID `{source_id}` not found. Please check the ID and try again."
+                text=f"No relevant code found for queries:\n{queries_str}\n\nin {package_name} ({registry})"
             )]
-        return [TextContent(
-            type="text",
-            text=f"❌ API Error: {str(e)}\n\nStatus Code: {e.status_code}\nDetails: {e.detail}"
-        )]
+
+        response_lines = [
+            f"# 🔎 Package Semantic Search: {package_name} ({registry})",
+            "**Queries:**"
+        ]
+
+        for query in semantic_queries:
+            response_lines.append(f"- {query}")
+
+        response_lines.append("")
+
+        if version_used:
+            response_lines.append(f"**Version:** {version_used}")
+        elif version:
+            response_lines.append(f"**Version:** {version}")
+        if pattern:
+            response_lines.append(f"**Pattern Filter:** `{pattern}`")
+
+        response_lines.append(f"\n**Found {len(results)} relevant code sections**\n")
+
+        # Handle hybrid result format: {id: "...", document: "content", metadata: {...}}
+        for i, item in enumerate(results, 1):
+            response_lines.append(f"## Result {i}")
+
+            # Extract metadata if available
+            metadata = item.get("metadata", {})
+            if metadata.get("filename"):
+                response_lines.append(f"**File:** `{metadata['filename']}`")
+
+            # Show SHA256 for read_file tool usage (from metadata)
+            if metadata.get("filename_sha256"):
+                response_lines.append(f"**SHA256:** `{metadata['filename_sha256']}`")
+
+            if metadata.get("start_line") and metadata.get("end_line"):
+                response_lines.append(f"**Lines:** {metadata['start_line']}-{metadata['end_line']}")
+            if metadata.get("language"):
+                response_lines.append(f"**Language:** {metadata['language']}")
+
+            # Get document content
+            content = item.get("document", "")
+            if content:
+                response_lines.append("```")
+                response_lines.append(content)
+                response_lines.append("```\n")
+
+        # Add truncation message if present
+        if result.get("truncation_message"):
+            response_lines.append(f"⚠️ **Note:** {result['truncation_message']}")
+
+        # Add usage hint for read_file workflow (hybrid tool)
+        response_lines.append("\n💡 **To read full file content:**")
+        response_lines.append("Copy a SHA256 above and use: `nia_package_search_read_file(registry=..., package_name=..., filename_sha256=\"...\", start_line=1, end_line=100)`")
+
+        return [TextContent(type="text", text="\n".join(response_lines))]
+
     except Exception as e:
-        logger.error(f"Unexpected error checking local filesystem status: {e}")
+        logger.error(f"Error in package search hybrid: {e}")
         return [TextContent(
             type="text",
-            text=f"❌ Error: An unexpected error occurred: {str(e)}"
+            text=f"❌ Error in hybrid search: {str(e)}\n\n"
+                 f"Make sure:\n"
+                 f"- The registry is one of: crates_io, golang_proxy, npm, py_pi\n"
+                 f"- The package name is correct\n"
+                 f"- Semantic queries are provided (1-5 queries)"
         )]
 
 @mcp.tool()
-async def search_local_filesystem(
-    source_id: str,
-    query: str,
-    include_sources: bool = True
+async def nia_package_search_read_file(
+    registry: str,
+    package_name: str,
+    filename_sha256: str,
+    start_line: int,
+    end_line: int,
+    version: Optional[str] = None
 ) -> List[TextContent]:
     """
-    Search an indexed local filesystem directory using its source ID.
-    
-    To search local files:
-    1. First index a directory using `index_local_filesystem` - this will return a source_id
-    2. Use that source_id with this tool to search the indexed content
-    
-    Args:
-        source_id: The source ID returned when the directory was indexed (required)
-        query: Your search query in natural language (required)
-        include_sources: Whether to include source code snippets in results (default: True)
-        
-    Returns:
-        Search results with relevant file snippets and explanations
-        
-    Example:
-        # After indexing returns source_id "abc123-def456"
-        search_local_filesystem(
-            source_id="abc123-def456",
-            query="configuration settings"
-        )
-        
-    Note: To find your source IDs, use `list_documentation` and look for 
-    sources with source_type="local_filesystem"
+    Reads exact lines from a source file of a public package. Useful for fetching specific code regions by
+    line range.
+
+    Required Args: "registry", "package_name", "filename_sha256", "start_line", "end_line" Optional Args:
+    "version"
+
+    Best for: Inspecting exact code snippets when you already know the file and line numbers. Max 200
+    lines.
+
+    Parameters:
+        end_line: 1-based inclusive end line to read
+        filename_sha256: The sha256 hash of the file to filter for
+        package_name: The name of the requested package. Pass the name as it appears in the package
+            manager. For Go packages, use the GitHub organization and repository name in the format
+            {org}/{repo}, if unsure check the GitHub URL for the package and use {org}/{repo} from that URL.
+        registry: The name of the registry containing the requested package. Must be one of:
+            "crates_io", "golang_proxy", "npm", or "py_pi".
+        start_line: 1-based inclusive start line to read
+        version: Optionally, the specific version of the package whose source code to search.
+            If provided, must be in semver format: {major}.{minor}.{patch}. Otherwise, the latest indexed
+            version of the package available will be used.
     """
     try:
-        # Validate inputs
-        if not source_id:
+        # Validate line range
+        if end_line - start_line + 1 > 200:
             return [TextContent(
                 type="text",
-                text="❌ Error: 'source_id' parameter is required. Use the ID returned from index_local_filesystem."
+                text="❌ Error: Maximum 200 lines can be read at once. Please reduce the line range."
             )]
-            
-        if not query:
+
+        if start_line < 1 or end_line < start_line:
             return [TextContent(
                 type="text",
-                text="❌ Error: 'query' parameter is required"
+                text="❌ Error: Invalid line range. Start line must be >= 1 and end line must be >= start line."
             )]
-        
+
+        # Use API client for backend routing
         client = await ensure_api_client()
-        
-        # Check if the source exists and is ready
-        logger.info(f"Checking status of source {source_id}")
-        try:
-            status = await client.get_data_source_status(source_id)
-            if not status:
-                return [TextContent(
-                    type="text",
-                    text=f"❌ Source ID '{source_id}' not found. Please check the ID and try again."
-                )]
-            
-            source_status = status.get("status", "unknown")
-            if source_status == "processing":
-                progress = status.get("progress", 0)
-                return [TextContent(
-                    type="text",
-                    text=f"⏳ This source is still being indexed ({progress}% complete).\n\n"
-                         f"Use `check_local_filesystem_status(\"{source_id}\")` to check progress."
-                )]
-            elif source_status == "failed":
-                error = status.get("error", "Unknown error")
-                return [TextContent(
-                    type="text",
-                    text=f"❌ This source failed to index.\n\nError: {error}"
-                )]
-            elif source_status != "completed":
-                return [TextContent(
-                    type="text",
-                    text=f"❌ Source is not ready for search. Status: {source_status}"
-                )]
-        except Exception as e:
-            logger.warning(f"Could not check source status: {e}")
-            # Continue anyway in case it's just a status check issue
-        
-        # Perform the search
-        logger.info(f"Searching local filesystem source {source_id} with query: {query}")
-        
-        # Use the unified query endpoint with data_sources parameter
-        result = client.query_unified(
-            messages=[{"role": "user", "content": query}],
-            data_sources=[source_id],
-            include_sources=include_sources,
-            stream=False
+        logger.info(f"Reading file from {package_name} ({registry}): sha256={filename_sha256}, lines {start_line}-{end_line}")
+
+        # Read file content through backend
+        result = await client.package_search_read_file(
+            registry=registry,
+            package_name=package_name,
+            filename_sha256=filename_sha256,
+            start_line=start_line,
+            end_line=end_line,
+            version=version
         )
-        
-        # Parse the response
-        response_text = ""
-        async for chunk in result:
-            data = json.loads(chunk)
-            if "content" in data:
-                response_text = data["content"]
-                sources = data.get("sources", [])
-                break
-        
-        # Format the response nicely for local filesystem results
-        if response_text:
-            # Extract the local filesystem results section if present
-            if "**Local filesystem results" in response_text:
-                # Keep the original response
-                formatted_response = response_text
-            else:
-                # Create our own formatted response
-                formatted_response = f"🔍 **Search Results for Local Directory**\n"
-                formatted_response += f"🔎 Query: \"{query}\"\n\n"
-                formatted_response += response_text
-            
-            # Add sources if available and requested
-            if include_sources and sources:
-                formatted_response += "\n\n**📄 Source Details:**\n"
-                for i, source in enumerate(sources[:5], 1):
-                    metadata = source.get("metadata", {})
-                    file_path = metadata.get("file_path", "Unknown file")
-                    formatted_response += f"\n{i}. `{file_path}`\n"
-                    
-                    # Add snippet of content
-                    content = source.get("content", "")
-                    if content:
-                        # Truncate to reasonable length
-                        lines = content.split('\n')[:10]
-                        snippet = '\n'.join(lines)
-                        if len(lines) > 10:
-                            snippet += "\n..."
-                        formatted_response += f"```\n{snippet}\n```\n"
-            
-            return [TextContent(type="text", text=formatted_response)]
+
+        # Handle raw Chroma response (read_file typically returns content directly)
+        response_lines = [
+            f"# 📄 Package File Content: {package_name} ({registry})",
+            f"**File SHA256:** `{filename_sha256}`",
+            f"**Lines:** {start_line}-{end_line}"
+        ]
+
+        if version:
+            response_lines.append(f"**Version:** {version}")
+
+        response_lines.append("\n```")
+        # For read_file, Chroma typically returns the content directly as a string
+        if isinstance(result, str):
+            response_lines.append(result)
+        elif isinstance(result, dict) and result.get("content"):
+            response_lines.append(result["content"])
         else:
-            return [TextContent(
-                type="text",
-                text=f"No results found for query: \"{query}\" in the indexed directory."
-            )]
-            
-    except APIError as e:
-        logger.error(f"API error searching local filesystem: {e}")
-        return [TextContent(
-            type="text",
-            text=f"❌ API Error: {str(e)}\n\nStatus Code: {e.status_code}\nDetails: {e.detail}"
-        )]
+            response_lines.append(str(result))
+        response_lines.append("```")
+
+        return [TextContent(type="text", text="\n".join(response_lines))]
+
     except Exception as e:
-        logger.error(f"Unexpected error searching local filesystem: {e}")
+        logger.error(f"Error reading package file: {e}")
         return [TextContent(
             type="text",
-            text=f"❌ Error: An unexpected error occurred: {str(e)}"
+            text=f"❌ Error reading file: {str(e)}\n\n"
+                 f"Make sure:\n"
+                 f"- The registry is one of: crates_io, golang_proxy, npm, py_pi\n"
+                 f"- The package name is correct\n"
+                 f"- The filename_sha256 is valid\n"
+                 f"- The line range is valid (1-based, max 200 lines)"
         )]
 
 @mcp.tool()