### ExcelServer Start Method

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/INDEX.md

Provides the method signature for starting the ExcelServer. It returns an error if the server fails to start.

```go
func (s *ExcelServer) Start() error
```

--------------------------------

### Install Excel MCP Server via NPM (Windows)

Source: https://github.com/negokaz/excel-mcp-server/blob/main/README.md

Configuration for installing the Excel MCP Server on Windows using NPM. Sets the command to 'cmd' and specifies arguments for npx execution.

```json
{
    "mcpServers": {
        "excel": {
            "command": "cmd",
            "args": ["/c", "npx", "--yes", "@negokaz/excel-mcp-server"],
            "env": {
                "EXCEL_MCP_PAGING_CELLS_LIMIT": "4000"
            }
        }
    }
}
```

--------------------------------

### Example Usage of LoadConfig()

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/configuration.md

Demonstrates how to call LoadConfig(), handle potential validation issues, and access the configuration values.

```go
config, issues := LoadConfig()
if issues != nil {
    return imcp.NewToolResultZogIssueMap(issues), nil
}
pageSize := config.EXCEL_MCP_PAGING_CELLS_LIMIT
```

--------------------------------

### Install Excel MCP Server via Smithery CLI

Source: https://github.com/negokaz/excel-mcp-server/blob/main/README.md

Command to install the Excel MCP Server for Claude Desktop using the Smithery CLI. Ensures automatic installation for the specified client.

```bash
npx -y @smithery/cli install @negokaz/excel-mcp-server --client claude
```

--------------------------------

### Install Excel MCP Server via NPM (Other Platforms)

Source: https://github.com/negokaz/excel-mcp-server/blob/main/README.md

Configuration for installing the Excel MCP Server on non-Windows platforms using NPM. Directly uses 'npx' as the command.

```json
{
    "mcpServers": {
        "excel": {
            "command": "npx",
            "args": ["--yes", "@negokaz/excel-mcp-server"],
            "env": {
                "EXCEL_MCP_PAGING_CELLS_LIMIT": "4000"
            }
        }
    }
}
```

--------------------------------

### Example Usage of excel_describe_sheets

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/mcp-tools.md

Demonstrates how to call the excel_describe_sheets tool with a file path and the expected JSON response structure.

```json
Call excel_describe_sheets with:
{
    "fileAbsolutePath": "/absolute/path/to/file.xlsx"
}

Returns:
{
    "backend": "excelize",
    "sheets": [
        {
            "name": "Sheet1",
            "usedRange": "A1:C10",
            "tables": [],
            "pivotTables": [],
            "pagingRanges": ["A1:C5", "A6:C10"]
        }
    ]
}
```

--------------------------------

### Call excel_create_table Tool

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/mcp-tools.md

Example of how to call the excel_create_table tool with necessary parameters. Ensure the file path, sheet name, and table name are correctly specified.

```json
{
    "fileAbsolutePath": "/absolute/path/to/file.xlsx",
    "sheetName": "Sheet1",
    "range": "A1:D10",
    "tableName": "DataTable"
}
```

--------------------------------

### Print Area Pagination Example Calculation

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/pagination.md

Illustrates the calculation of pagination ranges based on a defined print area and horizontal page breaks. This example shows how ranges are split according to the specified breaks.

```text
Print Area: A1:Z500
H Page Breaks: [100, 250, 400]
Result: [
    A1:Z99,
    A100:Z249,
    A250:Z399,
    A400:Z500,
]
```

--------------------------------

### Example Input Cell Styles

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/style-registry.md

Defines sample cell styles, including font (bold, size) and fill (solid pattern with yellow color), for registration.

```go
styles := [][]*excel.CellStyle{
    {
        {
            Font: &excel.FontStyle{
                Bold: &trueBool,
                Size: &twelve,
            },
        },
        {
            Fill: &excel.FillStyle{
                Type: excel.FillTypePattern,
                Pattern: excel.FillPatternSolid,
                Color: []string{"#FFFF00"},
            },
        },
    },
}
```

--------------------------------

### Pagination Workflow Example: Second Call

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/pagination.md

Demonstrates a subsequent call to `excel_read_sheet` using the `nextRange` provided in the previous response. The response returns the requested data and the next sequential range.

```text
Request: excel_read_sheet("file.xlsx", "Sheet1", range="A154:Z306", ...)
Response: 
  - Data: A154:Z306
  - Metadata.nextRange: "A307:Z459"
```

--------------------------------

### ExcelizeFixedSizePagingStrategy Example 2 Calculation

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/pagination.md

Demonstrates a pagination scenario with a smaller page size than the total used cells, resulting in multiple pages, including a final partial page.

