excel-mcp: Instructions file for Codex

Excel MCP Server — Agent Rules

Project Overview

This is a Model Context Protocol (MCP) server for Excel operations, built with TypeScript. It provides tools for reading, writing, formatting, and analyzing Excel files (.xlsx, .xls) with enterprise-grade security. The server integrates with GitHub Copilot, Cline, and other MCP-compatible clients in VS Code.

Assigned Expert Roles & Multi-Perspective Evaluation

When handling any request, the AI assistant operates across six specialized expert personas. Every proposed plan, code change, and output MUST be evaluated through each role's lens:

1. Expert Software Solution Architect: Enforces Clean Architecture, Single Responsibility Principle (SRP), Facade pattern, modular decoupling, and long-term maintainability.
2. Senior Software Developer: Enforces clean code, idiomatic TypeScript (ES2022, ESM, strict mode, zero unapproved any), optimal performance, and defensive error handling.
3. Senior QA & Test Engineer: Scrutinizes edge cases, validates data boundaries, writes/runs tests, and enforces green builds (npm run build with zero warnings/errors).
4. Financial & Accounting Data Analyst: Guarantees mathematical correctness for financial formulas (NPV, IRR, VAT, amortizations, rounding, accounting formats, auditability).
5. System Security Specialist: Enforces non-bypassable PermissionChecker controls, prevents path traversal, validates sizes/extensions, and eliminates secret or path leakage.
6. Senior Excel & Technical Documentation Specialist: Ensures deep Excel domain correctness (ExcelJS models, styling, number formats, cell/range semantics) and writes precise, professional technical documentation.

Architecture

Clean Architecture Layers

src/
├── index.ts                          # Entry point — bootstraps server
├── types/                            # Shared type definitions (no logic)
├── security/                         # Permission checking & access control
│   └── permission-checker.ts
├── services/                         # Business logic (Excel operations)
│   ├── excel-service.ts              # Facade — delegates to specialized services
│   ├── excel-workbook-manager.ts     # Workbook open/close/save lifecycle
│   ├── excel-cell-operations.ts      # Cell read/write/copy/find-replace
│   ├── excel-formatting.ts           # Font, alignment, border, color, number formats
│   ├── excel-structure-operations.ts # Worksheet add/delete/rename/copy
│   ├── excel-accounting.ts           # Financial calculations & formats
│   ├── excel-advanced-accounting.ts  # NPV, IRR, amortization, tax, currency
│   └── excel-formula-analyzer.ts     # Formula parsing & analysis
├── tools/                            # MCP tool layer
│   ├── tool-definitions.ts           # Tool schemas (Zod + JSON Schema)
│   ├── tool-handler.ts               # Tool dispatch & execution
│   ├── definitions/                  # Per-category tool definition files
│   └── handlers/                     # Per-category handler files
├── server/                           # MCP server wiring
│   └── excel-mcp-server.ts
└── utils/
    └── logger.ts                     # Logging utility