Enhancement: Safe Automation of SharePoint/OneDrive Workbooks via Attach-to-Running-Instance

[ckelsoe]

Enhancement: Safe Automation of SharePoint/OneDrive Workbooks via Attach-to-Running-Instance

Status: Proposed enhancement with working implementation and verified test results. I would welcome the opportunity to discuss this with the project maintainer, as I am not as familiar with the full codebase and may have missed nuances that someone with deeper knowledge would catch.

The problem

Excel automation tools that create a new Excel.Application process cannot operate on files that are already open. They demand exclusive file access. For workbooks hosted on SharePoint or synced through OneDrive, this creates a serious gap: the tool either fails with a file-lock error, or it works around the lock by replacing the file on disk, which silently destroys the file's SharePoint identity.

When a file is replaced rather than edited in place, SharePoint treats it as a deletion followed by a creation. The filename stays the same. The content looks correct. But from SharePoint's perspective, it is a different file. Every sharing link breaks. Every permission disappears. Every version history entry is lost. Co-authoring state is destroyed. Power Automate flows pointed at the original file's item ID stop triggering. The user gets no warning that any of this happened.

Why this matters

Enterprise environments run on SharePoint. Workbooks are shared across teams, linked in Teams channels, embedded in wikis, referenced by Power Automate flows. Each file has a unique SharePoint item ID that ties together:

• Sharing links distributed across emails, Teams messages, and documentation
• Granular permissions managed by IT or the file owner
• Version history used for compliance, audit trails, and rollback
• Co-authoring state that lets multiple people edit simultaneously
• Comments, annotations, and threaded discussions stored in SharePoint
• Power Automate flows triggered by file changes

When automation replaces the file instead of editing it through Excel, all of those connections break silently. The filename stays the same. The content looks correct. But it is a different file with a different SharePoint item ID.

Why mcp-server-excel is the right foundation

The mcp-server-excel project made an excellent architectural choice by building on Excel's native COM interface rather than on file-format libraries (openpyxl, EPPlus, xlsxwriter, etc.). File-format libraries read and write .xlsx files as ZIP archives of XML. They bypass Excel entirely, which means they cannot participate in co-authoring, cannot refresh data connections, cannot evaluate formulas with full fidelity, and cannot preserve SharePoint file identity when writing back to a synced path.

COM interop, by contrast, drives Excel as an application. Every operation goes through the same interface that the user's keyboard and mouse use. This means the full power of Excel is available: real formula calculation, native pivot table support, Power Query refresh, VBA execution, and correct handling of every file format nuance that file-format libraries get wrong.

This architectural decision is what makes the proposed enhancement possible. Because mcp-server-excel already speaks COM, extending it to attach to a running instance is a natural step. The ExcelBatch class already manages an Excel.Application COM object on a dedicated STA thread. The ExcelContext that every downstream operation receives already holds a COM reference to the workbook. The only question is how that COM reference was obtained: by creating a new process, or by connecting to one that already exists. All 165+ operations work identically either way.

A file-format library could not be extended in this direction. COM interop can, and mcp-server-excel already built the foundation for it.

The solution: session attach

session attach builds on this COM foundation by connecting to the user's already-running Excel instance instead of creating a new one. The automation operates through the same COM interface that the keyboard and mouse use. Excel handles the OneDrive sync. SharePoint sees a normal edit. Co-authors see changes appear in real time.

No files are copied, replaced, or re-created. The workbook's SharePoint item ID, sharing links, permissions, version history, and co-authoring state all remain intact because the file was never closed and reopened. From SharePoint's perspective, an AI agent editing through session attach is indistinguishable from a human user typing into cells.

How it works

The feature adds a third session mode alongside the existing open (open a file in a new Excel process) and create (create a new file).

Standard mode creates a new Excel.Application process via Activator.CreateInstance, opens the file exclusively, and owns both the process and the workbook. When the session closes, it saves the workbook, quits Excel, and force-kills the process if necessary.

Attach mode connects to an existing Excel.Application process via oleaut32.dll GetActiveObject, finds the workbook by name in the already-open workbooks collection, and borrows a COM reference. When the session closes, it releases the COM reference and walks away. It does not close the workbook. It does not quit Excel. It does not touch the process.

The P/Invoke declaration that makes this possible:

[DllImport("oleaut32.dll", PreserveSig = false)]
private static extern void GetActiveObject(
    ref Guid rclsid,
    IntPtr pvReserved,
    [MarshalAs(UnmanagedType.IUnknown)] out object ppunk);

