sbroenne__mcp-server-excel/.github/copilot-instructions.md

GitHub Copilot Instructions - ExcelMcp

🎯 Optimized for AI Coding Agents - Modular, path-specific instructions

📋 Critical Files (Read These First)

ALWAYS read when working on code:

• CRITICAL-RULES.md - 19 mandatory rules (Success flag, COM cleanup, tests, etc.)
• Architecture Patterns - Batch API, command pattern, resource management

Read based on task type:

• Adding/fixing commands → Excel COM Interop
• Writing tests → Testing Strategy
• MCP Server work → MCP Server Guide
• Creating PR → Development Workflow
• Fixing bugs → Bug Fixing Checklist

Less frequently needed:

• Excel Connection Types - Only for connection-specific work
• README Management - Only when updating READMEs
• Documentation Structure - Only when creating docs

---

What is ExcelMcp?

ExcelMcp is a Windows-only toolset for programmatic Excel automation via COM interop, designed for coding agents and automation scripts.

Four Layers:

1. ComInterop (src/ExcelMcp.ComInterop) - Reusable COM automation patterns (STA threading, session management, batch operations, OLE message filter)
2. Core (src/ExcelMcp.Core) - Excel-specific business logic (Power Query, VBA, worksheets, parameters)
3. CLI (src/ExcelMcp.CLI) - Command-line interface for scripting
4. MCP Server (src/ExcelMcp.McpServer) - Model Context Protocol for AI assistants

---

🎯 Quick Reference

Test Commands

# ⚠️ CRITICAL: Integration tests take 45+ MINUTES for full suite
# ALWAYS use surgical testing - test only what you changed!

# Fast feedback (excludes VBA) - Still takes 10-15 minutes
dotnet test --filter "Category=Integration&RunType!=OnDemand&Feature!=VBA&Feature!=VBATrust"

# Surgical testing - Feature-specific (2-5 minutes per feature)
dotnet test --filter "Feature=PowerQuery&RunType!=OnDemand"
dotnet test --filter "Feature=Ranges&RunType!=OnDemand"
dotnet test --filter "Feature=PivotTables&RunType!=OnDemand"

# Session/batch changes (MANDATORY)
dotnet test --filter "RunType=OnDemand"

Code Patterns

// Core: NEVER wrap batch.Execute() in try-catch that returns error result
// Let exceptions propagate naturally - batch.Execute() handles them via TaskCompletionSource
public DataType Method(IExcelBatch batch, string arg1)
{
    return batch.Execute((ctx, ct) => {
        dynamic? item = null;
        try {
            // Operation code here
            item = ctx.Book.SomeObject;
            // For CRUD: return void (throws on error)
            // For queries: return actual data
            return someData;
        }
        finally {
            // ✅ ONLY finally blocks for COM cleanup
            ComUtilities.Release(ref item!);
        }
        // ❌ NO catch blocks that return error results
    });
}


// CLI: Wrap Core calls
public int Method(string[] args)
{
    try {
        using var batch = ExcelSession.BeginBatch(filePath);
        _coreCommands.Method(batch, arg1);
        return 0;
    } catch (Exception ex) {
        AnsiConsole.MarkupLine($"[red]Error:[/] {ex.Message.EscapeMarkup()}");
        return 1;
    }
}

// Tests: Use batch API
[Fact]
public void TestMethod()
{
    using var batch = ExcelSession.BeginBatch(_testFile);
    var result = _commands.Method(batch, args);
    Assert.NotNull(result); // Or other appropriate assertion
}

Tool Selection

• Code changes → replace_string_in_file (3-5 lines context)
• Find code → grep_search or semantic_search
• Check errors → get_errors
• Build/test/git → run_in_terminal

---

🔄 Key Lessons (Update After Major Work)

Success Flag: NEVER Success = true with ErrorMessage. Set Success in try block, always false in catch.

Batch API: Create NEW simple tests. CLI needs try-catch wrapping.

Excel Quirks: Type 3/4 both handle TEXT. RefreshAll() unreliable. Use queryTable.Refresh(false).

MCP Design: Prompts are shortcuts, not tutorials. LLMs know Excel/programming.

Tool Priority: replace_string_in_file > grep_search > run_in_terminal. Avoid PowerShell for code.

Pre-Commit: Search TODO/FIXME/HACK, delete commented code, verify tests, check docs.

PR Review: Check automated comments immediately (Copilot, GitHub Security). Fix before human review.

Surgical Testing: Integration tests take 45+ minutes. ALWAYS test only the feature you changed using --filter "Feature=<name>".

---

📚 How Path-Specific Instructions Work

GitHub Copilot auto-loads instructions based on files you're editing:

• tests/**/*.cs → Testing Strategy
• src/ExcelMcp.Core/**/*.cs → Excel COM Interop
• src/ExcelMcp.McpServer/**/*.cs → MCP Server Guide
• .github/workflows/**/*.yml → Development Workflow
• ** (all files) → CRITICAL-RULES.md

Modular approach = relevant context without overload.