configure_file_watcher

Configure file monitoring settings to automatically rebuild code indexes when files change, with options for debounce timing, exclusion patterns, and observer backends.

Instructions

Configure file watcher service settings.

Args:
    enabled: Whether to enable file watcher
    debounce_seconds: Debounce time in seconds before triggering rebuild
    additional_exclude_patterns: Additional directory/file patterns to exclude
    observer_type: Observer backend to use. Options:
        - "auto" (default): kqueue on macOS for reliability, platform default elsewhere
        - "kqueue": Force kqueue observer (macOS/BSD)
        - "fsevents": Force FSEvents observer (macOS only, has known reliability issues)
        - "polling": Cross-platform polling fallback (slower but most compatible)

Input Schema

TableJSON Schema

Name	Required	Description	Default
`enabled`	No
`debounce_seconds`	No
`additional_exclude_patterns`	No
`observer_type`	No

Implementation Reference

src/code_index_mcp/server.py:321-342 (handler)

MCP tool handler for 'configure_file_watcher', decorated with @mcp.tool() which registers the tool and handles execution by delegating to SystemManagementService.

@mcp.tool()
@handle_mcp_tool_errors(return_type='str')
def configure_file_watcher(
    ctx: Context,
    enabled: bool = None,
    debounce_seconds: float = None,
    additional_exclude_patterns: list = None,
    observer_type: str = None
) -> str:
    """Configure file watcher service settings.

    Args:
        enabled: Whether to enable file watcher
        debounce_seconds: Debounce time in seconds before triggering rebuild
        additional_exclude_patterns: Additional directory/file patterns to exclude
        observer_type: Observer backend to use. Options:
            - "auto" (default): kqueue on macOS for reliability, platform default elsewhere
            - "kqueue": Force kqueue observer (macOS/BSD)
            - "fsevents": Force FSEvents observer (macOS only, has known reliability issues)
            - "polling": Cross-platform polling fallback (slower but most compatible)
    """
    return SystemManagementService(ctx).configure_file_watcher(enabled, debounce_seconds, additional_exclude_patterns, observer_type)

src/code_index_mcp/services/system_management_service.py:64-89 (helper)

Core business logic method in SystemManagementService that validates inputs and applies file watcher configuration by updating settings.

def configure_file_watcher(self, enabled: Optional[bool] = None,
                         debounce_seconds: Optional[float] = None,
                         additional_exclude_patterns: Optional[list] = None,
                         observer_type: Optional[str] = None) -> str:
    """
    Configure file watcher settings with business validation.

    Args:
        enabled: Whether to enable file watcher
        debounce_seconds: Debounce time in seconds
        additional_exclude_patterns: Additional patterns to exclude
        observer_type: Observer backend type ("auto", "kqueue", "fsevents", "polling")

    Returns:
        Success message with configuration details

    Raises:
        ValueError: If configuration is invalid
    """
    # Business validation
    self._validate_configuration_request(enabled, debounce_seconds, additional_exclude_patterns, observer_type)

    # Business workflow: Apply configuration
    result = self._apply_file_watcher_configuration(enabled, debounce_seconds, additional_exclude_patterns, observer_type)

    return result

src/code_index_mcp/services/system_management_service.py:336-395 (helper)

Private helper method that actually applies the configuration updates to the settings service and generates the response message.

def _apply_file_watcher_configuration(self, enabled: Optional[bool],
                                    debounce_seconds: Optional[float],
                                    additional_exclude_patterns: Optional[list],
                                    observer_type: Optional[str]) -> str:
    """
    Business logic to apply file watcher configuration.

    Args:
        enabled: Enable flag
        debounce_seconds: Debounce time
        additional_exclude_patterns: Exclude patterns
        observer_type: Observer backend type

    Returns:
        Success message

    Raises:
        ValueError: If configuration cannot be applied
    """
    # Business rule: Settings must be available
    if (not hasattr(self.ctx.request_context.lifespan_context, 'settings') or
        not self.ctx.request_context.lifespan_context.settings):
        raise ValueError("Settings not available - project path not set")

    settings = self.ctx.request_context.lifespan_context.settings

    # Build updates dictionary
    updates = {}
    if enabled is not None:
        updates["enabled"] = enabled
    if debounce_seconds is not None:
        updates["debounce_seconds"] = debounce_seconds
    if additional_exclude_patterns is not None:
        updates["additional_exclude_patterns"] = additional_exclude_patterns
    if observer_type is not None:
        updates["observer_type"] = observer_type

    if not updates:
        return "No configuration changes specified"

    # Apply configuration
    settings.update_file_watcher_config(updates)

    # Business logic: Generate informative result message
    changes_summary = []
    if 'enabled' in updates:
        changes_summary.append(f"enabled={updates['enabled']}")
    if 'debounce_seconds' in updates:
        changes_summary.append(f"debounce={updates['debounce_seconds']}s")
    if 'additional_exclude_patterns' in updates:
        pattern_count = len(updates['additional_exclude_patterns'])
        changes_summary.append(f"exclude_patterns={pattern_count}")
    if 'observer_type' in updates:
        changes_summary.append(f"observer_type={updates['observer_type']}")

    changes_str = ", ".join(changes_summary)

    return (f"File watcher configuration updated: {changes_str}. "
            f"Restart may be required for changes to take effect.")

code-index-mcp