mcp-gsheets 1.9.0 → 1.10.0

package/README.md

@@ -312,6 +312,62 @@ cp .env.example .env
 npm run dev  # Watch mode with auto-reload
 ```
 
+## 🎚️ Reducing context cost with toolsets
+
+All 44 tools together cost about **9,900 tokens of context in every session**,
+before the model does anything. Most workflows need a fraction of that.
+`GSHEETS_TOOLSETS` limits which tools the server exposes:
+
+```json
+{
+  "mcpServers": {
+    "gsheets": {
+      "command": "npx",
+      "args": ["mcp-gsheets"],
+      "env": {
+        "GOOGLE_PROJECT_ID": "your-project-id",
+        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/key.json",
+        "GSHEETS_TOOLSETS": "core,charts"
+      }
+    }
+  }
+}
+```
+
+| Toolset | Tools | What it covers |
+|---|---|---|
+| `core` | 11 | Read/write values, metadata, sheet structure, create spreadsheet |
+| `sheets` | 9 | Sheet lifecycle, rows and columns |
+| `formatting` | 15 | Colours, borders, merges, conditional rules, links, dates |
+| `charts` | 3 | Create, update, delete charts |
+| `tables` | 4 | Native tables |
+| `analysis` | 2 | Full-sheet snapshot, range comparison |
+
+Measured `tools/list` cost:
+
+| Configuration | Tools | ≈ Tokens |
+|---|---|---|
+| _unset_ (default, all toolsets) | 44 | 9,875 |
+| `GSHEETS_TOOLSETS=core` | 11 | 1,986 |
+| `GSHEETS_TOOLSETS=core,sheets` | 20 | 3,548 |
+| `GSHEETS_READ_ONLY=true` | 16 | 3,599 |
+| `GSHEETS_TOOLSETS=core` + read-only | 6 | 912 |
+
+Notes:
+
+- **The default is unchanged** — leave `GSHEETS_TOOLSETS` unset and you get
+  every tool, exactly as before.
+- **`core` is always included.** `GSHEETS_TOOLSETS=charts` means "charts as
+  well as core", not "charts only" — without core the server cannot read a cell.
+- **A typo is a startup error**, not a silently smaller tool list.
+- `GSHEETS_READ_ONLY=true` drops every writing tool and can be combined with
+  `GSHEETS_TOOLSETS`. It is enforced when a tool is called, not just when the
+  list is built, so a client cannot write by naming a hidden tool.
+
+All tools also carry MCP annotations (`readOnlyHint`, `destructiveHint`,
+`idempotentHint`), so clients can skip confirmation prompts on reads and warn
+before destructive operations.
+
 ## 📋 Available Tools
 
 ### Reading Data

package/dist/index.js

@@ -18036,6 +18036,141 @@ function validateAuth() {
   }
 }
 
+// src/config/toolsets.ts
+var TOOLSET_NAMES = [
+  "core",
+  "sheets",
+  "formatting",
+  "charts",
+  "tables",
+  "analysis"
+];
+var TOOLSETS = {
+  /** Reading and writing cells, plus the metadata needed to do it safely. */
+  core: [
+    "sheets_check_access",
+    "sheets_get_metadata",
+    "sheets_get_sheet_structure",
+    "sheets_get_sheet_dimensions",
+    "sheets_get_values",
+    "sheets_batch_get_values",
+    "sheets_update_values",
+    "sheets_batch_update_values",
+    "sheets_append_values",
+    "sheets_clear_values",
+    "sheets_create_spreadsheet"
+  ],
+  /** Sheet lifecycle and row/column structure. */
+  sheets: [
+    "sheets_insert_sheet",
+    "sheets_delete_sheet",
+    "sheets_duplicate_sheet",
+    "sheets_copy_to",
+    "sheets_update_sheet_properties",
+    "sheets_batch_delete_sheets",
+    "sheets_insert_rows",
+    "sheets_delete_rows",
+    "sheets_delete_columns"
+  ],
+  /** Cell appearance: colours, borders, merges, conditional rules, links. */
+  formatting: [
+    "sheets_format_cells",
+    "sheets_batch_format_cells",
+    "sheets_update_borders",
+    "sheets_get_border_map",
+    "sheets_merge_cells",
+    "sheets_unmerge_cells",
+    "sheets_get_merged_cells",
+    "sheets_get_sheet_formatting",
+    "sheets_get_formatting_compact",
+    "sheets_add_conditional_formatting",
+    "sheets_get_conditional_formatting",
+    "sheets_get_data_validation",
+    "sheets_get_basic_filter",
+    "sheets_insert_link",
+    "sheets_insert_date"
+  ],
+  charts: ["sheets_create_chart", "sheets_update_chart", "sheets_delete_chart"],
+  tables: ["sheets_add_table", "sheets_update_table", "sheets_delete_table", "sheets_get_tables"],
+  /** Whole-sheet reads and diffing — powerful, but the heaviest schemas. */
+  analysis: ["sheets_get_full_sheet_snapshot", "sheets_compare_ranges"]
+};
+var READ_ONLY_TOOLS = /* @__PURE__ */ new Set([
+  "sheets_check_access",
+  "sheets_get_metadata",
+  "sheets_get_sheet_structure",
+  "sheets_get_sheet_dimensions",
+  "sheets_get_values",
+  "sheets_batch_get_values",
+  "sheets_get_border_map",
+  "sheets_get_merged_cells",
+  "sheets_get_sheet_formatting",
+  "sheets_get_formatting_compact",
+  "sheets_get_conditional_formatting",
+  "sheets_get_data_validation",
+  "sheets_get_basic_filter",
+  "sheets_get_tables",
+  "sheets_get_full_sheet_snapshot",
+  "sheets_compare_ranges"
+]);
+var DESTRUCTIVE_TOOLS = /* @__PURE__ */ new Set([
+  "sheets_clear_values",
+  "sheets_delete_sheet",
+  "sheets_batch_delete_sheets",
+  "sheets_delete_rows",
+  "sheets_delete_columns",
+  "sheets_delete_chart",
+  "sheets_delete_table",
+  "sheets_unmerge_cells"
+]);
+var ToolsetConfigError = class extends Error {
+};
+function parseList(raw) {
+  return raw.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+}
+function resolveToolsets(env = process.env) {
+  const raw = env.GSHEETS_TOOLSETS?.trim();
+  const readOnly = env.GSHEETS_READ_ONLY?.trim().toLowerCase() === "true";
+  let enabled;
+  if (!raw || raw.toLowerCase() === "all") {
+    enabled = [...TOOLSET_NAMES];
+  } else {
+    const requested = parseList(raw);
+    const unknown2 = requested.filter((n) => !TOOLSET_NAMES.includes(n));
+    if (unknown2.length > 0) {
+      throw new ToolsetConfigError(
+        `Unknown toolset${unknown2.length > 1 ? "s" : ""}: ${unknown2.join(", ")}. Valid toolsets: ${TOOLSET_NAMES.join(", ")}, all.`
+      );
+    }
+    const set = new Set(requested);
+    set.add("core");
+    enabled = TOOLSET_NAMES.filter((n) => set.has(n));
+  }
+  const allowed = /* @__PURE__ */ new Set();
+  for (const name of enabled) {
+    for (const tool of TOOLSETS[name]) {
+      if (readOnly && !READ_ONLY_TOOLS.has(tool)) {
+        continue;
+      }
+      allowed.add(tool);
+    }
+  }
+  return { enabled, readOnly, allowed };
+}
+function annotationsFor(toolName) {
+  if (READ_ONLY_TOOLS.has(toolName)) {
+    return { readOnlyHint: true, idempotentHint: true };
+  }
+  const annotations = {};
+  if (!DESTRUCTIVE_TOOLS.has(toolName)) {
+    annotations.destructiveHint = false;
+  }
+  if (toolName !== "sheets_append_values") {
+    annotations.idempotentHint = true;
+  }
+  return annotations;
+}
+
 // src/utils/error-handler.ts
 function handleError(error2) {
   console.error("Error in Google Sheets operation:", error2);
@@ -23925,6 +24060,23 @@ async function main() {
     console.error("Authentication Error:", error2.message);
     process.exit(1);
   }
+  let toolsetConfig;
+  try {
+    toolsetConfig = resolveToolsets();
+  } catch (error2) {
+    if (error2 instanceof ToolsetConfigError) {
+      console.error(`Configuration Error: ${error2.message}`);
+      process.exit(1);
+    }
+    throw error2;
+  }
+  const { enabled, readOnly, allowed } = toolsetConfig;
+  const exposedTools = allTools.filter((tool) => allowed.has(tool.name)).map((tool) => ({ ...tool, annotations: annotationsFor(tool.name) }));
+  if (enabled.length < Object.keys(TOOLSETS).length || readOnly) {
+    console.error(
+      `Toolsets: ${enabled.join(", ")}${readOnly ? " (read-only)" : ""} \u2014 ${exposedTools.length}/${allTools.length} tools`
+    );
+  }
   const server = new Server(
     {
       name: "spreadsheet",
@@ -23940,11 +24092,16 @@ async function main() {
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
-      tools: allTools
+      tools: exposedTools
     };
   });
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
+    if (!allowed.has(name)) {
+      throw new Error(
+        toolHandlers.has(name) ? `Tool ${name} is disabled by the current GSHEETS_TOOLSETS/GSHEETS_READ_ONLY configuration` : `Unknown tool: ${name}`
+      );
+    }
     const handler = toolHandlers.get(name);
     if (!handler) {
       throw new Error(`Unknown tool: ${name}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-gsheets",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "mcpName": "io.github.freema/mcp-gsheets",
   "description": "Model Context Protocol (MCP) server for Google Sheets API integration",
   "author": "freema",