Marshal.GetActiveObject("Excel.Application") was available in .NET Framework but removed in .NET 5+. This P/Invoke to oleaut32.dll achieves the same result on .NET 10. The PreserveSig = false attribute converts COM HRESULT failures into catchable exceptions, so a missing Excel instance surfaces as a COMException with MK_E_UNAVAILABLE (0x800401E3) rather than a cryptic return code.

Architecture

All downstream operations (worksheets, ranges, tables, charts, pivots, Power Query, VBA, screenshots, conditional formatting) flow through ExcelContext, which holds three things: a workbook path string, an Excel.Application COM object, and an Excel.Workbook COM object. Every operation in the codebase receives this context. None of them care how the COM objects were obtained.

This means the change is isolated to the session creation path. The 165+ operations that already exist work identically in attach mode with zero modifications.

                           ┌──────────────────────────────────────────┐
  session open ──────────► │  ExcelBatch (STA thread + message pump)  │
  session create ────────► │                                          │
  session attach ────────► │  _excel: Excel.Application               │
                           │  _workbook: Excel.Workbook               │
                           │  _context: ExcelContext                  │
                           └──────────────┬───────────────────────────┘
                                          │
                                          ▼
                           ┌──────────────────────────────────────────┐
                           │  165+ operations                         │
                           │  (range, table, chart, pivot, PQ, VBA…)  │
                           │  All receive ExcelContext                │
                           │  All work unchanged in attach mode       │
                           └──────────────────────────────────────────┘

Code changes

Ten source files were modified. Four contain the core behavioral change. Six expose it through the CLI, MCP server, and service layer.

Core: ExcelBatch.cs

This is the file that manages the STA thread, the Excel COM lifecycle, and the workbook session. Three areas changed.

1. Attach via GetActiveObject instead of Activator.CreateInstance

Before (standard mode only):

Excel.Application tempExcel = (Excel.Application)Activator.CreateInstance(excelType)!;
tempExcel.Visible = _showExcel;
tempExcel.DisplayAlerts = false;

// Capture process ID, set AutomationSecurity...

After (attach mode branch added):

Excel.Application tempExcel;

if (_attachToRunning)
{
    // Connect to the user's running Excel — do not create a new process,
    // capture PID, set Visible/DisplayAlerts, or change AutomationSecurity
    try
    {
        Guid clsid = excelType.GUID;
        GetActiveObject(ref clsid, IntPtr.Zero, out object ppunk);
        tempExcel = (Excel.Application)ppunk;
    }
    catch (COMException ex) when (ex.HResult == unchecked((int)0x800401E3))
    {
        throw new InvalidOperationException(
            "No running Excel instance found. Open the workbook in Excel first, " +
            "then use attach mode.", ex);
    }
}
else
{
    // Standard mode: create a new Excel process
    tempExcel = (Excel.Application)Activator.CreateInstance(excelType)!;
    tempExcel.Visible = _showExcel;
    tempExcel.DisplayAlerts = false;
    // ... PID capture, AutomationSecurity (unchanged) ...
}

The attach branch deliberately skips every configuration step that standard mode performs. It does not set Visible (the user's Excel is already visible). It does not set DisplayAlerts (the user may want dialogs). It does not capture the process ID (it does not own the process). It does not set AutomationSecurity (the user's security settings should be respected).

2. Find workbook by name instead of opening by path

Before (standard mode only):

foreach (var path in _allWorkbookPaths)
{
    Excel.Workbook wb;
    string normalizedPath = Path.GetFullPath(path);

    if (_createNewFile) { /* ... */ }
    else
    {
        FileAccessValidator.ValidateFileNotLocked(path);
        wb = (Excel.Workbook)tempExcel.Workbooks.Open(path);
    }
}

After (attach branch added before the existing branches):

if (_attachToRunning)
{
    string targetName = Path.GetFileName(path);
    Excel.Workbook? found = null;
    foreach (Excel.Workbook openWb in tempExcel.Workbooks)
    {
        if (string.Equals(openWb.Name, targetName, StringComparison.OrdinalIgnoreCase))
        {
            found = openWb;
            break;
        }
    }
    if (found == null)
        throw new InvalidOperationException(
            $"Workbook '{targetName}' is not open in the running Excel instance.");
    wb = found;
    normalizedPath = wb.FullName; // May be a SharePoint URL
}
else if (_createNewFile) { /* unchanged */ }
else { /* unchanged */ }

The workbook's FullName property returns the SharePoint URL (e.g., https://company.sharepoint.com/teams/.../file.xlsx) rather than a local file path when the file is synced via OneDrive. This is stored as the session's workbook path and serves as the file's identity throughout the session.

