hanzo-mcp 0.8.8__py3-none-any.whl → 0.9.0__py3-none-any.whl

hanzo_mcp/tools/common/config_tool.py

@@ -87,17 +87,11 @@ Automatically detects projects based on LLM.md files and manages .hanzo/ directo
 
         try:
             if action == "get":
-                return await self._get_config(
-                    scope, setting_path, project_name, project_path
-                )
+                return await self._get_config(scope, setting_path, project_name, project_path)
             elif action == "set":
-                return await self._set_config(
-                    scope, setting_path, value, project_name, project_path
-                )
+                return await self._set_config(scope, setting_path, value, project_name, project_path)
             elif action == "add_server":
-                return await self._add_mcp_server(
-                    server_name, server_config, scope, project_name
-                )
+                return await self._add_mcp_server(server_name, server_config, scope, project_name)
             elif action == "remove_server":
                 return await self._remove_mcp_server(server_name, scope, project_name)
             elif action == "enable_server":
@@ -158,10 +152,7 @@ Automatically detects projects based on LLM.md files and manages .hanzo/ directo
                 "agent": settings.agent.__dict__,
                 "vector_store": settings.vector_store.__dict__,
                 "hub_enabled": settings.hub_enabled,
-                "mcp_servers": {
-                    name: server.__dict__
-                    for name, server in settings.mcp_servers.items()
-                },
+                "mcp_servers": {name: server.__dict__ for name, server in settings.mcp_servers.items()},
                 "current_project": settings.current_project,
                 "projects": list(settings.projects.keys()),
             }
@@ -239,9 +230,7 @@ Automatically detects projects based on LLM.md files and manages .hanzo/ directo
         else:
             return f"Error: MCP server '{server_name}' already exists"
 
-    async def _remove_mcp_server(
-        self, server_name: Optional[str], scope: str, project_name: Optional[str]
-    ) -> str:
+    async def _remove_mcp_server(self, server_name: Optional[str], scope: str, project_name: Optional[str]) -> str:
         """Remove an MCP server."""
         if not server_name:
             return "Error: server_name is required"
@@ -254,9 +243,7 @@ Automatically detects projects based on LLM.md files and manages .hanzo/ directo
         else:
             return f"Error: MCP server '{server_name}' not found"
 
-    async def _enable_mcp_server(
-        self, server_name: Optional[str], scope: str, project_name: Optional[str]
-    ) -> str:
+    async def _enable_mcp_server(self, server_name: Optional[str], scope: str, project_name: Optional[str]) -> str:
         """Enable an MCP server."""
         if not server_name:
             return "Error: server_name is required"
@@ -269,9 +256,7 @@ Automatically detects projects based on LLM.md files and manages .hanzo/ directo
         else:
             return f"Error: MCP server '{server_name}' not found"
 
-    async def _disable_mcp_server(
-        self, server_name: Optional[str], scope: str, project_name: Optional[str]
-    ) -> str:
+    async def _disable_mcp_server(self, server_name: Optional[str], scope: str, project_name: Optional[str]) -> str:
         """Disable an MCP server."""
         if not server_name:
             return "Error: server_name is required"
@@ -297,9 +282,7 @@ Automatically detects projects based on LLM.md files and manages .hanzo/ directo
         else:
             return f"Error: MCP server '{server_name}' not found"
 
-    async def _add_project(
-        self, project_name: Optional[str], project_path: Optional[str]
-    ) -> str:
+    async def _add_project(self, project_name: Optional[str], project_path: Optional[str]) -> str:
         """Add a project configuration."""
         if not project_path:
             return "Error: project_path is required"
@@ -325,9 +308,7 @@ Automatically detects projects based on LLM.md files and manages .hanzo/ directo
         else:
             return f"Error: Project '{project_name}' already exists"
 
-    async def _set_current_project(
-        self, project_name: Optional[str], project_path: Optional[str]
-    ) -> str:
+    async def _set_current_project(self, project_name: Optional[str], project_path: Optional[str]) -> str:
         """Set the current active project."""
         settings = load_settings()
 

