fix(powerquery): refresh error propagation and new features (#399, #400) (#401)

* fix(powerquery): refresh error propagation (#399)

BREAKING FIX: refresh action now properly throws on Power Query errors

ROOT CAUSE: Connection.Refresh() silently swallowed errors for worksheet
queries (InModel=false), returning success even when M code had errors.

FIX: Route worksheet queries through QueryTable.Refresh(false) which
properly throws exceptions. Data Model queries continue using
Connection.Refresh() which does throw errors correctly.

- Added RefreshQueryTableByName() helper for worksheet query refresh
- Updated Refresh() to detect query type and route accordingly
- 6 regression tests covering error propagation scenarios

Closes #399

* feat(powerquery): add Evaluate action for ad-hoc M code execution (#400)

New 'evaluate' action executes M code directly and returns tabular results
WITHOUT creating a permanent query in the workbook. Useful for:
- Testing M code before creating a permanent query
- One-off queries without polluting the workbook
- Ad-hoc data exploration and M code debugging

Implementation:
- Creates temp query + worksheet, refreshes, reads data, cleans up
- Errors propagate properly (invalid M code throws with error message)
- Returns PowerQueryEvaluateResult with columns, rows, counts

Changes:
- Added Evaluate to PowerQueryAction enum and ActionExtensions
- Added IPowerQueryCommands.Evaluate interface method
- Added PowerQueryCommands.Evaluate.cs implementation
- Added PowerQueryEvaluateResult type
- MCP Server: ExcelPowerQueryTool handler
- CLI: ExcelDaemon handler + PowerQueryCommand case
- 7 integration tests covering success/error scenarios
- Updated skills/prompts with evaluate guidance
- Updated operation counts: 210 → 211

Closes #400

* feat(powerquery): add mCodeFile parameter for M code from file

MCP Server excel_powerquery now accepts mCodeFile parameter as alternative to
inline mCode for create, update, and evaluate actions.

Same behavior as CLI --mcode-file option:
- If mCodeFile is provided, reads M code from file
- If both provided, mCodeFile takes precedence
- FileNotFoundException if file doesn't exist

Useful for large/complex queries stored in .m or .pq files.

* feat(vba): add vbaCodeFile parameter for VBA code from file

MCP Server excel_vba now accepts vbaCodeFile parameter as alternative to
inline vbaCode for import and update actions.

Same behavior as CLI --code-file option:
- If vbaCodeFile is provided, reads VBA code from file
- If both provided, vbaCodeFile takes precedence
- FileNotFoundException if file doesn't exist

Useful for large modules stored in .bas or .vba files.

* fix(table): auto-expand single cell range using CurrentRegion

* test(llm): add allowed_tools filter to MCP test for faster LLM execution

* docs: update CHANGELOG with mCodeFile, vbaCodeFile, and table CurrentRegion fix

* fix: use specific COMException instead of generic catch clause

Addresses CodeQL security finding - generic catch clause should specify
exception type. The catch handles expected COMException when ListObject
doesn't have a QueryTable.

---------

Co-authored-by: Stefan Broenner <[email protected]>

Author: sbroenne

CHANGELOG.md

@@ -10,6 +10,38 @@ This changelog covers all components:
 
 ## [Unreleased]
 
+### Fixed
+
+- **Power Query Refresh Error Propagation** (#399): Fixed bug where `refresh` action returned `success: true` even when Power Query had formula errors
+  - ROOT CAUSE: `Connection.Refresh()` silently swallows errors for worksheet queries (InModel=false)
+  - FIX: Now uses `QueryTable.Refresh(false)` for worksheet queries which properly throws errors
+  - Data Model queries (InModel=true) continue using `Connection.Refresh()` which does throw errors
+  - Errors now surface clearly: `"[Expression.Error] The name 'Source' wasn't recognized..."`
+
+- **Table Create Auto-Expand from Single Cell**: Fixed issue where `table create --range A1` created single-cell table
+  - ROOT CAUSE: Excel's `ListObjects.Add()` doesn't auto-expand from a single cell
+  - FIX: Now uses `Range.CurrentRegion` when single cell provided, capturing all contiguous data
+  - Prevents Data Model issues where tables only contain header column
+
+### Added
+
+- **Power Query Evaluate** (#400): New `evaluate` action to execute M code directly and return results
+  - Execute arbitrary M code without creating a permanent query
+  - Returns tabular results (columns, rows) in JSON format
+  - Automatically cleans up temporary query and worksheet
+  - Errors propagate properly (e.g., invalid M syntax throws with error message)
+  - Example: `excelcli powerquery evaluate --file data.xlsx --mcode "let Source = #table({\"Name\",...})"`
+
+- **MCP Power Query mCodeFile Parameter**: Read M code from file instead of inline string
+  - New `mCodeFile` parameter on `excel_powerquery` tool for `create`, `update`, `evaluate` actions
+  - Avoids JSON escaping issues with complex M code containing special characters
+  - File takes precedence if both `mCode` and `mCodeFile` provided
+
+- **MCP VBA vbaCodeFile Parameter**: Read VBA code from file instead of inline string
+  - New `vbaCodeFile` parameter on `excel_vba` tool for `create-module`, `update-module` actions
+  - Handles VBA code with quotes and special characters cleanly
+  - File takes precedence if both `vbaCode` and `vbaCodeFile` provided
+
 ## [1.5.14] - 2025-02-01
 
 ### Added

FEATURES.md

@@ -1,6 +1,6 @@
 # ExcelMcp - Complete Feature Reference
 
-**22 specialized tools with 210 operations for comprehensive Excel automation**
+**22 specialized tools with 211 operations for comprehensive Excel automation**
 
 ---
 
@@ -15,7 +15,7 @@
 
 ---
 
-## 🔄 Power Query & M Code (11 operations)
+## 🔄 Power Query & M Code (12 operations)
 
 **Atomic Operations** - Single-call workflows:
 - **List:** List all Power Query queries in workbook
@@ -29,6 +29,7 @@
 - **Get Load Config:** Get current load configuration
 - **Unload:** Remove data from all destinations (keeps query definition)
 - **Delete:** Remove Power Query from workbook
+- **Evaluate:** Execute M code directly and return results (without creating a permanent query)
 
 **Automatic M-Code Formatting:** M code is automatically formatted on write operations (Create, Update) using the powerqueryformatter.com API (by mogularGmbH, MIT License). Read operations return M code as stored in Excel. Formatting adds ~100-500ms network latency but dramatically improves readability with proper indentation, spacing, and line breaks. Graceful fallback returns original M code if formatting fails.
 
@@ -390,7 +391,7 @@
 | Category | Operations |
 |----------|-----------|
 | File Operations | 6 |
-| Power Query | 10 |
+| Power Query | 12 |
 | Data Model/DAX | 19 |
 | Excel Tables | 27 |
 | PivotTables | 30 |
@@ -402,7 +403,7 @@
 | VBA Macros | 6 |
 | Slicers | 8 |
 | Conditional Formatting | 2 |
-| **Total** | **209** |
+| **Total** | **211** |
 
 ---
 

README.md

@@ -18,7 +18,7 @@
 
 **Automate Excel with AI - A Model Context Protocol (MCP) server for comprehensive Excel automation through conversational AI.**
 
-**MCP Server for Excel** enables AI assistants (GitHub Copilot, Claude, ChatGPT) to automate Excel through natural language commands. Automate Power Query, DAX measures, VBA macros, PivotTables, Charts, formatting, and data transformations (22 tools with 210 operations).
+**MCP Server for Excel** enables AI assistants (GitHub Copilot, Claude, ChatGPT) to automate Excel through natural language commands. Automate Power Query, DAX measures, VBA macros, PivotTables, Charts, formatting, and data transformations (22 tools with 211 operations).
 
 ### CLI vs MCP Server
 
@@ -81,7 +81,7 @@ Download the `.mcpb` file from the [latest release](https://github.com/sbroenne/
 
 ## 🎯 What You Can Do
 
-**22 specialized tools with 210 operations:**
+**22 specialized tools with 211 operations:**
 
 - 🔄 **Power Query** (1 tool, 11 ops) - Atomic workflows, M code management, load destinations
 - 📊 **Data Model/DAX** (2 tools, 18 ops) - Measures with auto-formatted DAX, relationships, model structure
@@ -97,7 +97,7 @@ Download the `.mcpb` file from the [latest release](https://github.com/sbroenne/
 - �️ **Slicers** (1 tool, 8 ops) - Interactive filtering for PivotTables and Tables
 - �🎨 **Conditional Formatting** (1 tool, 2 ops) - Rules and clearing
 
-📚 **[Complete Feature Reference →](FEATURES.md)** - Detailed documentation of all 210 operations
+📚 **[Complete Feature Reference →](FEATURES.md)** - Detailed documentation of all 211 operations
 
 
 ## 💬 Example Prompts

gh-pages/404.md

@@ -17,7 +17,7 @@ The page you're looking for doesn't exist or has been moved.
 
 ## Quick Links
 
-- [Features](/features/) — All 22 tools and 210 operations
+- [Features](/features/) — All 22 tools and 211 operations
 - [Installation](/installation/) — Setup guides for VS Code, Claude, and CLI
 - [Changelog](/changelog/) — Release notes and version history
 - [GitHub Repository](https://github.com/sbroenne/mcp-server-excel) — Source code and issues

gh-pages/features.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: "Complete Feature Reference"
-description: "22 specialized tools with 210 operations for comprehensive Excel automation. Power Query, DAX, VBA, Charts, PivotTables, and more."
+description: "22 specialized tools with 211 operations for comprehensive Excel automation. Power Query, DAX, VBA, Charts, PivotTables, and more."
 keywords: "Excel MCP features, Power Query automation, DAX measures, VBA macros, Excel tools, MCP operations"
 permalink: /features/
 ---
@@ -10,7 +10,7 @@ permalink: /features/
   <div class="container">
     <div class="hero-content">
       <h1 class="hero-title">Complete Feature Reference</h1>
-      <p class="hero-subtitle">22 specialized tools with 210 operations for comprehensive Excel automation</p>
+      <p class="hero-subtitle">22 specialized tools with 211 operations for comprehensive Excel automation</p>
     </div>
   </div>
 </div>

gh-pages/index.md

@@ -102,7 +102,7 @@ It works with any MCP-compatible AI assistant like GitHub Copilot, Claude Deskto
 </div>
 </div>
 
-<p><a href="/features/">See all 22 tools and 210 operations →</a></p>
+<p><a href="/features/">See all 22 tools and 211 operations →</a></p>
 
 ## What Can You Do With It?
 
@@ -182,7 +182,7 @@ excelcli -q session close --session 1 --save
 
 ## Documentation
 
-📖 **[Complete Feature Reference](/features/)** — All 22 tools and 210 operations
+📖 **[Complete Feature Reference](/features/)** — All 22 tools and 211 operations
 
 📥 **[Installation Guide](/installation/)** — Setup for VS Code, Claude Desktop, other MCP clients, and CLI
 

mcpb/README.md

@@ -12,7 +12,7 @@ Excel MCP Server lets you automate Excel through conversation with Claude:
 - **Format & Style** - Conditional formatting, number formats, table styles
 - **Automate** - VBA macros, batch operations, data refresh
 
-**22 tools with 210 operations** for comprehensive Excel automation.
+**22 tools with 211 operations** for comprehensive Excel automation.
 
 ## Requirements
 

mcpb/manifest.json

@@ -4,7 +4,7 @@
   "display_name": "Excel (Windows)",
   "version": "1.1.5",
   "description": "Manage Sheets, Power Query, DAX, VBA, PowerPivot, Tables, Ranges, Charts, Formatting, Validation & more - requires Excel to be installed",
-  "long_description": "Enterprise-grade MCP server for Microsoft Excel automation. 22 specialized tools with 210 operations for Power Query, DAX, VBA, Charts, PivotTables, Conditional Formatting, and more. Windows-only, requires Microsoft Excel desktop application (2016 or later).",
+  "long_description": "Enterprise-grade MCP server for Microsoft Excel automation. 22 specialized tools with 211 operations for Power Query, DAX, VBA, Charts, PivotTables, Conditional Formatting, and more. Windows-only, requires Microsoft Excel desktop application (2016 or later).",
   "author": {
     "name": "Stefan Broenner",
     "url": "https://github.com/sbroenne"

skills/shared/excel_powerquery.md

@@ -28,6 +28,7 @@ Alternative path (for existing worksheet tables):
 
 - create: Import NEW query using inline `mCode` (FAILS if query already exists - use update instead)
 - update: Update EXISTING query M code + refresh data (use this if query exists)
+- evaluate: Execute M code directly, return results WITHOUT creating a permanent query (test before create!)
 - rename: Change query name (requires both `queryName` and `newName` parameters)
 - load-to: Loads to worksheet or data model or both (not just config change) - CHECKS for sheet conflicts
 - unload: Removes data from ALL destinations (worksheet AND Data Model) - keeps query definition
@@ -49,6 +50,22 @@ Alternative path (for existing worksheet tables):
 - Query already exists? → Use update (create will error "already exists")
 - Not sure? → Check with list action first, then use update if exists or create if new
 
+**RECOMMENDED WORKFLOW - Always evaluate before create**:
+
+1. `evaluate` → verify data looks correct (catches syntax errors, missing sources, wrong columns)
+2. `create` → stores validated query in workbook
+
+Skip evaluate only for trivial literal tables (`#table` with hardcoded values).
+
+**IF CREATE/UPDATE FAILS**: Use `evaluate` to get detailed Power Query error message, fix code, retry.
+This avoids polluting the workbook with broken queries and gives better error messages than COM exceptions.
+
+**Additional evaluate use cases**:
+
+- Execute one-off queries without creating permanent queries
+- Ad-hoc data exploration or debugging M code transformations
+- Returns tabular data (columns, rows) in JSON - no cleanup needed
+
 **List action and IsConnectionOnly**:
 
 - `IsConnectionOnly=true` means query has NO data destination (not in worksheet, not in Data Model)

src/ExcelMcp.CLI/Commands/PowerQueryCommand.cs

@@ -50,6 +50,7 @@ public override async Task<int> ExecuteAsync(CommandContext context, Settings se
             "load-to" => new { queryName = settings.QueryName, loadDestination = settings.LoadDestination },
             "get-load-config" => new { queryName = settings.QueryName },
             "unload" => new { queryName = settings.QueryName },
+            "evaluate" => new { mCode },
             _ => new { queryName = settings.QueryName }
         };
 
@@ -92,7 +93,7 @@ public override async Task<int> ExecuteAsync(CommandContext context, Settings se
     internal sealed class Settings : CommandSettings
     {
         [CommandArgument(0, "<ACTION>")]
-        [Description("The action to perform (e.g., list, view, create, update, refresh)")]
+        [Description("The action to perform (e.g., list, view, create, update, refresh, evaluate)")]
         public string Action { get; init; } = string.Empty;
 
         [CommandOption("-s|--session <SESSION>")]