3. Skip shutdown on dispose

Before (always closes workbook and quits Excel):

ExcelShutdownService.CloseAndQuit(_workbook, _excel, false, _workbookPath, _logger);

After (attach mode skips shutdown entirely):

if (_attachToRunning)
{
    // Release COM references only. Do NOT close workbook or quit Excel.
    _logger.LogDebug("Attach mode: releasing COM references without closing workbook or quitting Excel");
}
else
{
    ExcelShutdownService.CloseAndQuit(_workbook, _excel, false, _workbookPath, _logger);
}

The force-kill path in Dispose() is also guarded:

// Before:
if (_operationTimedOut && _excelProcessId.HasValue && _staThread != null && _staThread.IsAlive)

// After:
if (!_attachToRunning && _operationTimedOut && _excelProcessId.HasValue && _staThread != null && _staThread.IsAlive)

And IsExcelProcessAlive() returns true in attach mode since there is no captured PID to check:

public bool IsExcelProcessAlive()
{
    if (_disposed != 0) return false;
    if (_attachToRunning) return true;  // Added
    if (!_excelProcessId.HasValue) return false;
    // ...
}

Core: ExcelSession.cs

A new factory method alongside the existing BeginBatch:

public static IExcelBatch BeginAttached(string workbookName, TimeSpan? operationTimeout = null)
{
    if (string.IsNullOrWhiteSpace(workbookName))
        throw new ArgumentException("Workbook name is required", nameof(workbookName));

    return ExcelBatch.AttachToRunning(workbookName, logger: null, operationTimeout: operationTimeout);
}

Core: SessionManager.cs

A new AttachSession method alongside the existing CreateSession. The key difference: it skips File.Exists validation (the file may only exist as a SharePoint URL), skips the same-file-in-another-session check (inapplicable for attached sessions), and does not call TrackExcelProcess (the process is not owned by this session).

public string AttachSession(string workbookName, TimeSpan? operationTimeout = null,
    SessionOrigin origin = SessionOrigin.Unknown)
{
    string sessionId = Guid.NewGuid().ToString("N");
    IExcelBatch? batch = null;
    try
    {
        batch = _sessionCreationPipeline.Execute(
            () => ExcelSession.BeginAttached(workbookName, operationTimeout));

        _activeSessions.TryAdd(sessionId, batch);
        _sessionFilePaths[sessionId] = batch.WorkbookPath;
        _activeOperationCounts[sessionId] = 0;
        _showExcelFlags[sessionId] = true;
        _sessionOrigins[sessionId] = origin;
        _sessionCreatedAt[sessionId] = DateTime.UtcNow;

        // Do NOT add to _activeFilePaths — path may be a SharePoint URL
        // Do NOT call TrackExcelProcess — we don't own this process

        var result = sessionId;
        batch = null;
        return result;
    }
    catch (Exception ex)
    {
        throw new InvalidOperationException(
            $"Failed to attach to workbook '{workbookName}': {ex.Message}", ex);
    }
    finally { batch?.Dispose(); }
}

Core: ToolActions.cs

One line added to the FileAction enum:

[System.Text.Json.Serialization.JsonStringEnumMemberName("attach")]
Attach

Command surface: SessionCommands.cs (CLI)

A new SessionAttachCommand registered in the CLI. Takes a workbook name (not a file path) as its argument:

internal sealed class SessionAttachCommand : AsyncCommand<SessionAttachCommand.Settings>
{
    public override async Task<int> ExecuteAsync(CommandContext context, Settings settings,
        CancellationToken cancellationToken)
    {
        using var client = await DaemonAutoStart.EnsureAndConnectAsync(cancellationToken);
        var response = await client.SendAsync(new ServiceRequest
        {
            Command = "session.attach",
            Args = JsonSerializer.Serialize(new {
                workbookName = settings.WorkbookName,
                timeoutSeconds = settings.TimeoutSeconds
            }, ServiceProtocol.JsonOptions)
        }, cancellationToken);
        // ...
    }

    internal sealed class Settings : CommandSettings
    {
        [CommandArgument(0, "<WORKBOOK_NAME>")]
        [Description("Name of the workbook already open in Excel (e.g., budget.xlsx)")]
        public string WorkbookName { get; init; } = string.Empty;
    }
}

Command surface: Program.cs (CLI registration)

branch.AddCommand<SessionAttachCommand>("attach")
    .WithDescription("Attach to a workbook already open in the user's running Excel instance.");

Command surface: ExcelMcpService.cs (service routing)

A new "attach" case in the session command switch, a new HandleSessionAttach handler, and a new SessionAttachArgs class:

"attach" => HandleSessionAttach(request),

private ServiceResponse HandleSessionAttach(ServiceRequest request)
{
    var args = ServiceRegistry.DeserializeArgs<SessionAttachArgs>(request.Args);
    if (string.IsNullOrWhiteSpace(args?.WorkbookName))
        return new ServiceResponse { Success = false, ErrorMessage = "workbookName is required" };

    var sessionId = _sessionManager.AttachSession(args.WorkbookName,
        operationTimeout: timeout, origin: SessionOrigin.CLI);

    return new ServiceResponse
    {
        Success = true,
        Result = JsonSerializer.Serialize(new { success = true, sessionId, workbookName = args.WorkbookName },
            ServiceProtocol.JsonOptions)
    };
}

Command surface: ExcelFileTool.cs (MCP server)

A new AttachSessionAsync method and a new case in the action switch, so the MCP file tool supports action: "attach". The method sends session.attach through the service bridge, same as the CLI.

Usage

CLI:

excelcli -q session attach budget.xlsx
# Returns: {"success":true,"sessionId":"dee49aad...","workbookName":"budget.xlsx"}

excelcli -q range set-values --session dee49aad... --range-address A1 --values '[["Updated"]]'
excelcli -q session close --session dee49aad...
# Session closed. Workbook stays open. Excel keeps running.

MCP:

{ "action": "attach", "path": "budget.xlsx" }

Test results

The P/Invoke approach was validated on a live SharePoint-synced workbook before any production code was written. All tests ran on .NET 10.0.201, Windows 11 Enterprise, Microsoft 365 Excel (Version 16.0), against a workbook hosted on SharePoint and synced to the local machine via OneDrive.

#	Test	Result
1	oleaut32.dll GetActiveObject P/Invoke works on .NET 10	PASS
2	Retrieved Excel.Application can access Workbooks and find open workbook	PASS
3	Can add worksheets through attached COM reference	PASS
4	Can write cell values and create Excel Tables through attached COM reference	PASS
5	workbook.Save() through attached reference saves via Excel's native path	PASS
6	FullName remains SharePoint URL after save (file identity preserved)	PASS
7	Excel remains running after test app exits (no Quit() called)	PASS
8	OneDrive sync processes the save normally	PASS

After the changes were integrated into the full codebase, the complete solution built with zero errors and zero warnings. An end-to-end test on a OneDrive-synced workbook confirmed that session attach connected to the running Excel instance, data written via range set-values appeared in the workbook immediately, and session close released the COM references without closing the workbook or quitting Excel.

Co-authoring was also tested with a SharePoint-hosted workbook where the folder was synced to the local hard drive. The CLI made changes to the locally synced file through the attached Excel instance, and those changes appeared in the Excel Online view of the same sheet in real time, in the same way they would if the user were making changes manually. From SharePoint's perspective, the CLI session was indistinguishable from a human user editing the workbook.

Skill updates

The CLI skill (skills/excel-cli/) was updated so that AI agents know about session attach and when to use it. Changes were made to the Scriban template (skills/templates/SKILL.cli.sbn) and the shared behavioral rules (skills/shared/behavioral-rules.md) so they survive the build-time regeneration process.

Specific updates:

• SKILL.md description and triggers now include SharePoint, OneDrive, co-authoring, and attach
• Workflow checklist updated from session create/open to session create/open/attach
• Rule 1 (discovery table) added: "Is the file open in Excel?" with session attach as the action
• Rule 3 (session lifecycle) expanded with full session attach documentation: when to use it, the syntax (workbook name not file path), and the behavioral differences (does not close workbook, does not quit Excel, does not create a new process)
• Rule 8 (batch mode) updated to note that session.attach participates in auto-capture of session IDs
• Behavioral rules reference updated with the attach workflow alongside the existing open workflow

When an agent reads the updated skill, it will choose session attach over session open when the user's workbook is already open in Excel or is hosted on SharePoint/OneDrive.

What stays the same

Every existing workflow continues to work exactly as before. The session open command still creates a new Excel process, demands exclusive file access, and closes everything on session end. The session create command still creates new workbooks. The 165+ operations (range, table, chart, pivot, Power Query, DAX, VBA, conditional formatting, screenshots, slicers, data models) all route through the same ExcelContext interface and are unaware of which session mode created it.

The change is additive. No existing behavior was modified.