hanzo_mcp/tools/common/context.py

@@ -67,9 +67,7 @@ class ToolContext:
         """
         return self._mcp_context.client_id
 
-    async def set_tool_info(
-        self, tool_name: str, execution_id: str | None = None
-    ) -> None:
+    async def set_tool_info(self, tool_name: str, execution_id: str | None = None) -> None:
         """Set information about the currently executing tool.
 
         Args:

hanzo_mcp/tools/common/critic_tool.py

@@ -153,9 +153,7 @@ Recommendations:
 
         # Validate required analysis parameter
         if not analysis:
-            await tool_ctx.error(
-                "Parameter 'analysis' is required but was None or empty"
-            )
+            await tool_ctx.error("Parameter 'analysis' is required but was None or empty")
             return "Error: Parameter 'analysis' is required but was None or empty"
 
         if analysis.strip() == "":

hanzo_mcp/tools/common/decorators.py

@@ -120,9 +120,7 @@ def _is_valid_context(ctx: Any) -> bool:
     )
 
 
-def mcp_tool(
-    server: Any, name: str | None = None, description: str | None = None
-) -> Callable[[F], F]:
+def mcp_tool(server: Any, name: str | None = None, description: str | None = None) -> Callable[[F], F]:
     """Enhanced MCP tool decorator that includes context normalization.
 
     This decorator combines the standard MCP tool registration with
@@ -192,9 +190,7 @@ def create_tool_handler(server: Any, tool: Any) -> Callable[[], None]:
                 # Apply context normalization
                 normalized = with_context_normalization(func)
                 # Apply original decorator
-                return original_tool_decorator(name=name, description=description)(
-                    normalized
-                )
+                return original_tool_decorator(name=name, description=description)(normalized)
 
             return decorator
 

hanzo_mcp/tools/common/enhanced_base.py

@@ -85,9 +85,7 @@ class AutoRegisterTool(BaseTool, ABC):
         params = list(sig.parameters.items())
 
         # Skip 'self' and 'ctx' parameters
-        tool_params = [
-            (name, param) for name, param in params if name not in ("self", "ctx")
-        ]
+        tool_params = [(name, param) for name, param in params if name not in ("self", "ctx")]
 
         # Create the handler function dynamically
         async def handler(ctx: MCPContext, **kwargs: Any) -> Any:
@@ -98,6 +96,4 @@ class AutoRegisterTool(BaseTool, ABC):
         normalized_handler = with_context_normalization(handler)
 
         # Register with the server
-        mcp_server.tool(name=self.name, description=self.description)(
-            normalized_handler
-        )
+        mcp_server.tool(name=self.name, description=self.description)(normalized_handler)

hanzo_mcp/tools/common/fastmcp_pagination.py

@@ -143,9 +143,7 @@ class FastMCPPaginator(Generic[T]):
         cursor_data = CursorData.from_cursor(cursor) if cursor else CursorData()
 
         # Use provided page size or default
-        actual_page_size = min(
-            page_size or cursor_data.page_size or self.page_size, self.max_page_size
-        )
+        actual_page_size = min(page_size or cursor_data.page_size or self.page_size, self.max_page_size)
 
         # Get starting position
         start_idx = cursor_data.offset
@@ -207,9 +205,7 @@ class FastMCPPaginator(Generic[T]):
         cursor_data = CursorData.from_cursor(cursor) if cursor else CursorData()
 
         # Determine page size
-        limit = min(
-            page_size or cursor_data.page_size or self.page_size, self.max_page_size
-        )
+        limit = min(page_size or cursor_data.page_size or self.page_size, self.max_page_size)
 
         # Execute query with cursor position
         results = query_func(
@@ -258,9 +254,7 @@ class TokenAwarePaginator:
         self.max_tokens = max_tokens
         self.paginator = FastMCPPaginator()
 
-    def paginate_by_tokens(
-        self, items: List[Any], cursor: Optional[str] = None, estimate_func=None
-    ) -> Dict[str, Any]:
+    def paginate_by_tokens(self, items: List[Any], cursor: Optional[str] = None, estimate_func=None) -> Dict[str, Any]:
         """Paginate items based on token count.
 
         Args:
@@ -275,9 +269,7 @@ class TokenAwarePaginator:
 
         # Default token estimation
         if not estimate_func:
-            estimate_func = lambda x: estimate_tokens(
-                json.dumps(x) if not isinstance(x, str) else x
-            )
+            estimate_func = lambda x: estimate_tokens(json.dumps(x) if not isinstance(x, str) else x)
 
         # Parse cursor
         cursor_data = CursorData.from_cursor(cursor) if cursor else CursorData()

hanzo_mcp/tools/common/forgiving_edit.py

@@ -42,9 +42,7 @@ class ForgivingEditHelper:
         return "\n".join(lines)
 
     @staticmethod
-    def find_fuzzy_match(
-        haystack: str, needle: str, threshold: float = 0.85
-    ) -> Optional[Tuple[int, int, str]]:
+    def find_fuzzy_match(haystack: str, needle: str, threshold: float = 0.85) -> Optional[Tuple[int, int, str]]:
         """Find a fuzzy match for the needle in the haystack.
 
         Args:
@@ -81,13 +79,9 @@ class ForgivingEditHelper:
 
             # Find end position by counting lines in needle
             needle_lines = norm_needle.count("\n") + 1
-            end_pos = sum(
-                len(line) + 1 for line in original_lines[: lines_before + needle_lines]
-            )
+            end_pos = sum(len(line) + 1 for line in original_lines[: lines_before + needle_lines])
 
-            matched = "\n".join(
-                original_lines[lines_before : lines_before + needle_lines]
-            )
+            matched = "\n".join(original_lines[lines_before : lines_before + needle_lines])
             return (start_pos, end_pos - 1, matched)
 
         # Try fuzzy matching on lines
@@ -119,9 +113,7 @@ class ForgivingEditHelper:
                 candidate_norm = ForgivingEditHelper.normalize_whitespace(candidate)
                 needle_norm = ForgivingEditHelper.normalize_whitespace(needle)
 
-                ratio = difflib.SequenceMatcher(
-                    None, candidate_norm, needle_norm
-                ).ratio()
+                ratio = difflib.SequenceMatcher(None, candidate_norm, needle_norm).ratio()
 
                 if ratio >= threshold:
                     start_pos = sum(len(l) + 1 for l in haystack_lines[:i])
@@ -130,9 +122,7 @@ class ForgivingEditHelper:
         return None
 
     @staticmethod
-    def suggest_matches(
-        haystack: str, needle: str, max_suggestions: int = 3
-    ) -> List[Tuple[float, str]]:
+    def suggest_matches(haystack: str, needle: str, max_suggestions: int = 3) -> List[Tuple[float, str]]:
         """Suggest possible matches when exact match fails.
 
         Args:
@@ -154,9 +144,7 @@ class ForgivingEditHelper:
             for line in haystack.split("\n"):
                 if line.strip():  # Skip empty lines
                     line_norm = ForgivingEditHelper.normalize_whitespace(line)
-                    ratio = difflib.SequenceMatcher(
-                        None, line_norm, needle_norm
-                    ).ratio()
+                    ratio = difflib.SequenceMatcher(None, line_norm, needle_norm).ratio()
                     if ratio > 0.5:  # Only reasonably similar lines
                         suggestions.append((ratio, line))
 
@@ -170,9 +158,7 @@ class ForgivingEditHelper:
                 candidate = "\n".join(candidate_lines)
                 candidate_norm = ForgivingEditHelper.normalize_whitespace(candidate)
 
-                ratio = difflib.SequenceMatcher(
-                    None, candidate_norm, needle_norm
-                ).ratio()
+                ratio = difflib.SequenceMatcher(None, candidate_norm, needle_norm).ratio()
                 if ratio > 0.5:
                     suggestions.append((ratio, candidate))
 
