enh / fix: refactor quantbook support for docker instead of hacky original

README.md

@@ -68,6 +68,8 @@ Get up and running in under 2 minutes:
 > **Prerequisites:** You must have QuantConnect credentials (User ID and API Token) before running the server. The server will not function without proper authentication. See [Authentication](#-authentication) section for details on obtaining these credentials.
 
 ### **Install with uvx (Recommended)**
+
+#### Core Installation (API Tools Only)
 ```bash
 # Install and run directly from PyPI - no cloning required!
 uvx quantconnect-mcp
@@ -77,6 +79,17 @@ uv pip install quantconnect-mcp
 pip install quantconnect-mcp
 ```
 
+#### Full Installation (with QuantBook Support)
+```bash
+# Install with QuantBook container functionality
+uv pip install "quantconnect-mcp[quantbook]"
+pip install "quantconnect-mcp[quantbook]"
+
+# Requires Docker and lean-cli to be installed
+docker --version  # Ensure Docker is available
+pip install lean    # Install QuantConnect lean-cli
+```
+
 
 ### One-Click Claude Desktop Install (Recommended)
 
@@ -95,18 +108,63 @@ pip install quantconnect-mcp
 export QUANTCONNECT_USER_ID="your_user_id"        # Required
 export QUANTCONNECT_API_TOKEN="your_api_token"    # Required
 export QUANTCONNECT_ORGANIZATION_ID="your_org_id" # Optional
+
+# Optional: Enable QuantBook container functionality (default: false)
+export ENABLE_QUANTBOOK="true"                    # Requires Docker + quantconnect-mcp[quantbook]
 ```
 
 ### 3. **Launch the Server**
 ```bash
 # STDIO transport (default) - Recommended for MCP clients
 uvx quantconnect-mcp
 
+# With QuantBook functionality enabled
+ENABLE_QUANTBOOK=true uvx quantconnect-mcp
+
 # HTTP transport
 MCP_TRANSPORT=streamable-http MCP_PORT=8000 uvx quantconnect-mcp
+
+# Full configuration example
+ENABLE_QUANTBOOK=true \
+LOG_LEVEL=DEBUG \
+MCP_TRANSPORT=streamable-http \
+MCP_PORT=8000 \
+uvx quantconnect-mcp
 ```
 
-### 4. **Interact with Natural Language**
+### 4. **QuantBook Container Functionality (Optional)**
+
+The server supports optional QuantBook functionality that runs research environments using lean-cli managed Docker containers. This provides:
+
+- **🐳 lean-cli Integration**: Uses official QuantConnect lean-cli for container management
+- **📔 Jupyter Notebook Environment**: Code executes in `/LeanCLI/research.ipynb` with pre-initialized `qb`
+- **🔒 Enhanced Security**: Isolated containers with resource limits
+- **⚡ Scalable Sessions**: Multiple concurrent research sessions with automatic cleanup
+- **📊 Interactive Analysis**: Execute Python code with full QuantConnect research libraries
+
+#### **Requirements**
+- Docker installed and running
+- lean-cli installed: `pip install lean`
+- Install with QuantBook support: `pip install "quantconnect-mcp[quantbook]"`
+- Set environment variable: `ENABLE_QUANTBOOK=true`
+
+#### **Key Features**
+- QuantBook (`qb`) is pre-initialized in Jupyter notebooks
+- Research notebooks located at `/LeanCLI/research.ipynb`
+- New notebooks must use the `Foundation-Py-Default` kernel for qb access
+- Automatic notebook modification for code execution
+- Compatible with QuantConnect's standard research environment
+
+### 5. **QuantBook Usage Notes**
+
+When using QuantBook functionality, keep these key points in mind:
+
+#### **📔 Notebook-Based Execution**
+- All QuantBook code executes by modifying `/LeanCLI/research.ipynb`
+- `qb` (QuantBook instance) is **pre-initialized** and ready to use
+- The LLM should not try to import or create QuantBook - just use `qb` directly, it's not available outside this environment
+
+### 6. **Interact with Natural Language**
 
 Instead of calling tools programmatically, you use natural language with a connected AI client (like Claude, a GPT, or any other MCP-compatible interface).
 
@@ -233,24 +291,26 @@ This MCP server is designed to be used with natural language. Below are examples
 | `update_file_content` | Update file content | `project_id`, `name`, `content` |
 | `update_file_name` | Rename file in project | `project_id`, `old_file_name`, `new_name` |
 
-### ◆ QuantBook Research Tools
+### ◆ QuantBook Research Tools (Optional - Requires ENABLE_QUANTBOOK=true)
 
 | Tool | Description | Key Parameters |
 |------|-------------|----------------|
-| `initialize_quantbook` | Create new research instance | `instance_name`, `organization_id`, `token` |
-| `list_quantbook_instances` | View all active instances | - |
-| `get_quantbook_info` | Get instance details | `instance_name` |
-| `remove_quantbook_instance` | Clean up instance | `instance_name` |
+| `initialize_quantbook` | Create new containerized research instance | `instance_name`, `memory_limit`, `cpu_limit`, `timeout` |
+| `list_quantbook_instances` | View all active container instances | - |
+| `get_quantbook_info` | Get container instance details | `instance_name` |
+| `remove_quantbook_instance` | Clean up container instance | `instance_name` |
+| `execute_quantbook_code` | Execute Python code via notebook modification | `code`, `instance_name`, `timeout` |
+| `get_session_manager_status` | Get container session manager status | - |
 
-### ◆ Data Retrieval Tools
+### ◆ Data Retrieval Tools (Optional - Requires ENABLE_QUANTBOOK=true)
 
 | Tool | Description | Key Parameters |
 |------|-------------|----------------|
-| `add_equity` | Add single equity security | `ticker`, `resolution`, `instance_name` |
-| `add_multiple_equities` | Add multiple securities | `tickers`, `resolution`, `instance_name` |
-| `get_history` | Get historical price data | `symbols`, `start_date`, `end_date`, `resolution` |
-| `add_alternative_data` | Subscribe to alt data | `data_type`, `symbol`, `instance_name` |
-| `get_alternative_data_history` | Get alt data history | `data_type`, `symbols`, `start_date`, `end_date` |
+| `add_equity` | Add single equity security via notebook | `ticker`, `resolution`, `instance_name` |
+| `add_multiple_equities` | Add multiple securities via notebook | `tickers`, `resolution`, `instance_name` |
+| `get_history` | Get historical price data via notebook | `symbols`, `start_date`, `end_date`, `resolution` |
+| `add_alternative_data` | Subscribe to alt data via notebook | `data_type`, `symbol`, `instance_name` |
+| `get_alternative_data_history` | Get alt data history via notebook | `data_type`, `symbols`, `start_date`, `end_date` |
 
 ### ◆ Statistical Analysis Tools
 
@@ -332,13 +392,31 @@ quantconnect-mcp/
 
 ### Environment Variables
 
+#### Core Server Configuration
 | Variable | Description | Default | Example |
 |----------|-------------|---------|---------|
 | `MCP_TRANSPORT` | Transport method | `stdio` | `streamable-http` |
 | `MCP_HOST` | Server host | `127.0.0.1` | `0.0.0.0` |
 | `MCP_PORT` | Server port | `8000` | `3000` |
 | `MCP_PATH` | HTTP endpoint path | `/mcp` | `/api/v1/mcp` |
 | `LOG_LEVEL` | Logging verbosity | `INFO` | `DEBUG` |
+| `LOG_FILE` | Log file path | None | `/var/log/quantconnect-mcp.log` |
+
+#### QuantConnect Authentication
+| Variable | Description | Required | Example |
+|----------|-------------|----------|---------|
+| `QUANTCONNECT_USER_ID` | Your QuantConnect user ID | ◉ Yes | `123456` |
+| `QUANTCONNECT_API_TOKEN` | Your QuantConnect API token | ◉ Yes | `abc123...` |
+| `QUANTCONNECT_ORGANIZATION_ID` | Organization ID (optional) | ◦ No | `org123` |
+
+#### QuantBook Container Configuration (Optional)
+| Variable | Description | Default | Example |
+|----------|-------------|---------|---------|
+| `ENABLE_QUANTBOOK` | Enable QuantBook functionality | `false` | `true` |
+| `QUANTBOOK_MEMORY_LIMIT` | Container memory limit | `2g` | `4g` |
+| `QUANTBOOK_CPU_LIMIT` | Container CPU limit | `1.0` | `2.0` |
+| `QUANTBOOK_SESSION_TIMEOUT` | Session timeout (seconds) | `3600` | `7200` |
+| `QUANTBOOK_MAX_SESSIONS` | Maximum concurrent sessions | `10` | `20` |
 
 ### System Resources
 

pyproject.toml

@@ -22,7 +22,12 @@ dependencies = [
     "seaborn>=0.13.2",
     "statsmodels>=0.14.4",
     "quantconnect-lean",
-    "quantconnect>=0.1.0",
+    "docker>=7.1.0",
+]
+
+[project.optional-dependencies]
+quantbook = [
+    "docker>=7.1.0",
 ]
 
 [project.scripts]