mcp-server-excel: Instructions file for Codex

ExcelMcp agent instructions

ExcelMcp automates installed desktop Excel through COM on Windows. Use PowerShell 7.4 or later (pwsh) and the SDK selected by global.json. Desktop Excel is required for COM tests; GitHub-hosted runners do not have Excel.

MCP Server and excelcli are equal entry points: behavior, defaults, validation, results, and documentation must agree.

ExcelMcp always operates in the current user's Windows session and security context. Discover and reconnect only to Excel instances accessible in that context; do not seek access to other users' sessions or elevate permissions. Workbook location does not change this scope. Running in the user's context does not authorize changes to unrelated workbooks.

Code Review Rules

Report high-confidence defects introduced by the change, not style or unrelated cleanup. Establish a reachable failure, its affected caller/workbook state, and the missing or misleading test evidence. Review does not require builds, dependency installation, or edits unless requested.

• Trace changed catches and fallbacks through their caller. Logging an error then returning empty/default data, skipping a failed item, or reporting success still hides failure. Optional COM reads may suppress only exact documented unavailable-member HRESULTs; 0x800A03EC is not a missing-property diagnosis. Unexpected COM errors must fail with their context.
• Check failure ownership: Core leaves execution errors to batch/Service; transport boundaries may convert failures, not erase them. Preserve original cause, cancellation, timeout, session recovery, and exact partial state. Cancellation is not rollback; reject unrequested workbook cleanup.
• Review COM ownership across every exit and failure path. Acquired references need finally release, not session-owned objects. Process cleanup needs PID/start-time identity and retained handles. EXL011 and EXL005 reject dynamic declarations and late-bound calls in production and test builds.
• Follow changed source contracts through generated Service, CLI options/batch JSON, MCP schemas, and manual exceptions. Names, defaults, validation, results, and timeouts must agree. Adapters must not acquire Core/session ownership.
• Check MCP protocol output, including bootstrap paths, not just direct console calls. Telemetry must never wait on setup, export, flush, or disposal on product paths, delay incremental results/cancellation/exit, or alter results/errors. Bound queues; verify local delivery separately from responsiveness and privacy.
• Check guidance against implemented inputs, defaults, and capabilities. Distinguish MCP snake_case inputs, CLI flags, nested JSON keys, and outputs. Flag nonexistent actions, forced unrequested work, emojis, required unattended screenshots, and consent prose presented as implemented server elicitation.
• Tests must establish returned fields and actual Excel state, including the partial state after failure; success alone or mocked COM is not evidence. Compiler checks catch supported patterns, not correct HRESULT semantics, complete COM ownership, runtime state, or matching entry-point behavior.
• Use ponytail-review when available after correctness/security review for concrete behavior-preserving simplifications. Required COM cleanup, validation, failure reporting, tests, and generated contracts are not bloat.