```plaintext
Another Example:
- Worksheet dimension: A1:Z500 (26 columns, 500 rows = 13000 cells)
- pageSize: 4000

Calculation:

totalCols = 26
rowsPerPage = 4000 / 26 = 153 (integer division)
Pages:
  1. A1:Z153 (26 cols × 153 rows = 3978 cells)
  2. A154:Z306 (26 cols × 153 rows = 3978 cells)
  3. A307:Z459 (26 cols × 153 rows = 3978 cells)
  4. A460:Z500 (26 cols × 41 rows = 1066 cells - final partial page)
```

--------------------------------

### Pagination Workflow Example: First Call

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/pagination.md

Illustrates the initial request to `excel_read_sheet` when no specific range is provided. The response includes the first data range and the `nextRange` for the subsequent request.

```text
Request: excel_read_sheet("file.xlsx", "Sheet1", range="", ...)
Response: 
  - Data: A1:Z153
  - Metadata.nextRange: "A154:Z306"
```

--------------------------------

### Example Usage for excel_copy_sheet

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/mcp-tools.md

Demonstrates how to call the excel_copy_sheet tool with the required parameters: absolute path to the Excel file, source sheet name, and destination sheet name.

```json
Call excel_copy_sheet with:
{
    "fileAbsolutePath": "/absolute/path/to/file.xlsx",
    "srcSheetName": "Template",
    "dstSheetName": "NewSheet"
}
```

--------------------------------

### ExcelDescribeSheets JSON Example

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/types.md

An example JSON payload representing the response from describing sheets. This shows the expected format for backend, sheets, ranges, and tables.

```json
{
    "backend": "excelize",
    "sheets": [
        {
            "name": "Sheet1",
            "usedRange": "A1:C10",
            "tables": [{"name": "DataTable", "range": "A1:C10"}],
            "pivotTables": [],
            "pagingRanges": ["A1:C5", "A6:C10"]
        }
    ]
}
```

--------------------------------

### ExcelizeFixedSizePagingStrategy Example 1 Calculation

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/pagination.md

Illustrates a pagination calculation where the page size matches the total used cells, resulting in a single page covering the entire range.

```plaintext
Given:
- Worksheet dimension: A1:D1000 (4 columns, 1000 rows = 4000 cells used)
- pageSize: 4000 (default)

Calculation:

totalCols = 4
rowsPerPage = 4000 / 4 = 1000
Result: [A1:D1000]  (single page covers entire used range)
```

--------------------------------

### RegisterStyle Example

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/style-registry.md

Demonstrates how to register a complex cell style, including font and fill properties. The function returns a slice of style IDs corresponding to the registered components of the cell style.

```go
style := &excel.CellStyle{
    Font: &excel.FontStyle{Bold: &trueBool},
    Fill: &excel.FillStyle{
        Type: excel.FillTypePattern,
        Pattern: excel.FillPatternSolid,
        Color: []string{"#FFFF00"},
    },
}
styleIDs := sr.RegisterStyle(style)
// styleIDs might be: ["f1", "l1"]
```

--------------------------------

### Example Error Response for Invalid Integer

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/configuration.md

This is an example of the structured error response received when a configuration value, such as EXCEL_MCP_PAGING_CELLS_LIMIT, is not a valid integer.

```text
Error: Invalid argument
Content:
  - "Invalid argument: EXCEL_MCP_PAGING_CELLS_LIMIT: must be a valid integer"
IsError: true
```

--------------------------------

### Example Usage for excel_format_range

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/mcp-tools.md

Illustrates how to call the excel_format_range tool. This example applies a left border, bold font, and yellow fill to the cell at A1, and leaves B1, A2, and B2 unformatted (null). Ensure the styles array dimensions match the specified range.

```json
Call excel_format_range with:
{
    "fileAbsolutePath": "/absolute/path/to/file.xlsx",
    "sheetName": "Sheet1",
    "range": "A1:B2",
    "styles": [
        [
            {
                "border": [{"type": "left", "style": "continuous", "color": "#000000"}],
                "font": {"bold": true, "size": 12},
                "fill": {"type": "pattern", "pattern": "solid", "color": ["#FFFF00"]}
            },
            null
        ],
        [null, null]
    ]
}
```

--------------------------------

### Example Usage of Excel Screen Capture Tool

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/mcp-tools.md

Demonstrates how to call the excel_screen_capture tool with specific parameters for file path, sheet name, and cell range. The expected output is a PNG image encoded in base64, along with metadata.

```json
{
    "fileAbsolutePath": "C:\\absolute\\path\\to\\file.xlsx",
    "sheetName": "Sheet1",
    "range": "A1:D10"
}
```

--------------------------------

### Graceful Fallback for Invalid Configuration

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/configuration.md

