Implement security-first Power Query privacy levels and VBA trust guidance

.github/copilot-instructions.md

@@ -114,17 +114,56 @@ excelcli is a Windows-only command-line tool that provides programmatic access t
 - `cell-get-formula "file.xlsx" "Sheet" "A1"` - Get cell formula
 - `cell-set-formula "file.xlsx" "Sheet" "A1" "=SUM(B1:B10)"` - Set cell formula
 
-### VBA Script Management ⚠️ **Requires .xlsm files!**
+### VBA Script Management ⚠️ **Requires .xlsm files and manual VBA trust setup!**
 - `script-list "file.xlsm"` - List all VBA modules and procedures
 - `script-export "file.xlsm" "Module" "output.vba"` - Export VBA code to file
 - `script-import "file.xlsm" "ModuleName" "source.vba"` - Import VBA module from file
 - `script-update "file.xlsm" "ModuleName" "source.vba"` - Update existing VBA module
 - `script-run "file.xlsm" "Module.Procedure" [param1] [param2] ...` - Execute VBA macros with parameters
 - `script-delete "file.xlsm" "ModuleName"` - Remove VBA module
 
-### Setup Commands
-- `setup-vba-trust` - Enable VBA project access (one-time setup for VBA automation)
-- `check-vba-trust` - Check VBA trust configuration status
+**VBA Trust Setup (Manual, One-Time):**
+VBA operations require "Trust access to the VBA project object model" to be enabled in Excel settings. Users must configure this manually:
+1. Open Excel → File → Options → Trust Center → Trust Center Settings
+2. Select "Macro Settings"
+3. Check "✓ Trust access to the VBA project object model"
+4. Click OK twice to save
+
+If VBA trust is not enabled, commands will display step-by-step setup instructions. ExcelMcp never modifies security settings automatically - users remain in control.
+
+### Power Query Privacy Levels 🔒 **Security-First Design**
+
+Power Query operations that combine data from multiple sources support an optional `--privacy-level` parameter for explicit user consent:
+
+```powershell
+# Operations supporting privacy levels:
+excelcli pq-import "file.xlsx" "QueryName" "code.pq" --privacy-level Private
+excelcli pq-update "file.xlsx" "QueryName" "code.pq" --privacy-level Organizational
+excelcli pq-set-load-to-table "file.xlsx" "QueryName" "Sheet1" --privacy-level Public
+```
+
+**Privacy Level Options:**
+- `None` - Ignores privacy levels (least secure)
+- `Private` - Prevents sharing data between sources (most secure, recommended for sensitive data)
+- `Organizational` - Data can be shared within organization (recommended for internal data)
+- `Public` - For publicly available data sources
+
+**Environment Variable** (for automation):
+```powershell
+$env:EXCEL_DEFAULT_PRIVACY_LEVEL = "Private"  # Applies to all operations
+```
+
+If privacy level is needed but not specified, operations return `PowerQueryPrivacyErrorResult` with:
+- Detected privacy levels from existing queries
+- Recommended privacy level based on workbook analysis
+- Clear explanation of privacy implications
+- Guidance on how to proceed
+
+**Security Principles:**
+- ✅ Never auto-apply privacy levels without explicit user consent
+- ✅ Always fail safely on first attempt without privacy parameter
+- ✅ Educate users about privacy level meanings and security implications
+- ✅ LLM acts as intermediary for conversational consent workflow
 
 ## MCP Server for AI Development Workflows ✨ **NEW CAPABILITY**
 
@@ -144,6 +183,8 @@ The MCP server provides 6 domain-focused tools with 36 total actions, perfectly
 
 2. **`excel_powerquery`** - Power Query M code management (11 actions: list, view, import, export, update, delete, set-load-to-table, set-load-to-data-model, set-load-to-both, set-connection-only, get-load-config)
    - 🎯 **LLM-Optimized**: Complete Power Query lifecycle for AI-assisted M code development and data loading configuration
+   - 🔒 **Security-First**: Supports optional `privacyLevel` parameter (None, Private, Organizational, Public) for data combining operations
+   - ✅ **Privacy Consent**: Returns `PowerQueryPrivacyErrorResult` with recommendations when privacy level needed but not specified
 
 3. **`excel_worksheet`** - Worksheet operations and bulk data handling (9 actions: list, read, write, create, rename, copy, delete, clear, append)
    - 🎯 **LLM-Optimized**: Full worksheet lifecycle with bulk data operations for efficient AI-driven Excel automation
@@ -156,6 +197,8 @@ The MCP server provides 6 domain-focused tools with 36 total actions, perfectly
 
 6. **`excel_vba`** - VBA macro management and execution (6 actions: list, export, import, update, run, delete)
    - 🎯 **LLM-Optimized**: Complete VBA lifecycle for AI-assisted macro development and automation
