mirror of
https://github.com/sbroenne/mcp-server-excel.git
synced 2026-09-19 07:53:08 +08:00
Stefan Broenner
d72d8f8d1b
* chore: remove telemetry diagnostic output
* chore: update packages to .NET 10 and MCP SDK 0.4.1-preview.1
- Microsoft.Extensions.Hosting: 9.0.10 -> 10.0.0
- Microsoft.Extensions.Logging: 9.0.10 -> 10.0.0
- Microsoft.Extensions.Configuration: 9.0.10 -> 10.0.0
- Microsoft.Extensions.DependencyInjection: 9.0.10 -> 10.0.0
- System.Text.Json: 9.0.10 -> 10.0.0
- ModelContextProtocol: 0.4.0-preview.3 -> 0.4.1-preview.1
All packages forward-compatible with .NET 8.0 runtime.
No breaking changes - verified build passes with 0 warnings.
* refactor: migrate MCP tools from [Description] attributes to XML documentation
- Convert all 12 tool files to use XML docs (/// <summary>, /// <param>)
- XML docs processed by MCP SDK's XmlToDescriptionGenerator source generator
- Remove all CA1861 pragma warnings and [SuppressMessage] attributes (not needed)
- Remove dead code: ThrowUnknownAction() and invalid action error handlers
- Add GlobalUsings.cs for Chart and Range namespaces
- Update mcp-server-guide.instructions.md with NO EMOJIS rule
The XmlToDescriptionGenerator converts XML comments to [Description] attributes
at compile time, providing better IDE support and documentation integration.
* feat(mcp): add tool categories and remove outdated LLM guidance
- Add [McpMeta("category", "...")] to all 12 tools for better LLM discovery
- Remove unhelpful LLM guidance (suggestedNextActions, retryGuidance, workflowHint, operationContext)
- Update ExcelResourceProvider to use excel_file sessions
Follows principle: state facts, not guidance - LLMs figure out next steps
* fix: add prominent warning to prevent premature session close
- Update ServerInstructions in Program.cs to explicitly warn LLMs:
- WAIT for ALL pending tool calls before closing
- Closing while operations running causes failures
- Expand excel_file tool description with detailed session lifecycle
- Addresses race condition where close was called during parallel operations
* feat: add showExcel parameter to watch Excel during automation
- Add showExcel parameter to excel_file open action
- When true, Excel window becomes visible during operations
- Perfect for debugging, demos, and learning what AI is doing
Implementation:
- ExcelFileTool: Added showExcel parameter to ExcelFile() and OpenSessionAsync()
- SessionManager: Added showExcel parameter to CreateSession()
- ExcelSession: Added BeginBatch overload with showExcel parameter
- ExcelBatch: Sets Excel.Visible based on showExcel flag
Server instructions:
- Added prominent session close warnings (wait for all operations)
- LLM instructed to proactively offer showExcel for complex tasks
- Example prompt: 'Would you like me to show Excel so you can watch?'
Documentation updated:
- README.md: User-facing section with natural language examples
- FEATURES.md: Added to File Operations section
- INSTALLATION.md: Added tip after test installation step
- gh-pages/index.md: Added tip to Interactive Development feature
- McpServer README: Added to AI-Powered Workflows list
- VS Code extension copilot-instructions.md: LLM guidance
ExcelMcp Tests
⚠️ No Traditional Unit Tests: ExcelMcp has no unit tests. Integration tests ARE our unit tests because Excel COM cannot be meaningfully mocked. See
docs/ADR-001-NO-UNIT-TESTS.mdfor full architectural rationale.
Quick Start
# Development (fast feedback - excludes VBA tests)
dotnet test --filter "Category=Integration&RunType!=OnDemand&Feature!=VBA&Feature!=VBATrust"
# Pre-commit (comprehensive - excludes VBA tests)
dotnet test --filter "Category=Integration&RunType!=OnDemand&Feature!=VBA&Feature!=VBATrust"
# Session/batch changes (MANDATORY when modifying session/batch code)
dotnet test --filter "RunType=OnDemand"
# VBA tests (manual only - requires VBA trust enabled)
dotnet test --filter "(Feature=VBA|Feature=VBATrust)&RunType!=OnDemand"
Documentation
For complete testing guidance, see:
- Testing Strategy - Quick reference, templates, common mistakes
- Critical Rules - Mandatory development rules (Rule 14: SaveAsync)
Test Architecture
tests/
├── ExcelMcp.Core.Tests/ # Core business logic (Unit + Integration)
├── ExcelMcp.McpServer.Tests/ # MCP protocol layer (Unit + Integration)
├── ExcelMcp.CLI.Tests/ # CLI wrapper (Unit + Integration)
└── ExcelMcp.ComInterop.Tests/ # COM utilities (Unit + OnDemand)
Test Categories
| Category | Speed | Requirements | Run By Default |
|---|---|---|---|
| Unit | Fast (2-5 sec) | None | ✅ Yes (CI/CD) |
| Integration | Medium (10-20 min) | Excel + Windows | ✅ Yes (local) |
| OnDemand | Slow (3-5 min) | Excel + Windows | ❌ No (explicit only) |
Feature-Specific Tests
# Test specific feature only
dotnet test --filter "Feature=PowerQuery&RunType!=OnDemand"
dotnet test --filter "Feature=DataModel&RunType!=OnDemand"
dotnet test --filter "Feature=Tables&RunType!=OnDemand"
dotnet test --filter "Feature=PivotTables&RunType!=OnDemand"
dotnet test --filter "Feature=Ranges&RunType!=OnDemand"
dotnet test --filter "Feature=Connections&RunType!=OnDemand"
When to Run Which Tests
| Scenario | Command |
|---|---|
| Daily development | dotnet test --filter "Category=Integration&RunType!=OnDemand&Feature!=VBA" |
| Before commit | dotnet test --filter "Category=Integration&RunType!=OnDemand&Feature!=VBA" |
| Modified session/batch code | dotnet test --filter "RunType=OnDemand" (see Rule 3) |
| VBA development | dotnet test --filter "(Feature=VBA|Feature=VBATrust)&RunType!=OnDemand" |
VBA Testing
Why VBA Tests Are Excluded by Default
VBA tests are excluded from normal test runs because:
- Stable codebase - VBA features are mature with minimal changes
- Performance - Excluding VBA tests makes integration tests ~25% faster (10-15 min vs 15-20 min)
- Special requirements - VBA tests require VBA trust enabled in Excel settings
- Opt-in model - Explicit testing when VBA code changes, rather than every commit
When to Run VBA Tests
Run VBA tests manually when:
- Modifying VBA-related code (ScriptCommands, VbaTrustDetection)
- Adding new VBA features
- Before releasing VBA-related changes
- Troubleshooting VBA-specific issues
How to Run VBA Tests
# Run ONLY VBA tests
dotnet test --filter "(Feature=VBA|Feature=VBATrust)&RunType!=OnDemand"
# Run ALL tests including VBA (takes longer)
dotnet test --filter "Category=Integration&RunType!=OnDemand"
VBA Test Files
All VBA tests are tagged with [Trait("Feature", "VBA")] or [Trait("Feature", "VBATrust")]:
tests/ExcelMcp.Core.Tests/Integration/Commands/Script/
- ScriptCommandsTests.cs
- ScriptCommandsTests.Lifecycle.cs
- VbaTrustDetectionTests.ScriptCommands.cs
- VbaTrustDetectionTests.cs
tests/ExcelMcp.CLI.Tests/Integration/Commands/
- ScriptAndSetupCommandsTests.cs
VBA Trust Setup
VBA tests require VBA trust enabled in Excel:
# Enable VBA trust (required for VBA tests)
Set-ItemProperty -Path "HKCU:\Software\Microsoft\Office\16.0\Excel\Security" -Name "AccessVBOM" -Value 1
# Verify setting
Get-ItemProperty -Path "HKCU:\Software\Microsoft\Office\16.0\Excel\Security" -Name "AccessVBOM"
Security Note: Only enable VBA trust in development environments. Production systems should keep this disabled.
Key Principles
- ✅ File Isolation - Each test creates unique file (no sharing)
- ✅ Binary Assertions - Pass OR fail, never "accept both"
- ✅ Verify Excel State - Always verify actual Excel state after operations
- ❌ No SaveAsync - Unless testing persistence (see Rule 14)
Getting Help
- Test failures: Check test output for detailed error messages
- Excel issues: Ensure Excel 2016+ installed and activated
- Session/batch issues: Run OnDemand tests to verify cleanup
- Writing tests: See Testing Strategy