Illustrates how the system gracefully falls back to a default value when a configuration setting is invalid. For example, if EXCEL_MCP_PAGING_CELLS_LIMIT is set to an invalid value, it defaults to 4000.

```go
// If EXCEL_MCP_PAGING_CELLS_LIMIT="invalid", uses default 4000
config.EXCEL_MCP_PAGING_CELLS_LIMIT // = 4000
```

--------------------------------

### Get Paging Strategy

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/excel-interface.md

Creates a pagination strategy for large worksheets based on a specified maximum number of cells per page. Returns a PagingStrategy implementation or an error.

```go
func (w *Worksheet) GetPagingStrategy(pageSize int) (PagingStrategy, error) {
    // Implementation details omitted
}
```

--------------------------------

### Pagination Workflow Example: Final Call

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/pagination.md

Shows the final request in a pagination sequence, where the client requests the last available range. The response indicates that there are no more ranges by setting `nextRange` to an empty string.

```text
Request: excel_read_sheet("file.xlsx", "Sheet1", range="A460:Z500", ...)
Response: 
  - Data: A460:Z500
  - Metadata.nextRange: "" (empty - no more ranges)
```

--------------------------------

### Fixing Invalid File Path Input

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/errors.md

Illustrates incorrect and correct formats for specifying file paths. Ensure paths are absolute, starting with '/' on Unix-like systems or a drive letter on Windows.

```json
// Wrong
{"fileAbsolutePath": "data/file.xlsx"}

// Correct - Unix/Linux/macOS
{"fileAbsolutePath": "/home/user/data/file.xlsx"}

// Correct - Windows
{"fileAbsolutePath": "C:\\Users\\user\\data\\file.xlsx"}
```

--------------------------------

### Write to Excel Sheet Tool

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/mcp-tools.md

Use this tool to write data and formulas to an Excel sheet. It can create new sheets or append to existing ones. Ensure the file path is absolute and the range dimensions match the provided values. Formulas should be strings starting with '='.

```go
func AddExcelWriteToSheetTool(server *server.MCPServer)
func handleWriteToSheet(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error)
func writeSheet(fileAbsolutePath string, sheetName string, newSheet bool, rangeStr string, values [][]any) (*mcp.CallToolResult, error)
```

```json
{
    "fileAbsolutePath": "/absolute/path/to/file.xlsx",
    "sheetName": "Sheet1",
    "newSheet": false,
    "range": "A1:C2",
    "values": [
        ["Name", "Value", "Formula"],
        ["Item", "100", "=A2*2"]
    ]
}
```

--------------------------------

### Load Configuration and Handle Errors

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/configuration.md

This snippet demonstrates how to load configuration and check for fatal errors during server startup. If any issues are found, they are returned as structured errors.

```go
config, issues := LoadConfig()
if issues != nil {
    return imcp.NewToolResultZogIssueMap(issues), nil
}
```

--------------------------------

### Usage of excel_describe_sheets for Pagination

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/pagination.md

Demonstrates how to load configuration, obtain a paging strategy, and initialize a PagingRangeService using `excel_describe_sheets`. This sets up the service for subsequent range calculations.

```go
config, _ := LoadConfig()
strategy, err := sheet.GetPagingStrategy(config.EXCEL_MCP_PAGING_CELLS_LIMIT)
pagingService := excel.NewPagingRangeService(strategy)
pagingRanges := pagingService.GetPagingRanges()
```

--------------------------------

### Build and Development Commands

Source: https://github.com/negokaz/excel-mcp-server/blob/main/CLAUDE.md

Commands for building Go binaries and compiling TypeScript, watching for file changes, and debugging.

```bash
npm run build     # Build Go binaries + compile TypeScript
npm run watch     # Watch TypeScript files for changes
npm run debug     # Debug with MCP inspector
```

--------------------------------

### JSON Example: Single Validation Error Response

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/errors.md

An example of a JSON response indicating a single validation error, such as a sheet not being found. The error message is contained within the 'content' array.

```json
{
    "content": [
        {
            "type": "text",
            "text": "Invalid argument: sheetName: sheet not found: NonexistentSheet"
        }
    ],
    "isError": true
}
```

--------------------------------

### Validation Error Response Example

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/mcp-tools.md

This is an example of a structured error response returned by the validation library when an argument is invalid. It includes the type of error, content detailing the specific field and message, and an error flag.

```text
Type: Tool error result
Content: "Invalid argument: {field}: {message}"
IsError: true
```

--------------------------------

### NewStyleRegistry Constructor

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/style-registry.md

Creates and returns a new instance of StyleRegistry. It initializes all internal maps for style tracking and sets counters to zero, preparing the registry for style registrations.

