xcode-mcp-server 1.0.4__py3-none-any.whl → 1.0.6__py3-none-any.whl

xcode_mcp_server/__init__.py

@@ -1,18 +1,80 @@
 """Xcode MCP Server - Model Context Protocol server for Xcode integration"""
 
+__version__ = "1.0.6"
+
 def main():
     """Entry point for the xcode-mcp-server command"""
     import sys
+    import os
+    import argparse
+    import subprocess
     from . import __main__
     
-    # Initialize allowed folders
-    __main__.ALLOWED_FOLDERS = __main__.get_allowed_folders()
+    # Parse command line arguments
+    parser = argparse.ArgumentParser(description="Xcode MCP Server")
+    parser.add_argument("--version", action="version", version=f"xcode-mcp-server {__version__}")
+    parser.add_argument("--allowed", action="append", help="Add an allowed folder path (can be used multiple times)")
+    parser.add_argument("--show-notifications", action="store_true", help="Enable notifications for tool invocations")
+    parser.add_argument("--hide-notifications", action="store_true", help="Disable notifications for tool invocations")
+    args = parser.parse_args()
+    
+    # Handle notification settings
+    if args.show_notifications and args.hide_notifications:
+        print("Error: Cannot use both --show-notifications and --hide-notifications", file=sys.stderr)
+        sys.exit(1)
+    elif args.show_notifications:
+        __main__.NOTIFICATIONS_ENABLED = True
+        print("Notifications enabled", file=sys.stderr)
+    elif args.hide_notifications:
+        __main__.NOTIFICATIONS_ENABLED = False
+        print("Notifications disabled", file=sys.stderr)
+    
+    # Initialize allowed folders from environment and command line
+    __main__.ALLOWED_FOLDERS = __main__.get_allowed_folders(args.allowed)
+    
+    # Check if we have any allowed folders
+    if not __main__.ALLOWED_FOLDERS:
+        error_msg = """
+========================================================================
+ERROR: Xcode MCP Server cannot start - No valid allowed folders!
+========================================================================
+
+No valid folders were found to allow access to.
+
+To fix this, you can either:
+
+1. Set the XCODEMCP_ALLOWED_FOLDERS environment variable:
+   export XCODEMCP_ALLOWED_FOLDERS="/path/to/folder1:/path/to/folder2"
+
+2. Use the --allowed command line option:
+   xcode-mcp-server --allowed /path/to/folder1 --allowed /path/to/folder2
+
+3. Ensure your $HOME directory exists and is accessible
+
+All specified folders must:
+- Be absolute paths
+- Exist on the filesystem
+- Be directories (not files)
+- Not contain '..' components
+
+========================================================================
+"""
+        print(error_msg, file=sys.stderr)
+        
+        # Show macOS notification
+        try:
+            subprocess.run(['osascript', '-e', 
+                          'display alert "Xcode MCP Server Error" message "No valid allowed folders found. Check your configuration."'], 
+                          capture_output=True)
+        except:
+            pass  # Ignore notification errors
+        
+        sys.exit(1)
     
     # Debug info
-    print(f"Allowed folders: {__main__.ALLOWED_FOLDERS}", file=sys.stderr)
+    print(f"Total allowed folders: {__main__.ALLOWED_FOLDERS}", file=sys.stderr)
     
     # Run the server
     __main__.mcp.run()
 
-__version__ = "1.0.4"
-__all__ = ["main"]
+__all__ = ["main", "__version__"]

xcode_mcp_server/__main__.py

@@ -3,6 +3,7 @@ import os
 import sys
 import subprocess
 import json
+import argparse
 from typing import Optional, Dict, List, Any, Tuple, Set
 from dataclasses import dataclass
 
@@ -10,6 +11,7 @@ from mcp.server.fastmcp import FastMCP, Context
 
 # Global variables for allowed folders
 ALLOWED_FOLDERS: Set[str] = set()
+NOTIFICATIONS_ENABLED = False  # No type annotation to avoid global declaration issues
 
 class XCodeMCPError(Exception):
     def __init__(self, message, code=None):
@@ -23,28 +25,42 @@ class AccessDeniedError(XCodeMCPError):
 class InvalidParameterError(XCodeMCPError):
     pass
 
-def get_allowed_folders() -> Set[str]:
+def get_allowed_folders(command_line_folders: Optional[List[str]] = None) -> Set[str]:
     """
-    Get the allowed folders from environment variable.
+    Get the allowed folders from environment variable and command line.
     Validates that paths are absolute, exist, and are directories.
+    
+    Args:
+        command_line_folders: List of folders provided via command line
+        
+    Returns:
+        Set of validated folder paths
     """
     allowed_folders = set()
+    folders_to_process = []
     
     # Get from environment variable
     folder_list_str = os.environ.get("XCODEMCP_ALLOWED_FOLDERS")
     
     if folder_list_str:
         print(f"Using allowed folders from environment: {folder_list_str}", file=sys.stderr)
-    else:
-        print("Warning: Allowed folders was not specified.", file=sys.stderr)
-        print("Set XCODEMCP_ALLOWED_FOLDERS environment variable to a colon-separated list of allowed folders.", file=sys.stderr)
+        folders_to_process.extend(folder_list_str.split(":"))
+    
+    # Add command line folders
+    if command_line_folders:
+        print(f"Adding {len(command_line_folders)} folder(s) from command line", file=sys.stderr)
+        folders_to_process.extend(command_line_folders)
+    
+    # If no folders specified, use $HOME
+    if not folders_to_process:
+        print("Warning: No allowed folders specified via environment or command line.", file=sys.stderr)
+        print("Set XCODEMCP_ALLOWED_FOLDERS environment variable or use --allowed flag.", file=sys.stderr)
         home = os.environ.get("HOME", "/")
-        print(f"Trying $HOME, {home}", file=sys.stderr)
-        folder_list_str = home
+        print(f"Using default: $HOME = {home}", file=sys.stderr)
+        folders_to_process = [home]
 
-    # Process the list
-    folder_list = folder_list_str.split(":")
-    for folder in folder_list:
+    # Process all folders
+    for folder in folders_to_process:
         folder = folder.rstrip("/")  # Normalize by removing trailing slash
         
         # Skip empty entries
@@ -90,11 +106,8 @@ def is_path_allowed(project_path: str) -> bool:
     
     # If no allowed folders are specified, nothing is allowed
     if not ALLOWED_FOLDERS:
-        # try to fetch folder list
-        ALLOWED_FOLDERS = get_allowed_folders()
-        if not ALLOWED_FOLDERS:
-            print(f"Warning: not ALLOWED_FOLDERS: {', '.join(ALLOWED_FOLDERS)}", file=sys.stderr)
-            return False
+        print(f"Warning: ALLOWED_FOLDERS is empty, denying access", file=sys.stderr)
+        return False
     
     # Normalize the path
     project_path = os.path.abspath(project_path).rstrip("/")
@@ -115,7 +128,31 @@ def is_path_allowed(project_path: str) -> bool:
     return False
 
 # Initialize the MCP server
-mcp = FastMCP("Xcode MCP Server")
+mcp = FastMCP("Xcode MCP Server",
+    instructions="""
+        This server provides access to the Xcode IDE. For any project intended
+        for Apple platforms, such as iOS or macOS, this MCP server is the best
+        way to build or run .xcodeproj or .xcworkspace Xcode projects, and should
+        always be preferred over using `xcodebuild`, `swift build`, or
+        `swift package build`. Building with this tool ensures the build happens
+        exactly the same way as when the user builds with Xcode, with all the same
+        settings, so you will get the same results the user sees. The user can also
+        see any results immediately and a subsequent build and run by the user will
+        happen almost instantly for the user.
+
+        You might start with `get_frontmost_project` to see if the user currently
+        has an Xcode project already open.
+
+        You can call `get_xcode_projects` to find Xcode project (.xcodeproj) and
+        Xcode workspace (.xcworkspace) folders under a given root folder.
+
+        You can call `get_project_schemes` to get the build scheme names for a given
+        .xcodeproj or .xcworkspace.
+
+        Call build_project to build the project and get back the first 25 lines of
+        error output. `build_project` will default to the active scheme if none is provided.
+    """
+)
 
 # Helper functions for Xcode interaction
 def get_frontmost_project() -> str:
@@ -171,62 +208,91 @@ def run_applescript(script: str) -> Tuple[bool, str]:
     except subprocess.CalledProcessError as e:
         return False, e.stderr.strip()
 
+def show_notification(title: str, message: str):
+    """Show a macOS notification if notifications are enabled"""
+    if NOTIFICATIONS_ENABLED:
+        try:
+            subprocess.run(['osascript', '-e', 
+                          f'display notification "{message}" with title "{title}"'], 
+                          capture_output=True)
+        except:
+            pass  # Ignore notification errors
+
 # MCP Tools for Xcode
 
-# @mcp.tool()
-# def reinit_dirs() -> str:
-#     """
-#     Reinitialize the allowed folders.
-#     """
-#     global ALLOWED_FOLDERS
-#     ALLOWED_FOLDERS = get_allowed_folders()
-#     return f"Allowed folders reinitialized to: {ALLOWED_FOLDERS}"
+@mcp.tool()
+def version() -> str:
+    """
+    Get the current version of the Xcode MCP Server.
+    
+    Returns:
+        The version string of the server
+    """
+    show_notification("Xcode MCP", "Getting server version")
+    return f"Xcode MCP Server version {__import__('xcode_mcp_server').__version__}"
 
 
 @mcp.tool()
-def get_xcode_projects(search_path: str) -> str:
+def get_xcode_projects(search_path: str = "") -> str:
     """
     Search the given search_path to find .xcodeproj (Xcode project) and
      .xcworkspace (Xcode workspace) paths. If the search_path is empty,
      all paths to which this tool has been granted access are searched.
+     Searching all paths to which this tool has been granted access can
+     uses `mdfind` (Spotlight indexing) to find the relevant files, and
+     so will only return .xcodeproj and .xcworkspace folders that are
+     indexed.
     
     Args:
-        search_path: Path to searched.
+        search_path: Path to search. If empty, searches all allowed folders.
         
     Returns:
         A string which is a newline-separated list of .xcodeproj and
         .xcworkspace paths found. If none are found, returns an empty string.
     """
-
-
-    project_path = search_path
-
-    # Validate input
-    if not search_path or search_path.strip() == "":
-        project_path = "/Users/andrew/Documents/ncc_source"
-        # return "Error: project_path cannot be empty"
-
+    global ALLOWED_FOLDERS
     
-    # Security check
-    if not is_path_allowed(project_path):
-        raise AccessDeniedError(f"Access to path '{project_path}' is not allowed. Set XCODEMCP_ALLOWED_FOLDERS environment variable.")
-        # return f"Error: Access to path '{project_path}' is not allowed. Set XCODEMCP_ALLOWED_FOLDERS environment variable."
+    # Determine paths to search
+    paths_to_search = []
     
-    # Check if the path exists
-    if os.path.exists(project_path):
-        # Show the basic file structure
+    if not search_path or search_path.strip() == "":
+        # Search all allowed folders
+        show_notification("Xcode MCP", f"Searching all {len(ALLOWED_FOLDERS)} allowed folders for Xcode projects")
+        paths_to_search = list(ALLOWED_FOLDERS)
+    else:
+        # Search specific path
+        project_path = search_path.strip()
+        
+        # Security check
+        if not is_path_allowed(project_path):
+            raise AccessDeniedError(f"Access to path '{project_path}' is not allowed. Set XCODEMCP_ALLOWED_FOLDERS environment variable.")
+        
+        # Check if the path exists
+        if not os.path.exists(project_path):
+            raise InvalidParameterError(f"Project path does not exist: {project_path}")
+            
+        show_notification("Xcode MCP", f"Searching {project_path} for Xcode projects")
+        paths_to_search = [project_path]
+    
+    # Search for projects in all paths
+    all_results = []
+    for path in paths_to_search:
         try:
-            #mdfind -onlyin /Users/andrew/Documents/ncc_source/cursor 'kMDItemFSName == "*.xcodeproj" || kMDItemFSName == "*.xcworkspace"' 
-            mdfindResult = subprocess.run(['mdfind', '-onlyin', project_path, 'kMDItemFSName == "*.xcodeproj" || kMDItemFSName == "*.xcworkspace"'], 
-                                   capture_output=True, text=True, check=True)
+            # Use mdfind to search for Xcode projects
+            mdfindResult = subprocess.run(['mdfind', '-onlyin', path, 
+                                         'kMDItemFSName == "*.xcodeproj" || kMDItemFSName == "*.xcworkspace"'], 
+                                         capture_output=True, text=True, check=True)
             result = mdfindResult.stdout.strip()
-            return result
+            if result:
+                all_results.extend(result.split('\n'))
         except Exception as e:
-            raise XCodeMCPError(f"Error listing files in {project_path}: {str(e)}")
-            # return f"Error listing files in {project_path}: {str(e)}"
-    else:
-        raise InvalidParameterError(f"Project path does not exist: {project_path}")
-        # return f"Project path does not exist: {project_path}"
+            print(f"Warning: Error searching in {path}: {str(e)}", file=sys.stderr)
+            continue
+    
+    # Remove duplicates and sort
+    unique_results = sorted(set(all_results))
+    
+    return '\n'.join(unique_results) if unique_results else ""
 
 
 @mcp.tool()
@@ -235,7 +301,8 @@ def get_project_hierarchy(project_path: str) -> str:
     Get the hierarchy of the specified Xcode project or workspace.
     
     Args:
-        project_path: Path to an Xcode project/workspace directory.
+        project_path: Path to an Xcode project/workspace directory, which must
+        end in '.xcodeproj' or '.xcworkspace' and must exist.
         
     Returns:
         A string representation of the project hierarchy
@@ -243,41 +310,178 @@ def get_project_hierarchy(project_path: str) -> str:
     # Validate input
     if not project_path or project_path.strip() == "":
         raise InvalidParameterError("project_path cannot be empty")
-        # return "Error: project_path cannot be empty"
+    
+    project_path = project_path.strip()
+    
+    # Verify path ends with .xcodeproj or .xcworkspace
+    if not (project_path.endswith('.xcodeproj') or project_path.endswith('.xcworkspace')):
+        raise InvalidParameterError("project_path must end with '.xcodeproj' or '.xcworkspace'")
+    
+    show_notification("Xcode MCP", f"Getting hierarchy for {os.path.basename(project_path)}")
     
     # Security check
     if not is_path_allowed(project_path):
         raise AccessDeniedError(f"Access to path '{project_path}' is not allowed. Set XCODEMCP_ALLOWED_FOLDERS environment variable.")
-        # return f"Error: Access to path '{project_path}' is not allowed. Set XCODEMCP_ALLOWED_FOLDERS environment variable."
     
     # Check if the path exists
-    if os.path.exists(project_path):
-        # Show the basic file structure
-        try:
-            result = subprocess.run(['find', project_path, '-type', 'f', '-name', '*.swift', '-o', '-name', '*.h', '-o', '-name', '*.m'], 
-                                   capture_output=True, text=True, check=True)
-            files = result.stdout.strip().split('\n')
-            if not files or (len(files) == 1 and files[0] == ''):
-                raise InvalidParameterError(f"No source files found in {project_path}")
-                # return f"No source files found in {project_path}"
+    if not os.path.exists(project_path):
+        raise InvalidParameterError(f"Project path does not exist: {project_path}")
+    
+    # Get the parent directory to scan
+    parent_dir = os.path.dirname(project_path)
+    project_name = os.path.basename(project_path)
+    
+    # Build the hierarchy
+    def build_hierarchy(path: str, prefix: str = "", is_last: bool = True, base_path: str = "") -> List[str]:
+        """Recursively build a visual hierarchy of files and folders"""
+        lines = []
+        
+        if not base_path:
+            base_path = path
             