@@ -181,9 +167,7 @@ class ForgivingEditHelper:
         return suggestions[:max_suggestions]
 
     @staticmethod
-    def create_edit_suggestion(
-        file_content: str, old_string: str, new_string: str
-    ) -> dict:
+    def create_edit_suggestion(file_content: str, old_string: str, new_string: str) -> dict:
         """Create a helpful edit suggestion when match fails.
 
         Args:
@@ -212,10 +196,7 @@ class ForgivingEditHelper:
         if suggestions:
             return {
                 "error": "Could not find exact or fuzzy match",
-                "suggestions": [
-                    {"similarity": f"{score:.0%}", "text": text}
-                    for score, text in suggestions
-                ],
+                "suggestions": [{"similarity": f"{score:.0%}", "text": text} for score, text in suggestions],
                 "hint": "Try using one of these suggestions as old_string",
             }
 

hanzo_mcp/tools/common/mode.py

@@ -94,11 +94,7 @@ def register_default_modes():
 def get_mode_from_env() -> Optional[str]:
     """Get mode name from environment variables."""
     # Check for HANZO_MODE, PERSONALITY, or MODE env vars
-    return (
-        os.environ.get("HANZO_MODE")
-        or os.environ.get("PERSONALITY")
-        or os.environ.get("MODE")
-    )
+    return os.environ.get("HANZO_MODE") or os.environ.get("PERSONALITY") or os.environ.get("MODE")
 
 
 def activate_mode_from_env():

hanzo_mcp/tools/common/paginated_base.py

@@ -68,11 +68,7 @@ class PaginatedBaseTool(BaseTool):
         if cursor:
             # For continuation, check if we have cached results
             cursor_data = CursorManager.parse_cursor(cursor)
-            if (
-                cursor_data
-                and "tool" in cursor_data
-                and cursor_data["tool"] != self.name
-            ):
+            if cursor_data and "tool" in cursor_data and cursor_data["tool"] != self.name:
                 return {"error": "Cursor is for a different tool", "code": -32602}
 
         # Execute the tool
@@ -90,15 +86,11 @@ class PaginatedBaseTool(BaseTool):
             if isinstance(paginated_result, dict) and "nextCursor" in paginated_result:
                 # Enhance the cursor with tool information
                 if "nextCursor" in paginated_result:
-                    cursor_data = CursorManager.parse_cursor(
-                        paginated_result["nextCursor"]
-                    )
+                    cursor_data = CursorManager.parse_cursor(paginated_result["nextCursor"])
                     if cursor_data:
                         cursor_data["tool"] = self.name
                         cursor_data["params"] = params  # Store params for continuation
-                        paginated_result["nextCursor"] = CursorManager.create_cursor(
-                            cursor_data
-                        )
+                        paginated_result["nextCursor"] = CursorManager.create_cursor(cursor_data)
 
             return paginated_result
         else:

hanzo_mcp/tools/common/paginated_response.py

@@ -35,31 +35,21 @@ class AutoPaginatedResponse:
         """
         # Handle different content types
         if isinstance(content, str):
-            return AutoPaginatedResponse._handle_string_response(
-                content, cursor, max_tokens
-            )
+            return AutoPaginatedResponse._handle_string_response(content, cursor, max_tokens)
         elif isinstance(content, list):
-            return AutoPaginatedResponse._handle_list_response(
-                content, cursor, max_tokens
-            )
+            return AutoPaginatedResponse._handle_list_response(content, cursor, max_tokens)
         elif isinstance(content, dict):
             # If dict already has pagination info, return as-is
             if "nextCursor" in content or "cursor" in content:
                 return content
             # Otherwise treat as single item
-            return AutoPaginatedResponse._handle_dict_response(
-                content, cursor, max_tokens
-            )
+            return AutoPaginatedResponse._handle_dict_response(content, cursor, max_tokens)
         else:
             # Convert to string for other types
-            return AutoPaginatedResponse._handle_string_response(
-                str(content), cursor, max_tokens
-            )
+            return AutoPaginatedResponse._handle_string_response(str(content), cursor, max_tokens)
 
     @staticmethod
-    def _handle_string_response(
-        content: str, cursor: Optional[str], max_tokens: int
-    ) -> Dict[str, Any]:
+    def _handle_string_response(content: str, cursor: Optional[str], max_tokens: int) -> Dict[str, Any]:
         """Handle pagination for string responses."""
         # Parse cursor to get offset
         offset = 0
@@ -124,9 +114,7 @@ class AutoPaginatedResponse:
         return response
 
     @staticmethod
-    def _handle_list_response(
-        items: List[Any], cursor: Optional[str], max_tokens: int
-    ) -> Dict[str, Any]:
+    def _handle_list_response(items: List[Any], cursor: Optional[str], max_tokens: int) -> Dict[str, Any]:
         """Handle pagination for list responses."""
         # Parse cursor to get offset
         offset = 0
@@ -164,9 +152,7 @@ class AutoPaginatedResponse:
                         truncated = item[:5000] + "... [truncated]"
                         result_items.append(truncated)
                     else:
-                        result_items.append(
-                            {"error": "Item too large", "index": item_index}
-                        )
+                        result_items.append({"error": "Item too large", "index": item_index})
                     item_index += 1
                 break
 
@@ -199,9 +185,7 @@ class AutoPaginatedResponse:
         return response
 
     @staticmethod
-    def _handle_dict_response(
-        content: Dict[str, Any], cursor: Optional[str], max_tokens: int
-    ) -> Dict[str, Any]:
+    def _handle_dict_response(content: Dict[str, Any], cursor: Optional[str], max_tokens: int) -> Dict[str, Any]:
         """Handle pagination for dict responses."""
         # For dicts, check if it's too large as-is
         content_str = json.dumps(content, indent=2)
@@ -280,17 +264,13 @@ def paginate_if_needed(
         Original response if small enough, otherwise paginated dict
     """
     # Quick check - if response is already paginated, return as-is
-    if isinstance(response, dict) and (
-        "nextCursor" in response or "pagination_info" in response
-    ):
+    if isinstance(response, dict) and ("nextCursor" in response or "pagination_info" in response):
         return response
 
     # For small responses, don't paginate unless forced
     if not force_pagination:
         try:
-            response_str = (
-                json.dumps(response) if not isinstance(response, str) else response
-            )
+            response_str = json.dumps(response) if not isinstance(response, str) else response
             if len(response_str) < 10000:  # Quick heuristic
                 return response
         except Exception:

hanzo_mcp/tools/common/pagination.py

@@ -154,9 +154,7 @@ class StreamPaginator(Generic[T]):
         """
         self.page_size = page_size
 
-    def paginate_stream(
-        self, stream_generator, cursor: Optional[str] = None
-    ) -> PaginatedResponse[T]:
+    def paginate_stream(self, stream_generator, cursor: Optional[str] = None) -> PaginatedResponse[T]:
         """Paginate results from a stream/generator.
 
         Args:
@@ -185,18 +183,14 @@ class StreamPaginator(Generic[T]):
             items.append(item)
             if len(items) >= self.page_size:
                 # We have a full page, create cursor for next page
-                next_cursor = CursorManager.create_cursor(
-                    {"skip": skip_count + len(items)}
-                )
+                next_cursor = CursorManager.create_cursor({"skip": skip_count + len(items)})
                 return PaginatedResponse(items=items, next_cursor=next_cursor)
 
         # No more items
         return PaginatedResponse(items=items, next_cursor=None)
 
 
-def paginate_list(
-    items: List[T], cursor: Optional[str] = None, page_size: int = 100
-) -> PaginatedResponse[T]:
+def paginate_list(items: List[T], cursor: Optional[str] = None, page_size: int = 100) -> PaginatedResponse[T]:
     """Convenience function to paginate a list.
 
     Args:

hanzo_mcp/tools/common/path_utils.py

@@ -0,0 +1,34 @@
+"""Path utility functions for consistent path handling across MCP tools."""
+
+import os
+from pathlib import Path
+
+
+def resolve_path(path: str) -> str:
+    """Resolve a path by expanding user home directory (~) and environment variables.
+    
+    This is the centralized path resolution function used by all filesystem tools
+    to ensure consistent path handling across the MCP system.
+    
+    Args:
+        path: The path to resolve, may contain ~ or environment variables
+        
+    Returns:
+        The fully resolved absolute path
+        
+    Examples:
+        >>> resolve_path('~/Documents/file.txt')
+        '/Users/username/Documents/file.txt'
+        
+        >>> os.environ['MYDIR'] = '/tmp/test'
+        >>> resolve_path('$MYDIR/file.txt')
+        '/tmp/test/file.txt'
+    """
+    # First expand environment variables, then user home directory
+    # This order is important for cases like $HOME_ALIAS where the env var contains ~
+    expanded = os.path.expandvars(path)
+    expanded = os.path.expanduser(expanded)
+    
+    # Convert to Path object and resolve to get absolute path
+    # This handles relative paths and resolves symlinks
+    return str(Path(expanded).resolve())

hanzo_mcp/tools/common/permissions.py

@@ -8,6 +8,9 @@ from typing import Any, TypeVar, final
 from pathlib import Path
 from collections.abc import Callable, Awaitable
 
+# Import centralized path resolution
+from hanzo_mcp.tools.common.path_utils import resolve_path
+
 # Define type variables for better type annotations
 T = TypeVar("T")
 P = TypeVar("P")
@@ -81,7 +84,8 @@ class PermissionManager:
         Args:
             path: The path to allow
         """
-        resolved_path: Path = Path(path).resolve()
+        # Use centralized path resolution
+        resolved_path = Path(resolve_path(path))
         self.allowed_paths.add(resolved_path)
 
     def remove_allowed_path(self, path: str) -> None:
@@ -90,7 +94,8 @@ class PermissionManager:
         Args:
             path: The path to remove
         """
-        resolved_path: Path = Path(path).resolve()
+        # Use centralized path resolution
+        resolved_path = Path(resolve_path(path))
         if resolved_path in self.allowed_paths:
             self.allowed_paths.remove(resolved_path)
 
@@ -100,7 +105,8 @@ class PermissionManager:
         Args:
             path: The path to exclude
         """
-        resolved_path: Path = Path(path).resolve()
+        # Use centralized path resolution
+        resolved_path = Path(resolve_path(path))
         self.excluded_paths.add(resolved_path)
 
     def add_exclusion_pattern(self, pattern: str) -> None:
@@ -120,7 +126,8 @@ class PermissionManager:
         Returns:
             True if the path is allowed, False otherwise
         """
-        resolved_path: Path = Path(path).resolve()
+        # Use centralized path resolution
+        resolved_path = Path(resolve_path(path))
 
         # Check exclusions first
         if self._is_path_excluded(resolved_path):
@@ -225,13 +232,9 @@ class PermissibleOperation:
         """
         self.permission_manager: PermissionManager = permission_manager
         self.operation: str = operation
-        self.get_path_fn: Callable[[list[Any], dict[str, Any]], str] | None = (
-            get_path_fn
-        )
+        self.get_path_fn: Callable[[list[Any], dict[str, Any]], str] | None = get_path_fn
 
-    def __call__(
-        self, func: Callable[..., Awaitable[T]]
-    ) -> Callable[..., Awaitable[T]]:
+    def __call__(self, func: Callable[..., Awaitable[T]]) -> Callable[..., Awaitable[T]]:
         """Decorate the function.
 
         Args:
@@ -255,9 +258,7 @@ class PermissibleOperation:
 
             # Check permission
             if not self.permission_manager.is_path_allowed(path):
-                raise PermissionError(
-                    f"Operation '{self.operation}' not allowed for path: {path}"
-                )
+                raise PermissionError(f"Operation '{self.operation}' not allowed for path: {path}")
 
             # Call the function
             return await func(*args, **kwargs)