```go
func NewStyleRegistry() *StyleRegistry
```

--------------------------------

### JSON Example: Multiple Validation Errors Response

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/errors.md

An example of a JSON response detailing multiple validation errors. Each error is represented as an object within the 'content' array, specifying the invalid argument and the reason.

```json
{
    "content": [
        {
            "type": "text",
            "text": "Invalid argument: fileAbsolutePath: Path 'relative/path' is not absolute"
        },
        {
            "type": "text",
            "text": "Invalid argument: sheetName: sheet not found: BadSheet"
        }
    ],
    "isError": true
}
```

--------------------------------

### excel_describe_sheets Configuration Usage

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/configuration.md

Shows how excel_describe_sheets loads configuration and uses the paging strategy.

```go
config, issues := LoadConfig()
strategy, err := sheet.GetPagingStrategy(config.EXCEL_MCP_PAGING_CELLS_LIMIT)
```

--------------------------------

### Get Worksheet Name

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/excel-interface.md

Retrieves the name of the worksheet. Returns the worksheet name as a string and an error if retrieval fails.

```go
func (w *Worksheet) Name() (string, error) {
    // Implementation details omitted
}
```

--------------------------------

### ExcelServer Type Definition

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/types.md

Defines the ExcelServer struct, which holds the main MCP server instance. It includes constructors and start methods.

```go
type ExcelServer struct {
    server *server.MCPServer
}

func New(version string) *ExcelServer
func (s *ExcelServer) Start() error
```

--------------------------------

### HTML Cell with Style

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/style-registry.md

Example of an HTML table cell that has a style reference. The 'style-ref' attribute points to a registered style, indicated by 'f1'.

```html
<td style-ref="f1">Styled</td>
```

--------------------------------

### Detect Formulas in Excel Values

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/README.md

Formulas in Excel values are identified by a leading '=' sign. This example shows a list of values, some of which are formulas.

```json
["=SUM(A1:A10)", "=B1*2", "regular value"]
```

--------------------------------

### PagingRangeService Definition

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/types.md

A service for managing pagination ranges, providing methods to get all ranges, filter remaining ones, and find the next range.

```go
type PagingRangeService struct {
    strategy PagingStrategy
}

func NewPagingRangeService(strategy PagingStrategy) *PagingRangeService
func (s *PagingRangeService) GetPagingRanges() []string
func (s *PagingRangeService) FilterRemainingPagingRanges(allRanges []string, knownRanges []string) []string
func (s *PagingRangeService) FindNextRange(allRanges []string, currentRange string) string
```

--------------------------------

### Parse Dimension String

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/pagination.md

Parses a dimension string into start and end column and row numbers. The function returns 1-based indices for columns and rows.

```Go
startCol, startRow, endCol, endRow, err := ParseRange(dimension)
```

--------------------------------

### Dual-Backend Design

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/README.md

Illustrates the fallback mechanism for opening files, prioritizing OLE for live Excel and falling back to Excelize for file-based operations.

```text
OpenFile()
├─ Try: OLE (Windows) → live Excel
└─ Fallback: Excelize → file-based
```

--------------------------------

### Get Worksheet Dimension

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/excel-interface.md

Identifies and returns the bounding box of all used cells in the worksheet in the format 'A1:C10'. An error is returned if the dimension cannot be determined.

```go
func (w *Worksheet) GetDimention() (string, error) {
    // Implementation details omitted
}
```

--------------------------------

### NewExcelizeFixedSizePagingStrategy Constructor

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/pagination.md

Creates a new instance of ExcelizeFixedSizePagingStrategy. It requires the desired page size and the worksheet to paginate. An error is returned if the worksheet's dimension cannot be determined.

```go
func NewExcelizeFixedSizePagingStrategy(pageSize int, worksheet *ExcelizeWorksheet) (*ExcelizeFixedSizePagingStrategy, error)
```

--------------------------------

### Open Excel File with Backend Selection

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/configuration.md

This function attempts to open an Excel file using the OLE backend on Windows first. If OLE fails or is not available, it falls back to using the Excelize backend for cross-platform compatibility.

```go
func OpenFile(absoluteFilePath string) (Excel, func(), error) {
    // Try OLE first (Windows only, requires live Excel)
    ole, releaseFn, err := NewExcelOle(absoluteFilePath)
    if err == nil {
        return ole, releaseFn, nil
    }
    // Fallback to Excelize (cross-platform, file-based)
    workbook, err := excelize.OpenFile(absoluteFilePath)
    if err != nil {
        return nil, func() {}, err
    }
    return NewExcelizeExcel(workbook), func() { workbook.Close() }, nil
}
```

--------------------------------

### Go Testing Commands

