Build Unblocker MCP

Instructions

Implementation Reference

• src/build_unblocker_mcp/server.py:35-77 (handler)

  Main handler function for the 'unblock_build' tool. It examines processes matching specified names, checks if they are idle for the given duration, and kills them if not in dry-run mode. Returns a summary dictionary.
  def unblock_build(idle_seconds: int = 90, process_names: t.List[str] | None = None, dry_run: bool = False) -> dict: """ Terminates hung build executables that are idle for a specified duration. Args: idle_seconds: The duration in seconds a process must be idle to be considered hung. process_names: A list of process names to monitor. Defaults to DEFAULT_PROCESSES. dry_run: If True, logs actions without actually killing processes. Returns: A dictionary summarizing the examination and killing of processes. """ settings = Settings(idle_seconds=idle_seconds, process_names=process_names or DEFAULT_PROCESSES, dry_run=dry_run) examined_count = 0 killed_count = 0 killed_processes = [] for proc in psutil.process_iter(['pid', 'name', 'create_time']): if proc.info['name'] in settings.process_names: examined_count += 1 if is_process_idle(proc, settings.idle_seconds): if settings.dry_run: print(f"Dry run: Would kill process {proc.info['name']} (PID: {proc.info['pid']}) - idle for > {settings.idle_seconds}s", file=sys.stderr) else: try: print(f"Killing process {proc.info['name']} (PID: {proc.info['pid']}) - idle for > {settings.idle_seconds}s", file=sys.stderr) proc.kill() killed_count += 1 killed_processes.append({"name": proc.info['name'], "pid": proc.info['pid']}) except (psutil.NoSuchProcess, psutil.AccessDenied): print(f"Failed to kill process {proc.info['name']} (PID: {proc.info['pid']})", file=sys.stderr) return { "examined": examined_count, "killed": killed_count, "killed_processes": killed_processes, "timestamp": datetime.utcnow().isoformat() + "Z", "dry_run": settings.dry_run, "idle_seconds_threshold": settings.idle_seconds, "process_names_monitored": settings.process_names, }
• src/build_unblocker_mcp/server.py:34-34 (registration)

  MCP tool registration decorator that registers the unblock_build function with name 'unblock_build'.
  @mcp.tool(name="unblock_build", description="Kill build executables idle > idle_seconds.")
• src/build_unblocker_mcp/server.py:15-33 (helper)

  Helper function used by the handler to determine if a process is idle based on low CPU usage and sufficient age.
  def is_process_idle(proc: psutil.Process, idle_seconds: int) -> bool: """Checks if a process is idle based on CPU usage and age.""" try: # Check CPU usage over a 1-second interval cpu_percent = proc.cpu_percent(interval=1.0) if cpu_percent >= 1.0: return False # Check process age create_time = proc.create_time() process_age = time.time() - create_time if process_age < idle_seconds: return False return True except (psutil.NoSuchProcess, psutil.AccessDenied, psutil.ZombieProcess): # Process may have exited or access denied, treat as not idle for safety return False
• src/build_unblocker_mcp/config.py:4-18 (helper)

  Default list of process names that the tool monitors for hanging builds.
  DEFAULT_PROCESSES: t.List[str] = [ "cl.exe", "link.exe", "msbuild.exe", "rc.exe", "csc.exe", "devenv.exe", # Visual Studio IDE process, can also hang builds "cmake.exe", "ninja.exe", "make.exe", "gcc.exe", "g++.exe", "clang.exe", "clang++.exe", ]
• src/build_unblocker_mcp/config.py:20-24 (helper)

  Dataclass used internally to hold the tool's configuration settings.
  @dataclass class Settings: idle_seconds: int = 90 process_names: t.List[str] = field(default_factory=lambda: DEFAULT_PROCESSES) dry_run: bool = False