mirror of https://github.com/sbroenne/mcp-server-excel.git synced 2026-09-19 07:53:08 +08:00

Files

T

Stefan Broenner 959094f52e feat: Re-add Rename operations + session timeout fix (#330 )

* docs: Update specs to reflect verified Data Model table rename limitation

VERIFIED FINDING (2025-12-20):
- ModelTable.Name is READ-ONLY in Excel COM API
- Direct assignment throws TargetParameterCountException (HResult: 0x8002000E)
- No workaround exists (tested: PQ rename, connection rename, refresh, save/reopen)

Updated files:
- research.md: Decision 2 corrected - rename is NOT POSSIBLE
- spec.md: User Story 2 now expects error message, not success
- data-model.md: Added Known Limitations section
- plan.md: Phase 4 simplified to attempt + return clear error
- tasks.md: US2 tasks simplified (no fallback logic)
- quickstart.md: Added limitation caveat for Data Model rename

* feat: Add Rename operations for Power Query and Data Model tables

This feature adds rename capabilities to both Power Query and Data Model tools:

- New 'Rename' action in excel_powerquery MCP tool
- New 'powerquery rename' CLI command
- Validates: empty names, no-op (same name), duplicate conflicts
- Case-insensitive conflict detection
- 10 integration tests covering all scenarios

- New 'RenameTable' action in excel_datamodel MCP tool
- New 'datamodel rename-table' CLI command
- Handles Excel COM limitation: ModelTable.Name is read-only
- For PQ-backed tables: renames underlying query, returns clear error explaining table name is cached
- For non-PQ tables: returns clear error about immutability
- 12 integration tests covering edge cases

- RenameNameRules.cs: Shared validation (Normalize, IsEmpty, IsNoOp, HasConflict)
- COM object cleanup in finally blocks per CRITICAL-RULES
- Exception propagation via batch.Execute() pattern
- 6 MCP contract tests + 2 smoke tests added

- Operation counts: MCP 180->182, CLI 172->174
- All READMEs updated (root, MCP Server, CLI, VS Code extension, gh-pages)
- FEATURES.md updated with new operations
- Quickstart examples for both CLI and MCP usage

Resolves spec: 001-rename-queries-tables
All 33 tasks complete (T001-T033)

* docs: Mark all tasks complete after implementation recovery

* fix: Increase session close timeouts to handle large files

The STA thread join timeout (10s) was shorter than the Excel.Quit() timeout (30s),
causing Dispose() to return before Excel finished closing. This resulted in
intermittent 'file still open' issues when session close was reported.

Changes:
- Excel.Quit() timeout: 30s -> 2 minutes (handles large file saves)
- STA thread join timeout: 10s -> 2.5 minutes (quit timeout + margin)

---------

Co-authored-by: Stefan Broenner <stefan.broenner@microsoft.comm>

2025-12-20 16:32:19 +01:00

ExcelMcp.CLI.Tests

perf: replace CreateUniqueTestFile with fixture-based file creation (#266 )

2025-12-04 09:06:26 +00:00

ExcelMcp.ComInterop.Tests

fix: resolve code scanning alerts for generic catch clauses (#319 )

2025-12-16 19:12:48 +00:00

ExcelMcp.Core.Tests

feat: Re-add Rename operations + session timeout fix (#330 )

2025-12-20 16:32:19 +01:00

ExcelMcp.McpServer.Tests

feat: Re-add Rename operations + session timeout fix (#330 )

2025-12-20 16:32:19 +01:00

Directory.Build.props

refactor: simplify telemetry - always enabled, build-time connection string (#246 )

2025-12-01 13:34:39 +00:00

README.md

fix: CodeQL useless-assignment violation in ExcelRangeTool.SetStyleAsync + scripts cleanup (#120 )

2025-11-04 06:33:59 +00:00

README.md

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.md for 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