Source: https://github.com/negokaz/excel-mcp-server/blob/main/CLAUDE.md

Commands for running Go tests, including all tests, specific packages, or individual test cases.

```bash
go test ./...                           # Run all Go tests
go test ./internal/tools -v             # Run specific package tests
go test -run TestReadSheetData ./internal/tools  # Run specific test
```

--------------------------------

### HTML Cell without Style

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/style-registry.md

Example of an HTML table cell that does not have a style reference. This occurs when the cell's style is considered empty or nil by the Style Registry.

```html
<td>Unstyled</td>
```

--------------------------------

### Go Linting and Formatting Commands

Source: https://github.com/negokaz/excel-mcp-server/blob/main/CLAUDE.md

Commands for formatting Go code and checking for potential issues.

```bash
go fmt ./...      # Format Go code
go vet ./...      # Vet Go code for issues
```

--------------------------------

### Fallback to Excelize on OLE Initialization Failure

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/errors.md

This Go code demonstrates the fallback mechanism where the system attempts to use the OLE backend for Excel operations. If OLE initialization fails, it automatically falls back to using the Excelize library.

```Go
ole, releaseFn, err := NewExcelOle(absoluteFilePath)
if err == nil {
    return ole, releaseFn, nil
}
// Falls back to Excelize
workbook, err := excelize.OpenFile(absoluteFilePath)
```

--------------------------------

### Excelize GetFormula Method Implementation

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/excel-interface.md

Retrieves the formula for a given cell. Ensures the formula string starts with an '=' prefix. If no formula is found, it returns the cell's value.

```go
func (w *ExcelizeWorksheet) GetFormula(cell string) (string, error) {
    formula, err := w.file.GetCellFormula(w.sheetName, cell)
    if err != nil {
        return "", err
    }
    if formula == "" {
        return w.GetValue(cell)
    }
    if !strings.HasPrefix(formula, "=") {
        formula = "=" + formula
    }
    return formula, nil
}
```

--------------------------------

### LoadConfig() Function Signature and Schema

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/configuration.md

Defines the EnvConfig struct, the configuration schema using z.Struct, and the signature for the LoadConfig function.

```go
type EnvConfig struct {
    EXCEL_MCP_PAGING_CELLS_LIMIT int
}

var configSchema = z.Struct(z.Shape{
    "EXCEL_MCP_PAGING_CELLS_LIMIT": z.Int().GT(0).Default(4000),
})

func LoadConfig() (EnvConfig, z.ZogIssueMap)
```

--------------------------------

### ExcelServer Structure and Constructor

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/INDEX.md

Defines the ExcelServer struct and its constructor. The server is initialized with a version string.

```go
type ExcelServer struct {
    server *server.MCPServer
}

func New(version string) *ExcelServer
```

--------------------------------

### File Structure Overview

Source: https://github.com/negokaz/excel-mcp-server/blob/main/CLAUDE.md

Directory structure of the Excel MCP Server project.

```tree
cmd/excel-mcp-server/     # Main application entry point
internal/
  excel/                  # Excel abstraction layer
  server/                 # MCP server implementation  
  tools/                  # MCP tool implementations
launcher/                 # TypeScript launcher
memory-bank/              # Development context and progress
```

--------------------------------

### Get Cell Style

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/excel-interface.md

Retrieves the style information for a specified cell. Returns a pointer to a CellStyle struct, or nil if no style is applied. An error is returned if style retrieval fails.

```go
func (w *Worksheet) GetCellStyle(cell string) (*CellStyle, error) {
    // Implementation details omitted
}
```

--------------------------------

### excel_read_sheet Configuration Usage

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/configuration.md

Illustrates how excel_read_sheet loads configuration and applies it to the paging strategy for range determination.

```go
config, issues := LoadConfig()
strategy, err := worksheet.GetPagingStrategy(config.EXCEL_MCP_PAGING_CELLS_LIMIT)
```

--------------------------------

### Get Tables from Worksheet

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/excel-interface.md

Retrieves all tables present in the worksheet. Returns a slice of Table structs, each containing the table's name and range. An error is returned if retrieval fails.

```go
func (w *Worksheet) GetTables() ([]Table, error) {
    // Implementation details omitted
}
```

--------------------------------

### ExcelizeFixedSizePagingStrategy Constructor

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/pagination.md

Initializes a new ExcelizeFixedSizePagingStrategy. It retrieves the worksheet's dimension and calculates the number of rows per page based on the provided page size and the total number of columns in the used range.

