xcode-mcp-server 1.3.11b4__tar.gz → 1.3.13__tar.gz

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xcode-mcp-server
-Version: 1.3.11b4
+Version: 1.3.13
 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
@@ -17,7 +17,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
-Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: mcp[cli]>=1.7.0
 Requires-Dist: questionary>=2.0.0
 Requires-Dist: rich>=13.0.0
 Description-Content-Type: text/markdown

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/pyproject.toml

@@ -23,7 +23,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
 ]
 dependencies = [
-    "mcp[cli]>=1.2.0",
+    "mcp[cli]>=1.7.0",
     "questionary>=2.0.0",
     "rich>=13.0.0",
 ]

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/__init__.py

@@ -1,6 +1,6 @@
 """Xcode MCP Server - Model Context Protocol server for Xcode integration"""
 
-__version__ = "1.3.11b4"
+__version__ = "1.3.13"
 
 
 def main():

xcode_mcp_server-1.3.13/xcode_mcp_server/server.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""FastMCP server instance for Xcode MCP Server"""
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+
+# Initialize the 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.
+
+        Call `get_xcode_projects` to find Xcode project (.xcodeproj) and
+        Xcode workspace (.xcworkspace) folders under a given root folder.
+
+        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 (and/or potentially warning) output. `build_project` will default to the
+        active scheme if none is provided.
+    """
+)
+
+# Tool behavior annotations (advisory hints for MCP clients).
+#
+# These describe how a tool affects its environment so clients can gate
+# auto-approval and label tools appropriately. The build/run/test tools are
+# marked destructive AND open-world: a build executes arbitrary third-party
+# code (Run Script phases, SPM plugins/macros) and resolves packages from
+# arbitrary remote hosts, so we cannot honestly claim it is additive-only,
+# idempotent, or hermetic.
+
+# Pure observers: reading state, listing, screenshots. No mutation, no network.
+TOOL_READONLY = ToolAnnotations(
+    readOnlyHint=True,
+    idempotentHint=True,
+    destructiveHint=False,
+    openWorldHint=False,
+)
+
+# Builds and runs: execute arbitrary build/install scripts and fetch packages.
+TOOL_BUILD = ToolAnnotations(
+    readOnlyHint=False,
+    idempotentHint=False,
+    destructiveHint=True,
+    openWorldHint=True,
+)
+
+# Clean: deletes build artifacts. Destructive but locally bounded and idempotent.
+TOOL_CLEAN = ToolAnnotations(
+    readOnlyHint=False,
+    idempotentHint=True,
+    destructiveHint=True,
+    openWorldHint=False,
+)
+
+# Create: writes a fresh template and refuses to overwrite. Additive, local.
+TOOL_CREATE = ToolAnnotations(
+    readOnlyHint=False,
+    idempotentHint=False,
+    destructiveHint=False,
+    openWorldHint=False,
+)
+
+# Settles a piece of local state (run destination, stopping a run). Re-applying
+# the same call lands on the same state, and nothing is destroyed.
+TOOL_MUTATING_IDEMPOTENT = ToolAnnotations(
+    readOnlyHint=False,
+    idempotentHint=True,
+    destructiveHint=False,
+    openWorldHint=False,
+)

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/build_project.py

@@ -8,14 +8,14 @@ import sys
 import time
 from typing import Optional
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_BUILD
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.security import validate_and_normalize_project_path
 from xcode_mcp_server.exceptions import InvalidParameterError, XCodeMCPError
 from xcode_mcp_server.utils.applescript import (
-    BUILD_TIMEOUT_SECONDS,
     build_open_and_wait_applescript,
     build_wait_for_completion_applescript,
+    resolve_build_timeout,
     escape_applescript_string,
     run_applescript,
     show_notification,
@@ -283,18 +283,20 @@ def _supplement_with_xcactivitylog_warnings(
         return errors_json
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_BUILD)
 @apply_config
 def build_project(project_path: str,
                  scheme: Optional[str] = None,
                  include_warnings: Optional[bool] = None,
                  regex_filter: Optional[str] = None,
-                 max_lines: int = 25) -> str:
+                 max_lines: int = 25,
+                 timeout: Optional[int] = None) -> str:
     """
     Build the specified Xcode project or workspace.
 
-    Builds will run for up to 10 minutes before timing out. This timeout is hardcoded
-    to prevent issues with builds hanging indefinitely.
+    Builds run for up to `timeout` seconds (default 600, i.e. 10 minutes) before
+    timing out, which guards against a build that hangs indefinitely. Raise it
+    for large projects whose cold build exceeds the default.
 
     Args:
         project_path: Path to an Xcode project or workspace directory.
@@ -302,6 +304,8 @@ def build_project(project_path: str,
         include_warnings: Include warnings in build output. If not provided, uses global setting.
         regex_filter: Optional regex to filter error/warning lines
         max_lines: Maximum number of error/warning lines to show (default 25)
+        timeout: Maximum seconds to wait for the build to complete. If not
+            provided, defaults to 600. Must be a positive integer.
 
     Returns:
         Always returns JSON with format:
@@ -317,6 +321,10 @@ def build_project(project_path: str,
     if include_warnings is not None and not isinstance(include_warnings, bool):
         raise InvalidParameterError("include_warnings must be a boolean value")
 
+    # Resolve the build timeout up front so an invalid value errors immediately,
+    # before any AppleScript runs.
+    effective_timeout = resolve_build_timeout(timeout)
+
     # Validate regex_filter up front so a bad pattern produces a clear error
     # immediately, before any AppleScript runs. The supplement helper assumes
     # the pattern compiles.
@@ -340,7 +348,7 @@ def build_project(project_path: str,
     script = (
         build_open_and_wait_applescript(escaped_path, escaped_scheme)
         + '    set actionResult to build workspaceDoc\n'
-        + build_wait_for_completion_applescript("actionResult", BUILD_TIMEOUT_SECONDS)
+        + build_wait_for_completion_applescript("actionResult", effective_timeout)
         + '    set buildStatus to "unknown"\n'
         + '    try\n'
         + '        set buildStatus to status of actionResult as string\n'
@@ -359,10 +367,10 @@ def build_project(project_path: str,
         manifest_path = os.path.join(derived_data_path, "Logs", "Build", "LogStoreManifest.plist")
         pre_build_uuids = snapshot_build_uuids(manifest_path)
 
-    # The script polls inside AppleScript for up to BUILD_TIMEOUT_SECONDS; the
+    # The script polls inside AppleScript for up to effective_timeout; the
     # subprocess timeout must exceed that, with a small buffer for workspace
     # load and IPC overhead.
-    success, output = run_applescript(script, timeout=BUILD_TIMEOUT_SECONDS + 60)
+    success, output = run_applescript(script, timeout=effective_timeout + 60)
 
     if success:
         # Parse the BUILD_STATUS: prefix from the AppleScript output

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/clean_project.py

@@ -2,14 +2,15 @@
 """clean_project tool - Clean an Xcode project"""
 
 import os
+from typing import Optional
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_CLEAN
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.security import validate_and_normalize_project_path
 from xcode_mcp_server.exceptions import XCodeMCPError
 from xcode_mcp_server.utils.applescript import (
-    BUILD_TIMEOUT_SECONDS,
     build_open_and_wait_applescript,
+    resolve_build_timeout,
     escape_applescript_string,
     run_applescript,
     show_result_notification,
@@ -17,14 +18,16 @@ from xcode_mcp_server.utils.applescript import (
 )
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_CLEAN)
 @apply_config
-def clean_project(project_path: str) -> str:
+def clean_project(project_path: str, timeout: Optional[int] = None) -> str:
     """
     Clean the specified Xcode project or workspace.
 
     Args:
         project_path: Path to an Xcode project/workspace directory.
+        timeout: Maximum seconds to wait for the clean to complete. If not
+            provided, defaults to 600. Must be a positive integer.
 
     Returns:
         Output message
@@ -32,6 +35,7 @@ def clean_project(project_path: str) -> str:
     # Validate and normalize path
     normalized_path = validate_and_normalize_project_path(project_path, "Cleaning")
     escaped_path = escape_applescript_string(normalized_path)