+   - 🔒 **Security-First**: Returns `VbaTrustRequiredResult` with manual setup instructions when VBA trust is not enabled
+   - ✅ **User Control**: Never modifies VBA trust settings automatically - users configure Excel settings manually
 
 ### Development-Focused Use Cases ⚠️ **NOT for ETL!**
 
@@ -175,12 +218,36 @@ Developer: "This Power Query is slow and hard to read. Can you refactor it?"
 Copilot: [Uses excel_powerquery view -> analyzes M code -> excel_powerquery update with optimized code]
 ```
 
+**Power Query with Privacy Level (Security-First):**
+```text
+Developer: "Import this Power Query that combines data from multiple sources"
+Copilot: [Attempts excel_powerquery import without privacyLevel]
+         [Receives PowerQueryPrivacyErrorResult with recommendation: "Private"]
+         "This query combines data sources. Excel requires a privacy level. Based on your existing queries, I recommend 'Private' for maximum data protection. Shall I proceed with that?"
+Developer: "Yes, use Private"
+Copilot: [Uses excel_powerquery import with privacyLevel="Private"]
+```
+
 **VBA Enhancement:**
 ```text  
 Developer: "Add comprehensive error handling to this VBA module"
 Copilot: [Uses excel_vba export -> enhances with try-catch patterns -> excel_vba update]
 ```
 
+**VBA with Trust Guidance (Security-First):**
+```text
+Developer: "List the VBA modules in this file"
+Copilot: [Attempts excel_vba list]
+         [Receives VbaTrustRequiredResult with setup instructions]
+         "VBA trust access is not enabled. You need to configure this manually in Excel:
+         1. Open Excel → File → Options → Trust Center → Trust Center Settings
+         2. Select 'Macro Settings'
+         3. Check '✓ Trust access to the VBA project object model'
+         4. Click OK twice
+
+         This is a one-time setup. After enabling, VBA operations will work. Would you like me to try again once you've configured it?"
+```
+
 **Code Review:**
 ```text
 Developer: "Review this Power Query and suggest performance improvements"  

docs/CLI.md

@@ -27,8 +27,9 @@ $env:PATH += ";C:\Tools\excelcli"
 excelcli create-empty "test.xlsx"
 excelcli sheet-read "test.xlsx" "Sheet1"
 
-# For VBA operations (one-time setup)
-excelcli setup-vba-trust
+# For VBA operations (one-time manual setup in Excel)
+# Enable VBA trust: Excel → File → Options → Trust Center → Trust Center Settings
+# → Macro Settings → Check "Trust access to the VBA project object model"
 excelcli create-empty "macros.xlsm"
 ```
 

docs/COMMANDS.md

@@ -33,9 +33,11 @@ excelcli pq-view <file.xlsx> <query-name>
 **pq-import** - Create or import query from file
 
 ```powershell
-excelcli pq-import <file.xlsx> <query-name> <source.pq>
+excelcli pq-import <file.xlsx> <query-name> <source.pq> [--privacy-level <None|Private|Organizational|Public>]
 ```
 
+Import a Power Query from an M code file. If the query combines data from multiple sources and privacy level is not specified, you'll receive guidance on which privacy level to choose.
+
 **pq-export** - Export query to file
 
 ```powershell
@@ -45,9 +47,11 @@ excelcli pq-export <file.xlsx> <query-name> <output.pq>
 **pq-update** - Update existing query from file
 
 ```powershell
-excelcli pq-update <file.xlsx> <query-name> <code.pq>
+excelcli pq-update <file.xlsx> <query-name> <code.pq> [--privacy-level <None|Private|Organizational|Public>]
 ```
 
+Update an existing Power Query with new M code. If the query combines data from multiple sources and privacy level is not specified, you'll receive guidance on which privacy level to choose.
+
 **pq-refresh** - Refresh query data
 
 ```powershell
@@ -236,22 +240,54 @@ excelcli script-run "Analysis.xlsm" "CalculateTotal" "Sheet1" "A1:C10"
 excelcli script-delete <file.xlsm> <module-name>
 ```
 
-## Setup Commands
+## VBA Trust Configuration
 
-Configure VBA trust settings for automation.
+VBA operations require **"Trust access to the VBA project object model"** to be enabled in Excel settings. This is a one-time manual setup for security reasons.
 
-**setup-vba-trust** - Enable VBA project access
+### How to Enable VBA Trust
 
