mcp-gsheets 1.5.3 → 1.6.0

package/README.md

@@ -137,6 +137,7 @@ For other MCP clients, use the standard configuration format shown above. Ensure
 4. Create Service Account:
    - Go to "APIs & Services" → "Credentials"
    - Click "Create Credentials" → "Service Account"
+   - In the service accounts list, click the three dots in the `Actions` column → `Manage keys` → `Add key` → `Create new key` → select JSON format
    - Download the JSON key file
 5. Share your spreadsheets:
    - Open your Google Sheet
@@ -474,6 +475,10 @@ See [CHANGELOG.md](CHANGELOG.md) for a list of changes in each version.
 5. Push to the branch (`git push origin feature/amazing-feature`)
 6. Open a Pull Request
 
+## 👤 Author
+
+**Tomáš Grásl** - [tomasgrasl.cz](https://www.tomasgrasl.cz/)
+
 ## 📄 License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/dist/index.js

@@ -15748,6 +15748,399 @@ async function handleInsertRows(input) {
   }
 }
 
+// src/resources/index.ts
+function parseResourceUri(uri) {
+  let path;
+  if (uri.startsWith("spreadsheet://")) {
+    path = uri.slice("spreadsheet://".length);
+  } else {
+    return null;
+  }
+  const parts = path.split("/");
+  if (parts.length < 2) {
+    return null;
+  }
+  const spreadsheetId = parts[0];
+  if (parts[1] === "info" && spreadsheetId) {
+    return { type: "info", spreadsheetId };
+  }
+  if (parts[1] === "sheets" && spreadsheetId) {
+    return { type: "sheets", spreadsheetId };
+  }
+  if (parts[1] === "sheet" && parts.length >= 3 && spreadsheetId) {
+    const sheetName = decodeURIComponent(parts.slice(2).join("/"));
+    if (sheetName) {
+      return { type: "sheet-data", spreadsheetId, sheetName };
+    }
+  }
+  return null;
+}
+async function readSpreadsheetInfo(spreadsheetId, uri) {
+  try {
+    const sheets = await getAuthenticatedClient();
+    const response = await sheets.spreadsheets.get({
+      spreadsheetId,
+      fields: "spreadsheetId,properties,spreadsheetUrl"
+    });
+    const data = {
+      spreadsheetId: response.data.spreadsheetId,
+      title: response.data.properties?.title,
+      locale: response.data.properties?.locale,
+      timeZone: response.data.properties?.timeZone,
+      url: response.data.spreadsheetUrl
+    };
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify(data, null, 2)
+        }
+      ]
+    };
+  } catch (error) {
+    const errorResponse = handleError(error);
+    const errorText = errorResponse.content[0]?.text ?? "Unknown error";
+    throw new Error(errorText);
+  }
+}
+async function readSheetList(spreadsheetId, uri) {
+  try {
+    const sheets = await getAuthenticatedClient();
+    const response = await sheets.spreadsheets.get({
+      spreadsheetId,
+      fields: "sheets.properties"
+    });
+    const sheetList = response.data.sheets?.map((sheet) => ({
+      sheetId: sheet.properties?.sheetId,
+      title: sheet.properties?.title,
+      index: sheet.properties?.index,
+      sheetType: sheet.properties?.sheetType,
+      rowCount: sheet.properties?.gridProperties?.rowCount,
+      columnCount: sheet.properties?.gridProperties?.columnCount,
+      frozenRowCount: sheet.properties?.gridProperties?.frozenRowCount,
+      frozenColumnCount: sheet.properties?.gridProperties?.frozenColumnCount
+    })) || [];
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify({ sheets: sheetList }, null, 2)
+        }
+      ]
+    };
+  } catch (error) {
+    const errorResponse = handleError(error);
+    const errorText = errorResponse.content[0]?.text ?? "Unknown error";
+    throw new Error(errorText);
+  }
+}
+async function readSheetData(spreadsheetId, sheetName, uri) {
+  try {
+    const sheets = await getAuthenticatedClient();
+    const response = await sheets.spreadsheets.values.get({
+      spreadsheetId,
+      range: sheetName,
+      valueRenderOption: "FORMATTED_VALUE"
+    });
+    const values = response.data.values || [];
+    const data = {
+      range: response.data.range,
+      majorDimension: response.data.majorDimension,
+      values,
+      rowCount: values.length,
+      columnCount: values[0]?.length || 0
+    };
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify(data, null, 2)
+        }
+      ]
+    };
+  } catch (error) {
+    const errorResponse = handleError(error);
+    const errorText = errorResponse.content[0]?.text ?? "Unknown error";
+    throw new Error(errorText);
+  }
+}
+var resourceTemplates = [
+  {
+    uriTemplate: "spreadsheet://{spreadsheetId}/info",
+    name: "Spreadsheet Info",
+    description: "Get metadata about a Google Spreadsheet including title, locale, timezone, and URL",
+    mimeType: "application/json"
+  },
+  {
+    uriTemplate: "spreadsheet://{spreadsheetId}/sheets",
+    name: "Sheet List",
+    description: "List all sheets in a spreadsheet with their properties (id, title, row/column counts, frozen rows/columns)",
+    mimeType: "application/json"
+  },
+  {
+    uriTemplate: "spreadsheet://{spreadsheetId}/sheet/{sheetName}",
+    name: "Sheet Data",
+    description: "Get all data from a specific sheet by name",
+    mimeType: "application/json"
+  }
+];
+async function handleResourceRead(uri) {
+  const parsed = parseResourceUri(uri);
+  if (!parsed) {
+    throw new Error(
+      `Invalid resource URI: ${uri}. Expected format: spreadsheet://{spreadsheetId}/info, spreadsheet://{spreadsheetId}/sheets, or spreadsheet://{spreadsheetId}/sheet/{sheetName}`
+    );
+  }
+  switch (parsed.type) {
+    case "info":
+      return readSpreadsheetInfo(parsed.spreadsheetId, uri);
+    case "sheets":
+      return readSheetList(parsed.spreadsheetId, uri);
+    case "sheet-data":
+      if (!parsed.sheetName) {
+        throw new Error("Sheet name is required for sheet-data resource");
+      }
+      return readSheetData(parsed.spreadsheetId, parsed.sheetName, uri);
+  }
+}
+
+// src/prompts/index.ts
+var createTablePrompt = {
+  name: "create-table",
+  description: "Guide for creating a new table with headers and data in a Google Spreadsheet",
+  arguments: [
+    {
+      name: "spreadsheetId",
+      description: "The ID of the target spreadsheet (from the URL)",
+      required: true
+    },
+    {
+      name: "sheetName",
+      description: "Name of the sheet to create the table in (default: Sheet1)",
+      required: false
+    },
+    {
+      name: "dataDescription",
+      description: "Description of the data/table you want to create",
+      required: true
+    }
+  ]
+};
+function handleCreateTable(args) {
+  const spreadsheetId = args.spreadsheetId || "{spreadsheetId}";
+  const sheetName = args.sheetName || "Sheet1";
+  const dataDescription = args.dataDescription || "your data";
+  return {
+    description: `Create a table for: ${dataDescription}`,
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: `I want to create a table in Google Sheets.
+
+Spreadsheet ID: ${spreadsheetId}
+Sheet: ${sheetName}
+Data description: ${dataDescription}
+
+Please help me:
+1. First, check if I have access to the spreadsheet using sheets_check_access
+2. Define appropriate column headers based on the data description
+3. Create the table structure using sheets_update_values
+4. Optionally format the header row (bold, background color) using sheets_format_cells
+
+Please proceed step by step.`
+        }
+      }
+    ]
+  };
+}
+var formatReportPrompt = {
+  name: "format-report",
+  description: "Format existing data as a professional report with headers, borders, and styling",
+  arguments: [
+    {
+      name: "spreadsheetId",
+      description: "The ID of the spreadsheet containing the data",
+      required: true
+    },
+    {
+      name: "range",
+      description: 'The range containing data to format (e.g., "Sheet1!A1:E20")',
+      required: true
+    },
+    {
+      name: "reportStyle",
+      description: 'Style preference: "professional", "minimal", or "colorful"',
+      required: false
+    }
+  ]
+};
+function handleFormatReport(args) {
+  const spreadsheetId = args.spreadsheetId || "{spreadsheetId}";
+  const range = args.range || "Sheet1!A1:E20";
+  const reportStyle = args.reportStyle || "professional";
+  const styleGuide = {
+    professional: "navy blue headers with white text, light gray alternating rows, thin borders",
+    minimal: "bold headers, subtle bottom border on header row only, clean white background",
+    colorful: "vibrant colored headers, light pastel alternating row colors, medium borders"
+  };
+  return {
+    description: `Format report in ${reportStyle} style`,
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: `I want to format my data as a ${reportStyle} report.
+
+Spreadsheet ID: ${spreadsheetId}
+Data range: ${range}
+Style: ${reportStyle} - ${styleGuide[reportStyle] || styleGuide["professional"]}
+
+Please help me:
+1. First, read the data to understand its structure using sheets_get_values
+2. Format the header row (first row) with appropriate styling using sheets_format_cells
+3. Add borders to the data range using sheets_update_borders
+4. Optionally auto-resize columns for better readability
+
+Use the ${reportStyle} style guidelines to make the report look great.`
+        }
+      }
+    ]
+  };
+}
+var summarizeDataPrompt = {
+  name: "summarize-data",
+  description: "Analyze spreadsheet data and provide insights or create a summary",
+  arguments: [
+    {
+      name: "spreadsheetId",
+      description: "The ID of the spreadsheet to analyze",
+      required: true
+    },
+    {
+      name: "range",
+      description: 'The range containing data to analyze (e.g., "Sheet1!A1:F100")',
+      required: true
+    },
+    {
+      name: "analysisType",
+      description: 'Type of analysis: "overview", "statistics", or "trends"',
+      required: false
+    }
+  ]
+};
+function handleSummarizeData(args) {
+  const spreadsheetId = args.spreadsheetId || "{spreadsheetId}";
+  const range = args.range || "Sheet1!A:Z";
+  const analysisType = args.analysisType || "overview";
+  return {
+    description: `Analyze data: ${analysisType}`,
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: `I want to analyze and summarize my spreadsheet data.
+
+Spreadsheet ID: ${spreadsheetId}
+Data range: ${range}
+Analysis type: ${analysisType}
+
+Please help me:
+1. First, get the spreadsheet metadata using sheets_get_metadata to understand the structure
+2. Read the data from the specified range using sheets_get_values
+3. Analyze the data and provide:
+   - Overview of the data structure (columns, rows, data types)
+   - Key statistics (counts, sums, averages where applicable)
+   - Notable patterns or insights
+4. Suggest any potential improvements to the data organization
+
+Focus on a ${analysisType} analysis.`
+        }
+      }
+    ]
+  };
+}
+var createChartGuidePrompt = {
+  name: "create-chart-guide",
+  description: "Step-by-step guide to create a chart from spreadsheet data",
+  arguments: [
+    {
+      name: "spreadsheetId",
+      description: "The ID of the spreadsheet containing the data",
+      required: true
+    },
+    {
+      name: "dataRange",
+      description: 'The range containing data for the chart (e.g., "Sheet1!A1:B10")',
+      required: true
+    },
+    {
+      name: "chartType",
+      description: 'Preferred chart type: "COLUMN", "BAR", "LINE", "PIE", "AREA", or "SCATTER"',
+      required: false
+    }
+  ]
+};
+function handleCreateChartGuide(args) {
+  const spreadsheetId = args.spreadsheetId || "{spreadsheetId}";
+  const dataRange = args.dataRange || "Sheet1!A1:B10";
+  const chartType = args.chartType || "COLUMN";
+  return {
+    description: `Create ${chartType} chart`,
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: `I want to create a ${chartType} chart from my spreadsheet data.
+
+Spreadsheet ID: ${spreadsheetId}
+Data range: ${dataRange}
+Chart type: ${chartType}
+
+Please help me:
+1. First, read the data to understand what we're visualizing using sheets_get_values
+2. Get the sheet ID needed for chart creation using sheets_get_metadata
+3. Create the chart using sheets_create_chart with appropriate configuration:
+   - Title based on the data
+   - Proper axis labels
+   - Legend if needed
+4. Position the chart appropriately on the sheet
+
+Provide the chart configuration and create it step by step.`
+        }
+      }
+    ]
+  };
+}
+var allPrompts = [
+  createTablePrompt,
+  formatReportPrompt,
+  summarizeDataPrompt,
+  createChartGuidePrompt
+];
+var promptHandlers = /* @__PURE__ */ new Map([
+  ["create-table", handleCreateTable],
+  ["format-report", handleFormatReport],
+  ["summarize-data", handleSummarizeData],
+  ["create-chart-guide", handleCreateChartGuide]
+]);
+function handleGetPrompt(name, args) {
+  const handler = promptHandlers.get(name);
+  if (!handler) {
+    throw new Error(
+      `Unknown prompt: ${name}. Available prompts: ${allPrompts.map((p) => p.name).join(", ")}`
+    );
+  }
+  return handler(args || {});
+}
+
 // src/index.ts
 if (process.env.NODE_ENV !== "production") {
   try {
@@ -15832,12 +16225,13 @@ async function main() {
   const server = new Server(
     {
       name: "spreadsheet",
-      version: "1.0.0"
+      version: "1.6.0"
     },
     {
       capabilities: {
-        resources: {},
-        tools: {}
+        resources: { listChanged: false },
+        tools: { listChanged: false },
+        prompts: { listChanged: false }
       }
     }
   );
@@ -15859,11 +16253,22 @@ async function main() {
       throw error;
     }
   });
+  server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
+    return { resourceTemplates };
+  });
   server.setRequestHandler(ListResourcesRequestSchema, async () => {
     return { resources: [] };
   });
-  server.setRequestHandler(ReadResourceRequestSchema, async () => {
-    throw new Error("Resource reading not implemented");
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    return handleResourceRead(uri);
+  });
+  server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    return { prompts: allPrompts };
+  });
+  server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    return handleGetPrompt(name, args);
   });
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-gsheets",
-  "version": "1.5.3",
+  "version": "1.6.0",
   "description": "Model Context Protocol (MCP) server for Google Sheets API integration",
   "author": "freema",
   "license": "MIT",
@@ -47,7 +47,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.1",
-    "googleapis": "^140.0.0",
+    "googleapis": "^164.1.0",
     "zod": "^3.22.4"
   },
   "devDependencies": {