Add border-map and compare-ranges tools | increase tests coverage by marcin-uliasz · Pull Request #125 · freema/mcp-gsheets

marcin-uliasz · 2026-04-16T15:34:07Z

After working with this MCP Server there was a need to create two additional tools: border-map & compare-ranges for AI Agent to better understand the Google Spreadsheet it was analysing.

I also increased tests coverage:

Detailed summary of changes in PR:

This pull request introduces two new tools for analyzing Google Sheets formatting—border mapping and range comparison—along with improvements to the conditional formatting tool and minor refactoring in chart creation. The main changes expand the API's ability to inspect and compare spreadsheet formatting, making it easier to programmatically verify and visualize cell styles and borders.

New tools for formatting analysis:

Added sheets_get_border_map tool (getBorderMapTool and handleGetBorderMap) to generate a compact, visual map of cell borders for a given range, with an option to include line styles, colors, and widths.

Added sheets_compare_ranges tool (compareRangesTool and handleCompareRanges) to compare cell formatting between two ranges, returning a diff of all differing cells and properties, with support for row-by-row or full block comparison.

Integration of new tools:

Registered the new border map and range comparison tools in the main tool handler map and tool list in src/index.ts. [1] [2]

Improvements to conditional formatting data tool:

Enhanced sheets_get_conditional_formatting to optionally normalize conditional formatting formulas to English locale (comma separators), with metadata for original formulas and a new normalizeFormulas input. [1] [2] [3]

Minor refactoring and test coverage:

Simplified axis title assignment in chart creation and added coverage ignore comments for unreachable code paths. [1] [2] [3]

Add comprehensive unit tests for many tools and utils (append-values, batch-update-values, create-chart enhancements, insert-rows edge cases, update-values fallback, google-auth, json-parser, response-helpers, validation-helpers, error-messages, and range-helpers including colIndexToLetter). Also simplify axis title assignment in create-chart and add /* v8 ignore next 3 */ hints to avoid optimizer warnings in create-chart and google-auth. These changes increase test coverage, handle several edge cases, and make minor defensive code adjustments.

Introduce two new tools to inspect formatting: sheets_get_border_map (visual border grids) and sheets_compare_ranges (cell-format diffs). Register and export the tools, and wire their handlers in src/index.ts and src/tools/index.ts. Add a new utility (src/utils/formula-locale.ts) that normalizes conditional-format formulas to English locale and integrate it into conditional-formatting and full-sheet-snapshot flows (new normalizeFormulas option for conditional format tool; includeConditionalFormatting and compactMode default changes in full-sheet-snapshot). Also adjust conditional-formatting tool to return a _formulaLocaleRaw field when normalization runs. Error handling, field filtering, and formatting outputs added for the new tools.

# Conflicts: # src/tools/get-conditional-formatting-data.ts # tests/unit/utils/range-helpers.test.ts

Copilot

Pull request overview

This PR expands the Sheets MCP server’s formatting-inspection capabilities by adding two new analysis tools (border mapping and range formatting diff), and improves conditional formatting handling via formula locale normalization. It also includes a broad set of new/expanded unit tests to raise coverage and minor refactors in chart creation.

Changes:

Added sheets_get_border_map and sheets_compare_ranges tools and registered them in the tool registry/exports.
Added formula locale normalization utilities and integrated them into conditional-formatting related tools/snapshots.
Increased unit test coverage across validators, helpers, auth, formatters, and multiple tools.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
src/index.ts	Registers the new tools in the handler map and tool list.
src/tools/index.ts	Exports the new tool modules for consumption by the main index.
src/tools/get-border-map.ts	New tool to produce compact horizontal/vertical border line grids for a range.
src/tools/compare-ranges.ts	New tool to diff formatting between two same-sized ranges.
src/utils/formula-locale.ts	New utility to normalize Sheets formulas to comma-separated (English) locale.
src/tools/get-conditional-formatting-data.ts	Adds optional formula normalization and raw-formula metadata in CF output.
src/tools/get-full-sheet-snapshot.ts	Changes snapshot defaults (compact mode on) and adds conditional formatting inclusion toggle + normalization.
src/tools/create-chart.ts	Minor refactor of axis title assignment + coverage ignore annotations.
src/utils/google-auth.ts	Adds coverage ignore annotations for an unreachable private-key validation branch.
tests/unit/utils/validators.test.ts	Adds additional validator test cases for edge conditions and new validators.
tests/unit/utils/validation-helpers.test.ts	New tests for shared validation helper utilities (with validators mocked).
tests/unit/utils/response-helpers.test.ts	New tests for response helper formatting utilities.
tests/unit/utils/range-helpers.test.ts	Adds tests for additional edge cases and `colIndexToLetter`.
tests/unit/utils/json-parser.test.ts	New tests for JSON input parsing helper.
tests/unit/utils/google-auth.test.ts	New tests for auth validation and client creation/caching behavior.
tests/unit/utils/formatters.test.ts	Adds an edge-case test for null first-row values.
tests/unit/utils/error-messages.test.ts	New tests validating error message constants/factories.
tests/unit/tools/update-values.test.ts	Adds edge-case test for missing `updatedCells`.
tests/unit/tools/insert-rows.test.ts	Adds multiple edge-case tests around range parsing and sheet name handling.
tests/unit/tools/create-chart.test.ts	Adds extensive branch/edge-case coverage for chart creation.
tests/unit/tools/batch-update-values.test.ts	New tests for batch update values tool.
tests/unit/tools/append-values.test.ts	New tests for append values tool.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Use extractSheetName and case-insensitive column parsing across compare-ranges and get-border-map to accept quoted sheet names and lowercase A1 refs; normalize column letters with toUpperCase and make range regex case-insensitive. Harden null/optional checks and formatting extraction (safe returns when no format). Fix border-map logic to correctly prioritize bottom/top and left/right checks and ensure encodeBorder/includeStyle handling. Also add unit tests for compare-ranges, get-border-map, and formula-locale to cover quoted sheet names, lowercase ranges, field filtering, border resolution, and formula locale normalization.