```APIDOC
## NewExcelizeFixedSizePagingStrategy

### Description
Constructs a new `ExcelizeFixedSizePagingStrategy` instance.

### Constructor Signature
```go
func NewExcelizeFixedSizePagingStrategy(pageSize int, worksheet *ExcelizeWorksheet) (*ExcelizeFixedSizePagingStrategy, error)
```

### Parameters
- **pageSize** (int) - Required - Maximum number of cells allowed per page. Typically derived from `EXCEL_MCP_PAGING_CELLS_LIMIT`.
- **worksheet** (*ExcelizeWorksheet) - Required - The worksheet object to paginate.

### Returns
- `(*ExcelizeFixedSizePagingStrategy, error)` - A pointer to the created strategy instance and an error if the worksheet dimension cannot be read.
```

--------------------------------

### CreateNewSheet Method

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/excel-interface.md

Creates a new worksheet with the specified name. Errors if creation fails or if a sheet with that name already exists.

```go
func (e *Excel) CreateNewSheet(sheetName string) error
```

--------------------------------

### Add Excel Screen Capture Tool to MCP Server

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/mcp-tools.md

Initializes the Excel screen capture tool within the MCP server. This function is essential for enabling the screen capture functionality.

```go
func AddExcelScreenCaptureTool(server *server.MCPServer)
```

--------------------------------

### Get Cell Formula

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/excel-interface.md

Retrieves the formula string for a specified cell, always prefixed with '='. If no formula exists, it returns the cell's calculated value. An error is returned for invalid cell addresses.

```go
func (w *Worksheet) GetFormula(cell string) (string, error) {
    // Implementation details omitted
}
```

--------------------------------

### Usage of excel_read_sheet for Pagination Navigation

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/pagination.md

Shows how to use the PagingRangeService with `excel_read_sheet` to find the next available data range. This is crucial for clients to sequentially read paginated data from a large Excel file.

```go
allRanges := pagingService.GetPagingRanges()
currentRange := valueRange  // or first range if not specified
nextRange := pagingService.FindNextRange(allRanges, currentRange)
```

--------------------------------

### Get Pivot Tables from Worksheet

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/excel-interface.md

Retrieves all pivot tables present in the worksheet. Returns a slice of PivotTable structs, each containing the pivot table's name and range. An error is returned if retrieval fails.

```go
func (w *Worksheet) GetPivotTables() ([]PivotTable, error) {
    // Implementation details omitted
}
```

--------------------------------

### Project File Organization

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/README.md

Provides a hierarchical view of the project's documentation files and their approximate line counts.

```text
output/
├── INDEX.md                          # Start here
├── README.md                         # This file
├── types.md                          # 559 lines
├── configuration.md                  # 308 lines
├── errors.md                         # 488 lines
└── api-reference/
    ├── mcp-tools.md                 # 529 lines
    ├── excel-interface.md           # 458 lines
    ├── pagination.md                # 392 lines
    └── style-registry.md            # 489 lines

Total: 3,630 lines of documentation
```

--------------------------------

### Get Cell Value

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/excel-interface.md

Retrieves the calculated value of a specified cell as a string. For formula cells, it returns the computed result; for value cells, it returns the stored value. An error is returned for invalid cell addresses.

```go
func (w *Worksheet) GetValue(cell string) (string, error) {
    // Implementation details omitted
}
```

--------------------------------

### NewPagingRangeService Constructor

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/pagination.md

Constructs a new instance of PagingRangeService. It requires a PagingStrategy implementation to be provided during initialization.

```go
func NewPagingRangeService(strategy PagingStrategy) *PagingRangeService
```

--------------------------------

### GetBackendName Method

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/excel-interface.md

Identifies the active Excel backend. Use this to understand if OLE or Excelize is being used.

```go
func (e *Excel) GetBackendName() string
```

--------------------------------

### String Slice Type Conversion for Hashing

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/style-registry.md

Demonstrates the string representation of a string slice when converted for hashing.

```text
color: ["#FFFF00", "#FF0000"]  →  "color: [#FFFF00, #FF0000]"
```

--------------------------------

### Handle File Not Found Error

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/errors.md

This snippet shows how to handle a 'file not found' error when opening an Excel file. Ensure the provided file path is correct.

```Go
workbook, release, err := excel.OpenFile(fileAbsolutePath)
if err != nil {
    return nil, err
}
```

--------------------------------

### Excelize Backend: Screen Capture Not Supported

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/errors.md

This Go function indicates that the CapturePicture operation is not supported when using the Excelize backend. This typically occurs on non-Windows systems or when OLE is unavailable.

```Go
func (w *ExcelizeWorksheet) CapturePicture(captureRange string) (string, error) {
    return "", fmt.Errorf("CapturePicture is not supported in Excelize")
}
```

--------------------------------

### EnvConfig Structure

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/types.md

Defines environment configuration settings for the Excel MCP server, including a limit for cells per page.

