mcp-server-powerpoint: Instructions file for GitHub Copilot

CRITICAL RULES - MUST FOLLOW

NON-NEGOTIABLE rules for all PowerPointMcp development

Rule 1: Success/ErrorMessage Invariant

NEVER Success = true with a non-null ErrorMessage. Set Success only in the success path; the field defaults to false (or is set explicitly false) alongside ErrorMessage on every failure path.

Why Critical: Confuses LLM callers and downstream consumers of the MCP JSON payload — a non-null error message on a "successful" result is silently ignored by most clients.

Rule 1b: No Exception Suppression in Core

NEVER wrap batch.Execute() in a try-catch that swallows the exception and returns an error result. Let exceptions propagate naturally out of Core commands — IPresentationBatch.Execute's underlying TaskCompletionSource plumbing (in PresentationBatch, ComInterop layer) already surfaces them to the caller.

The only place a catch-all belongs is the MCP tool boundary (PowerPointToolsBase.ExecuteToolAction in src/PowerPointMcp.McpServer/Tools/), which logs the HResult to stderr and serializes a structured error so the MCP host never crashes.

// CORRECT — Core: exceptions propagate
public ShapeOperationResult AddRectangle(IPresentationBatch batch, int slideIndex, ...)
{
    return batch.Execute((ctx, ct) => {
        // COM access — no try/catch here
    });
}

// WRONG — Core: swallowing and returning a fabricated error result
public ShapeOperationResult AddRectangle(IPresentationBatch batch, int slideIndex, ...)
{
    try { return batch.Execute(...); }
    catch (Exception ex) { return new ShapeOperationResult { Success = false, ErrorMessage = ex.Message }; }
}

Expected, caller-correctable failures ARE validated up front and returned as Success=false without throwing — e.g. an out-of-range slideIndex, a missing file, or an unknown sessionId. The distinction: validation failures are known preconditions checked BEFORE touching COM; unexpected COM/runtime exceptions are allowed to propagate and are only ever caught at the MCP tool boundary.