claude-session-manager

Instructions

Implementation Reference

• src/claude_session_manager_mcp/server.py:438-499 (handler)

  Core handler function that starts the web GUI server by launching a subprocess for the Flask app, manages the process PID, handles port specification, browser opening, and error cases.
  def start_web_gui(port: int = 5050, open_browser: bool = True) -> dict: """Start the web GUI server.""" global _web_server_process # Check if already running if _web_server_process is not None and _web_server_process.poll() is None: url = f"http://localhost:{port}" if open_browser: webbrowser.open(url) return { "success": True, "message": "Web GUI is already running", "url": url, "pid": _web_server_process.pid } try: # Get the package directory package_dir = Path(__file__).parent.parent.parent # Start Flask server as subprocess _web_server_process = subprocess.Popen( [sys.executable, "-m", "claude_session_manager_mcp.web"], cwd=str(package_dir), stdout=subprocess.PIPE, stderr=subprocess.PIPE, start_new_session=True ) # Wait briefly to check if it started successfully import time time.sleep(1) if _web_server_process.poll() is not None: # Process ended, get error _, stderr = _web_server_process.communicate() return { "success": False, "message": f"Failed to start web GUI: {stderr.decode()}" } url = f"http://localhost:{port}" if open_browser: webbrowser.open(url) return { "success": True, "message": "Web GUI started successfully", "url": url, "pid": _web_server_process.pid } except Exception as e: return { "success": False, "message": f"Failed to start web GUI: {str(e)}" } def stop_web_gui() -> dict: """Stop the web GUI server.""" global _web_server_process
• src/claude_session_manager_mcp/server.py:656-673 (registration)

  Registers the 'start_gui' tool with the MCP server, defining its name, description, and input schema for optional port and open_browser parameters.
  Tool( name="start_gui", description="Start the web GUI for session management and open it in browser", inputSchema={ "type": "object", "properties": { "port": { "type": "integer", "description": "Port to run the web server on (default: 5050)" }, "open_browser": { "type": "boolean", "description": "Whether to open browser automatically (default: true)" } }, "required": [] } ),
• src/claude_session_manager_mcp/server.py:728-732 (handler)

  Tool dispatch logic in the MCP call_tool handler that extracts arguments and invokes the start_web_gui function.
  elif name == "start_gui": port = arguments.get("port", 5050) open_browser = arguments.get("open_browser", True) result = start_web_gui(port, open_browser)