mirror of
https://github.com/sbroenne/mcp-server-excel.git
synced 2026-09-19 07:53:08 +08:00
Stefan Broenner
937b5681cf
* spec(006): Add .NET 10 upgrade feature specification Complete speckit workflow for upgrading from .NET 8 to .NET 10: - Update constitution.md to v1.1.0 with .NET 10 SDK requirement - Create spec.md with 4 user stories and 15 functional requirements - Create plan.md with implementation strategy and file inventory - Create research.md with SDK version, package compatibility findings - Create tasks.md with 38 tasks organized by user story - Update copilot-instructions.md with .NET 10 context Covers: SDK (global.json), 8 csproj files, 5 workflows, Dockerfile, and 7+ documentation files. No code changes - configuration only. * Add LLM-based tests for MCP Server using agent-benchmark Closes #340 - Add LLM test infrastructure with PowerShell runner (Run-LLMTests.ps1) - Create test scenario for excel_file and excel_worksheet tools - Configure Azure OpenAI with gpt-4.1 and gpt-5.2-chat agents - Update testing-strategy.instructions.md with LLM test documentation - All 20 tests passing with 100% success rate Test results: 464,502 tokens consumed across 20 tests Average time: ~7.4s per test * feat: optimize JSON token usage for LLM efficiency (#341) - Set WriteIndented=false for compact JSON output - Add DefaultIgnoreCondition.WhenWritingNull to omit null properties - Add [JsonPropertyName] attributes with short names to result types: - ResultBase: ok, err, fp - OperationResult: act - WorksheetInfo: n, i, v - RangeValueResult: sn, ra, d, r, c - TableInfo: n, sn, ra, hh, st, r, c, cols, tot - And more... - Update SerializeToolError to use short property names - Fix UUID templating syntax in LLM test file Token usage reduced from 464,502 to 443,601 (~4.5% reduction) Closes #341 * feat(mcp): JSON token optimization - tool splitting and parameter abbreviation Issue #341: Reduce JSON token consumption for LLM efficiency ## Tool Splitting (12 → 21 tools) - excel_range → excel_range, excel_range_edit, excel_range_format, excel_range_link - excel_table → excel_table, excel_table_column - excel_pivottable → excel_pivottable, excel_pivottable_field, excel_pivottable_calc - excel_datamodel → excel_datamodel, excel_datamodel_rel - excel_chart → excel_chart, excel_chart_config - excel_worksheet → excel_worksheet, excel_worksheet_style ## Parameter Name Abbreviation - sessionId → sid, sheetName → sn, tableName → tn - rangeAddress → addr, values → vals, excelPath → path - pivotTableName → ptn, chartName → cn, and more ## XML Documentation Optimization - Removed redundant action lists (schema provides) - Standardized 'Related:' cross-tool reference pattern - Trimmed verbose descriptions (~500+ tokens saved) ## Test Updates - McpServerSmokeTests: Updated all parameter names - McpServerIntegrationTests: Updated expected tool count (12 → 21) - Other integration tests: Updated parameter names Note: Pre-commit coverage audit requires update to account for tool splitting Build: 0 errors, 0 warnings Smoke test: 15 steps passed * docs: Update documentation for 21 tools, backfill changelog, add LLM testing callout - Updated all docs to reflect 21 tools with 182 operations (was 12 tools) - Backfilled CHANGELOG.md with missing versions 1.4.35-1.4.49 - Added JSON Token Optimization and LLM Integration Testing to changelog - Added LLM-Tested Quality callout to README, gh-pages, and VS Code extension - Added LLM-Tested Quality feature card to gh-pages index - Updated testing-strategy.instructions.md with LLM test guidance - Updated architecture-patterns.instructions.md with 21 tools reference - Fixed audit-core-coverage.ps1 to handle sub-tool enum grouping Files updated: - README.md, FEATURES.md, gh-pages/*.md - vscode-extension/CHANGELOG.md, vscode-extension/README.md - src/ExcelMcp.McpServer/README.md, src/ExcelMcp.CLI/README.md - tests/README.md, tests/ExcelMcp.McpServer.LLM.Tests/README.md - .github/instructions/*.md - scripts/audit-core-coverage.ps1 * test(llm): consolidate and improve LLM modification pattern tests - Rename excel-incremental-update-test.yaml to excel-modification-patterns-test.yaml - Consolidate tests from 9 sessions down to 4 focused sessions: - Range Updates: Formula canary (D1=1004) proves targeted cell updates - Table Operations: Table count canary verifies no delete/recreate - Chart Modifications: Chart count canary confirms title change only - Sheet Structural Changes: ROW() formulas prove proper row shifting - Add canary verification to detect 'delete and rebuild' anti-patterns - Simplify other test files: - excel-file-worksheet-test.yaml: 11 tests -> 2 consolidated tests - excel-range-test.yaml: 10 tests -> 2 consolidated tests - excel-table-test.yaml: 12 tests -> 2 consolidated tests - Remove unsupported tool_param_contains assertions (agent-benchmark limitation) - Remove custom system_prompt and rate_limits (use defaults) - Increase server_delay to 30s for reliability - Clean up CHANGELOG.md (remove maintenance releases) Addresses user feedback about 'small step-by-step changes instead of frequently deleting and rebuild' behavior. All 10 LLM tests passing (4 modification patterns + 6 other scenarios). * feat: upgrade to .NET 10 - Update SDK to .NET 10.0.100 - Update all source and test projects to target net10.0 - Update package versions to latest stable for .NET 10: - Microsoft.Extensions packages remain at 10.0.1 (latest available) - Spectre.Console at 0.54.0 - ModelContextProtocol at 0.5.0-preview.1 - Fix IDE0060 unused parameter warning in test class - Build succeeds with 0 warnings, 0 errors All projects now target net10.0 and build successfully. * ci: update to .NET 10 and document changelog - Update GitHub Actions workflows to use .NET 10 SDK: - build-mcp-server.yml: 8.0.x → 10.0.x - build-cli.yml: 8.0.x → 10.0.x - Update build artifact paths from net8.0 to net10.0 - Update CHANGELOG.md with .NET 10 upgrade details GitHub Actions now build and test against .NET 10.0. * refactor: Upgrade to C# 14 and finalize .NET 10 migration - Explicitly set LangVersion=14 in Directory.Build.props (was: latest) - Refactor telemetry code to use modern Dictionary initializer syntax - Apply C# 14 collection expressions for empty list patterns - Update workflow artifacts from net8.0 to net10.0 paths - Update all remaining .NET 8.0 references to .NET 10 across workflow and docs Files modified: 16 - Directory.Build.props - Core refactoring: ExcelMcpTelemetry.cs, OlapPivotTableFieldStrategy.cs, TableCommands.Data.cs - Workflow/documentation: .github/workflows/*.yml, vscode-extension/*, examples/*, docs/* * refactor: remove dead code, use LINQ, and add proper exception suppression comments - DataModelCommands.RenameTable.cs: Remove dead try-catch for COM rename (always fails), add CA1031 pragmas with justification - PivotTableCommands.Fields.cs: Simplify ListCubeFieldsAsync and ListRegularFieldsAsync by removing redundant try-catch wrappers - RenameNameRules.cs: Convert foreach loop to LINQ expression per code review feedback --------- Co-authored-by: Stefan Broenner <stefan.broenner@microsoft.comm>
Excel MCP Server - AI-Powered Excel Automation
Control Microsoft Excel with AI through GitHub Copilot - just ask in natural language!
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 - no Excel programming knowledge required.
🛡️ 100% Safe - Uses Excel's Native COM API - Zero risk of file corruption. Unlike third-party libraries that manipulate .xlsx files directly, this project uses Excel's official API ensuring complete safety and compatibility.
💡 Interactive Development - See results instantly in Excel. Create a query, run it, inspect the output, refine and repeat. Excel becomes your AI-powered workspace for rapid development and testing.
🧪 LLM-Tested Quality - Tool behavior validated with real AI agents using agent-benchmark. We test that LLMs correctly understand and use our tools.
Features
The Excel MCP Server provides 21 specialized tools with 182 operations for comprehensive Excel automation:
- 🔄 Power Query (1 tool, 10 ops) - Atomic workflows, M code management, load destinations
- 📊 Data Model/DAX (2 tools, 17 ops) - Measures, relationships, model structure
- 🎨 Excel Tables (2 tools, 24 ops) - Lifecycle, filtering, sorting, structured references
- 📈 PivotTables (3 tools, 30 ops) - Creation, fields, aggregations, calculated members/fields
- 📉 Charts (2 tools, 14 ops) - Create, configure, manage series and formatting
- 📝 VBA (1 tool, 6 ops) - Modules, execution, version control
- 📋 Ranges (4 tools, 42 ops) - Values, formulas, formatting, validation, protection
- 📄 Worksheets (2 tools, 16 ops) - Lifecycle, colors, visibility, cross-workbook moves
- 🔌 Connections (1 tool, 9 ops) - OLEDB/ODBC management and refresh
- 🏷️ Named Ranges (1 tool, 6 ops) - Parameters and configuration
- 📁 Files (1 tool, 6 ops) - Session management and workbook creation
- 🎨 Conditional Formatting (1 tool, 2 ops) - Rules and clearing
📚 Complete Feature Reference →
💬 Example Prompts
Data Transformation & Analysis:
- "Optimize all my Power Queries in this workbook for better performance"
- "Create a PivotTable from SalesData table showing top 10 products by region with sum and average"
- "Create a data model from the following tables ... "
- "Build a DAX measure calculating year-over-year growth with proper time intelligence"
- "Filter this table by Column Product = Sushi"
- *"Create a treemap chart from this table".
Formatting & Styling (No Programming Required):
- "Format the revenue columns as currency, make headers bold with blue background, and add borders to the table"
- "Apply conditional formatting to highlight values above $10,000 in red and below $5,000 in yellow"
- "Convert this data range to an Excel Table with style TableStyleMedium2, add auto-filters, and create a totals row"
Workflow Automation:
- "Find all cells containing 'Q1 2024' and replace with 'Q1 2025', then sort the table by Date descending"
- "Add data validation dropdowns to the Status column with options: Active, Pending, Completed"
- "Merge the header cells, center-align them, and auto-fit all column widths to content"
Quick Start
- Install this extension (you just did!)
- Ask Copilot in the chat panel:
- "List all Power Query queries in workbook.xlsx"
- "Create a DAX measure for year-over-year revenue growth"
- "Export all Powere Queires and VBA modules to .vba files for version control"
That's it! The extension automatically installs .NET 8 runtime and includes a bundled MCP server.
➡️ Learn more and see examples
Requirements
- Windows OS - Excel COM automation requires Windows
- Microsoft Excel 2016+ - Must be installed on your system
- .NET 8 Runtime - Automatically installed by the extension
Potential Issues
"Excel is not installed" error:
- Ensure Microsoft Excel 2016+ is installed on your Windows machine
- Try opening Excel manually to verify it works
"VBA access denied" error:
- VBA operations require one-time manual setup in Excel
- Go to: File → Options → Trust Center → Trust Center Settings → Macro Settings
- Check "Trust access to the VBA project object model"
Copilot doesn't see Excel tools:
-
Restart VS Code after installing the extension
-
Troubleshooting
-
Check Output panel → "Excel MCP Server" for connection status
Documentation & Support
- Complete Documentation - Full guides and examples
- Report Issues - Bug reports and feature requests
License
MIT License - see LICENSE
Built with GitHub Copilot | Powered by Model Context Protocol