nia-mcp-server 1.0.25__tar.gz → 1.0.26__tar.gz

{nia_mcp_server-1.0.25 → nia_mcp_server-1.0.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nia-mcp-server
-Version: 1.0.25
+Version: 1.0.26
 Summary: Nia Knowledge Agent
 Project-URL: Homepage, https://trynia.ai
 Project-URL: Documentation, https://docs.trynia.ai

{nia_mcp_server-1.0.25 → nia_mcp_server-1.0.26}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nia-mcp-server"
-version = "1.0.25"
+version = "1.0.26"
 description = "Nia Knowledge Agent"
 readme = "README.md"
 requires-python = ">=3.8"

{nia_mcp_server-1.0.25 → nia_mcp_server-1.0.26}/src/nia_mcp_server/__init__.py

@@ -3,4 +3,4 @@ NIA MCP Server - Proxy server for NIA Knowledge Agent
 """
 
 
-__version__ = "1.0.25"
+__version__ = "1.0.26"

{nia_mcp_server-1.0.25 → nia_mcp_server-1.0.26}/src/nia_mcp_server/api_client.py

@@ -28,7 +28,7 @@ class NIAApiClient:
         self.client = httpx.AsyncClient(
             headers={
                 "Authorization": f"Bearer {api_key}",
-                "User-Agent": "nia-mcp-server/1.0.25",
+                "User-Agent": "nia-mcp-server/1.0.26",
                 "Content-Type": "application/json"
             },
             timeout=720.0  # 12 minute timeout for deep research operations
@@ -432,7 +432,80 @@ class NIAApiClient:
         except Exception as e:
             logger.error(f"Failed to rename repository: {e}")
             raise APIError(f"Failed to rename repository: {str(e)}")
-    
+
+    async def get_repository_hierarchy(
+        self,
+        owner_repo: str,
+        include_classes: bool = True,
+        include_methods: bool = False,
+        include_tree: bool = False
+    ) -> Dict[str, Any]:
+        """Get the file hierarchy for a repository."""
+        try:
+            # Check if this looks like owner/repo format (contains /)
+            if '/' in owner_repo:
+                # First, get the repository ID
+                status = await self.get_repository_status(owner_repo)
+                if not status:
+                    raise APIError(f"Repository {owner_repo} not found", 404)
+
+                # Extract the repository ID from status
+                repo_id = status.get("repository_id") or status.get("id")
+                if not repo_id:
+                    # Try to get it from list as fallback
+                    repos = await self.list_repositories()
+                    for repo in repos:
+                        if repo.get("repository") == owner_repo:
+                            repo_id = repo.get("repository_id") or repo.get("id")
+                            break
+
+                if not repo_id:
+                    raise APIError(f"No repository ID found for {owner_repo}", 404)
+
+                # Get hierarchy using the ID
+                params = {
+                    "include_classes": include_classes,
+                    "include_methods": include_methods
+                }
+
+                headers = {}
+                if include_tree:
+                    headers["X-Include-Tree"] = "true"
+
+                response = await self.client.get(
+                    f"{self.base_url}/v2/repositories/{repo_id}/hierarchy",
+                    params=params,
+                    headers=headers
+                )
+                response.raise_for_status()
+                return response.json()
+            else:
+                # Assume it's already a repository ID
+                params = {
+                    "include_classes": include_classes,
+                    "include_methods": include_methods
+                }
+
+                headers = {}
+                if include_tree:
+                    headers["X-Include-Tree"] = "true"
+
+                response = await self.client.get(
+                    f"{self.base_url}/v2/repositories/{owner_repo}/hierarchy",
+                    params=params,
+                    headers=headers
+                )
+                response.raise_for_status()
+                return response.json()
+
+        except httpx.HTTPStatusError as e:
+            raise self._handle_api_error(e)
+        except APIError:
+            raise
+        except Exception as e:
+            logger.error(f"Failed to get repository hierarchy: {e}")
+            raise APIError(f"Failed to get repository hierarchy: {str(e)}")
+
     # Data Source methods
     
     async def create_data_source(

{nia_mcp_server-1.0.25 → nia_mcp_server-1.0.26}/src/nia_mcp_server/server.py

@@ -80,15 +80,10 @@ async def index_repository(
     branch: Optional[str] = None
 ) -> List[TextContent]:
     """
-    Index a GitHub repository for intelligent code search.
-    
     Args:
         repo_url: GitHub repository URL (e.g., https://github.com/owner/repo or https://github.com/owner/repo/tree/branch)
         branch: Branch to index (optional, defaults to main branch)
-        
-    Returns:
-        Status of the indexing operation
-    
+
     Important:
         - When started indexing, prompt users to either use check_repository_status tool or go to app.trynia.ai to check the status.
     """
@@ -157,31 +152,12 @@ async def search_codebase(
     Search indexed repositories 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.
-        repositories: List of repositories to search (owner/repo or owner/repo/tree/branch if indexed differently before).
-            - "owner/repo" - Search entire repository (e.g., "facebook/react")
-            - "owner/repo/tree/branch/folder" - Search specific folder indexed separately
-              (e.g., "PostHog/posthog/tree/master/docs")
-            Use the EXACT format shown in list_repositories output for folder-indexed repos.
-            If not specified, searches all indexed repos.
-        include_sources: Whether to include source code in results
+        query: Natural language search query.
+        repositories: List of repositories to search (owner/repo or owner/repo/tree/branch).
+        include_sources: default to True.
         
     Returns:
         Search results with relevant code snippets and explanations
-        
-    Examples:
-        # Search all indexed repositories
-        search_codebase("How does authentication work?")
-        
-        # Search specific repository
-        search_codebase("How to create custom hooks?", ["facebook/react"])
-        
-        # Search folder-indexed repository (use exact format from list_repositories)
-        search_codebase("What is Flox?", ["PostHog/posthog/tree/master/docs"])
-
-    Important:
-        - If you want to search a specific folder, use the EXACT repository path shown above
-        - Example: `search_codebase(\"query\", [\"owner/repo/tree/branch/folder\"])`
     """
     try:
         client = await ensure_api_client()
@@ -336,18 +312,11 @@ async def search_documentation(
     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 identifiers to search. Preferred format is UUID, but also supports:
-            - Source UUIDs (e.g., "550e8400-e29b-41d4-a716-446655440000") - RECOMMENDED
-            - Display names (e.g., "Vercel AI SDK - Core")
-            - URLs (e.g., "https://sdk.vercel.ai/docs")
-        include_sources: Whether to include source references in results
-
-    Returns:
-        Search results with relevant documentation excerpts
-
+            - Source UUIDs - RECOMMENDED
+            - Display names 
+            - URLs
     Important:
         - UUIDs are the preferred identifier format for best performance
-        - Use `list_documentation` tool to see available sources and their UUIDs
-        - Display names and URLs are also supported for convenience
     """
     try:
         client = await ensure_api_client()
@@ -474,9 +443,7 @@ async def search_documentation(
 
 # @mcp.tool()
 # async def list_repositories() -> List[TextContent]:
-    """
-    List all indexed repositories.
-    
+    """    
     Returns:
         List of indexed repositories with their status
     """
@@ -563,9 +530,6 @@ async def search_documentation(
     
     Args:
         repository: Repository in owner/repo format
-        
-    Returns:
-        Current status of the repository
     """
     try:
         client = await ensure_api_client()
@@ -636,25 +600,8 @@ async def index_documentation(
     
     Args:
         url: URL of the documentation site to index
-        url_patterns: Optional list of URL patterns to include in crawling (e.g., ["/docs/*", "/guide/*"])
-        exclude_patterns: Optional list of URL patterns to exclude from crawling (e.g., ["/blog/*", "/changelog/*"])
-        max_age: Maximum age of cached content in seconds (for fast scraping mode)
-        only_main_content: Extract only main content (removes navigation, ads, etc.)
-        wait_for: Time to wait for page to load in milliseconds (defaults to backend setting)
-        include_screenshot: Whether to capture full page screenshots (defaults to backend setting)
-        check_llms_txt: Check for llms.txt file for curated documentation URLs (default: True)
-        llms_txt_strategy: How to use llms.txt if found:
-            - "prefer": Start with llms.txt URLs, then crawl additional pages if under limit
-            - "only": Only index URLs listed in llms.txt
-            - "ignore": Skip llms.txt check (traditional behavior)
-        
-    Returns:
-        Status of the indexing operation
-
-    Important:
-        - When started indexing, prompt users to either use check_documentation_status tool or go to app.trynia.ai to check the status.
-        - By default, crawls the entire domain (up to 10,000 pages)
-        - Use exclude_patterns to filter out unwanted sections like blogs, changelogs, etc.
+        url_patterns: Optional list of URL patterns to include in crawling
+        exclude_patterns: Optional list of URL patterns to exclude from crawling
     """
     try:
         client = await ensure_api_client()
@@ -708,8 +655,6 @@ async def index_documentation(
 # @mcp.tool()
 # async def list_documentation() -> List[TextContent]:
     """
-    List all indexed documentation sources.
-    
     Returns:
         List of indexed documentation with their status
     """
@@ -767,8 +712,6 @@ async def index_documentation(
 # @mcp.tool()
 # async def check_documentation_status(source_id: str) -> List[TextContent]:
     """
-    Check the indexing status of a documentation source.
-    
     Args:
         source_id: Documentation source ID
         
@@ -844,17 +787,8 @@ async def rename_resource(
     Args:
         resource_type: Type of resource - "repository" or "documentation"
         identifier:
-            - For repository: Repository in owner/repo format (e.g., "facebook/react")
-            - For documentation: UUID preferred, also supports display name or URL (e.g., "550e8400-e29b-41d4-a716-446655440000", "Vercel AI SDK - Core", or "https://docs.trynia.ai/")
-        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", "550e8400-e29b-41d4-a716-446655440000", "Python Official Docs")
-        - rename_resource("documentation", "https://docs.trynia.ai/", "NIA Documentation")
+            - For repos: Repository in owner/repo format (e.g., "facebook/react")
+            - For docs: UUID preferred, also supports display name or URL
     """
     try:
         # Validate resource type
@@ -915,16 +849,8 @@ async def delete_resource(
     Args:
         resource_type: Type of resource - "repository" or "documentation"
         identifier:
-            - For repository: Repository in owner/repo format (e.g., "facebook/react")
-            - For documentation: UUID preferred, also supports display name or URL (e.g., "550e8400-e29b-41d4-a716-446655440000", "Vercel AI SDK - Core", or "https://docs.trynia.ai/")
-
-    Returns:
-        Confirmation of deletion
-
-    Examples:
-        - delete_resource("repository", "facebook/react")
-        - delete_resource("documentation", "550e8400-e29b-41d4-a716-446655440000")
-        - delete_resource("documentation", "https://docs.trynia.ai/")
+            - For repos: Repository in owner/repo format (e.g., "facebook/react")
+            - For docs: UUID preferred, also supports display name or URL
     """
     try:
         # Validate resource type
@@ -978,19 +904,8 @@ async def check_resource_status(
     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
+            - For repos: Repository in owner/repo format 
+            - For docs: Source ID (UUID format only)
     """
     try:
         # Validate resource type
@@ -1093,11 +1008,6 @@ async def list_resources(
 
     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
@@ -1219,9 +1129,6 @@ async def list_resources(
     
     Args:
         source_id: Documentation source ID to delete
-        
-    Returns:
-        Confirmation of deletion
     """
     try:
         client = await ensure_api_client()
@@ -1258,9 +1165,6 @@ async def list_resources(
     
     Args:
         repository: Repository in owner/repo format
-        
-    Returns:
-        Confirmation of deletion
     """
     try:
         client = await ensure_api_client()
@@ -1298,9 +1202,6 @@ async def list_resources(
     Args:
         repository: Repository in owner/repo format
         new_name: New display name for the repository (1-100 characters)
-        
-    Returns:
-        Confirmation of rename operation
     """
     try:
         # Validate name length
@@ -1345,9 +1246,6 @@ async def list_resources(
     Args:
         source_id: Documentation source ID
         new_name: New display name for the documentation (1-100 characters)
-        
-    Returns:
-        Confirmation of rename operation
     """
     try:
         # Validate name length
@@ -1393,30 +1291,14 @@ async def nia_web_search(
     find_similar_to: Optional[str] = None
 ) -> List[TextContent]:
     """
-    Search repositories, documentation, and other content using AI-powered search.
-    Returns results formatted to guide next actions.
-    
-    USE THIS TOOL WHEN:
-    - Finding specific repos/docs/content ("find X library", "trending Y frameworks")
-    - Looking for examples or implementations
-    - Searching for what's available on a topic
-    - Simple, direct searches that need quick results
-    - Finding similar content to a known URL
-    
-    DON'T USE THIS FOR:
-    - Comparative analysis (use nia_deep_research_agent instead)
-    - Complex multi-faceted questions (use nia_deep_research_agent instead)
-    - Questions requiring synthesis of multiple sources (use nia_deep_research_agent instead)
+    Search repositories, documentation, and other content using web search.
     
     Args:
         query: Natural language search query (e.g., "best RAG implementations", "trending rust web frameworks")
         num_results: Number of results to return (default: 5, max: 10)
         category: Filter by category: "github", "company", "research paper", "news", "tweet", "pdf"
         days_back: Only show results from the last N days (for trending content)
-        find_similar_to: URL to find similar content to
-        
-    Returns:
-        Search results with actionable next steps
+        find_similar_to: URL to find similar content
     """
     try:
         client = await ensure_api_client()
@@ -1516,13 +1398,7 @@ async def nia_web_search(
         
         # Add prominent call-to-action if we found indexable content
         if github_repos or documentation:
-            response_text += "\n## 🎯 **Ready to unlock NIA's AI capabilities?**\n"
-            response_text += "The repositories and documentation above can be indexed for:\n"
-            response_text += "- 🤖 AI-powered code understanding and search\n"
-            response_text += "- 💡 Instant answers to technical questions\n"
-            response_text += "- 🔍 Deep architectural insights\n"
-            response_text += "- 📚 Smart documentation Q&A\n\n"
-            response_text += "**Just copy and paste the index commands above!**\n"
+            response_text += "\n## 🎯 **Ready to unlock nia's tools**\n"
         
         # Add search metadata
         response_text += f"\n---\n"
@@ -1562,27 +1438,6 @@ async def nia_deep_research_agent(
 ) -> List[TextContent]:
     """
     Perform deep, multi-step research on a topic using advanced AI research capabilities.
-    Best for complex questions that need comprehensive analysis. Don't just use keywords or unstrctured query, make a comprehensive question to get the best results possible.
-    
-    USE THIS TOOL WHEN:
-    - Comparing multiple options ("compare X vs Y vs Z")
-    - Analyzing pros and cons
-    - Questions with "best", "top", "which is better"
-    - Needing structured analysis or synthesis
-    - Complex questions requiring multiple sources
-    - Questions about trends, patterns, or developments
-    - Requests for comprehensive overviews
-    
-    DON'T USE THIS FOR:
-    - Simple lookups (use nia_web_search instead)
-    - Finding a specific known item (use nia_web_search instead)
-    - Quick searches for repos/docs (use nia_web_search instead)
-    
-    COMPLEXITY INDICATORS:
-    - Words like: compare, analyze, evaluate, pros/cons, trade-offs
-    - Multiple criteria mentioned
-    - Asking for recommendations based on context
-    - Needing structured output (tables, lists, comparisons)
     
     Args:
         query: Research question (e.g., "Compare top 3 RAG frameworks with pros/cons")
@@ -1732,162 +1587,6 @@ async def nia_deep_research_agent(
                  "Try simplifying your question or using the regular nia_web_search tool."
         )]
 
-@mcp.tool()
-async def initialize_project(
-    project_root: str,
-    profiles: Optional[List[str]] = None
-) -> List[TextContent]:
-    """
-    Initialize a NIA-enabled project with IDE-specific rules and configurations.
-    
-    This tool sets up your project with NIA integration, creating configuration files
-    and rules tailored to your IDE or editor. It enables AI assistants to better
-    understand and work with NIA's knowledge search capabilities.
-    
-    Args:
-        project_root: Absolute path to the project root directory
-        profiles: List of IDE profiles to set up (default: ["cursor"]). 
-                 Options: cursor, vscode, claude, windsurf, cline, codex, zed, jetbrains, neovim, sublime
-        
-    Returns:
-        Status of the initialization with created files and next steps
-    
-    Examples:
-        - Basic: initialize_project("/path/to/project")
-        - Multiple IDEs: initialize_project("/path/to/project", profiles=["cursor", "vscode"])
-        - Specific IDE: initialize_project("/path/to/project", profiles=["windsurf"])
-    """
-    try:
-        # Validate project root
-        project_path = Path(project_root)
-        if not project_path.is_absolute():
-            return [TextContent(
-                type="text",
-                text=f"❌ Error: project_root must be an absolute path. Got: {project_root}"
-            )]
-        
-        # Default to cursor profile if none specified
-        if profiles is None:
-            profiles = ["cursor"]
-        
-        # Validate profiles
-        supported = get_supported_profiles()
-        invalid_profiles = [p for p in profiles if p not in supported]
-        if invalid_profiles:
-            return [TextContent(
-                type="text",
-                text=f"❌ Unknown profiles: {', '.join(invalid_profiles)}\n\n"
-                     f"Supported profiles: {', '.join(supported)}"
-            )]
-        
-        logger.info(f"Initializing NIA project at {project_root} with profiles: {profiles}")
-        
-        # Initialize the project
-        result = initialize_nia_project(
-            project_root=project_root,
-            profiles=profiles
-        )
-        
-        if not result.get("success"):
-            return [TextContent(
-                type="text",
-                text=f"❌ Failed to initialize project: {result.get('error', 'Unknown error')}"
-            )]
-        
-        # Format success response
-        response_lines = [
-            f"✅ Successfully initialized NIA project at: {project_root}",
-            "",
-            "## 📁 Created Files:",
-        ]
-        
-        for file in result.get("files_created", []):
-            response_lines.append(f"- {file}")
-        
-        if result.get("profiles_initialized"):
-            response_lines.extend([
-                "",
-                "## 🎨 Initialized Profiles:",
-            ])
-            for profile in result["profiles_initialized"]:
-                response_lines.append(f"- {profile}")
-        
-        if result.get("warnings"):
-            response_lines.extend([
-                "",
-                "## ⚠️ Warnings:",
-            ])
-            for warning in result["warnings"]:
-                response_lines.append(f"- {warning}")
-        
-        if result.get("next_steps"):
-            response_lines.extend([
-                "",
-                "## 🚀 Next Steps:",
-            ])
-            for i, step in enumerate(result["next_steps"], 1):
-                response_lines.append(f"{i}. {step}")
-        
-        # Add profile-specific instructions
-        response_lines.extend([
-            "",
-            "## 💡 Quick Start:",
-        ])
-        
-        if "cursor" in profiles:
-            response_lines.extend([
-                "**For Cursor:**",
-                "1. Restart Cursor to load the NIA MCP server",
-                "2. Run `list_repositories` to verify connection",
-                "3. Start indexing with `index_repository https://github.com/owner/repo`",
-                ""
-            ])
-        
-        if "vscode" in profiles:
-            response_lines.extend([
-                "**For VSCode:**",
-                "1. Reload the VSCode window (Cmd/Ctrl+R)",
-                "2. Open command palette (Cmd/Ctrl+Shift+P)",
-                "3. Run 'NIA: Index Repository' task",
-                ""
-            ])
-        
-        if "claude" in profiles:
-            response_lines.extend([
-                "**For Claude Desktop:**",
-                "1. The .claude directory has been created",
-                "2. Claude will now understand NIA commands",
-                "3. Try: 'Search for authentication patterns'",
-                ""
-            ])
-        
-        # Add general tips
-        response_lines.extend([
-            "## 📚 Tips:",
-            "- Use natural language for searches: 'How does X work?'",
-            "- Index repositories before searching them",
-            "- Use `nia_web_search` to discover new repositories",
-            "- Check `list_repositories` to see what's already indexed",
-            "",
-            "Ready to supercharge your development with AI-powered code search! 🚀"
-        ])
-        
-        return [TextContent(
-            type="text",
-            text="\n".join(response_lines)
-        )]
-        
-    except Exception as e:
-        logger.error(f"Error in initialize_project tool: {e}")
-        return [TextContent(
-            type="text",
-            text=f"❌ Error initializing project: {str(e)}\n\n"
-                 "Please check:\n"
-                 "- The project_root path is correct and accessible\n"
-                 "- You have write permissions to the directory\n"
-                 "- The NIA MCP server is properly installed"
-        )]
-
 @mcp.tool()
 async def read_source_content(
     source_type: str,
@@ -1897,22 +1596,15 @@ async def read_source_content(
     """
     Read the full content of a specific source file or document.
     
-    This tool allows AI to fetch complete content from sources identified during search,
-    enabling deeper analysis when the truncated search results are insufficient.
-    
     Args:
         source_type: Type of source - "repository" or "documentation"
         source_identifier: 
-            - For repository: "owner/repo:path/to/file.py" (e.g., "facebook/react:src/React.js")
+            - For repository: "owner/repo:path/to/file.py"
             - For documentation: The source URL or document ID
         metadata: Optional metadata from search results to help locate the source
         
     Returns:
         Full content of the requested source with metadata
-        
-    Examples:
-        - read_source_content("repository", "langchain-ai/langchain:libs/core/langchain_core/runnables/base.py")
-        - read_source_content("documentation", "https://docs.python.org/3/library/asyncio.html")
     """
     try:
         client = await ensure_api_client()
@@ -2016,6 +1708,170 @@ async def read_source_content(
             text=f"❌ Error reading source content: {str(e)}"
         )]
 
+@mcp.tool()
+async def get_repository_hierarchy(
+    repository: str,
+    include_classes: bool = True,
+    include_methods: bool = False,
+    include_tree: bool = False
+) -> List[TextContent]:
+    """
+    Get the file hierarchy for an indexed repository.
+
+    Args:
+        repository: Repository identifier in owner/repo format (e.g., "facebook/react")
+        include_classes: Whether to include class names in the hierarchy (default: True)
+        include_methods: Whether to include method names in the hierarchy (default: False)
+        include_tree: Whether to include the full tree structure (default: False)
+
+    Returns:
+        Repository file hierarchy with statistics and structural information
+    """
+    try:
+        client = await ensure_api_client()
+
+        logger.info(f"Getting repository hierarchy for: {repository}")
+
+        # Get the hierarchy data
+        result = await client.get_repository_hierarchy(
+            owner_repo=repository,
+            include_classes=include_classes,
+            include_methods=include_methods,
+            include_tree=include_tree
+        )
+
+        # Format the response
+        response_lines = []
+
+        # Header
+        response_lines.extend([
+            f"# 🏗️ Repository File Hierarchy: {repository}",
+            "",
+            f"**Repository ID:** {result.get('repository_id', 'Unknown')}",
+            f"**Generated:** {result.get('generated_at', 'Unknown')}",
+            ""
+        ])
+
+        # Options used
+        options = result.get("options", {})
+        response_lines.extend([
+            "**Options:**",
+            f"- Include Classes: {'✅' if options.get('include_classes', include_classes) else '❌'}",
+            f"- Include Methods: {'✅' if options.get('include_methods', include_methods) else '❌'}",
+            f"- Include Tree: {'✅' if include_tree else '❌'}",
+            ""
+        ])
+
+        # Statistics
+        stats = result.get("stats", {})
+        if stats:
+            response_lines.extend([
+                "## 📊 Statistics",
+                ""
+            ])
+
+            if stats.get("total_files"):
+                response_lines.append(f"📄 **Total Files:** {stats['total_files']:,}")
+            if stats.get("total_directories"):
+                response_lines.append(f"📁 **Total Directories:** {stats['total_directories']:,}")
+            if stats.get("total_classes"):
+                response_lines.append(f"🏷️ **Total Classes:** {stats['total_classes']:,}")
+            if stats.get("total_methods"):
+                response_lines.append(f"⚙️ **Total Methods:** {stats['total_methods']:,}")
+
+            # File types breakdown
+            if stats.get("file_types"):
+                response_lines.extend([
+                    "",
+                    "**File Types:**"
+                ])
+                file_types = stats["file_types"]
+                # 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_lines.append(f"- `{ext}`: {count:,} files")
+                if len(sorted_types) > 10:
+                    response_lines.append(f"- ... and {len(sorted_types) - 10} more types")
+
+            response_lines.append("")
+
+        # Hierarchy text
+        hierarchy_text = result.get("hierarchy_text", "")
+        if hierarchy_text:
+            response_lines.extend([
+                "## 🌳 File Hierarchy",
+                "",
+                "```",
+                hierarchy_text,
+                "```",
+                ""
+            ])
+
+        # Tree structure if requested and available
+        if include_tree and result.get("hierarchy_tree"):
+            response_lines.extend([
+                "## 🗂️ Detailed Tree Structure",
+                "",
+                "```json",
+                json.dumps(result["hierarchy_tree"], indent=2),
+                "```",
+                ""
+            ])
+
+        # Usage tips
+        response_lines.extend([
+            "## 💡 Usage Tips",
+            "",
+            "- Use this hierarchy to understand the codebase structure before searching",
+            "- Include methods for detailed function discovery",
+            "- Use `search_codebase` with specific file paths found here",
+            "- Reference file paths when using `read_source_content`"
+        ])
+
+        return [TextContent(type="text", text="\n".join(response_lines))]
+
+    except APIError as e:
+        logger.error(f"API Error getting repository hierarchy: {e}")
+
+        if e.status_code == 404:
+            return [TextContent(
+                type="text",
+                text=f"❌ Repository '{repository}' not found. Please check:\n\n"
+                     "1. The repository name is correct (owner/repo format)\n"
+                     "2. The repository has been indexed\n"
+                     "3. You have access to this repository\n\n"
+                     "Use `list_repositories` to see available repositories."
+            )]
+        elif e.status_code == 400:
+            return [TextContent(
+                type="text",
+                text=f"❌ Repository not ready: {e.detail}\n\n"
+                     f"The repository may still be indexing. Use `check_resource_status(\"repository\", \"{repository}\")` to check status."
+            )]
+        elif e.status_code == 403 or "free tier limit" in str(e).lower():
+            if e.detail and "3 free indexing operations" in e.detail:
+                return [TextContent(
+                    type="text",
+                    text=f"❌ {e.detail}\n\n💡 Tip: Upgrade to Pro at https://trynia.ai/billing for unlimited access."
+                )]
+            else:
+                return [TextContent(
+                    type="text",
+                    text=f"❌ {str(e)}\n\n💡 Tip: You've reached the free tier limit. Upgrade to Pro for unlimited access."
+                )]
+        else:
+            return [TextContent(type="text", text=f"❌ {str(e)}")]
+    except Exception as e:
+        logger.error(f"Unexpected error getting repository hierarchy: {e}")
+        return [TextContent(
+            type="text",
+            text=f"❌ Error getting repository hierarchy: {str(e)}\n\n"
+                 "Please check that:\n"
+                 "- The repository identifier is correct\n"
+                 "- The repository is fully indexed\n"
+                 "- Your API connection is working"
+        )]
+
 # @mcp.tool()
 # async def index_local_filesystem(
 #     directory_path: str,
@@ -2432,6 +2288,7 @@ async def read_source_content(
 #   - npm: Node.js packages from NPM registry
 #   - crates_io: Rust packages from crates.io
 #   - golang_proxy: Go modules from Go proxy
+#   - ruby_gems: Ruby gems from RubyGems.org
 #
 # Authentication:
 #   - Requires CHROMA_API_KEY environment variable
@@ -2467,8 +2324,6 @@ async def nia_package_search_grep(
     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
@@ -2476,23 +2331,19 @@ async def nia_package_search_grep(
         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"
+        language: The languages to filter for. If not provided, all languages will be searched.
         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.
+            {org}/{repo}
         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.
+            "crates_io", "golang_proxy", "npm", "py_pi", or "ruby_gems".
+        version: Optional
     """
     try:
         # Use API client for backend routing
@@ -2604,33 +2455,24 @@ async def nia_package_search_hybrid(
     language: Optional[str] = None
 ) -> List[TextContent]:
     """
-    Searches package source code using semantic understanding AND optionally regex patterns. This
-    allows for hybrid search, allowing for prefiltering with regex, and semantic ranking.
+    Searches package source code using semantic understanding AND optionally regex patterns.
 
     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.
+        language: The languages to filter for. If not provided, all languages will be searched.
+        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}
         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".
+            "crates_io", "golang_proxy", "npm", "py_pi", or "ruby_gems".
         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.
+        version: Optional
     """
     try:
         # Use API client for backend routing
@@ -2748,21 +2590,16 @@ async def nia_package_search_read_file(
     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.
+            {org}/{repo}
         registry: The name of the registry containing the requested package. Must be one of:
-            "crates_io", "golang_proxy", "npm", or "py_pi".
+            "crates_io", "golang_proxy", "npm", "py_pi", or "ruby_gems".
         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.
+        version: Optional
     """
     try:
         # Validate line range
@@ -2833,24 +2670,11 @@ async def nia_bug_report(
     additional_context: Optional[str] = None
 ) -> List[TextContent]:
     """
-    Submit a bug report or feature request to the Nia development team.
-
-    This tool allows users to report bugs, request features, or provide feedback
-    directly to the development team. Reports are sent via email and Slack for
-    immediate attention.
-
+    Submit a bug report or feature request.
     Args:
         description: Detailed description of the bug or feature request (10-5000 characters)
         bug_type: Type of report - "bug", "feature-request", "improvement", or "other" (default: "bug")
         additional_context: Optional additional context, steps to reproduce, or related information
-
-    Returns:
-        Confirmation of successful submission with reference ID
-
-    Examples:
-        - nia_bug_report("The search is not returning any results for my repository")
-        - nia_bug_report("Add support for searching within specific file types", "feature-request")
-        - nia_bug_report("Repository indexing fails with large repos", "bug", "Happens with repos over 1GB")
     """
     try:
         client = await ensure_api_client()
@@ -2947,15 +2771,11 @@ async def save_context(
     """
     Save a conversation context for cross-agent sharing.
 
-    This tool enables agents to save conversation contexts that can be shared
-    with other AI agents, creating seamless handoffs between different coding
-    environments (e.g., Cursor → Claude Code).
-
     Args:
-        title: A descriptive title for the context (1-200 characters)
-        summary: Brief summary of the conversation (10-1000 characters)
+        title: A descriptive title for the context
+        summary: Brief summary of the conversation
         content: Full conversation context - the agent should compact the conversation history but keep all important parts togethers, as well as code snippets. No excuses.
-        agent_source: Which agent is creating this context (e.g., "cursor", "claude-code", "windsurf")
+        agent_source: Which agent is creating this context (e.g., "cursor")
         tags: Optional list of searchable tags
         metadata: Optional metadata like file paths, repositories discussed, etc.
         nia_references: Structured data about NIA resources used during conversation
@@ -2969,20 +2789,6 @@ async def save_context(
 
     Returns:
         Confirmation of successful context save with context ID
-
-    Example:
-        save_context(
-            title="Streaming AI SDK Implementation",
-            summary="Planning conversation about implementing streaming responses with AI SDK",
-            content="User asked about implementing streaming... [agent should include conversation]",
-            agent_source="cursor",
-            tags=["streaming", "ai-sdk", "implementation"],
-            nia_references={
-                "indexed_resources": [{"identifier": "vercel/ai", "resource_type": "repository", "purpose": "Reference for streaming implementation"}],
-                "search_queries": [{"query": "streaming API", "query_type": "documentation", "key_findings": "Found useChat hook with streaming"}]
-            },
-            edited_files=[{"file_path": "src/chat.ts", "operation": "created", "changes_description": "Added streaming chat component"}]
-        )
     """
     try:
         # Validate input parameters
@@ -3061,12 +2867,6 @@ async def list_contexts(
 
     Returns:
         List of conversation contexts with pagination info
-
-    Examples:
-        - list_contexts() - List recent 20 contexts
-        - list_contexts(limit=50) - List recent 50 contexts
-        - list_contexts(tags="streaming,ai-sdk") - Filter by tags
-        - list_contexts(agent_source="cursor") - Only contexts from Cursor
     """
     try:
         # Validate parameters
@@ -3333,9 +3133,6 @@ async def search_contexts(
     """
     Search conversation contexts by content, title, or summary.
 
-    Perfect for finding relevant contexts when you remember part of the
-    conversation but not the exact context ID.
-
     Args:
         query: Search query to match against title, summary, content, and tags
         limit: Maximum number of results to return (1-100, default: 20)
@@ -3344,11 +3141,6 @@ async def search_contexts(
 
     Returns:
         Search results with matching contexts
-
-    Examples:
-        - search_contexts("streaming AI SDK")
-        - search_contexts("authentication", tags="security,implementation")
-        - search_contexts("database", agent_source="cursor")
     """
     try:
         # Validate parameters
@@ -3450,13 +3242,6 @@ async def update_context(
 
     Returns:
         Confirmation of successful update
-
-    Example:
-        update_context(
-            context_id="550e8400-e29b-41d4-a716-446655440000",
-            title="Updated: Streaming AI SDK Implementation",
-            tags=["streaming", "ai-sdk", "completed"]
-        )
     """
     try:
         if not context_id or not context_id.strip():