nia-mcp-server 1.0.26__py3-none-any.whl → 1.0.27__py3-none-any.whl

nia_mcp_server/server.py

@@ -72,54 +72,188 @@ async def ensure_api_client() -> NIAApiClient:
             raise ValueError("Failed to validate API key. Check logs for details.")
     return api_client
 
+def _detect_resource_type(url: str) -> str:
+    """Detect if URL is a GitHub repository or documentation.
+
+    Args:
+        url: The URL to analyze
+
+    Returns:
+        "repository" if GitHub URL or repository pattern, "documentation" otherwise
+    """
+    import re
+    from urllib.parse import urlparse
+
+    try:
+        # First, check for repository-like patterns
+        # Pattern 1: owner/repo format (simple case with single slash)
+        if re.match(r'^[a-zA-Z0-9_-]+/[a-zA-Z0-9_.-]+$', url):
+            return "repository"
+
+        # Pattern 2: Git SSH format (git@github.com:owner/repo.git)
+        if url.startswith('git@'):
+            return "repository"
+
+        # Pattern 3: Git protocol (git://...)
+        if url.startswith('git://'):
+            return "repository"
+
+        # Pattern 4: Ends with .git
+        if url.endswith('.git'):
+            return "repository"
+
+        # Pattern 5: owner/repo/tree/branch or owner/repo/tree/branch/... format
+        if re.match(r'^[a-zA-Z0-9_-]+/[a-zA-Z0-9_.-]+/tree/.+', url):
+            return "repository"
+
+        # Parse as URL for domain-based detection
+        parsed = urlparse(url)
+        # Only treat as repository if it's actually the github.com domain
+        netloc = parsed.netloc.lower()
+        if netloc == "github.com" or netloc == "www.github.com":
+            return "repository"
+
+        return "documentation"
+    except Exception:
+        # Fallback to documentation if parsing fails
+        return "documentation"
+
 # Tools
 
 @mcp.tool()
-async def index_repository(
-    repo_url: str,
-    branch: Optional[str] = None
+async def index(
+    url: str,
+    resource_type: Optional[str] = None,
+    branch: Optional[str] = None,
+    url_patterns: Optional[List[str]] = None,
+    exclude_patterns: Optional[List[str]] = None,
+    max_age: Optional[int] = None,
+    only_main_content: Optional[bool] = True,
+    wait_for: Optional[int] = None,
+    include_screenshot: Optional[bool] = None,
+    check_llms_txt: Optional[bool] = True,
+    llms_txt_strategy: Optional[str] = "prefer"
 ) -> List[TextContent]:
     """
+    Universal indexing tool - intelligently indexes GitHub repositories or documentation.
+
+    Auto-detects resource type from URL:
+    - GitHub URLs (containing "github.com") → Repository indexing
+    - All other URLs → Documentation indexing
+
     Args:
-        repo_url: GitHub repository URL (e.g., https://github.com/owner/repo or https://github.com/owner/repo/tree/branch)
+        url: GitHub repository URL or documentation site URL (required)
+        resource_type: Optional override - "repository" or "documentation" (auto-detected if not provided)
+
+        # Repository-specific parameters:
         branch: Branch to index (optional, defaults to main branch)
 
+        # Documentation-specific parameters:
+        url_patterns: Optional list of URL patterns to include in crawling
+        exclude_patterns: Optional list of URL patterns to exclude from crawling
+        max_age: Maximum age of cached content in days
+        only_main_content: Extract only main content (default: True)
+        wait_for: Time to wait for page load in milliseconds
+        include_screenshot: Include screenshots of pages
+        check_llms_txt: Check for llms.txt file (default: True)
+        llms_txt_strategy: Strategy for llms.txt - "prefer", "only", or "ignore" (default: "prefer")
+
+    Returns:
+        Status of the indexing operation
+
+    Examples:
+        # Index a GitHub repository (auto-detected)
+        index("https://github.com/owner/repo", branch="main")
+
+        # Index documentation (auto-detected)
+        index("https://docs.example.com", url_patterns=["*/api/*"])
+
+        # Manual override (if needed for edge cases)
+        index("https://github.io/docs", resource_type="documentation")
+
     Important:
-        - When started indexing, prompt users to either use check_repository_status tool or go to app.trynia.ai to check the status.
+        - When indexing starts, use check_resource_status to monitor progress
+        - Repository identifier format: owner/repo or owner/repo/tree/branch
     """
     try:
         client = await ensure_api_client()
-        
-        # Start indexing
-        logger.info(f"Starting to index repository: {repo_url}")
-        result = await client.index_repository(repo_url, branch)
-        
-        repository = result.get("repository", repo_url)
-        status = result.get("status", "unknown")
-        
-        if status == "completed":
-            return [TextContent(
-                type="text",
-                text=f"✅ Repository already indexed: {repository}\n"
-                     f"Branch: {result.get('branch', 'main')}\n"
-                     f"You can now search this codebase!"
-            )]
+
+        # Detect or validate resource type
+        if 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'."
+                )]
+            detected_type = resource_type
         else:
-            # Wait for indexing to complete
-            return [TextContent(
-                type="text",
-                text=f"⏳ Indexing started for: {repository}\n"
-                     f"Branch: {branch or 'default'}\n"
-                     f"Status: {status}\n\n"
-                     f"Use `check_repository_status` to monitor progress."
-            )]
-            
+            detected_type = _detect_resource_type(url)
+
+        logger.info(f"Indexing {detected_type}: {url}")
+
+        # Route to appropriate indexing method
+        if detected_type == "repository":
+            # Index repository
+            result = await client.index_repository(url, branch)
+
+            repository = result.get("repository", url)
+            status = result.get("status", "unknown")
+
+            if status == "completed":
+                return [TextContent(
+                    type="text",
+                    text=f"✅ Repository already indexed: {repository}\n"
+                         f"Branch: {result.get('branch', 'main')}\n"
+                         f"You can now search this codebase!"
+                )]
+            else:
+                return [TextContent(
+                    type="text",
+                    text=f"⏳ Indexing started for: {repository}\n"
+                         f"Branch: {branch or 'default'}\n"
+                         f"Status: {status}\n\n"
+                         f"Use `check_resource_status(\"repository\", \"{repository}\")` to monitor progress."
+                )]
+
+        else:  # documentation
+            # Index documentation
+            result = await client.create_data_source(
+                url=url,
+                url_patterns=url_patterns,
+                exclude_patterns=exclude_patterns,
+                max_age=max_age,
+                only_main_content=only_main_content,
+                wait_for=wait_for,
+                include_screenshot=include_screenshot,
+                check_llms_txt=check_llms_txt,
+                llms_txt_strategy=llms_txt_strategy
+            )
+
+            source_id = result.get("id")
+            status = result.get("status", "unknown")
+
+            if status == "completed":
+                return [TextContent(
+                    type="text",
+                    text=f"✅ Documentation already indexed: {url}\n"
+                         f"Source ID: {source_id}\n"
+                         f"You can now search this documentation!"
+                )]
+            else:
+                return [TextContent(
+                    type="text",
+                    text=f"⏳ Documentation indexing started: {url}\n"
+                         f"Source ID: {source_id}\n"
+                         f"Status: {status}\n\n"
+                         f"Use `check_resource_status(\"documentation\", \"{source_id}\")` to monitor progress."
+                )]
+
     except APIError as e:
-        logger.error(f"API Error indexing repository: {e} (status_code={e.status_code}, detail={e.detail})")
+        logger.error(f"API Error indexing {detected_type}: {e} (status_code={e.status_code}, detail={e.detail})")
         if e.status_code == 403 or "free tier limit" in str(e).lower() or "indexing operations" in str(e).lower():
             if e.detail and "3 free indexing operations" in e.detail:
                 return [TextContent(
-                    type="text", 
+                    type="text",
                     text=f"❌ {e.detail}\n\n💡 Tip: Upgrade to Pro at https://trynia.ai/billing for unlimited indexing."
                 )]
             else:
@@ -130,7 +264,7 @@ async def index_repository(
         else:
             return [TextContent(type="text", text=f"❌ {str(e)}")]
     except Exception as e:
-        logger.error(f"Unexpected error indexing repository: {e}")
+        logger.error(f"Unexpected error indexing: {e}")
         error_msg = str(e)
         if "indexing operations" in error_msg.lower() or "lifetime limit" in error_msg.lower():
             return [TextContent(
@@ -139,9 +273,79 @@ async def index_repository(
             )]
         return [TextContent(
             type="text",
-            text=f"❌ Error indexing repository: {error_msg}"
+            text=f"❌ Error indexing: {error_msg}"
         )]
 
+# @mcp.tool()
+# async def index_repository(
+#     repo_url: str,
+#     branch: Optional[str] = None
+# ) -> List[TextContent]:
+#     """
+#     DEPRECATED: Use the unified `index` tool instead.
+#
+#     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)
+#
+#     Important:
+#         - When started indexing, prompt users to either use check_repository_status tool or go to app.trynia.ai to check the status.
+#     """
+#     try:
+#         client = await ensure_api_client()
+#
+#         # Start indexing
+#         logger.info(f"Starting to index repository: {repo_url}")
+#         result = await client.index_repository(repo_url, branch)
+#
+#         repository = result.get("repository", repo_url)
+#         status = result.get("status", "unknown")
+#
+#         if status == "completed":
+#             return [TextContent(
+#                 type="text",
+#                 text=f"✅ Repository already indexed: {repository}\n"
+#                      f"Branch: {result.get('branch', 'main')}\n"
+#                      f"You can now search this codebase!"
+#             )]
+#         else:
+#             # Wait for indexing to complete
+#             return [TextContent(
+#                 type="text",
+#                 text=f"⏳ Indexing started for: {repository}\n"
+#                      f"Branch: {branch or 'default'}\n"
+#                      f"Status: {status}\n\n"
+#                      f"Use `check_repository_status` to monitor progress."
+#             )]
+#
+#     except APIError as e:
+#         logger.error(f"API Error indexing repository: {e} (status_code={e.status_code}, detail={e.detail})")
+#         if e.status_code == 403 or "free tier limit" in str(e).lower() or "indexing operations" 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 indexing."
+#                 )]
+#             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 indexing repository: {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 indexing repository: {error_msg}"
+#         )]
+
 @mcp.tool()
 async def search_codebase(
     query: str,
@@ -300,6 +504,164 @@ async def search_codebase(
             text=f"❌ Error searching codebase: {error_msg}"
         )]
 
+@mcp.tool()
+async def regex_search(
+    repositories: List[str],
+    query: str,
+    pattern: Optional[str] = None,
+    file_extensions: Optional[List[str]] = None,
+    languages: Optional[List[str]] = None,
+    max_results: int = 50,
+    include_context: bool = True,
+    context_lines: int = 3
+) -> List[TextContent]:
+    """
+    Perform regex pattern search over indexed repository source code.
+
+    Args:
+        repositories: List of repositories to search (owner/repo format)
+        query: Natural language query or regex pattern (e.g., "function handleSubmit", "class UserController", "/async\\s+function/")
+        pattern: Optional explicit regex pattern (overrides automatic extraction from query)
+        file_extensions: File extensions to filter (e.g., [".js", ".tsx", ".py"])
+        languages: Programming languages to filter (e.g., ["python", "javascript", "typescript"])
+        max_results: Maximum number of results to return (default: 50)
+        include_context: Include surrounding context lines (default: True)
+        context_lines: Number of context lines before/after match (default: 3)
+
+    Returns:
+        Regex search results with exact matches, file locations, and context
+
+    Examples:
+        - Natural language: `regex_search(["owner/repo"], "function handleSubmit")`
+        - Direct regex: `regex_search(["owner/repo"], "/async\\s+function\\s+\\w+/")`
+        - With filters: `regex_search(["owner/repo"], "class Controller", file_extensions=[".py"])`
+    """
+    try:
+        client = await ensure_api_client()
+
+        # Require explicit repository selection
+        if not repositories:
+            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 `regex_search([\"owner/repo\"], \"pattern\")`\n\n"
+                     "**Examples:**\n"
+                     "```python\n"
+                     "# Natural language pattern\n"
+                     "regex_search([\"facebook/react\"], \"function useState\")\n\n"
+                     "# Direct regex pattern\n"
+                     "regex_search([\"django/django\"], \"/class\\s+\\w+Admin/\")\n\n"
+                     "# With file filters\n"
+                     "regex_search([\"owner/repo\"], \"import React\", file_extensions=[\".tsx\"])\n"
+                     "```"
+            )]
+
+        logger.info(f"Performing regex search in {len(repositories)} repositories for query: {query}")
+
+        # Call the regex search API
+        result = await client.regex_search(
+            repositories=repositories,
+            query=query,
+            pattern=pattern,
+            file_extensions=file_extensions,
+            languages=languages,
+            max_results=max_results,
+            include_context=include_context,
+            context_lines=context_lines
+        )
+
+        # Check for errors
+        if not result.get("success"):
+            error_msg = result.get("error", "Unknown error")
+            return [TextContent(
+                type="text",
+                text=f"❌ **Regex Search Error:** {error_msg}"
+            )]
+
+        # Format the results
+        response_parts = []
+
+        # Add search summary
+        total_matches = result.get("total_matches", 0)
+        total_files = result.get("total_files", 0)
+        pattern_used = result.get("pattern", query)
+
+        summary = f"🔍 **Regex Search Results**\n\n"
+        summary += f"**Query:** `{query}`\n"
+        if pattern and pattern != query:
+            summary += f"**Pattern Used:** `{pattern_used}`\n"
+        summary += f"**Matches Found:** {total_matches} matches in {total_files} files\n"
+
+        if file_extensions:
+            summary += f"**File Extensions:** {', '.join(file_extensions)}\n"
+        if languages:
+            summary += f"**Languages:** {', '.join(languages)}\n"
+
+        response_parts.append(summary)
+        response_parts.append("\n---\n")
+
+        # Add the actual results
+        results = result.get("results", [])
+
+        if not results:
+            response_parts.append("\n📭 No matches found for the given pattern.")
+        else:
+            # Group results by file
+            file_matches = {}
+            for match in results:
+                file_path = match.get("file_path", "Unknown")
+                if file_path not in file_matches:
+                    file_matches[file_path] = []
+                file_matches[file_path].append(match)
+
+            # Format each file's matches
+            for file_path, matches in file_matches.items():
+                response_parts.append(f"\n### 📄 `{file_path}`\n")
+
+                for match in matches:
+                    line_number = match.get("line_number", 0)
+                    matched_text = match.get("matched_text", "")
+                    context = match.get("context", "")
+
+                    response_parts.append(f"\n**Line {line_number}:** `{matched_text}`\n")
+
+                    if include_context and context:
+                        # Format context with line numbers
+                        context_start = match.get("context_start_line", line_number)
+                        response_parts.append("\n```\n")
+                        context_lines_list = context.split('\n')
+                        for i, line in enumerate(context_lines_list):
+                            current_line_num = context_start + i
+                            marker = ">" if current_line_num == line_number else " "
+                            response_parts.append(f"{marker}{current_line_num:4d}: {line}\n")
+                        response_parts.append("```\n")
+
+        # Add search hints if available
+        search_hints = result.get("search_hints", {})
+        if search_hints and search_hints.get("is_regex"):
+            response_parts.append("\n---\n")
+            response_parts.append("💡 **Search Hints:**\n")
+            if search_hints.get("case_sensitive"):
+                response_parts.append("- Case-sensitive search enabled\n")
+            if search_hints.get("whole_word"):
+                response_parts.append("- Whole word matching enabled\n")
+
+        # Combine all parts into final response
+        full_response = "".join(response_parts)
+
+        return [TextContent(
+            type="text",
+            text=full_response
+        )]
+
+    except Exception as e:
+        logger.error(f"Regex search error: {e}", exc_info=True)
+        return [TextContent(
+            type="text",
+            text=f"❌ **Regex Search Error:** {str(e)}"
+        )]
+
 @mcp.tool()
 async def search_documentation(
     query: str,
@@ -583,74 +945,76 @@ async def search_documentation(
             text=f"❌ Error checking repository status: {str(e)}"
         )]
 