Minor formatting updates across three files: aligned multiline destructuring in src/tools/compare-ranges.ts, normalized inline comment spacing for endRow in src/tools/compare-ranges.ts and src/tools/get-border-map.ts, and collapsed the function signature onto one line in src/utils/formula-locale.ts. No functional changes; purely readability/formatting cleanup.

Change compactMode default to false and update docs and behavior accordingly. The input schema and help text now state that full per-cell formatting is returned by default and compactMode:true enables run-length encoded collapsing. Introduce a local `compact` boolean (compactMode === true) and use it in conditional logic and in the returned formatting payload to normalize handling of the flag. Notes that compacting only applies when includeFormattingRange is set.

Update package.json version from 1.7.1 to 1.7.2 to prepare a patch release. No other changes were made in this commit.

marcin-uliasz · 2026-04-21T10:32:36Z

@freema In this PR I have added border-map and compare-ranges tools. I also increased tests coverage.

freema · 2026-04-21T14:08:50Z

Hi Marcin, thank you so much for this great contribution! 🧙‍♂️

The two new tools are genuinely useful — sheets_get_border_map solves the ambiguity of "right border of N vs left border of N+1" elegantly, and sheets_compare_ranges is going to save a lot of time when verifying repeated formatting patterns. On top of that, the conditional-formatting locale normalization fixes a real pain point for non-English users (the Polish ; separator issue — finally someone cared enough to fix it 🫡).

The test coverage bump is also a huge win — google-auth, validation-helpers, response-helpers, formula-locale, plus edge cases for append/batch-update/create-chart/insert-rows. That's exactly the kind of foundation work that pays dividends over time. The coverage chart went from "we have tests" to "we HAVE tests" 📈.

Merging now and shipping as part of v1.8.0. I'll follow up with a small cleanup commit in main (tightening the mode parameter in compare-ranges so it matches the schema, and a couple of minor typing touch-ups) so you don't need to push anything else here.

Thanks again for the effort and care! 🚀

@master-nevi

Ship the merged contributions from #125 and #126 as 1.8.0: - delete-columns / delete-rows tools (#126, @master-nevi) - border-map / compare-ranges tools + locale normalization + coverage (#125, @marcin-uliasz) Cleanup: - Remove unused `mode` parameter from sheets_compare_ranges schema (the tool always compared position-by-position — kept doc honest) - Bump server version string in src/index.ts to match package version

marcin-uliasz added 3 commits April 16, 2026 13:48

Merge remote-tracking branch 'upstream/main'

3b43ed5

# Conflicts: # src/tools/get-conditional-formatting-data.ts # tests/unit/utils/range-helpers.test.ts

Copilot AI review requested due to automatic review settings April 16, 2026 15:34

Copilot started reviewing on behalf of marcin-uliasz April 16, 2026 15:34 View session

Copilot AI reviewed Apr 16, 2026

View reviewed changes

marcin-uliasz changed the title ~~change: add border-map and compare-ranges tools | increase tests coverage~~ Add border-map and compare-ranges tools | increase tests coverage Apr 21, 2026

marcin-uliasz added 4 commits April 21, 2026 12:05

Bump package version to 1.7.2

ad0a1ec

Update package.json version from 1.7.1 to 1.7.2 to prepare a patch release. No other changes were made in this commit.

freema merged commit dcc7bc3 into freema:main Apr 21, 2026
3 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add border-map and compare-ranges tools | increase tests coverage#125

Add border-map and compare-ranges tools | increase tests coverage#125
freema merged 7 commits into
freema:mainfrom
marcin-uliasz:main

marcin-uliasz commented Apr 16, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marcin-uliasz commented Apr 21, 2026

Uh oh!

freema commented Apr 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

marcin-uliasz commented Apr 16, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marcin-uliasz commented Apr 21, 2026

Uh oh!

freema commented Apr 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants