feat(docker): add pre-cache feature for faster startup

- Add --pre-cache command-line option to populate cache and exit
- Update Dockerfile to automatically pre-cache during build
- Document pre-cache feature in CLAUDE.md
- Synced rule files with updated documentation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: jamesbrink

.cursorrules

@@ -24,6 +24,7 @@ Official repository: [https://github.com/utensils/mcp-nixos](https://github.com/
 - **Tools**: Search, info, and statistics tools
 - **Utils**: Cross-platform helpers and cache management
 - **Server**: FastMCP server implementation
+- **Pre-Cache**: Command-line option to populate cache data during setup/build
 
 ### Implementation Guidelines
 
@@ -50,6 +51,12 @@ Official repository: [https://github.com/utensils/mcp-nixos](https://github.com/
 - Strict null safety with defensive programming
 - Detailed error logging and user-friendly messages
 - Support wildcard searches and handle empty results
+- Cross-platform compatibility:
+  - Use pathlib.Path for platform-agnostic path handling
+  - Check sys.platform before using platform-specific features
+  - Handle file operations with appropriate platform-specific adjustments
+  - Use os.path.join() instead of string concatenation for paths
+  - Ensure tests work consistently across Windows, macOS, and Linux
 
 ## API Reference
 
@@ -96,6 +103,11 @@ Official repository: [https://github.com/utensils/mcp-nixos](https://github.com/
   - Integration tests: `@pytest.mark.integration`
   - Slow tests: `@pytest.mark.slow`
   - Async tests: `@pytest.mark.asyncio`
+- Cross-platform testing:
+  - CI runs tests on Linux, macOS, and Windows
+  - Linux and macOS tests use flake.nix for development environment
+  - Windows tests use Python's venv with special dependencies (pywin32)
+  - All tests must be platform-agnostic or include platform-specific handling
 - Run specific test categories:
   - Unit tests only: `nix run .#run-tests -- --unit`
   - Integration tests only: `nix run .#run-tests -- --integration`
@@ -110,6 +122,17 @@ Official repository: [https://github.com/utensils/mcp-nixos](https://github.com/
   - All tests must check for both default OS cache paths and test-specific paths
   - The gitignore file excludes `mcp_nixos_test_cache/` and `*test_cache*/` patterns
 
+### Logging Tests
+- Prefer direct behavior verification over implementation details
+- When testing log level filtering:
+  - Use `isEnabledFor()` assertions for level checks (platform-independent)
+  - Use mock handlers with explicit level settings
+  - Test both logger configuration and actual handler behavior
+  - Avoid patching internal logging methods (`_log`) which vary by platform
+  - Add clear error messages to assertions
+- Prevent test flakiness by avoiding sleep/timing dependencies
+- Use clean logger fixtures to prevent test interaction
+
 ### Dependency Management
 - Project uses `pyproject.toml` for dependency specification (PEP 621)
 - Core dependencies:
@@ -125,9 +148,15 @@ Official repository: [https://github.com/utensils/mcp-nixos](https://github.com/
 - Install: `pip install mcp-nixos`, `uv pip install mcp-nixos`, `uvx mcp-nixos`
 - Claude Code configuration: Add to `~/.config/claude/config.json`
 - Interactive shell: `python mcp_shell.py` (manual testing and tool exploration)
+- Docker deployment:
+  - Standard use: `docker run --rm ghcr.io/utensils/mcp-nixos`
+  - Docker image includes pre-cached data for immediate startup
+  - Build with pre-cache: `docker build -t mcp-nixos .`
+  - Deployed on Smithery.ai as a hosted service
 - Development:
   - Environment: `nix develop`
   - Run server: `run`
+  - Pre-cache data: `python -m mcp_nixos --pre-cache`
   - Tests: `run-tests`, `run-tests --unit`, `run-tests --integration`
   - Code quality: `lint`, `typecheck`, `format`
   - Stats: `loc`

.goosehints

@@ -24,6 +24,7 @@ Official repository: [https://github.com/utensils/mcp-nixos](https://github.com/
 - **Tools**: Search, info, and statistics tools
 - **Utils**: Cross-platform helpers and cache management
 - **Server**: FastMCP server implementation
+- **Pre-Cache**: Command-line option to populate cache data during setup/build
 
 ### Implementation Guidelines
 
@@ -50,6 +51,12 @@ Official repository: [https://github.com/utensils/mcp-nixos](https://github.com/
 - Strict null safety with defensive programming
 - Detailed error logging and user-friendly messages
 - Support wildcard searches and handle empty results
+- Cross-platform compatibility:
+  - Use pathlib.Path for platform-agnostic path handling
+  - Check sys.platform before using platform-specific features
+  - Handle file operations with appropriate platform-specific adjustments
+  - Use os.path.join() instead of string concatenation for paths
+  - Ensure tests work consistently across Windows, macOS, and Linux
 
 ## API Reference
 
@@ -96,6 +103,11 @@ Official repository: [https://github.com/utensils/mcp-nixos](https://github.com/
   - Integration tests: `@pytest.mark.integration`
   - Slow tests: `@pytest.mark.slow`
   - Async tests: `@pytest.mark.asyncio`
+- Cross-platform testing:
+  - CI runs tests on Linux, macOS, and Windows
+  - Linux and macOS tests use flake.nix for development environment
+  - Windows tests use Python's venv with special dependencies (pywin32)
+  - All tests must be platform-agnostic or include platform-specific handling
 - Run specific test categories:
   - Unit tests only: `nix run .#run-tests -- --unit`
   - Integration tests only: `nix run .#run-tests -- --integration`
@@ -110,6 +122,17 @@ Official repository: [https://github.com/utensils/mcp-nixos](https://github.com/
   - All tests must check for both default OS cache paths and test-specific paths
   - The gitignore file excludes `mcp_nixos_test_cache/` and `*test_cache*/` patterns
 
+### Logging Tests
+- Prefer direct behavior verification over implementation details
+- When testing log level filtering:
+  - Use `isEnabledFor()` assertions for level checks (platform-independent)
+  - Use mock handlers with explicit level settings
+  - Test both logger configuration and actual handler behavior
+  - Avoid patching internal logging methods (`_log`) which vary by platform
+  - Add clear error messages to assertions
+- Prevent test flakiness by avoiding sleep/timing dependencies
+- Use clean logger fixtures to prevent test interaction
+
 ### Dependency Management
 - Project uses `pyproject.toml` for dependency specification (PEP 621)
 - Core dependencies:
@@ -125,9 +148,15 @@ Official repository: [https://github.com/utensils/mcp-nixos](https://github.com/
 - Install: `pip install mcp-nixos`, `uv pip install mcp-nixos`, `uvx mcp-nixos`
 - Claude Code configuration: Add to `~/.config/claude/config.json`
 - Interactive shell: `python mcp_shell.py` (manual testing and tool exploration)
+- Docker deployment:
+  - Standard use: `docker run --rm ghcr.io/utensils/mcp-nixos`
+  - Docker image includes pre-cached data for immediate startup
+  - Build with pre-cache: `docker build -t mcp-nixos .`
+  - Deployed on Smithery.ai as a hosted service
 - Development:
   - Environment: `nix develop`
   - Run server: `run`
+  - Pre-cache data: `python -m mcp_nixos --pre-cache`
   - Tests: `run-tests`, `run-tests --unit`, `run-tests --integration`
   - Code quality: `lint`, `typecheck`, `format`
   - Stats: `loc`

.windsurfrules

@@ -24,6 +24,7 @@ Official repository: [https://github.com/utensils/mcp-nixos](https://github.com/
 - **Tools**: Search, info, and statistics tools
 - **Utils**: Cross-platform helpers and cache management
 - **Server**: FastMCP server implementation
+- **Pre-Cache**: Command-line option to populate cache data during setup/build
 
 ### Implementation Guidelines
 
@@ -50,6 +51,12 @@ Official repository: [https://github.com/utensils/mcp-nixos](https://github.com/
 - Strict null safety with defensive programming
 - Detailed error logging and user-friendly messages
 - Support wildcard searches and handle empty results
+- Cross-platform compatibility:
+  - Use pathlib.Path for platform-agnostic path handling
+  - Check sys.platform before using platform-specific features
+  - Handle file operations with appropriate platform-specific adjustments
+  - Use os.path.join() instead of string concatenation for paths
+  - Ensure tests work consistently across Windows, macOS, and Linux
 
 ## API Reference
 
@@ -96,6 +103,11 @@ Official repository: [https://github.com/utensils/mcp-nixos](https://github.com/
   - Integration tests: `@pytest.mark.integration`
   - Slow tests: `@pytest.mark.slow`
   - Async tests: `@pytest.mark.asyncio`
+- Cross-platform testing:
+  - CI runs tests on Linux, macOS, and Windows
+  - Linux and macOS tests use flake.nix for development environment
+  - Windows tests use Python's venv with special dependencies (pywin32)
+  - All tests must be platform-agnostic or include platform-specific handling
 - Run specific test categories:
   - Unit tests only: `nix run .#run-tests -- --unit`
   - Integration tests only: `nix run .#run-tests -- --integration`
@@ -110,6 +122,17 @@ Official repository: [https://github.com/utensils/mcp-nixos](https://github.com/
   - All tests must check for both default OS cache paths and test-specific paths
   - The gitignore file excludes `mcp_nixos_test_cache/` and `*test_cache*/` patterns
 
+### Logging Tests
+- Prefer direct behavior verification over implementation details
+- When testing log level filtering:
+  - Use `isEnabledFor()` assertions for level checks (platform-independent)
+  - Use mock handlers with explicit level settings
+  - Test both logger configuration and actual handler behavior
+  - Avoid patching internal logging methods (`_log`) which vary by platform
+  - Add clear error messages to assertions
+- Prevent test flakiness by avoiding sleep/timing dependencies
+- Use clean logger fixtures to prevent test interaction
+
 ### Dependency Management
 - Project uses `pyproject.toml` for dependency specification (PEP 621)
 - Core dependencies:
@@ -125,9 +148,15 @@ Official repository: [https://github.com/utensils/mcp-nixos](https://github.com/
 - Install: `pip install mcp-nixos`, `uv pip install mcp-nixos`, `uvx mcp-nixos`
 - Claude Code configuration: Add to `~/.config/claude/config.json`
 - Interactive shell: `python mcp_shell.py` (manual testing and tool exploration)
+- Docker deployment:
+  - Standard use: `docker run --rm ghcr.io/utensils/mcp-nixos`
+  - Docker image includes pre-cached data for immediate startup
+  - Build with pre-cache: `docker build -t mcp-nixos .`
+  - Deployed on Smithery.ai as a hosted service
 - Development:
   - Environment: `nix develop`
   - Run server: `run`
+  - Pre-cache data: `python -m mcp_nixos --pre-cache`
   - Tests: `run-tests`, `run-tests --unit`, `run-tests --integration`
   - Code quality: `lint`, `typecheck`, `format`
   - Stats: `loc`

CLAUDE.md

@@ -24,6 +24,7 @@ Official repository: [https://github.com/utensils/mcp-nixos](https://github.com/
 - **Tools**: Search, info, and statistics tools
 - **Utils**: Cross-platform helpers and cache management
 - **Server**: FastMCP server implementation
+- **Pre-Cache**: Command-line option to populate cache data during setup/build
 
 ### Implementation Guidelines
 
@@ -147,9 +148,15 @@ Official repository: [https://github.com/utensils/mcp-nixos](https://github.com/
 - Install: `pip install mcp-nixos`, `uv pip install mcp-nixos`, `uvx mcp-nixos`
 - Claude Code configuration: Add to `~/.config/claude/config.json`
 - Interactive shell: `python mcp_shell.py` (manual testing and tool exploration)
+- Docker deployment:
+  - Standard use: `docker run --rm ghcr.io/utensils/mcp-nixos`
+  - Docker image includes pre-cached data for immediate startup
+  - Build with pre-cache: `docker build -t mcp-nixos .`
+  - Deployed on Smithery.ai as a hosted service
 - Development:
   - Environment: `nix develop`
   - Run server: `run`
+  - Pre-cache data: `python -m mcp_nixos --pre-cache`
   - Tests: `run-tests`, `run-tests --unit`, `run-tests --integration`
   - Code quality: `lint`, `typecheck`, `format`
   - Stats: `loc`

Dockerfile

@@ -13,5 +13,9 @@ COPY . .
 # Install the package and dependencies
 RUN pip install --no-cache-dir -e .
 
+# Pre-cache data during build
+RUN echo "Running pre-cache to populate cache data..." && \
+    python -m mcp_nixos --pre-cache
+
 # Run the MCP server
 CMD ["python", "-m", "mcp_nixos"]

mcp_nixos/__main__.py

@@ -6,17 +6,26 @@
 framework to manage signal handling and graceful shutdown.
 """
 
+import argparse
 import sys
+import os
 
 # Import mcp from server
-from mcp_nixos.server import mcp, logger
-import os
+from mcp_nixos.server import mcp, logger, run_precache
+
+
+def parse_args():
+    """Parse command line arguments."""
+    parser = argparse.ArgumentParser(description="MCP-NixOS server")
+    parser.add_argument("--pre-cache", action="store_true", help="Run initialization to populate cache and then exit")
+    return parser.parse_args()
 
 
 def main():
     """Run the MCP-NixOS server."""
-    # Check if we're running under Windsurf for specific debugging
+    args = parse_args()
 
+    # Check if we're running under Windsurf for specific debugging
     windsurf_detected = False
     for env_var in os.environ:
         if "WINDSURF" in env_var.upper() or "WINDSURFER" in env_var.upper():
@@ -27,6 +36,12 @@ def main():
         logger.info("Running under Windsurf - monitoring for restart/refresh signals")
 
     try:
+        if args.pre_cache:
+            logger.info("Running in pre-cache mode - will exit after caching completes")
+            run_precache()
+            logger.info("Pre-cache completed successfully")
+            return 0
+
         # Run the server (this is a blocking call)
         logger.info("Starting server main loop")
         mcp.run()
@@ -44,4 +59,4 @@ def main():
 # This is needed for the "mcp-nixos = "mcp_nixos.__main__:mcp.run" entry point in pyproject.toml
 
 if __name__ == "__main__":
-    main()
+    sys.exit(main())

mcp_nixos/server.py

@@ -140,6 +140,67 @@ async def async_with_timeout(coro_func, timeout_seconds=5.0, operation_name="ope
         return None
 
 
+async def run_precache_async():
+    """Run all initialization and cache population, then exit.
+
+    This function runs the same initialization steps as the server startup
+    but waits for all caching operations to complete before returning.
+    """
+    logger.info("Starting pre-cache initialization")
+
+    # Start loading Home Manager data
+    logger.info("Loading Home Manager data...")
+    home_manager_context.hm_client.load_in_background()
+
+    # Start loading Darwin data
+    logger.info("Loading Darwin data...")
+    try:
+        await async_with_timeout(
+            lambda: darwin_context.startup(), timeout_seconds=30.0, operation_name="Darwin context startup"
+        )
+        logger.info(f"Darwin context status: {darwin_context.status}")
+    except Exception as e:
+        logger.error(f"Error starting Darwin context: {e}")
+
+    # Wait for Home Manager client to complete loading
+    # Use a polling approach since there's no explicit wait_for_loading method
+    logger.info("Waiting for Home Manager data to complete loading...")
+    max_wait_seconds = 120
+    wait_interval = 2
+    start_time = time.time()
+
+    while time.time() - start_time < max_wait_seconds:
+        with home_manager_context.hm_client.loading_lock:
+            if hasattr(home_manager_context.hm_client, "is_loaded") and home_manager_context.hm_client.is_loaded:
+                logger.info("Home Manager data finished loading")
+                break
+            if (
+                hasattr(home_manager_context.hm_client, "loading_error")
+                and home_manager_context.hm_client.loading_error
+            ):
+                logger.error(f"Home Manager loading failed: {home_manager_context.hm_client.loading_error}")
+                break
+        logger.debug(f"Home Manager data still loading, waiting {wait_interval}s...")
+        await asyncio.sleep(wait_interval)
+    else:
+        logger.warning(f"Timed out after {max_wait_seconds}s waiting for Home Manager data to load")
+
+    logger.info("All initialization completed successfully")
+    return True
+
+
+def run_precache():
+    """Run all initialization and cache population synchronously, then exit."""
+    try:
+        return asyncio.run(run_precache_async())
+    except KeyboardInterrupt:
+        logger.info("Pre-cache operation interrupted")
+        return False
+    except Exception as e:
+        logger.error(f"Error during pre-cache: {e}", exc_info=True)
+        return False
+
+
 # Define the lifespan context manager for app initialization
 @asynccontextmanager
 async def app_lifespan(mcp_server: FastMCP):