-@mcp.tool()
-async def index_documentation(
-    url: str,
-    url_patterns: Optional[List[str]] = None,
-    exclude_patterns: Optional[List[str]] = None,
-    max_age: Optional[int] = None,
-    only_main_content: Optional[bool] = True,
-    wait_for: Optional[int] = None,
-    include_screenshot: Optional[bool] = None,
-    check_llms_txt: Optional[bool] = True,
-    llms_txt_strategy: Optional[str] = "prefer"
-) -> List[TextContent]:
-    """
-    Index documentation or website for intelligent search.
-    
-    Args:
-        url: URL of the documentation site to index
-        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()
-        
-        # Create and start indexing
-        logger.info(f"Starting to index documentation: {url}")
-        result = await client.create_data_source(
-            url=url, 
-            url_patterns=url_patterns,
-            exclude_patterns=exclude_patterns,
-            max_age=max_age,
-            only_main_content=only_main_content,
-            wait_for=wait_for,
-            include_screenshot=include_screenshot,
-            check_llms_txt=check_llms_txt,
-            llms_txt_strategy=llms_txt_strategy
-        )
-        
-        source_id = result.get("id")
-        status = result.get("status", "unknown")
-        
-        if status == "completed":
-            return [TextContent(
-                type="text",
-                text=f"✅ Documentation already indexed: {url}\n"
-                     f"Source ID: {source_id}\n"
-                     f"You can now search this documentation!"
-            )]
-        else:
-            return [TextContent(
-                type="text",
-                text=f"⏳ Documentation indexing started: {url}\n"
-                     f"Source ID: {source_id}\n"
-                     f"Status: {status}\n\n"
-                     f"Use `check_documentation_status` to monitor progress."
-            )]
-            
-    except APIError as e:
-        logger.error(f"API Error indexing documentation: {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 indexing documentation: {e}")
-        return [TextContent(
-            type="text",
-            text=f"❌ Error indexing documentation: {str(e)}"
-        )]
+# @mcp.tool()
+# async def index_documentation(
+#     url: str,
+#     url_patterns: Optional[List[str]] = None,
+#     exclude_patterns: Optional[List[str]] = None,
+#     max_age: Optional[int] = None,
+#     only_main_content: Optional[bool] = True,
+#     wait_for: Optional[int] = None,
+#     include_screenshot: Optional[bool] = None,
+#     check_llms_txt: Optional[bool] = True,
+#     llms_txt_strategy: Optional[str] = "prefer"
+# ) -> List[TextContent]:
+#     """
+#     DEPRECATED: Use the unified `index` tool instead.
+#
+#     Index documentation or website for intelligent search.
+#
+#     Args:
+#         url: URL of the documentation site to index
+#         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()
+#
+#         # Create and start indexing
+#         logger.info(f"Starting to index documentation: {url}")
+#         result = await client.create_data_source(
+#             url=url,
+#             url_patterns=url_patterns,
+#             exclude_patterns=exclude_patterns,
+#             max_age=max_age,
+#             only_main_content=only_main_content,
+#             wait_for=wait_for,
+#             include_screenshot=include_screenshot,
+#             check_llms_txt=check_llms_txt,
+#             llms_txt_strategy=llms_txt_strategy
+#         )
+#
+#         source_id = result.get("id")
+#         status = result.get("status", "unknown")
+#
+#         if status == "completed":
+#             return [TextContent(
+#                 type="text",
+#                 text=f"✅ Documentation already indexed: {url}\n"
+#                      f"Source ID: {source_id}\n"
+#                      f"You can now search this documentation!"
+#             )]
+#         else:
+#             return [TextContent(
+#                 type="text",
+#                 text=f"⏳ Documentation indexing started: {url}\n"
+#                      f"Source ID: {source_id}\n"
+#                      f"Status: {status}\n\n"
+#                      f"Use `check_documentation_status` to monitor progress."
+#             )]
+#
+#     except APIError as e:
+#         logger.error(f"API Error indexing documentation: {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 indexing documentation: {e}")
+#         return [TextContent(
+#             type="text",
+#             text=f"❌ Error indexing documentation: {str(e)}"
+#         )]
 
 # @mcp.tool()
 # async def list_documentation() -> List[TextContent]:
@@ -776,73 +1140,450 @@ async def index_documentation(
 # Combined Resource Management Tools
 
 @mcp.tool()
-async def rename_resource(
-    resource_type: str,
-    identifier: str,
-    new_name: str
+async def manage_resource(
+    action: str,
+    resource_type: Optional[str] = None,
+    identifier: Optional[str] = None,
+    new_name: Optional[str] = None
 ) -> List[TextContent]:
     """
-    Rename a resource (repository or documentation) for better organization.
+    Unified resource management tool for repositories and documentation.
 
     Args:
-        resource_type: Type of resource - "repository" or "documentation"
-        identifier:
+        action: Action to perform - "list", "status", "rename", or "delete"
+        resource_type: Type of resource - "repository" or "documentation" (required for status/rename/delete, optional for list)
+        identifier: Resource identifier (required for status/rename/delete):
             - For repos: Repository in owner/repo format (e.g., "facebook/react")
             - For docs: UUID preferred, also supports display name or URL
+        new_name: New display name (required only for rename action, 1-100 characters)
+
+    Examples:
+        # List all resources
+        manage_resource(action="list")
+
+        # List only repositories
+        manage_resource(action="list", resource_type="repository")
+
+        # Check status
+        manage_resource(action="status", resource_type="repository", identifier="owner/repo")
+
+        # Rename resource
+        manage_resource(action="rename", resource_type="repository", identifier="owner/repo", new_name="My Project")
+
+        # Delete resource
+        manage_resource(action="delete", resource_type="documentation", identifier="uuid-here")
     """
     try:
-        # Validate resource type
-        if resource_type not in ["repository", "documentation"]:
+        # Validate action
+        valid_actions = ["list", "status", "rename", "delete"]
+        if action not in valid_actions:
             return [TextContent(
                 type="text",
-                text=f"❌ Invalid resource_type: '{resource_type}'. Must be 'repository' or 'documentation'."
+                text=f"❌ Invalid action: '{action}'. Must be one of: {', '.join(valid_actions)}"
             )]
 
-        # Validate name length
-        if not new_name or len(new_name) > 100:
+        # Validate resource_type when provided
+        if resource_type and resource_type not in ["repository", "documentation"]:
             return [TextContent(
                 type="text",
-                text="❌ Display name must be between 1 and 100 characters."
+                text=f"❌ Invalid resource_type: '{resource_type}'. Must be 'repository' or 'documentation'."
             )]
 
+        # Validate required parameters based on action
+        if action in ["status", "rename", "delete"]:
+            if not resource_type:
+                return [TextContent(
+                    type="text",
+                    text=f"❌ resource_type is required for action '{action}'"
+                )]
+            if not identifier:
+                return [TextContent(
+                    type="text",
+                    text=f"❌ identifier is required for action '{action}'"
+                )]
+
+        if action == "rename":
+            if not new_name:
+                return [TextContent(
+                    type="text",
+                    text="❌ new_name is required for rename action"
+                )]
+            # Validate name length
+            if 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"
+        # ===== LIST ACTION =====
+        if action == "list":
+            # 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."
+                )]
+
+            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` 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` 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` for GitHub repos or URLs\n")
+
+            return [TextContent(type="text", text="\n".join(lines))]
+
+        # ===== STATUS ACTION =====
+        elif action == "status":
+            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))]
+
+        # ===== RENAME ACTION =====
+        elif action == "rename":
+            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')}"
+                )]
+
+        # ===== DELETE ACTION =====
+        elif action == "delete":
+            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 in manage_resource ({action}): {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"Error in manage_resource ({action}): {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 in {action} operation: {error_msg}"
+        )]
+
+@mcp.tool()
+async def get_github_file_tree(
+    repository: str,
+    branch: Optional[str] = None,
+    include_paths: Optional[List[str]] = None,
+    exclude_paths: Optional[List[str]] = None,
+    file_extensions: Optional[List[str]] = None,
+    exclude_extensions: Optional[List[str]] = None,
+    show_full_paths: bool = False
+) -> List[TextContent]:
+    """
+    Get file and folder structure directly from GitHub API (no indexing required).
+
+    Args:
+        repository: Repository identifier (owner/repo format, e.g., "facebook/react")
+        branch: Optional branch name (defaults to repository's default branch)
+        include_paths: Only show files in these paths (e.g., ["src/", "lib/"])
+        exclude_paths: Hide files in these paths (e.g., ["node_modules/", "dist/", "test/"])
+        file_extensions: Only show these file types (e.g., [".py", ".js", ".ts"])
+        exclude_extensions: Hide these file types (e.g., [".md", ".lock", ".json"])
+        show_full_paths: Show full paths instead of tree structure (default: False)
+
+    Returns:
+        Filtered file tree structure from GitHub with stats
+    """
+    try:
+        client = await ensure_api_client()
 
-        if result.get("success"):
-            return [TextContent(
-                type="text",
-                text=f"✅ Successfully renamed {resource_desc} to '{new_name}'"
-            )]
-        else:
+        # Require explicit repository specification
+        if not repository:
             return [TextContent(
                 type="text",
-                text=f"❌ Failed to rename {resource_type}: {result.get('message', 'Unknown error')}"
+                text="🔍 **Please specify which repository to get file tree from:**\n\n"
+                     "Usage: `get_github_file_tree(\"owner/repo\")`\n\n"
+                     "**Examples:**\n"
+                     "```\n"
+                     "get_github_file_tree(\"facebook/react\")\n"
+                     "get_github_file_tree(\"microsoft/vscode\", \"main\")\n"
+                     "```"
             )]
 
+        logger.info(f"Getting GitHub tree for repository: {repository}, branch: {branch or 'default'}, filters: {include_paths or exclude_paths or file_extensions or exclude_extensions}")
+
+        # Call API with filters
+        result = await client.get_github_tree(
+            repository,
+            branch=branch,
+            include_paths=include_paths,
+            exclude_paths=exclude_paths,
+            file_extensions=file_extensions,
+            exclude_extensions=exclude_extensions,
+            show_full_paths=show_full_paths
+        )
+
+        # Format response
+        response_text = f"# 📁 GitHub File Tree: {result.get('owner')}/{result.get('repo')}\n\n"
+        response_text += f"**Branch:** `{result.get('branch')}`\n"
+        response_text += f"**SHA:** `{result.get('sha')}`\n"
+        response_text += f"**Retrieved:** {result.get('retrieved_at')}\n"
+        response_text += f"**Source:** GitHub API (always current)\n"
+
+        # Show active filters
+        filters = result.get("filters_applied", {})
+        active_filters = []
+        if filters.get("include_paths"):
+            active_filters.append(f"📂 Included paths: {', '.join(filters['include_paths'])}")
+        if filters.get("exclude_paths"):
+            active_filters.append(f"🚫 Excluded paths: {', '.join(filters['exclude_paths'])}")
+        if filters.get("file_extensions"):
+            active_filters.append(f"📄 File types: {', '.join(filters['file_extensions'])}")
+        if filters.get("exclude_extensions"):
+            active_filters.append(f"🚫 Excluded types: {', '.join(filters['exclude_extensions'])}")
+        if filters.get("show_full_paths"):
+            active_filters.append(f"📍 Showing full paths")
+
+        if active_filters:
+            response_text += f"**Filters:** {' | '.join(active_filters)}\n"
+
+        response_text += "\n"
+
+        # Add stats
+        stats = result.get("stats", {})
+        response_text += "## 📊 Statistics\n\n"
+        response_text += f"- **Total Files:** {stats.get('total_files', 0)}\n"
+        response_text += f"- **Total Directories:** {stats.get('total_directories', 0)}\n"
+        response_text += f"- **Max Depth:** {stats.get('max_depth', 0)} levels\n"
+
+        # File extensions breakdown
+        file_extensions = stats.get("file_extensions", {})
+        if file_extensions:
+            response_text += f"\n**File Types:**\n"
+            sorted_extensions = sorted(file_extensions.items(), key=lambda x: x[1], reverse=True)
+            for ext, count in sorted_extensions[:10]:  # Show top 10
+                ext_name = ext if ext != "no_extension" else "(no extension)"
+                response_text += f"  - `{ext_name}`: {count} files\n"
+
+        # Tree structure (full)
+        tree_text = result.get("tree_text", "")
+        if tree_text:
+            response_text += "\n## 🌳 Directory Structure\n\n"
+            response_text += "```\n"
+            response_text += tree_text
+            response_text += "\n```\n"
+
+        # Truncation warning
+        if result.get("truncated"):
+            response_text += "\n⚠️ **Note:** Repository is very large. Tree may be truncated by GitHub.\n"
+
+        # Usage hints
+        response_text += "\n---\n"
+        response_text += "💡 **Next Steps:**\n"
+        response_text += f"- Index this repository: `index(\"{repository}\")`\n"
+        response_text += "- Refine with filters (examples below)\n"
+        response_text += "- Use `manage_resource(\"status\", \"repository\", \"{}\")` to check indexing status\n\n".format(repository)
+
+        # Show filter examples if no filters were used
+        if not active_filters:
+            response_text += "**Filter Examples:**\n"
+            response_text += f"- Only Python files: `file_extensions=[\".py\"]`\n"
+            response_text += f"- Exclude tests: `exclude_paths=[\"test/\", \"tests/\"]`\n"
+            response_text += f"- Only src directory: `include_paths=[\"src/\"]`\n"
+            response_text += f"- Full paths: `show_full_paths=True`\n"
+
+        return [TextContent(type="text", text=response_text)]
+
     except APIError as e:
-        logger.error(f"API Error renaming {resource_type}: {e}")
+        logger.error(f"API Error getting GitHub tree: {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."
+        if e.status_code == 404:
+            error_msg = f"❌ Repository '{repository}' not found or not accessible.\n\n"
+            error_msg += "**Possible reasons:**\n"
+            error_msg += "- Repository doesn't exist\n"
+            error_msg += "- Repository is private and GitHub App not installed\n"
+            error_msg += "- Invalid owner/repo format\n\n"
+            error_msg += "**Note:** You must have the repository indexed first, or have GitHub App installed."
         return [TextContent(type="text", text=error_msg)]
     except Exception as e:
-        logger.error(f"Error renaming {resource_type}: {e}")
+        logger.error(f"Error getting GitHub tree: {e}")
         return [TextContent(
             type="text",
-            text=f"❌ Error renaming {resource_type}: {str(e)}"
+            text=f"❌ Error getting GitHub file tree: {str(e)}"
         )]
 
-@mcp.tool()
-async def delete_resource(
-    resource_type: str,
-    identifier: str
-) -> List[TextContent]:
+# DEPRECATED: Use manage_resource(action="delete") instead
+# @mcp.tool()
+# async def delete_resource(
+#     resource_type: str,
+#     identifier: str
+# ) -> List[TextContent]:
     """
     Delete an indexed resource (repository or documentation).
 
@@ -893,11 +1634,12 @@ async def delete_resource(
             text=f"❌ Error deleting {resource_type}: {str(e)}"
         )]
 
-@mcp.tool()
-async def check_resource_status(
-    resource_type: str,
-    identifier: str
-) -> List[TextContent]:
+# DEPRECATED: Use manage_resource(action="status") instead
+# @mcp.tool()
+# async def check_resource_status(
+#     resource_type: str,
+#     identifier: str
+# ) -> List[TextContent]:
     """
     Check the indexing status of a resource (repository or documentation).
 
@@ -996,10 +1738,11 @@ async def check_resource_status(
             text=f"❌ Error checking {resource_type} status: {str(e)}"
         )]
 
-@mcp.tool()
-async def list_resources(
-    resource_type: Optional[str] = None
-) -> List[TextContent]:
+# DEPRECATED: Use manage_resource(action="list") instead
+# @mcp.tool()
+# async def list_resources(
+#     resource_type: Optional[str] = None
+# ) -> List[TextContent]:
     """
     List indexed resources (repositories and/or documentation).
 
@@ -1707,171 +2450,6 @@ async def read_source_content(
             type="text",
             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,
@@ -2758,16 +3336,545 @@ async def nia_bug_report(
 # Context Sharing Tools
 
 @mcp.tool()
-async def save_context(
-    title: str,
-    summary: str,
-    content: str,
-    agent_source: str,
+async def context(
+    action: str,
+    # For save action
+    title: Optional[str] = None,
+    summary: Optional[str] = None,
+    content: Optional[str] = None,
+    agent_source: Optional[str] = None,
     tags: Optional[List[str]] = None,
     metadata: Optional[dict] = None,
     nia_references: Optional[dict] = None,
-    edited_files: Optional[List[dict]] = None
+    edited_files: Optional[List[dict]] = None,
+    # For list/search actions
+    limit: int = 20,
+    offset: int = 0,
+    # For retrieve/update/delete actions
+    context_id: Optional[str] = None,
+    # For search action
+    query: Optional[str] = None
 ) -> List[TextContent]:
+    """
+    Unified context management tool for saving, listing, retrieving, searching, updating, and deleting conversation contexts.
+
+    Args:
+        action: Action to perform - "save", "list", "retrieve", "search", "update", or "delete"
+
+        # Save action parameters (all required except tags, metadata, nia_references, edited_files):
+        title: Descriptive title for the context
+        summary: Brief summary of the conversation (10-1000 chars)
+        content: Full conversation context (minimum 50 chars)
+        agent_source: Which agent is creating this context (e.g., "cursor", "claude-code")
+        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
+        edited_files: List of files that were modified during conversation
+
+        # List action parameters (all optional):
+        limit: Number of contexts to return (1-100, default: 20)
+        offset: Number of contexts to skip for pagination (default: 0)
+
+        # Retrieve action parameters:
+        context_id: The unique ID of the context to retrieve (required)
+
+        # Search action parameters:
+        query: Search query to match against title, summary, content, and tags (required)
+        limit: Maximum number of results to return (1-100, default: 20)
+
+        # Update action parameters:
+        context_id: The unique ID of the context to update (required)
+        title: Updated title (optional)
+        summary: Updated summary (optional)
+        content: Updated content (optional)
+        tags: Updated tags list (optional)
+        metadata: Updated metadata (optional)
+
+        # Delete action parameters:
+        context_id: The unique ID of the context to delete (required)
+
+    Examples:
+        # Save context
+        context(action="save", title="API Design", summary="Discussed REST patterns",
+                content="Full conversation...", agent_source="cursor")
+
+        # List contexts
+        context(action="list", limit=10, agent_source="cursor")
+
+        # Retrieve context
+        context(action="retrieve", context_id="550e8400-e29b-41d4-a716-446655440000")
+
+        # Search contexts
+        context(action="search", query="authentication", limit=10)
+
+        # Update context
+        context(action="update", context_id="550e8400...", title="New Title", tags=["updated"])
+
+        # Delete context
+        context(action="delete", context_id="550e8400-e29b-41d4-a716-446655440000")
+    """
+    try:
+        # Validate action
+        valid_actions = ["save", "list", "retrieve", "search", "update", "delete"]
+        if action not in valid_actions:
+            return [TextContent(
+                type="text",
+                text=f"❌ Invalid action: '{action}'. Must be one of: {', '.join(valid_actions)}"
+            )]
+
+        client = await ensure_api_client()
+
+        # ===== SAVE ACTION =====
+        if action == "save":
+            # Validate required parameters
+            if not title or not title.strip():
+                return [TextContent(type="text", text="❌ Error: title is required for save action")]
+            if not summary:
+                return [TextContent(type="text", text="❌ Error: summary is required for save action")]
+            if not content:
+                return [TextContent(type="text", text="❌ Error: content is required for save action")]
+            if not agent_source or not agent_source.strip():
+                return [TextContent(type="text", text="❌ Error: agent_source is required for save action")]
+
+            # Validate field lengths
+            if len(title) > 200:
+                return [TextContent(type="text", text="❌ Error: Title must be 200 characters or less")]
+            if len(summary) < 10 or len(summary) > 1000:
+                return [TextContent(type="text", text="❌ Error: Summary must be 10-1000 characters")]
+            if len(content) < 50:
+                return [TextContent(type="text", text="❌ Error: Content must be at least 50 characters")]
+
+            logger.info(f"Saving context: title='{title}', agent={agent_source}, content_length={len(content)}")
+
+            result = await client.save_context(
+                title=title.strip(),
+                summary=summary.strip(),
+                content=content,
+                agent_source=agent_source.strip(),
+                tags=tags or [],
+                metadata=metadata or {},
+                nia_references=nia_references,
+                edited_files=edited_files or []
+            )
+
+            context_id_result = result.get("id")
+
+            return [TextContent(
+                type="text",
+                text=f"✅ **Context Saved Successfully!**\n\n"
+                     f"🆔 **Context ID:** `{context_id_result}`\n"
+                     f"📝 **Title:** {title}\n"
+                     f"🤖 **Source Agent:** {agent_source}\n"
+                     f"📊 **Content Length:** {len(content):,} characters\n"
+                     f"🏷️ **Tags:** {', '.join(tags) if tags else 'None'}\n\n"
+                     f"**Next Steps:**\n"
+                     f"• Other agents can now retrieve this context using the context ID\n"
+                     f"• Use `context(action='search', query='...')` to find contexts\n"
+                     f"• Use `context(action='list')` to see all your saved contexts\n\n"
+                     f"🔗 **Share this context:** Provide the context ID `{context_id_result}` to other agents"
+            )]
+
+        # ===== LIST ACTION =====
+        elif action == "list":
+            # Validate parameters
+            if limit < 1 or limit > 100:
+                return [TextContent(type="text", text="❌ Error: Limit must be between 1 and 100")]
+            if offset < 0:
+                return [TextContent(type="text", text="❌ Error: Offset must be 0 or greater")]
+
+            # Convert tags list to comma-separated string if provided
+            tags_filter = ','.join(tags) if tags and isinstance(tags, list) else (tags if isinstance(tags, str) else None)
+
+            result = await client.list_contexts(
+                limit=limit,
+                offset=offset,
+                tags=tags_filter,
+                agent_source=agent_source
+            )
+
+            contexts = result.get("contexts", [])
+            pagination = result.get("pagination", {})
+
+            if not contexts:
+                response = "📭 **No Contexts Found**\n\n"
+                if tags or agent_source:
+                    response += "No contexts match your filters.\n\n"
+                else:
+                    response += "You haven't saved any contexts yet.\n\n"
+
+                response += "**Get started:**\n"
+                response += "• Use `context(action='save', ...)` to save a conversation for cross-agent sharing\n"
+                response += "• Perfect for handoffs between Cursor and Claude Code!"
+
+                return [TextContent(type="text", text=response)]
+
+            # Format the response
+            response = f"📚 **Your Conversation Contexts** ({pagination.get('total', len(contexts))} total)\n\n"
+
+            for i, ctx in enumerate(contexts, offset + 1):
+                created_at = ctx.get('created_at', '')
+                if created_at:
+                    try:
+                        from datetime import datetime
+                        dt = datetime.fromisoformat(created_at.replace('Z', '+00:00'))
+                        formatted_date = dt.strftime('%Y-%m-%d %H:%M UTC')
+                    except:
+                        formatted_date = created_at
+                else:
+                    formatted_date = 'Unknown'
+
+                response += f"**{i}. {ctx['title']}**\n"
+                response += f"   🆔 ID: `{ctx['id']}`\n"
+                response += f"   🤖 Source: {ctx['agent_source']}\n"
+                response += f"   📅 Created: {formatted_date}\n"
+                response += f"   📝 Summary: {ctx['summary'][:100]}{'...' if len(ctx['summary']) > 100 else ''}\n"
+                if ctx.get('tags'):
+                    response += f"   🏷️ Tags: {', '.join(ctx['tags'])}\n"
+                response += "\n"
+
+            # Add pagination info
+            if pagination.get('has_more'):
+                next_offset = offset + limit
+                response += f"📄 **Pagination:** Showing {offset + 1}-{offset + len(contexts)} of {pagination.get('total')}\n"
+                response += f"   Use `context(action='list', offset={next_offset})` for next page\n"
+
+            response += "\n**Actions:**\n"
+            response += "• `context(action='retrieve', context_id='...')` - Get full context\n"
+            response += "• `context(action='search', query='...')` - Search contexts\n"
+            response += "• `context(action='delete', context_id='...')` - Remove context"
+
+            return [TextContent(type="text", text=response)]
+
+        # ===== RETRIEVE ACTION =====
+        elif action == "retrieve":
+            if not context_id or not context_id.strip():
+                return [TextContent(type="text", text="❌ Error: context_id is required for retrieve action")]
+
+            ctx = await client.get_context(context_id.strip())
+
+            if not ctx:
+                return [TextContent(
+                    type="text",
+                    text=f"❌ **Context Not Found**\n\n"
+                         f"Context ID `{context_id}` was not found.\n\n"
+                         f"**Possible reasons:**\n"
+                         f"• The context ID is incorrect\n"
+                         f"• The context belongs to a different user\n"
+                         f"• The context has been deleted\n\n"
+                         f"Use `context(action='list')` to see your available contexts."
+                )]
+
+            # Format the context display
+            created_at = ctx.get('created_at', '')
+            if created_at:
+                try:
+                    from datetime import datetime
+                    dt = datetime.fromisoformat(created_at.replace('Z', '+00:00'))
+                    formatted_date = dt.strftime('%Y-%m-%d %H:%M UTC')
+                except:
+                    formatted_date = created_at
+            else:
+                formatted_date = 'Unknown'
+
+            updated_at = ctx.get('updated_at', '')
+            formatted_updated = None
+            if updated_at:
+                try:
+                    from datetime import datetime
+                    dt = datetime.fromisoformat(updated_at.replace('Z', '+00:00'))
+                    formatted_updated = dt.strftime('%Y-%m-%d %H:%M UTC')
+                except:
+                    formatted_updated = updated_at
+
+            response = f"📋 **Context: {ctx['title']}**\n\n"
+            response += f"🆔 **ID:** `{ctx['id']}`\n"
+            response += f"🤖 **Source Agent:** {ctx['agent_source']}\n"
+            response += f"📅 **Created:** {formatted_date}\n"
+            if formatted_updated:
+                response += f"🔄 **Updated:** {formatted_updated}\n"
+
+            if ctx.get('tags'):
+                response += f"🏷️ **Tags:** {', '.join(ctx['tags'])}\n"
+
+            response += f"\n📝 **Summary:**\n{ctx['summary']}\n\n"
+
+            # Add NIA References
+            nia_refs = ctx.get('nia_references') or {}
+            if nia_refs:
+                response += "🧠 **NIA RESOURCES USED - RECOMMENDED ACTIONS:**\n"
+
+                indexed_resources = nia_refs.get('indexed_resources', [])
+                if indexed_resources:
+                    response += "**📦 Re-index these resources:**\n"
+                    for resource in indexed_resources:
+                        identifier = resource.get('identifier', 'Unknown')
+                        resource_type = resource.get('resource_type', 'unknown')
+                        purpose = resource.get('purpose', 'No purpose specified')
+
+                        if resource_type == 'repository':
+                            response += f"• `Index {identifier}` - {purpose}\n"
+                        elif resource_type == 'documentation':
+                            response += f"• `Index documentation {identifier}` - {purpose}\n"
+                        else:
+                            response += f"• `Index {identifier}` ({resource_type}) - {purpose}\n"
+                    response += "\n"
+
+                search_queries = nia_refs.get('search_queries', [])
+                if search_queries:
+                    response += "**🔍 Useful search queries to re-run:**\n"
+                    for q in search_queries:
+                        query_text = q.get('query', 'Unknown query')
+                        query_type = q.get('query_type', 'search')
+                        key_findings = q.get('key_findings', 'No findings specified')
+                        resources_searched = q.get('resources_searched', [])
+
+                        response += f"• **Query:** `{query_text}` ({query_type})\n"
+                        if resources_searched:
+                            response += f"  **Resources:** {', '.join(resources_searched)}\n"
+                        response += f"  **Key Findings:** {key_findings}\n"
+                    response += "\n"
+
+                session_summary = nia_refs.get('session_summary')
+                if session_summary:
+                    response += f"**📋 NIA Session Summary:** {session_summary}\n\n"
+
+            # Add Edited Files
+            edited_files_list = ctx.get('edited_files') or []
+            if edited_files_list:
+                response += "📝 **FILES MODIFIED - READ THESE TO GET UP TO SPEED:**\n"
+                for file_info in edited_files_list:
+                    file_path = file_info.get('file_path', 'Unknown file')
+                    operation = file_info.get('operation', 'modified')
+                    changes_desc = file_info.get('changes_description', 'No description')
+                    key_changes = file_info.get('key_changes', [])
+                    language = file_info.get('language', '')
+
+                    operation_emoji = {
+                        'created': '🆕',
+                        'modified': '✏️',
+                        'deleted': '🗑️'
+                    }.get(operation, '📄')
+
+                    response += f"• {operation_emoji} **`{file_path}`** ({operation})\n"
+                    response += f"  **Changes:** {changes_desc}\n"
+
+                    if key_changes:
+                        response += f"  **Key Changes:** {', '.join(key_changes)}\n"
+                    if language:
+                        response += f"  **Language:** {language}\n"
+
+                    response += f"  **💡 Action:** Read this file with: `Read {file_path}`\n"
+                response += "\n"
+
+            # Add metadata if available
+            metadata_dict = ctx.get('metadata') or {}
+            if metadata_dict:
+                response += f"📊 **Additional Metadata:**\n"
+                for key, value in metadata_dict.items():
+                    if isinstance(value, list):
+                        response += f"• **{key}:** {', '.join(map(str, value))}\n"
+                    else:
+                        response += f"• **{key}:** {value}\n"
+                response += "\n"
+
+            response += f"📄 **Full Context:**\n\n{ctx['content']}\n\n"
+
+            response += f"---\n"
+            response += f"🚀 **NEXT STEPS FOR SEAMLESS HANDOFF:**\n"
+            response += f"• This context was created by **{ctx['agent_source']}**\n"
+
+            if nia_refs.get('search_queries'):
+                response += f"• **RECOMMENDED:** Re-run the search queries to get the same insights\n"
+            if edited_files_list:
+                response += f"• **ESSENTIAL:** Read the modified files above to understand code changes\n"
+
+            response += f"• Use the summary and full context to understand the strategic planning\n"
+
+            return [TextContent(type="text", text=response)]
+
+        # ===== SEARCH ACTION =====
+        elif action == "search":
+            if not query or not query.strip():
+                return [TextContent(type="text", text="❌ Error: query is required for search action")]
+
+            if limit < 1 or limit > 100:
+                return [TextContent(type="text", text="❌ Error: Limit must be between 1 and 100")]
+
+            # Convert tags list to comma-separated string if provided
+            tags_filter = ','.join(tags) if tags and isinstance(tags, list) else (tags if isinstance(tags, str) else None)
+
+            result = await client.search_contexts(
+                query=query.strip(),
+                limit=limit,
+                tags=tags_filter,
+                agent_source=agent_source
+            )
+
+            contexts = result.get("contexts", [])
+
+            if not contexts:
+                response = f"🔍 **No Results Found**\n\n"
+                response += f"No contexts match your search query: \"{query}\"\n\n"
+
+                if tags or agent_source:
+                    response += f"**Active filters:**\n"
+                    if tags:
+                        response += f"• Tags: {tags if isinstance(tags, str) else ', '.join(tags)}\n"
+                    if agent_source:
+                        response += f"• Agent: {agent_source}\n"
+                    response += "\n"
+
+                response += f"**Suggestions:**\n"
+                response += f"• Try different keywords\n"
+                response += f"• Remove filters to broaden search\n"
+                response += f"• Use `context(action='list')` to see all contexts"
+
+                return [TextContent(type="text", text=response)]
+
+            # Format search results
+            response = f"🔍 **Search Results for \"{query}\"** ({len(contexts)} found)\n\n"
+
+            for i, ctx in enumerate(contexts, 1):
+                created_at = ctx.get('created_at', '')
+                if created_at:
+                    try:
+                        from datetime import datetime
+                        dt = datetime.fromisoformat(created_at.replace('Z', '+00:00'))
+                        formatted_date = dt.strftime('%Y-%m-%d %H:%M UTC')
+                    except:
+                        formatted_date = created_at
+                else:
+                    formatted_date = 'Unknown'
+
+                response += f"**{i}. {ctx['title']}**\n"
+                response += f"   🆔 ID: `{ctx['id']}`\n"
+                response += f"   🤖 Source: {ctx['agent_source']}\n"
+                response += f"   📅 Created: {formatted_date}\n"
+                response += f"   📝 Summary: {ctx['summary'][:150]}{'...' if len(ctx['summary']) > 150 else ''}\n"
+
+                if ctx.get('tags'):
+                    response += f"   🏷️ Tags: {', '.join(ctx['tags'])}\n"
+
+                response += "\n"
+
+            response += f"**Actions:**\n"
+            response += f"• `context(action='retrieve', context_id='...')` - Get full context\n"
+            response += f"• Refine search with different keywords\n"
+            response += f"• Use tags or agent filters for better results"
+
+            return [TextContent(type="text", text=response)]
+
+        # ===== UPDATE ACTION =====
+        elif action == "update":
+            if not context_id or not context_id.strip():
+                return [TextContent(type="text", text="❌ Error: context_id is required for update action")]
+
+            # Check that at least one field is being updated
+            if not any([title, summary, content, tags is not None, metadata is not None]):
+                return [TextContent(
+                    type="text",
+                    text="❌ Error: At least one field must be provided for update (title, summary, content, tags, or metadata)"
+                )]
+
+            # Validate fields if provided
+            if title is not None and (not title.strip() or len(title) > 200):
+                return [TextContent(type="text", text="❌ Error: Title must be 1-200 characters")]
+
+            if summary is not None and (len(summary) < 10 or len(summary) > 1000):
+                return [TextContent(type="text", text="❌ Error: Summary must be 10-1000 characters")]
+
+            if content is not None and len(content) < 50:
+                return [TextContent(type="text", text="❌ Error: Content must be at least 50 characters")]
+
+            if tags is not None and len(tags) > 10:
+                return [TextContent(type="text", text="❌ Error: Maximum 10 tags allowed")]
+
+            result = await client.update_context(
+                context_id=context_id.strip(),
+                title=title.strip() if title else None,
+                summary=summary.strip() if summary else None,
+                content=content,
+                tags=tags,
+                metadata=metadata
+            )
+
+            if not result:
+                return [TextContent(
+                    type="text",
+                    text=f"❌ Error: Context with ID `{context_id}` not found"
+                )]
+
+            # List updated fields
+            updated_fields = []
+            if title is not None:
+                updated_fields.append("title")
+            if summary is not None:
+                updated_fields.append("summary")
+            if content is not None:
+                updated_fields.append("content")
+            if tags is not None:
+                updated_fields.append("tags")
+            if metadata is not None:
+                updated_fields.append("metadata")
+
+            response = f"✅ **Context Updated Successfully!**\n\n"
+            response += f"🆔 **Context ID:** `{context_id}`\n"
+            response += f"📝 **Title:** {result['title']}\n"
+            response += f"🔄 **Updated Fields:** {', '.join(updated_fields)}\n"
+            response += f"🤖 **Source Agent:** {result['agent_source']}\n\n"
+
+            response += f"**Current Status:**\n"
+            response += f"• **Tags:** {', '.join(result['tags']) if result.get('tags') else 'None'}\n"
+            response += f"• **Content Length:** {len(result['content']):,} characters\n\n"
+
+            response += f"Use `context(action='retrieve', context_id='{context_id}')` to see the full updated context."
+
+            return [TextContent(type="text", text=response)]
+
+        # ===== DELETE ACTION =====
+        elif action == "delete":
+            if not context_id or not context_id.strip():
+                return [TextContent(type="text", text="❌ Error: context_id is required for delete action")]
+
+            success = await client.delete_context(context_id.strip())
+
+            if success:
+                return [TextContent(
+                    type="text",
+                    text=f"✅ **Context Deleted Successfully!**\n\n"
+                         f"🆔 **Context ID:** `{context_id}`\n\n"
+                         f"The context has been permanently removed from your account.\n"
+                         f"This action cannot be undone.\n\n"
+                         f"Use `context(action='list')` to see your remaining contexts."
+                )]
+            else:
+                return [TextContent(
+                    type="text",
+                    text=f"❌ **Context Not Found**\n\n"
+                         f"Context ID `{context_id}` was not found or has already been deleted.\n\n"
+                         f"Use `context(action='list')` to see your available contexts."
+                )]
+
+    except APIError as e:
+        logger.error(f"API Error in context ({action}): {e}")
+        return [TextContent(type="text", text=f"❌ API Error: {str(e)}")]
+    except Exception as e:
+        logger.error(f"Error in context ({action}): {e}")
+        return [TextContent(type="text", text=f"❌ Error in {action} operation: {str(e)}")]
+
+# DEPRECATED: Individual context tools below - use context() with action parameter instead
+
+# @mcp.tool()
+# async def save_context(
+#     title: str,
+#     summary: str,
+#     content: str,
+#     agent_source: str,
+#     tags: Optional[List[str]] = None,
+#     metadata: Optional[dict] = None,
+#     nia_references: Optional[dict] = None,
+#     edited_files: Optional[List[dict]] = None
+# ) -> List[TextContent]:
     """
     Save a conversation context for cross-agent sharing.
 
@@ -2849,13 +3956,14 @@ async def save_context(
         logger.error(f"Error saving context: {e}")
         return [TextContent(type="text", text=f"❌ Error saving context: {str(e)}")]
 
-@mcp.tool()
-async def list_contexts(
-    limit: int = 20,
-    offset: int = 0,
-    tags: Optional[str] = None,
-    agent_source: Optional[str] = None
-) -> List[TextContent]:
+# DEPRECATED: Use context(action="list") instead
+# @mcp.tool()
+# async def list_contexts(
+#     limit: int = 20,
+#     offset: int = 0,
+#     tags: Optional[str] = None,
+#     agent_source: Optional[str] = None
+# ) -> List[TextContent]:
     """
     List saved conversation contexts with pagination and filtering.
 
@@ -2946,8 +4054,9 @@ async def list_contexts(
         logger.error(f"Error listing contexts: {e}")
         return [TextContent(type="text", text=f"❌ Error listing contexts: {str(e)}")]
 
-@mcp.tool()
-async def retrieve_context(context_id: str) -> List[TextContent]:
+# DEPRECATED: Use context(action="retrieve") instead
+# @mcp.tool()
+# async def retrieve_context(context_id: str) -> List[TextContent]:
     """
     Retrieve a specific conversation context by ID.
 
@@ -3123,13 +4232,14 @@ async def retrieve_context(context_id: str) -> List[TextContent]:
         logger.error(f"Error retrieving context: {e}")
         return [TextContent(type="text", text=f"❌ Error retrieving context: {str(e)}")]
 
-@mcp.tool()
-async def search_contexts(
-    query: str,
-    limit: int = 20,
-    tags: Optional[str] = None,
-    agent_source: Optional[str] = None
-) -> List[TextContent]:
+# DEPRECATED: Use context(action="search") instead
+# @mcp.tool()
+# async def search_contexts(
+#     query: str,
+#     limit: int = 20,
+#     tags: Optional[str] = None,
+#     agent_source: Optional[str] = None
+# ) -> List[TextContent]:
     """
     Search conversation contexts by content, title, or summary.
 
@@ -3220,15 +4330,16 @@ async def search_contexts(
         logger.error(f"Error searching contexts: {e}")
         return [TextContent(type="text", text=f"❌ Error searching contexts: {str(e)}")]
 
-@mcp.tool()
-async def update_context(
-    context_id: str,
-    title: Optional[str] = None,
-    summary: Optional[str] = None,
-    content: Optional[str] = None,
-    tags: Optional[List[str]] = None,
-    metadata: Optional[dict] = None
-) -> List[TextContent]:
+# DEPRECATED: Use context(action="update") instead
+# @mcp.tool()
+# async def update_context(
+#     context_id: str,
+#     title: Optional[str] = None,
+#     summary: Optional[str] = None,
+#     content: Optional[str] = None,
+#     tags: Optional[List[str]] = None,
+#     metadata: Optional[dict] = None
+# ) -> List[TextContent]:
     """
     Update an existing conversation context.
 
@@ -3330,8 +4441,9 @@ async def update_context(
         logger.error(f"Error updating context: {e}")
         return [TextContent(type="text", text=f"❌ Error updating context: {str(e)}")]
 
-@mcp.tool()
-async def delete_context(context_id: str) -> List[TextContent]:
+# DEPRECATED: Use context(action="delete") instead
+# @mcp.tool()
+# async def delete_context(context_id: str) -> List[TextContent]:
     """
     Delete a conversation context.