```go
type EnvConfig struct {
    EXCEL_MCP_PAGING_CELLS_LIMIT int
}
```

--------------------------------

### Integer Validation with Minimum and Default

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/configuration.md

This Go code snippet defines a validation rule for an integer configuration value. It ensures the integer is greater than 0 and sets a default value of 4000 if none is provided or if the provided value is invalid. Use this for parameters that must be positive integers.

```go
z.Int().GT(0).Default(4000)
```

--------------------------------

### Register Style with Nil CellStyle Parameter

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/style-registry.md

Demonstrates that passing a nil CellStyle parameter to registerStyle results in an empty slice.

```go
registerStyle(nil)  // Returns: []string{}
```

--------------------------------

### Integer Type Conversion for Hashing

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/style-registry.md

Illustrates the string representation of an integer value when converted for hashing.

```text
size: 12    →  "size: 12"
```

--------------------------------

### ExcelizeFixedSizePagingStrategy CalculatePagingRanges Method

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/pagination.md

Calculates and returns a slice of strings, where each string represents a cell range for a page. This method implements the PagingStrategy interface.

```go
func (s *ExcelizeFixedSizePagingStrategy) CalculatePagingRanges() []string
```

--------------------------------

### Call excel_read_sheet Tool

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/mcp-tools.md

Demonstrates how to call the excel_read_sheet tool with specific parameters for reading an Excel sheet. Ensure the file path is absolute and parameters are correctly formatted.

```json
{
    "fileAbsolutePath": "/absolute/path/to/file.xlsx",
    "sheetName": "Sheet1",
    "range": "A1:C5",
    "showFormula": false,
    "showStyle": false
}
```

--------------------------------

### ExcelizeFixedSizePagingStrategy Definition

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/types.md

Implements a fixed-size pagination strategy for Excelize, calculating pagination ranges based on worksheet dimensions and a defined page size.

```go
type ExcelizeFixedSizePagingStrategy struct {
    pageSize  int
    worksheet *ExcelizeWorksheet
    dimension string
}

func NewExcelizeFixedSizePagingStrategy(pageSize int, worksheet *ExcelizeWorksheet) (*ExcelizeFixedSizePagingStrategy, error)
func (s *ExcelizeFixedSizePagingStrategy) CalculatePagingRanges() []string
```

--------------------------------

### Generate HTML Style Definitions

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/style-registry.md

Generates an HTML string containing style definitions for borders, fonts, fills, and number formats. Styles are grouped by type and sorted by ID.

```Go
func (sr *StyleRegistry) GenerateStyleDefinitions() string
```

```html
<h2>Style Definitions</h2>
<div class="style-definitions">
<code class="style language-yaml" id="b1">border: {type: left, style: continuous, ...}</code>
<code class="style language-yaml" id="f1">font: {bold: true, size: 12}</code>
<!-- ... more styles ... -->
</div>
```

--------------------------------

### Default Page Size Configuration

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/pagination.md

Retrieves the default page size limit for cells from the configuration. The default value is 4000.

```go
pageSize := config.EXCEL_MCP_PAGING_CELLS_LIMIT  // Default: 4000
```

--------------------------------

### ExcelCreateTableArguments Structure

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/types.md

Defines the arguments for the ExcelCreateTable tool. Requires file path, sheet name, range, and the desired table name.

```go
type ExcelCreateTableArguments struct {
    FileAbsolutePath string `zog:"fileAbsolutePath"`
    SheetName        string `zog:"sheetName"`
    Range            string `zog:"range"`
    TableName        string `zog:"tableName"`
}
```

--------------------------------

### NewStyleRegistry

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/style-registry.md

Constructs and returns a new StyleRegistry instance. The registry is initialized with empty maps for tracking different style types (borders, fonts, fills, number formats, decimals) and their corresponding counters.

```APIDOC
## NewStyleRegistry

### Description
Constructs and returns a new StyleRegistry instance. The registry is initialized with empty maps for tracking different style types (borders, fonts, fills, number formats, decimals) and their corresponding counters.

### Returns
* `*StyleRegistry` - A pointer to the newly created StyleRegistry.
```

--------------------------------

### Validate Integer Configuration in Go

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/errors.md

This Go code uses the 'z' library (likely Zod) to define a schema for configuration, specifically validating that EXCEL_MCP_PAGING_CELLS_LIMIT is a positive integer. Use this to ensure environment variables are correctly formatted and within acceptable ranges.

```go
var configSchema = z.Struct(z.Shape{
    "EXCEL_MCP_PAGING_CELLS_LIMIT": z.Int().GT(0).Default(4000),
})
```

--------------------------------

### Pagination System Logic

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/README.md

Explains the calculation for determining rows per page based on a default page size and column count, resulting in a list of cell ranges.

```text
pageSize (4000 default)
÷ columnCount
= rowsPerPage

Result: ["A1:Z100", "A101:Z200", ...]
```

--------------------------------

### AddExcelDescribeSheetsTool Function

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/mcp-tools.md

Function signature for adding the excel_describe_sheets tool to the MCP server.

```go
func AddExcelDescribeSheetsTool(server *server.MCPServer)
```

--------------------------------

### ExcelScreenCaptureArguments Structure

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/types.md

Defines the arguments for the ExcelScreenCapture tool. Requires the file path, sheet name, and range to capture.

```go
type ExcelScreenCaptureArguments struct {
    FileAbsolutePath string `zog:"fileAbsolutePath"`
    SheetName        string `zog:"sheetName"`
    Range            string `zog:"range"`
}
```

--------------------------------

### Basic Style Configuration

Source: https://github.com/negokaz/excel-mcp-server/blob/main/docs/design/excel-style-schema.md

Defines basic font and fill styles for a cell. Use for simple text formatting and background coloring.

```json
{
  "font": {
    "bold": true,
    "size": 12,
    "color": "#000000"
  },
  "fill": {
    "type": "pattern",
    "pattern": "solid",
    "color": ["#FFFF00"]
  }
}
```

--------------------------------

### BorderStyle Constants

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/excel-interface.md

Defines the available styles for cell borders.

```go
const (
    BorderStyleNone             BorderStyle = "none"
    BorderStyleContinuous       BorderStyle = "continuous"
    BorderStyleDash             BorderStyle = "dash"
    BorderStyleDot              BorderStyle = "dot"
    BorderStyleDouble           BorderStyle = "double"
    BorderStyleDashDot          BorderStyle = "dashDot"
    BorderStyleDashDotDot       BorderStyle = "dashDotDot"
    BorderStyleSlantDashDot     BorderStyle = "slantDashDot"
    BorderStyleMediumDashDot    BorderStyle = "mediumDashDot"
    BorderStyleMediumDashDotDot BorderStyle = "mediumDashDotDot"
)
```

--------------------------------

### CreateHTMLTableOfValuesWithStyle Function Signature

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/style-registry.md

This function signature outlines the parameters required to generate an HTML table with styles from a given worksheet range.

```go
func CreateHTMLTableOfValuesWithStyle(worksheet excel.Worksheet, 
                                     startCol int, startRow int, 
                                     endCol int, endRow int) (*string, error)
```

--------------------------------

### Convert to YAML Flow

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/style-registry.md

Converts any Go struct or value into a compact YAML flow string, suitable for hashing. It uses inline format and omits empty fields.

```Go
func convertToYAMLFlow(value any) string
```

--------------------------------

### Generate HTML Style Definition Tag

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/style-registry.md

Generates HTML code elements for a map of style IDs to YAML strings, prefixed with a given label.

```Go
func (sr *StyleRegistry) generateStyleDefTag(styles map[string]string, styleLabel string) string
```

```html
<code class="style language-yaml" id="f1">font: {bold: true, size: 12}</code>
<code class="style language-yaml" id="f2">font: {italic: true, color: #FF0000}</code>
```

--------------------------------

### Generated HTML with Style Definitions and Sheet Data

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/style-registry.md

Shows the final HTML output, including the generated style definitions (referenced by IDs like 'f1', 'l1') and the styled table data.

```html
<h2>Style Definitions</h2>
<div class="style-definitions">
<code class="style language-yaml" id="f1">font: {bold: true, size: 12}</code>
<code class="style language-yaml" id="l1">fill: {type: pattern, pattern: solid, color: [#FFFF00]}</code>
</div>

<h2>Sheet Data</h2>
<table>
<tr><th></th><th>A</th><th>B</th></tr>
<tr>
  <th>1</th>
  <td style-ref="f1">Value1</td>
  <td style-ref="l1">Value2</td>
</tr>
</table>
```

--------------------------------

### Register Style with Nil Pointers in Struct

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/style-registry.md

Illustrates that registering a CellStyle with nil Font and Fill pointers results in an empty slice.

```go
style := &excel.CellStyle{
    Font: nil,
    Fill: nil,
}
registerStyle(style)  // Returns: []string{}
```

--------------------------------

### GetPagingRanges Method

Source: https://github.com/negokaz/excel-mcp-server/blob/main/_autodocs/api-reference/pagination.md

Retrieves all available paging ranges configured for the service. This method returns a slice of strings, where each string represents a distinct paging range.

```go
func (s *PagingRangeService) GetPagingRanges() []string
```

```go
[]string{
    "A1:Z153",
    "A154:Z306",
    "A307:Z459",
    "A460:Z500",
}
```