google-sheet-mcp 1.0.0

package/src/cli/cli.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * google-sheet-mcp CLI
+ *
+ * Usage:
+ *   npx google-sheet-mcp init        — Setup (service account, default)
+ *   npx google-sheet-mcp init --auth oauth  — Setup (OAuth2, personal account)
+ *   npx google-sheet-mcp test        — Test connection
+ *   npx google-sheet-mcp token-status — Check OAuth2 token health
+ *   npx google-sheet-mcp list        — List sheets
+ *   npx google-sheet-mcp read        — Read sheet data
+ *   npx google-sheet-mcp config      — Show current config
+ */
+
+import { program } from "commander";
+import { initCommand } from "./commands/init.mjs";
+import { testCommand } from "./commands/test.mjs";
+import { listCommand } from "./commands/list.mjs";
+import { readCommand } from "./commands/read.mjs";
+import { configCommand } from "./commands/config.mjs";
+import { createCommand } from "./commands/create.mjs";
+import { appendCommand } from "./commands/append.mjs";
+import { tokenStatusCommand } from "./commands/token-status.mjs";
+
+program
+  .name("google-sheet-mcp")
+  .description(
+    "Connect Google Sheets to Cursor, VS Code, Claude Code and AI agents in 3 minutes."
+  )
+  .version("1.0.0");
+
+program
+  .command("init")
+  .description("Interactive setup: connect a Google Sheet")
+  .option(
+    "--auth <type>",
+    "Authentication type: service-account (default) or oauth",
+    "service-account"
+  )
+  .action(initCommand);
+
+program
+  .command("test")
+  .description("Test connection to the configured Google Sheet")
+  .option("-s, --sheet <name>", "Test reading a specific sheet")
+  .action(testCommand);
+
+program
+  .command("list")
+  .description("List all sheets in the connected spreadsheet")
+  .action(listCommand);
+
+program
+  .command("read")
+  .description("Read data from a sheet")
+  .requiredOption("-s, --sheet <name>", "Sheet name to read")
+  .option("-r, --range <range>", "Cell range in A1 notation (e.g., A1:Z100)")
+  .option("--raw", "Return raw 2D array instead of objects")
+  .action(readCommand);
+
+program
+  .command("config")
+  .description("Show current configuration")
+  .action(configCommand);
+
+program
+  .command("create")
+  .description("Create a new sheet")
+  .requiredOption("-s, --sheet <name>", "New sheet name")
+  .action(createCommand);
+
+program
+  .command("append")
+  .description("Append a row to a sheet")
+  .requiredOption("-s, --sheet <name>", "Sheet name")
+  .requiredOption(
+    "-d, --data <json>",
+    "Row data as JSON (e.g., '{\"name\":\"Anton\"}')"
+  )
+  .action(appendCommand);
+
+program
+  .command("token-status")
+  .description("Check OAuth2 token health (validates refresh token)")
+  .action(tokenStatusCommand);
+
+program.parse(process.argv);

package/src/cli/commands/append.mjs

@@ -0,0 +1,55 @@
+/**
+ * append — Add a row to a sheet.
+ */
+
+import chalk from "chalk";
+import ora from "ora";
+import { loadConfig } from "../../config/config.mjs";
+import { createSheetsClient } from "../../server/sheets-client.mjs";
+
+export async function appendCommand(options) {
+  const config = loadConfig();
+  if (!config) {
+    console.error(chalk.red("❌ No configuration found. Run `npx google-sheet-mcp init` first."));
+    process.exit(1);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(options.data);
+  } catch {
+    console.error(chalk.red("❌ Invalid JSON for --data. Example: '{\"name\":\"Anton\"}'"));
+    process.exit(1);
+  }
+
+  const spinner = ora(`Appending to "${options.sheet}"...`).start();
+
+  try {
+    // First, get headers to align columns
+    const sheets = createSheetsClient(config.credentialsPath);
+    const headerRes = await sheets.spreadsheets.values.get({
+      spreadsheetId: config.spreadsheetId,
+      range: `${options.sheet}!1:1`,
+    });
+
+    const headers = headerRes.data.values?.[0] || Object.keys(data);
+    const row = headers.map((h) => data[h] ?? "");
+
+    await sheets.spreadsheets.values.append({
+      spreadsheetId: config.spreadsheetId,
+      range: `${options.sheet}!A1`,
+      valueInputOption: "USER_ENTERED",
+      requestBody: {
+        values: [row],
+      },
+    });
+
+    spinner.succeed(`Row appended to "${options.sheet}"`);
+    console.log(chalk.gray(`  ${headers.slice(0, 6).join(" | ")}` + (headers.length > 6 ? "..." : "")));
+    console.log(chalk.white(`  ${row.slice(0, 6).join(" | ")}` + (row.length > 6 ? "..." : "")));
+
+  } catch (err) {
+    spinner.fail(`Failed: ${err.message}`);
+    process.exit(1);
+  }
+}

package/src/cli/commands/config.mjs

@@ -0,0 +1,93 @@
+/**
+ * config — Show current configuration.
+ */
+
+import chalk from "chalk";
+import { loadConfig } from "../../config/config.mjs";
+
+export async function configCommand() {
+  const config = loadConfig();
+  if (!config) {
+    console.log(chalk.yellow("⚠️  No configuration found."));
+    console.log();
+    console.log("To set up, run:");
+    console.log(chalk.cyan("  npx google-sheet-mcp init"));
+    console.log();
+    console.log("Or set environment variables:");
+    console.log(chalk.cyan("  Service Account: GOOGLE_SPREADSHEET_ID + GOOGLE_APPLICATION_CREDENTIALS"));
+    console.log(chalk.cyan("  OAuth2:          GOOGLE_SPREADSHEET_ID + GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET + GOOGLE_REFRESH_TOKEN"));
+    return;
+  }
+
+  const authType = config.authType || "service-account";
+
+  console.log(chalk.bold.cyan("\n⚙️  Current Configuration\n"));
+  console.log(chalk.gray(`  Source:          ${config.source}`));
+  if (config._path) {
+    console.log(chalk.gray(`  Config file:     ${config._path}`));
+  }
+  console.log(chalk.white(`  Spreadsheet ID:  ${config.spreadsheetId}`));
+  console.log(chalk.white(`  Auth type:       ${authType}`));
+
+  if (authType === "oauth2" && config.oauth2) {
+    console.log(
+      chalk.white(
+        `  Client ID:       ${config.oauth2.client_id?.substring(0, 16)}...`
+      )
+    );
+    console.log(
+      chalk.gray(`  Refresh token:   ${config.oauth2.refresh_token?.substring(0, 12)}...`)
+    );
+    console.log();
+    console.log(chalk.gray("  Token health:"));
+    console.log(chalk.cyan("    npx google-sheet-mcp token-status"));
+  } else {
+    console.log(chalk.white(`  Key file:        ${config.credentialsPath}`));
+  }
+
+  if (config.sheets && config.sheets.length > 0) {
+    console.log(chalk.white(`  Known sheets:    ${config.sheets.join(", ")}`));
+  }
+  console.log();
+
+  // MCP config hint
+  console.log(chalk.bold("MCP Configuration for AI IDEs:"));
+  console.log();
+  console.log(chalk.gray("  Add this to your MCP config:"));
+  console.log();
+
+  if (authType === "oauth2") {
+    console.log(
+      chalk.white(`  {
+    "mcpServers": {
+      "google-sheets": {
+        "command": "npx",
+        "args": ["google-sheet-mcp"],
+        "env": {
+          "GOOGLE_SPREADSHEET_ID": "${config.spreadsheetId}",
+          "GOOGLE_CLIENT_ID": "${config.oauth2?.client_id}",
+          "GOOGLE_CLIENT_SECRET": "${config.oauth2?.client_secret}",
+          "GOOGLE_REFRESH_TOKEN": "${config.oauth2?.refresh_token}"
+        }
+      }
+    }
+  }`)
+    );
+  } else {
+    console.log(
+      chalk.white(`  {
+    "mcpServers": {
+      "google-sheets": {
+        "command": "npx",
+        "args": ["google-sheet-mcp"],
+        "env": {
+          "GOOGLE_SPREADSHEET_ID": "${config.spreadsheetId}",
+          "GOOGLE_APPLICATION_CREDENTIALS": "${config.credentialsPath}"
+        }
+      }
+    }
+  }`)
+    );
+  }
+  console.log();
+}

package/src/cli/commands/create.mjs

@@ -0,0 +1,45 @@
+/**
+ * create — Create a new sheet tab in the spreadsheet.
+ */
+
+import chalk from "chalk";
+import ora from "ora";
+import { loadConfig } from "../../config/config.mjs";
+import { createSheetsClient } from "../../server/sheets-client.mjs";
+
+export async function createCommand(options) {
+  const config = loadConfig();
+  if (!config) {
+    console.error(chalk.red("❌ No configuration found. Run `npx google-sheet-mcp init` first."));
+    process.exit(1);
+  }
+
+  const spinner = ora(`Creating sheet "${options.sheet}"...`).start();
+
+  try {
+    const sheets = createSheetsClient(config.credentialsPath);
+
+    await sheets.spreadsheets.batchUpdate({
+      spreadsheetId: config.spreadsheetId,
+      requestBody: {
+        requests: [
+          {
+            addSheet: {
+              properties: {
+                title: options.sheet,
+              },
+            },
+          },
+        ],
+      },
+    });
+
+    spinner.succeed(`Sheet "${options.sheet}" created`);
+    console.log();
+    console.log(`  Read it: ${chalk.cyan(`npx google-sheet-mcp read -s "${options.sheet}"`)}`);
+
+  } catch (err) {
+    spinner.fail(`Failed: ${err.message}`);
+    process.exit(1);
+  }
+}

package/src/cli/commands/helpers/show-mcp-config.mjs

@@ -0,0 +1,71 @@
+/**
+ * Show MCP configuration snippets for all supported IDEs.
+ */
+
+import chalk from "chalk";
+
+export function showMCPConfig() {
+  console.log(chalk.bold("━━━ MCP Configuration ━━━"));
+  console.log();
+  console.log(chalk.bold("Cursor (.cursor/mcp.json):"));
+  console.log(
+    chalk.white(`{
+  "mcpServers": {
+    "google-sheets": {
+      "command": "npx",
+      "args": ["google-sheet-mcp"]
+    }
+  }
+}`)
+  );
+  console.log();
+  console.log(chalk.bold("VS Code (.vscode/mcp.json):"));
+  console.log(
+    chalk.white(`{
+  "servers": {
+    "google-sheets": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["google-sheet-mcp"]
+    }
+  }
+}`)
+  );
+  console.log();
+  console.log(chalk.bold("Claude Code (.claude/mcp.json):"));
+  console.log(
+    chalk.white(`{
+  "mcpServers": {
+    "google-sheets": {
+      "command": "npx",
+      "args": ["google-sheet-mcp"]
+    }
+  }
+}`)
+  );
+  console.log();
+  console.log(chalk.bold("Codex CLI (codex.json):"));
+  console.log(
+    chalk.white(`{
+  "mcpServers": {
+    "google-sheets": {
+      "command": "npx",
+      "args": ["-y", "google-sheet-mcp"]
+    }
+  }
+}`)
+  );
+  console.log();
+  console.log(chalk.gray("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"));
+  console.log();
+  console.log(
+    "After adding the config, restart your IDE. The AI will see these tools:"
+  );
+  console.log(chalk.green("  • sheets_list_tabs — list all sheets"));
+  console.log(chalk.green("  • sheets_read_range — read data"));
+  console.log(chalk.green("  • sheets_get_sheet — sheet metadata"));
+  console.log(chalk.green("  • sheets_write_range — write data"));
+  console.log(chalk.green("  • sheets_create_tab — create new tab"));
+  console.log(chalk.green("  • sheets_append_row — append a row"));
+  console.log();
+}