+    effective_timeout = resolve_build_timeout(timeout)
 
     script = build_open_and_wait_applescript(escaped_path) + (
         '    clean workspaceDoc\n'
@@ -41,7 +45,7 @@ def clean_project(project_path: str) -> str:
 
     # Clean is synchronous in AppleScript and can take minutes on large projects;
     # use the same budget as build/test rather than the short default.
-    success, output = run_applescript(script, timeout=BUILD_TIMEOUT_SECONDS + 60)
+    success, output = run_applescript(script, timeout=effective_timeout + 60)
 
     project_name = os.path.basename(normalized_path)
 

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/create_project.py

@@ -5,7 +5,7 @@ import json
 import os
 from typing import Optional
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_CREATE
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.security import validate_parent_for_new_project
 from xcode_mcp_server.exceptions import InvalidParameterError
@@ -23,7 +23,7 @@ from xcode_mcp_server.tools.get_xcode_projects import register_created_project
 SUPPORTED_PLATFORMS = {"ios", "macos"}
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_CREATE)
 @apply_config
 def create_project(
     parent_directory: str,

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/debug_list_notification_history.py

@@ -5,7 +5,7 @@ import os
 import subprocess
 import sys
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_READONLY
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.utils.applescript import get_notification_history
 from xcode_mcp_server.utils.paths import DEBUG_DIR
@@ -16,7 +16,7 @@ from xcode_mcp_server.utils.paths import DEBUG_DIR
 NOTIFICATION_HISTORY_FILE = os.path.join(DEBUG_DIR, "notification-history.txt")
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_READONLY)
 @apply_config
 def debug_list_notification_history() -> str:
     """

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/get_active_run_destination.py

@@ -7,7 +7,7 @@ import os
 import subprocess
 import sys
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_READONLY
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.security import validate_and_normalize_project_path
 from xcode_mcp_server.exceptions import XCodeMCPError
@@ -162,7 +162,7 @@ def _lookup_simulator_info(udid: str) -> tuple:
     return ("", "")
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_READONLY)
 @apply_config
 def get_active_run_destination(
     project_path: str,

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/get_build_errors.py

@@ -3,7 +3,7 @@
 
 from typing import Optional
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_READONLY
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.security import validate_and_normalize_project_path
 from xcode_mcp_server.exceptions import InvalidParameterError, XCodeMCPError
@@ -11,7 +11,7 @@ from xcode_mcp_server.utils.applescript import escape_applescript_string, run_ap
 from xcode_mcp_server.utils.xcresult import extract_build_errors_and_warnings
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_READONLY)
 @apply_config
 def get_build_errors(project_path: str,
                     include_warnings: Optional[bool] = None,

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/get_build_results.py

@@ -5,7 +5,7 @@ import os
 import json
 from typing import Optional
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_READONLY
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.security import validate_and_normalize_project_path
 from xcode_mcp_server.exceptions import XCodeMCPError
@@ -15,7 +15,7 @@ from xcode_mcp_server.utils.build_log_parser import (
 )
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_READONLY)
 @apply_config
 def get_build_results(project_path: str,
                      max_warnings: int = 50) -> str:

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/get_directory_listing.py

@@ -6,14 +6,14 @@ import re
 import datetime
 from typing import Optional
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_READONLY
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.security import validate_and_normalize_directory_path
 from xcode_mcp_server.exceptions import AccessDeniedError, InvalidParameterError, XCodeMCPError
 from xcode_mcp_server.utils.applescript import show_error_notification
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_READONLY)
 @apply_config
 def get_directory_listing(directory_path: str,
                          regex_filter: Optional[str] = None,

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/get_directory_tree.py

@@ -4,7 +4,7 @@
 import os
 from typing import List
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_READONLY
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.security import validate_and_normalize_directory_path
 from xcode_mcp_server.exceptions import InvalidParameterError, XCodeMCPError
@@ -32,7 +32,7 @@ SKIP_DIR_NAMES = frozenset([
 MAX_TREE_LINES = 5000
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_READONLY)
 @apply_config
 def get_directory_tree(directory_path: str, max_depth: int = 4) -> str:
     """

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/get_latest_test_results.py

@@ -5,7 +5,7 @@ import os
 import json
 import sys
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_READONLY
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.security import validate_and_normalize_project_path
 from xcode_mcp_server.utils.applescript import (
@@ -18,7 +18,7 @@ from xcode_mcp_server.utils.applescript import (
 from xcode_mcp_server.utils.xcresult import find_xcresult_bundle, extract_test_results_from_xcresult
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_READONLY)
 @apply_config
 def get_latest_test_results(project_path: str) -> str:
     """

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/get_project_schemes.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """get_project_schemes tool - Get available build schemes"""
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_READONLY
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.security import validate_and_normalize_project_path
 from xcode_mcp_server.exceptions import XCodeMCPError
@@ -14,7 +14,7 @@ from xcode_mcp_server.utils.applescript import (
 )
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_READONLY)
 @apply_config
 def get_project_schemes(project_path: str) -> str:
     """

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/get_runtime_output.py

@@ -5,7 +5,7 @@ import sys
 import json
 from typing import Optional
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_READONLY
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.security import validate_and_normalize_project_path
 from xcode_mcp_server.exceptions import InvalidParameterError, XCodeMCPError
@@ -13,7 +13,7 @@ from xcode_mcp_server.utils.xcresult import find_xcresult_for_project, extract_c
 from xcode_mcp_server.utils.applescript import show_error_notification, show_warning_notification, show_result_notification
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_READONLY)
 @apply_config
 def get_runtime_output(project_path: str,
                       regex_filter: Optional[str] = None,

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/get_xcode_projects.py

@@ -6,7 +6,7 @@ import sys
 import subprocess
 import re
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_READONLY
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.security import ALLOWED_FOLDERS, is_path_allowed
 from xcode_mcp_server.exceptions import AccessDeniedError, InvalidParameterError
@@ -179,7 +179,7 @@ def _filter_project_results(paths: list[str], search_paths: list[str] = None, ma
     return final_results
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_READONLY)
 @apply_config
 def get_xcode_projects(
     search_path: str = "",

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/list_booted_simulators.py

@@ -3,14 +3,14 @@
 
 import subprocess
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_READONLY
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.exceptions import XCodeMCPError
 from xcode_mcp_server.utils.applescript import show_result_notification, show_error_notification
 from xcode_mcp_server.utils.screenshot import _get_booted_simulators
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_READONLY)
 @apply_config
 def list_booted_simulators() -> str:
     """

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/list_mac_app_windows.py

@@ -5,13 +5,13 @@ import os
 import tempfile
 import subprocess
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_READONLY
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.exceptions import XCodeMCPError
 from xcode_mcp_server.utils.applescript import show_result_notification, show_error_notification
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_READONLY)
 @apply_config
 def list_mac_app_windows() -> str:
     """

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/list_project_tests.py

@@ -6,14 +6,14 @@ import re
 import subprocess
 import sys
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_READONLY
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.exceptions import XCodeMCPError
 from xcode_mcp_server.security import validate_and_normalize_project_path
 from xcode_mcp_server.utils.applescript import show_result_notification, show_error_notification
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_READONLY)
 @apply_config
 def list_project_tests(project_path: str) -> str:
     """

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/list_run_destinations.py

@@ -8,7 +8,7 @@ import subprocess
 import sys
 from typing import Optional
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_READONLY
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.security import validate_and_normalize_project_path
 from xcode_mcp_server.exceptions import XCodeMCPError
@@ -73,7 +73,7 @@ def _parse_destination_line(line: str) -> Optional[dict]:
     return result
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_READONLY)
 @apply_config
 def list_run_destinations(
     project_path: str,

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/list_running_mac_apps.py

@@ -1,13 +1,13 @@
 #!/usr/bin/env python3
 """list_running_mac_apps tool - List running macOS applications"""
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_READONLY
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.exceptions import XCodeMCPError
 from xcode_mcp_server.utils.applescript import show_notification, run_applescript, show_result_notification, show_error_notification
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_READONLY)
 @apply_config
 def list_running_mac_apps() -> str:
     """

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/run_project_tests.py

@@ -7,14 +7,15 @@ import time
 import json
 from typing import Optional, List
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_BUILD
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.security import validate_and_normalize_project_path
 from xcode_mcp_server.exceptions import InvalidParameterError
 from xcode_mcp_server.utils.applescript import (
-    BUILD_TIMEOUT_SECONDS,
     build_open_and_wait_applescript,
     build_wait_for_completion_applescript,
+    resolve_build_timeout,
+    format_timeout_duration,
     escape_applescript_string,
     run_applescript,
     show_notification,
@@ -149,19 +150,23 @@ from xcode_mcp_server.utils.xcresult import find_xcresult_bundle, extract_test_r
 #         return f"⏳ Tests did not complete within {max_wait_seconds} seconds"
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_BUILD)
 @apply_config
 def run_project_tests(project_path: str,
-                     scheme: Optional[str] = None) -> str:
+                     scheme: Optional[str] = None,
+                     timeout: Optional[int] = None) -> str:
     """
     Run tests for the specified Xcode project or workspace.
 
-    Tests will run for up to 10 minutes before timing out. This timeout is hardcoded
-    to prevent issues with test runs hanging indefinitely.
+    Tests run for up to `timeout` seconds (default 600, i.e. 10 minutes) before
+    timing out, which guards against a test run hanging indefinitely. Raise it
+    for large projects whose build-for-testing alone exceeds the default.
 
     Args:
         project_path: Path to Xcode project/workspace directory
         scheme: Optional scheme to test (uses active scheme if not specified)
+        timeout: Maximum seconds to wait for the build-for-testing plus test run
+            to complete. If not provided, defaults to 600. Must be a positive integer.
 
     Returns:
         JSON with test results if tests complete, otherwise plain text status message.
@@ -176,6 +181,10 @@ def run_project_tests(project_path: str,
     # Validate and normalize the project path
     project_path = validate_and_normalize_project_path(project_path, "run_project_tests")
 
+    # Resolve the test timeout up front so an invalid value errors immediately,
+    # before any AppleScript runs or notifications post.
+    effective_timeout = resolve_build_timeout(timeout)
+
     # Show notification
     show_notification("Drew's Xcode MCP", subtitle=os.path.basename(project_path), message="Running tests")
 
@@ -275,14 +284,14 @@ def run_project_tests(project_path: str,
     script = (
         build_open_and_wait_applescript(escaped_path, escaped_scheme)
         + '    set testResult to test workspaceDoc\n'
-        + build_wait_for_completion_applescript("testResult", BUILD_TIMEOUT_SECONDS)
+        + build_wait_for_completion_applescript("testResult", effective_timeout)
         + failure_extraction_tail
         + 'end tell\n'
     )
 
-    # The script polls inside AppleScript for up to BUILD_TIMEOUT_SECONDS; the
+    # The script polls inside AppleScript for up to effective_timeout; the
     # subprocess timeout must exceed that, plus buffer for workspace load.
-    success, output = run_applescript(script, timeout=BUILD_TIMEOUT_SECONDS + 60)
+    success, output = run_applescript(script, timeout=effective_timeout + 60)
 
     if not success:
         show_error_notification("Failed to run tests", os.path.basename(project_path))
@@ -307,10 +316,10 @@ def run_project_tests(project_path: str,
     output_lines = []
 
     if not completed:
-        minutes = BUILD_TIMEOUT_SECONDS // 60
-        output_lines.append(f"⏳ Tests did not complete within {minutes} minutes")
+        duration = format_timeout_duration(effective_timeout)
+        output_lines.append(f"⏳ Tests did not complete within {duration}")
         output_lines.append(f"Status: {status}")
-        show_warning_notification(f"Tests timeout ({minutes} min)")
+        show_warning_notification(f"Tests timeout ({duration})")
         return '\n'.join(output_lines)
 
     # If tests completed, get detailed results from xcresult

{xcode_mcp_server-1.3.11b4 → xcode_mcp_server-1.3.13}/xcode_mcp_server/tools/run_project_unmonitored.py

@@ -4,7 +4,7 @@
 import os
 from typing import Optional
 
-from xcode_mcp_server.server import mcp
+from xcode_mcp_server.server import mcp, TOOL_BUILD
 from xcode_mcp_server.config_manager import apply_config
 from xcode_mcp_server.security import validate_and_normalize_project_path
 from xcode_mcp_server.exceptions import XCodeMCPError
@@ -17,7 +17,7 @@ from xcode_mcp_server.utils.applescript import (
 )
 
 
-@mcp.tool()
+@mcp.tool(annotations=TOOL_BUILD)
 @apply_config
 def run_project_unmonitored(project_path: str,
                              scheme: Optional[str] = None) -> str: