AGENTS.md · sbroenne/mcp-server-excel

Sections

1. Code Review Rules
2. Task-specific guidance
3. Implementation
4. Errors
5. Build and validation
6. Git and release

First lines (shown under the repo's MIT license)

# 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.

For an unfamiliar area, start with [CONTEXT.md](CONTEXT.md) for the system map
and terminology. [Architecture decisions](docs/DECISIONS.md) explain current
choices and tradeoffs; read the records relevant to an architectural change,
not the entire collection for every task. Surface conflicts before changing a
decision. Actionable rules belong here and in the applicable guides below.

Work requests are tracked in GitHub Issues; see
[issue tracker](docs/agents/issue-tracker.md). Contributor setup and client
instruction discovery are in [agent development](docs/agents/development.md).

## Task-specific guidance

Before changing files, read the matching guides below, including nested
`AGENTS.md` files. Native discovery differs between Copilot, Claude Code, and
Codex; launching at the root does not guarantee every nested file is loaded.
Paths are relative to the repository root.

| Work | Required guidance |
| --- | --- |
| `src/**/*.cs` | [Runtime boundaries](src/AGENTS.md) |
| Core commands/action models, Service, CLI, MCP, generators, or `.github/usage-analytics-weights.json` | [Generated contracts](src/ExcelMcp.Core/AGENTS.md) |
| Core or ComInterop C# | [COM safety](src/ExcelMcp.ComInterop/AGENTS.md) |
| Connection commands/sanitizer or connection tests/helpers/fixtures | [Connections](src/ExcelMcp.Core/Commands/Connection/AGENTS.md) |
| `tests/**/*.cs` | [Testing strategy](tests/AGENTS.md) |
| Workflows, project files, SDK/build configuration, PowerShell scripts, `.changeset/**` | [Build and release](scripts/AGENTS.md) |
| README/index files, FEATURES, CHANGELOG, SECURITY, PRIVACY, docs, specs, skills, or website | [Documentation](docs/AGENTS.md) |
| Skill sources, Core command metadata, generators, MCP, or Build-AgentSkills.ps1 | [Product agent guidance](skills/AGENTS.md) |
| MCP Server or MCP generator | [MCP boundaries](src/ExcelMcp.McpServer/AGENTS.md) |
| `llm-tests/**` | [LLM evaluations](llm-tests/AGENTS.md) |
| Repository/agent instructions, CONTEXT, or `docs/agents/**` | [Instruction maintenance](docs/AGENTS.md#instruction-maintenance) |
| `vscode-extension/**` | [Extension](vscode-extension/AGENTS.md) |
| `videos/excel-mcp-intro/**` | [Video](videos/excel-mcp-intro/AGENTS.md) |
| `videos/agentic-world-bank-briefing/**` | [Agentic workflow video](videos/agentic-world-bank-briefing/AGENTS.md) |

## Implementation

The build enforces supported COM, contract, result, dynamic-access, and test
patterns. Fix diagnostics at their source; a suppression needs a reason, not an
assumption that passing compilation proves runtime correctness.

- Use typed Excel interop in production and tests. EXL011 rejects dynamic
  declarations and late-bound operations; EXL005 rejects casts to `dynamic`.
  Comments do not exempt them. The compiler checks whether the referenced PIA
  exposes a member; runtime availability still needs real-Excel validation.
- The user-approved document-property exception is confined to
  `ExcelDocumentProperties` in ComInterop. Its private native COM calls cover
  only workbook property collections/items, resolve member identifiers from
  Excel, and validate item identities. Do not reuse it for other features or
  add a general member-name, reflection, or dynamic fallback. Compiler checks
  remain enabled everywhere.

- Core `[ServiceCategory]` interfaces drive generated Service, CLI, and MCP
  routing. Change contracts/generators, not emitted code. Follow a changed
  contract through both entry points, tests, and shared guidance.
- Keep agent-facing metadata, server instructions, skills, and recovery messages
  consistent with implemented behavior. Follow the product agent guidance above;
  do not edit generated or installed skill copies.
- Preserve exact tool, action, parameter, and flag names in agent guidance.
  When MCP and CLI spellings differ, show both explicitly or use native examples;
  do not replace identifiers with vague descriptions.
- Do not tell agents to create or retain workbook backup/recovery copies, or to
  work on duplicate workbooks as a prerequisite to requested edits. Explain
  destructive consequences without adding file-copy steps. Copying or exporting
  is appropriate only when part of the user's request.
- Production code must access workbook contents through Excel COM. Never open
  an Excel workbook file as a ZIP/OOXML package or parse/modify its internal XML
  outside tests. The isolated Power Query user-settings archive reader is not a
  workbook-content path. Pre-open binary container detection may read only
  IRM/AIP protection metadata; it must not parse workbook content.
- Behavioral changes require a focused failing regression test before the fix.
  Documentation/configuration-only changes do not need synthetic tests.
- MCP Server and `excelcli` are the only supported product entry points. Do not
  preserve or add public Core/ComInterop compatibility APIs for hypothetical
  external consumers when neither entry point uses them.
- Keep customer/workbook data, credentials, connection strings, and private
  paths out of public artifacts. Keep temporary notes outside the repository.
- ExcelMcp acts for the current user. Task-relevant workbook contents, names,
  formulas, VBA/Power Query code, and file paths may be read and returned to
  that user through supported operations; do not hide them merely because
  they are private. This is not public disclosure or permission to access
  unrelated workbooks. Credential protections still apply; do not put private
  information in public artifacts or usage reporting.
- Returning an owned Excel dialog's visible text to its user for troubleshooting
  is allowed; this is not public disclosure. Do not copy it into public artifacts
  or telemetry, read password/input values, or answer the dialog automatically.

## Errors

- Handle failures only where the layer owns recovery or failure transport.
  Preserve the original exception and operation context. Optional reads must not
  treat arbitrary COM failures as absent data. A deliberate best-effort boundary
  must explain what failed and why continuing cannot misrepresent the operation.
  Cleanup must preserve the primary failure as well as any cleanup failure.
- Do not automatically clean up or roll back workbook changes when an
  operation fails. Report the exact partial state and error so the agent can
  inspect the workbook and decide whether cleanup is appropriate.

## Build and validation

For telemetry development, use the local Aspire dashboard first; see
[local telemetry development](docs/DEVELOPMENT.md#local-development-with-telemetry).
Verify actual logs/traces from both `excelcli` and MCP, including short-lived CLI
commands, as well as non-blocking behavior when the receiver is unavailable or
stalled. Passing in-memory tests or fast shutdown alone does not prove delivery.
If Aspire is unavailable, report the blocker; do not fall back to production.
Sending test telemetry to production Azure or changing its ingestion rules