-            return f"Project at {project_path} contains {len(files)} source files:\n" + '\n'.join(files)
-        except Exception as e:
-            raise XCodeMCPError(f"Error listing files in {project_path}: {str(e)}")
-            # return f"Error listing files in {project_path}: {str(e)}"
-    else:
+        # Get relative path for display
+        rel_path = os.path.relpath(path, os.path.dirname(base_path))
+        
+        # Add current item
+        if path != base_path:
+            connector = "└── " if is_last else "├── "
+            name = os.path.basename(path)
+            if os.path.isdir(path):
+                name += "/"
+            lines.append(prefix + connector + name)
+            
+            # Update prefix for children
+            extension = "    " if is_last else "│   "
+            prefix = prefix + extension
+        
+        # If it's a directory, recurse into it (with restrictions)
+        if os.path.isdir(path):
+            # Skip certain directories
+            if os.path.basename(path) in ['.build', 'build']:
+                return lines
+                
+            # Don't recurse into .xcodeproj or .xcworkspace directories
+            if path.endswith('.xcodeproj') or path.endswith('.xcworkspace'):
+                return lines
+            
+            try:
+                items = sorted(os.listdir(path))
+                # Filter out hidden files except for important ones
+                items = [item for item in items if not item.startswith('.') or item in ['.gitignore', '.swift-version']]
+                
+                for i, item in enumerate(items):
+                    item_path = os.path.join(path, item)
+                    is_last_item = (i == len(items) - 1)
+                    lines.extend(build_hierarchy(item_path, prefix, is_last_item, base_path))
+            except PermissionError:
+                pass
+                
+        return lines
+    
+    # Build hierarchy starting from parent directory
+    hierarchy_lines = [parent_dir + "/"]
+    
+    try:
+        items = sorted(os.listdir(parent_dir))
+        # Filter out hidden files and build directories
+        items = [item for item in items if not item.startswith('.') or item in ['.gitignore', '.swift-version']]
+        
+        for i, item in enumerate(items):
+            item_path = os.path.join(parent_dir, item)
+            is_last_item = (i == len(items) - 1)
+            hierarchy_lines.extend(build_hierarchy(item_path, "", is_last_item, parent_dir))
+            
+    except Exception as e:
+        raise XCodeMCPError(f"Error building hierarchy for {project_path}: {str(e)}")
+    
+    return '\n'.join(hierarchy_lines)
+
+@mcp.tool()
+def get_project_schemes(project_path: str) -> str:
+    """
+    Get the available build schemes for the specified Xcode project or workspace.
+    
+    Args:
+        project_path: Path to an Xcode project/workspace directory, which must
+        end in '.xcodeproj' or '.xcworkspace' and must exist.
+        
+    Returns:
+        A newline-separated list of scheme names, with the active scheme listed first.
+        If no schemes are found, returns an empty string.
+    """
+    # Validate input
+    if not project_path or project_path.strip() == "":
+        raise InvalidParameterError("project_path cannot be empty")
+    
+    project_path = project_path.strip()
+    
+    # Verify path ends with .xcodeproj or .xcworkspace
+    if not (project_path.endswith('.xcodeproj') or project_path.endswith('.xcworkspace')):
+        raise InvalidParameterError("project_path must end with '.xcodeproj' or '.xcworkspace'")
+    
+    show_notification("Xcode MCP", f"Getting schemes for {os.path.basename(project_path)}")
+    
+    # Security check
+    if not is_path_allowed(project_path):
+        raise AccessDeniedError(f"Access to path '{project_path}' is not allowed. Set XCODEMCP_ALLOWED_FOLDERS environment variable.")
+    
+    # Check if the path exists
+    if not os.path.exists(project_path):
         raise InvalidParameterError(f"Project path does not exist: {project_path}")
-        # return f"Project path does not exist: {project_path}"
+    
+    script = f'''
+    tell application "Xcode"
+        open "{project_path}"
+        
+        set workspaceDoc to first workspace document whose path is "{project_path}"
+        
+        -- Wait for it to load
+        repeat 60 times
+            if loaded of workspaceDoc is true then exit repeat
+            delay 0.5
+        end repeat
+        
+        if loaded of workspaceDoc is false then
+            error "Xcode workspace did not load in time."
+        end if
+        
+        -- Get active scheme name
+        set activeScheme to name of active scheme of workspaceDoc
+        
+        -- Get all scheme names
+        set schemeNames to {{}}
+        repeat with aScheme in schemes of workspaceDoc
+            set end of schemeNames to name of aScheme
+        end repeat
+        
+        -- Format output with active scheme first
+        set output to activeScheme & " (active)"
+        repeat with schemeName in schemeNames
+            if schemeName as string is not equal to activeScheme then
+                set output to output & "\\n" & schemeName
+            end if
+        end repeat
+        
+        return output
+    end tell
+    '''
+    
+    success, output = run_applescript(script)
+    
+    if success:
+        return output
+    else:
+        raise XCodeMCPError(f"Failed to get schemes for {project_path}: {output}")
 
 @mcp.tool()
 def build_project(project_path: str, 
-                 scheme: str) -> str:
+                 scheme: Optional[str] = None) -> str:
     """
     Build the specified Xcode project or workspace.
     
     Args:
         project_path: Path to an Xcode project workspace or directory.
-        scheme: Name of the scheme to build.
+        scheme: Name of the scheme to build. If not provided, uses the active scheme.
         
     Returns:
         On success, returns "Build succeeded with 0 errors."
@@ -287,6 +491,15 @@ def build_project(project_path: str,
     if not project_path or project_path.strip() == "":
         raise InvalidParameterError("project_path cannot be empty")
     
+    project_path = project_path.strip()
+    
+    # Verify path ends with .xcodeproj or .xcworkspace
+    if not (project_path.endswith('.xcodeproj') or project_path.endswith('.xcworkspace')):
+        raise InvalidParameterError("project_path must end with '.xcodeproj' or '.xcworkspace'")
+    
+    scheme_desc = scheme if scheme else "active scheme"
+    show_notification("Xcode MCP", f"Building {scheme_desc} in {os.path.basename(project_path)}")
+    
     # Security check
     if not is_path_allowed(project_path):
         raise AccessDeniedError(f"Access to path '{project_path}' is not allowed. Set XCODEMCP_ALLOWED_FOLDERS environment variable.")
@@ -294,14 +507,13 @@ def build_project(project_path: str,
     if not os.path.exists(project_path):
         raise InvalidParameterError(f"Project path does not exist: {project_path}")
     
-    # TODO: Implement build command using AppleScript or shell
-    script = f'''
+    # Build the AppleScript
+    if scheme:
+        # Use provided scheme
+        script = f'''
 set projectPath to "{project_path}"
 set schemeName to "{scheme}"
 
---
--- Then run with: osascript <thisfilename>
---
 tell application "Xcode"
         -- 1. Open the project file
         open projectPath
@@ -334,13 +546,51 @@ tell application "Xcode"
         -- 7. Check result
         set buildStatus to status of actionResult
         if buildStatus is succeeded then
-                -- display dialog "Build succeeded"
                 return "Build succeeded." 
         else
                 return build log of actionResult
         end if
+end tell
+    '''
+    else:
+        # Use active scheme
+        script = f'''
+set projectPath to "{project_path}"
 
-    end tell
+tell application "Xcode"
+        -- 1. Open the project file
+        open projectPath
+
+        -- 2. Get the workspace document
+        set workspaceDoc to first workspace document whose path is projectPath
+
+        -- 3. Wait for it to load (timeout after ~30 seconds)
+        repeat 60 times
+                if loaded of workspaceDoc is true then exit repeat
+                delay 0.5
+        end repeat
+
+        if loaded of workspaceDoc is false then
+                error "Xcode workspace did not load in time."
+        end if
+
+        -- 4. Build with current active scheme
+        set actionResult to build workspaceDoc
+
+        -- 5. Wait for completion
+        repeat
+                if completed of actionResult is true then exit repeat
+                delay 0.5
+        end repeat
+
+        -- 6. Check result
+        set buildStatus to status of actionResult
+        if buildStatus is succeeded then
+                return "Build succeeded." 
+        else
+                return build log of actionResult
+        end if
+end tell
     '''
     
     success, output = run_applescript(script)
@@ -531,13 +781,71 @@ def get_runtime_output(project_path: str,
     # This is a placeholder as you mentioned this functionality isn't available yet
     raise XCodeMCPError("Runtime output retrieval not yet implemented")
 
-# Run the server if executed directly
+# Main entry point for the server
 if __name__ == "__main__":
-    # Initialize allowed folders
-    ALLOWED_FOLDERS = get_allowed_folders()
+    # Parse command line arguments
+    parser = argparse.ArgumentParser(description="Xcode MCP Server")
+    parser.add_argument("--version", action="version", version=f"xcode-mcp-server {__import__('xcode_mcp_server').__version__}")
+    parser.add_argument("--allowed", action="append", help="Add an allowed folder path (can be used multiple times)")
+    parser.add_argument("--show-notifications", action="store_true", help="Enable notifications for tool invocations")
+    parser.add_argument("--hide-notifications", action="store_true", help="Disable notifications for tool invocations")
+    args = parser.parse_args()
+    
+    # Handle notification settings
+    if args.show_notifications and args.hide_notifications:
+        print("Error: Cannot use both --show-notifications and --hide-notifications", file=sys.stderr)
+        sys.exit(1)
+    elif args.show_notifications:
+        NOTIFICATIONS_ENABLED = True
+        print("Notifications enabled", file=sys.stderr)
+    elif args.hide_notifications:
+        NOTIFICATIONS_ENABLED = False
+        print("Notifications disabled", file=sys.stderr)
+    
+    # Initialize allowed folders from environment and command line
+    ALLOWED_FOLDERS = get_allowed_folders(args.allowed)
+    
+    # Check if we have any allowed folders
+    if not ALLOWED_FOLDERS:
+        error_msg = """
+========================================================================
+ERROR: Xcode MCP Server cannot start - No valid allowed folders!
+========================================================================
+
+No valid folders were found to allow access to.
+
+To fix this, you can either:
+
+1. Set the XCODEMCP_ALLOWED_FOLDERS environment variable:
+   export XCODEMCP_ALLOWED_FOLDERS="/path/to/folder1:/path/to/folder2"
+
+2. Use the --allowed command line option:
+   xcode-mcp-server --allowed /path/to/folder1 --allowed /path/to/folder2
+
+3. Ensure your $HOME directory exists and is accessible
+
+All specified folders must:
+- Be absolute paths
+- Exist on the filesystem
+- Be directories (not files)
+- Not contain '..' components
+
+========================================================================
+"""
+        print(error_msg, file=sys.stderr)
+        
+        # Show macOS notification
+        try:
+            subprocess.run(['osascript', '-e', 
+                          'display alert "Xcode MCP Server Error" message "No valid allowed folders found. Check your configuration."'], 
+                          capture_output=True)
+        except:
+            pass  # Ignore notification errors
+        
+        sys.exit(1)
     
     # Debug info
-    print(f"Allowed folders: {ALLOWED_FOLDERS}", file=sys.stderr)
+    print(f"Total allowed folders: {ALLOWED_FOLDERS}", file=sys.stderr)
     
     # Run the server
     mcp.run() 

{xcode_mcp_server-1.0.4.dist-info → xcode_mcp_server-1.0.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xcode-mcp-server
-Version: 1.0.4
+Version: 1.0.6
 Summary: Drew's MCP server for Xcode integration
 Project-URL: Homepage, https://github.com/drewster99/xcode-mcp-server
 Project-URL: Repository, https://github.com/drewster99/xcode-mcp-server
@@ -39,6 +39,7 @@ The server implements path-based security to prevent unauthorized access to file
 
 - You must specify allowed folders using the environment variable:
   - `XCODEMCP_ALLOWED_FOLDERS=/path1:/path2:/path3`
+- Otherwise, all files and subfolders from your home directory ($HOME) will be allowed.
 
 Security requirements:
 - All paths must be absolute (starting with /)
@@ -59,47 +60,113 @@ If no allowed folders are specified, access will be restricted and tools will re
 
 ## Setup
 
-1. Install dependencies:
+1. Configure Claude for Desktop:
 
-```bash
-# Using pip
-pip install -r requirements.txt
+First, using homebrew, install 'uv'. You might already have this on your system, but installing it via Homebrew usually ensures that `uvx` (part of `uv`)  is in the $PATH that Claude Desktop vends to on-device local MCP servers:
 
-# Or using uv (recommended)
-uv pip install -r requirements.txt
-```
+```brew install uv```
+
+Open/create your Claude for Desktop configuration file
+- Open Claude Desktop --> Settings --> Developer --> Edit Config (to find the file in finder)
+- It should be at `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Add the following:
 
-If you don't have pip installed, you can do:
+```json
+{
+    "mcpServers": {
+        "xcode-mcp-server": {
+            "command": "uvx",
+            "args": [
+                "xcode-mcp-server"
+            ]
+        }
+    }
+}
 ```
-brew install pip
+
+If you'd like to allow only certain projects or folders to be accessible by xcode-mcp-server, add the `env` option, with a colon-separated list of absolute folder paths, like this:
+
+```json
+{
+    "mcpServers": {
+        "xcode-mcp-server": {
+            "command": "uvx",
+            "args": [
+                "xcode-mcp-server"
+            ],
+            "env": {
+                "XCODEMCP_ALLOWED_FOLDERS": "/Users/andrew/my_project:/Users/andrew/Documents/source"
+            }
+        }
+    }
+}
 ```
 
-2. Configure Claude for Desktop:
+If you omit the `env` section, access will default to your $HOME directory.
+
+2. Add xcode-mcp-server to **Claude Code** (Anthropic's CLI-based agent)
+
+- Install claude code 
+- Add xcode-mcp-server:
+
+  claude mcp add --scope user --transport stdio `which uvx` xcode-mcp-server
+  
+3. Add xcode-mcp-server to **Cursor AI**
 
-Open/create your Claude for Desktop configuration file at `~/Library/Application Support/Claude/claude_desktop_config.json` and add:
+- Install Cursor, of course
+- In Cursor, navigate to: Cursor --> Settings --> Cursor Settings
+- Then choose 'Tools & Integrations'
+- Tap the + button for 'New MCP Server'
+
+The steps above will get you editing the file ~/.cursor/mcp.json, which you could also edit directly, if you prefer.  Add a section for 'xcode-mcp-server' in the 'mcpServers' section - like this:
 
 ```json
 {
     "mcpServers": {
-        "xcode": {
-            "command": "python3",
+        "xcode-mcp-server": {
+            "command": "uvx",
             "args": [
-                "/ABSOLUTE/PATH/TO/xcode_mcp.py"
+                "xcode-mcp-server"
+            ]
+        }
+    }
+}
+```
+
+If you'd like to allow only certain projects or folders to be accessible by xcode-mcp-server, add the `env` option, with a colon-separated list of absolute folder paths, like this:
+
+```json
+{
+    "mcpServers": {
+        "xcode-mcp-server": {
+            "command": "uvx",
+            "args": [
+                "xcode-mcp-server"
             ],
             "env": {
-                "XCODEMCP_ALLOWED_FOLDERS": "/path/to/projects:/path/to/other/projects"
+                "XCODEMCP_ALLOWED_FOLDERS": "/Users/andrew/my_project:/Users/andrew/Documents/source"
             }
         }
     }
 }
 ```
 
-Replace `/ABSOLUTE/PATH/TO/xcode_mcp.py` with the actual path to your xcode_mcp.py file, and set appropriate allowed folders in the `env` section.
+Be sure to hit Command-S to save the file.
+
+If you omit the `env` section, access will default to your $HOME directory.
+
+### Test it out
+- Open cursor to your favorite xcode project (just open the root folder of the project or git repo), and tell Cursor something like:
+
+    build this project using xcode-mcp-server
+    
+You'll get a permission prompt from Cursor and then one from macOS, and after that you should be off and running.
 
 ## Usage
 
 1. Open Xcode with a project
 2. Start Claude for Desktop
+   - If xcode-mcp-server failed to initialize properly, you'll see errors
 3. Look for the hammer icon to find available Xcode tools
 4. Use natural language to interact with Xcode, for example:
    - "Build the project at /path/to/MyProject.xcodeproj"
@@ -148,6 +215,5 @@ When testing in the MCP Inspector, provide input values as quoted strings:
 
 ## Limitations
 
-- Runtime output retrieval is not yet implemented
 - Project hierarchy is a simple file listing implementation
 - AppleScript syntax may need adjustments for specific Xcode versions # xcode-mcp-server

xcode_mcp_server-1.0.6.dist-info/RECORD

@@ -0,0 +1,6 @@
+xcode_mcp_server/__init__.py,sha256=-yQHFLCSDJZJS02NJ6mpGaL0PGEk2Zgct4ozciGy3Ls,3028
+xcode_mcp_server/__main__.py,sha256=Sonqk9OfjgBxqIa41t9qR477DJLDg9EIjYIwkdyhAhk,30952
+xcode_mcp_server-1.0.6.dist-info/METADATA,sha256=F2LFLWTjrey2gau1GoJBrop7pGsQOiH0dazp5ywheZA,6592
+xcode_mcp_server-1.0.6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+xcode_mcp_server-1.0.6.dist-info/entry_points.txt,sha256=u3sbPCAACGxesL3YtGByZRj6hXkL_FqncBmUMW1SEzo,59
+xcode_mcp_server-1.0.6.dist-info/RECORD,,

xcode_mcp_server-1.0.4.dist-info/RECORD

@@ -1,6 +0,0 @@
-xcode_mcp_server/__init__.py,sha256=P7r8UnSuuEfMndcdvf2Bt_9Emzrh4dgTkWtSRxFRbeE,474
-xcode_mcp_server/__main__.py,sha256=vBieXwq5-8wUc4taEQ3LgXxbDl_lwcL5zg5Mq30fSwo,19079
-xcode_mcp_server-1.0.4.dist-info/METADATA,sha256=aPfuF2rP7xgg_Z8j26APXzw6d9ZN-d1ntxWVNAHzBbs,4284
-xcode_mcp_server-1.0.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-xcode_mcp_server-1.0.4.dist-info/entry_points.txt,sha256=u3sbPCAACGxesL3YtGByZRj6hXkL_FqncBmUMW1SEzo,59
-xcode_mcp_server-1.0.4.dist-info/RECORD,,