-```powershell
-excelcli setup-vba-trust
-```
+1. Open Excel
+2. Go to **File → Options → Trust Center**
+3. Click **"Trust Center Settings"**
+4. Select **"Macro Settings"**
+5. Check **"✓ Trust access to the VBA project object model"**
+6. Click **OK** twice to save settings
+
+After enabling this setting, VBA operations will work automatically. If VBA trust is not enabled, commands will display detailed instructions.
+
+**Security Note:** ExcelMcp never modifies security settings automatically. Users must explicitly enable VBA trust through Excel's settings to maintain security control.
+
+For more information, see [Microsoft's documentation on macro security](https://support.microsoft.com/office/enable-or-disable-macros-in-office-files-12b036fd-d140-4e74-b45e-16fed1a7e5c6).
 
-**check-vba-trust** - Check VBA trust configuration
+## Power Query Privacy Levels
+
+When Power Query combines data from multiple sources, Excel requires a privacy level to be specified for security. ExcelMcp provides explicit control through the `--privacy-level` parameter.
+
+### Privacy Level Options
+
+- **None** - Ignores privacy levels, allows combining any data sources (least secure)
+- **Private** - Prevents sharing data with other sources (most secure, recommended for sensitive data)
+- **Organizational** - Data can be shared within organization (recommended for internal data)
+- **Public** - Publicly available data sources (appropriate for public APIs)
+
+### Using Privacy Levels
 
 ```powershell
-excelcli check-vba-trust
+# Specify privacy level explicitly
+excelcli pq-import data.xlsx "WebData" query.pq --privacy-level Private
+
+# Set default via environment variable (useful for automation)
+$env:EXCEL_DEFAULT_PRIVACY_LEVEL = "Private"
+excelcli pq-import data.xlsx "WebData" query.pq
 ```
 
+If a privacy level is needed but not specified, the command will display:
+- Existing privacy levels in the workbook
+- Recommended privacy level based on your queries
+- Clear instructions on how to proceed
+
+**Security Note:** ExcelMcp never applies privacy levels automatically. Users must explicitly choose the appropriate level for their data security requirements.
+
 ## File Format Support
 
 - **`.xlsx`** - Standard Excel workbooks (Power Query, worksheets, parameters)

docs/INSTALLATION.md

@@ -51,8 +51,12 @@ excelcli.exe create-empty "workbook.xlsx"
 excelcli.exe pq-list "workbook.xlsx"
 excelcli.exe sheet-read "workbook.xlsx" "Sheet1" "A1:D10"
 
-# VBA operations (requires one-time setup)
-excelcli.exe setup-vba-trust
+# Power Query with privacy levels
+excelcli.exe pq-import "workbook.xlsx" "MyQuery" "query.pq" --privacy-level Private
+
+# VBA operations (requires one-time manual setup in Excel)
+# Enable VBA trust: Excel → File → Options → Trust Center → Trust Center Settings
+# → Macro Settings → Check "Trust access to the VBA project object model"
 excelcli.exe create-empty "macros.xlsm"
 excelcli.exe script-list "macros.xlsm"
 ```
@@ -142,14 +146,38 @@ $env:PATH += ";C:\Tools\ExcelMcp-CLI"
 
 ### Required for VBA script operations
 
-If you plan to use VBA script commands, configure VBA trust:
+If you plan to use VBA script commands, you must manually enable VBA trust in Excel (one-time setup):
+
+**Steps to Enable VBA Trust:**
+
+1. Open Microsoft Excel
+2. Go to **File → Options → Trust Center**
+3. Click **"Trust Center Settings"**
+4. Select **"Macro Settings"**
+5. Check **"✓ Trust access to the VBA project object model"**
+6. Click **OK** twice to save settings
+
+After enabling this setting, VBA operations will work automatically. If VBA trust is not enabled, commands will display these instructions.
+
+**Security Note:** ExcelMcp never modifies registry settings or security configurations automatically. Users must explicitly enable VBA trust through Excel's settings to maintain security control.
+
+---
+
+## 🔧 Power Query Privacy Configuration
+
+### Optional: Set default privacy level for automation
+
+For automated workflows, you can set a default privacy level via environment variable:
 
 ```powershell
-# One-time setup for VBA automation
-excelcli.exe setup-vba-trust
+# Set default privacy level (None, Private, Organizational, or Public)
+$env:EXCEL_DEFAULT_PRIVACY_LEVEL = "Private"
+
+# Make it permanent (optional)
+[Environment]::SetEnvironmentVariable("EXCEL_DEFAULT_PRIVACY_LEVEL", "Private", "User")
 ```
 
-This configures the necessary registry settings to allow programmatic access to VBA projects.
+Without this setting, commands will prompt for privacy level when needed, providing recommendations based on your existing queries.
 
 ---
 
@@ -174,8 +202,9 @@ This configures the necessary registry settings to allow programmatic access to
 
 **VBA access denied:**
 
-- Run the VBA trust setup command once: `excelcli.exe setup-vba-trust`
-- Restart Excel after running the trust setup
+- Enable VBA trust manually in Excel: File → Options → Trust Center → Trust Center Settings → Macro Settings → Check "Trust access to the VBA project object model"
+- Restart Excel after enabling the setting
+- If VBA commands still fail, ensure Excel is not running with elevated privileges
 
 ### Getting Help
 
@@ -191,12 +220,11 @@ This configures the necessary registry settings to allow programmatic access to
 | Category | Commands | Description |
 |----------|----------|-------------|
 | **File Operations** | `create-empty` | Create Excel workbooks (.xlsx, .xlsm) |
-| **Power Query** | `pq-list`, `pq-view`, `pq-import`, `pq-export`, `pq-update`, `pq-refresh`, `pq-loadto`, `pq-delete` | Manage Power Query M code |
+| **Power Query** | `pq-list`, `pq-view`, `pq-import`, `pq-export`, `pq-update`, `pq-refresh`, `pq-loadto`, `pq-delete` | Manage Power Query M code with optional `--privacy-level` parameter |
 | **Worksheets** | `sheet-list`, `sheet-read`, `sheet-write`, `sheet-create`, `sheet-rename`, `sheet-copy`, `sheet-delete`, `sheet-clear`, `sheet-append` | Worksheet operations |
 | **Parameters** | `param-list`, `param-get`, `param-set`, `param-create`, `param-delete` | Named range management |
 | **Cells** | `cell-get-value`, `cell-set-value`, `cell-get-formula`, `cell-set-formula` | Individual cell operations |
-| **VBA Scripts** | `script-list`, `script-export`, `script-import`, `script-update`, `script-run`, `script-delete` | VBA macro management |
-| **Setup** | `setup-vba-trust`, `check-vba-trust` | VBA configuration |
+| **VBA Scripts** | `script-list`, `script-export`, `script-import`, `script-update`, `script-run`, `script-delete` | VBA macro management (requires manual VBA trust setup in Excel) |
 
 > **📋 [Complete Command Reference →](COMMANDS.md)** - Detailed documentation for all 40+ commands
 

docs/SECURITY.md

@@ -47,20 +47,30 @@ ExcelMcp implements comprehensive security measures:
 ExcelMcp uses Excel COM automation with security safeguards:
 
 - **Macro Execution**: ExcelMcp can execute VBA macros when using script-run command
-- **VBA Trust**: VBA operations require trust settings to be configured (use setup-vba-trust)
+- **VBA Trust**: VBA operations require "Trust access to the VBA project object model" to be manually enabled in Excel settings (one-time setup)
 - **File Validation**: Strict file extension validation (.xlsx, .xlsm, .xls only)
 - **File Access**: ExcelMcp requires read/write access to Excel files with size validation
 - **Process Isolation**: Each command runs in a separate process that terminates after completion
 - **Excel Instance**: Creates temporary Excel instances that are properly cleaned up
 - **Input Sanitization**: All arguments validated for length and content
 
+### Power Query Privacy Levels
+
+ExcelMcp implements security-first privacy level handling:
+
+- **Explicit Consent**: Privacy levels must be specified explicitly via `--privacy-level` parameter or `EXCEL_DEFAULT_PRIVACY_LEVEL` environment variable
+- **No Auto-Application**: Privacy levels are never applied automatically without user consent
+- **Privacy Detection**: Analyzes existing queries to recommend appropriate privacy levels
+- **Clear Guidance**: Provides detailed explanations of privacy level implications
+- **Security Options**: Supports None, Private (most secure), Organizational, and Public levels
+
 ### VBA Security Considerations
 
 - **Macro Content**: VBA scripts imported via script-import will be executed when called
-- **Trust Settings**: setup-vba-trust modifies registry settings to allow VBA automation
+- **Manual Trust Setup**: VBA trust must be enabled manually through Excel's Trust Center settings (never modified automatically by ExcelMcp)
 - **File Format**: Only .xlsm files can contain and execute VBA code
 - **Code Injection**: Always validate VBA source files before importing
-- **Registry Changes**: VBA trust setup requires administrative privileges
+- **User Control**: ExcelMcp never modifies registry settings or security configurations automatically
 
 ### Best Practices for Users
 
@@ -69,8 +79,10 @@ ExcelMcp uses Excel COM automation with security safeguards:
 3. **Network Files**: Be cautious when processing files from network locations
 4. **Permissions**: Run ExcelMcp with minimal necessary permissions
 5. **Backup**: Always backup important Excel files before processing
-6. **VBA Trust**: Only enable VBA trust on systems where it's needed
+6. **VBA Trust**: Only enable VBA trust in Excel settings on systems where it's needed (manual one-time setup)
 7. **Code Review**: Review VBA scripts before execution, especially from external sources
+8. **Privacy Levels**: Choose appropriate Power Query privacy levels based on data sensitivity (Private for sensitive data, Organizational for internal data, Public for public APIs)
+9. **Environment Variables**: Use `EXCEL_DEFAULT_PRIVACY_LEVEL` environment variable for consistent automation security
 
 ### Known Limitations