google-sheet-mcp 1.0.0

package/src/cli/commands/init.mjs

@@ -0,0 +1,415 @@
+/**
+ * init — Interactive setup wizard.
+ *
+ * Two auth modes:
+ *   service-account (default):  JSON key + share sheet
+ *   oauth:                      OAuth2 browser flow → refresh token
+ *
+ * OAuth2 flow:
+ *   1. User pastes client_id + client_secret
+ *   2. CLI prints auth URL
+ *   3. User opens URL, grants access, copies code
+ *   4. CLI exchanges code for refresh_token
+ *   5. Token auto-refreshes forever
+ */
+
+import chalk from "chalk";
+import ora from "ora";
+import inquirer from "inquirer";
+import http from "http";
+import { URL } from "url";
+import { loadConfig, saveConfig, extractSpreadsheetId } from "../../config/config.mjs";
+import {
+  createServiceAccountSheetsClient,
+  createOAuth2SheetsClient,
+} from "../../server/sheets-client.mjs";
+import {
+  generateAuthUrl,
+  exchangeCodeForTokens,
+} from "../../server/oauth2-client.mjs";
+import { showMCPConfig } from "./helpers/show-mcp-config.mjs";
+
+export async function initCommand(options) {
+  const authType = options.auth || "service-account";
+  const isOAuth = authType === "oauth";
+
+  const authLabel = isOAuth
+    ? "OAuth2 (Personal Google Account)"
+    : "Service Account";
+
+  console.log(chalk.bold.cyan(`\n🔗 Google Sheet MCP — Setup Wizard`));
+  console.log(chalk.gray(`   Auth mode: ${authLabel}`));
+  console.log();
+
+  // Check for existing config
+  const existing = loadConfig();
+  if (existing) {
+    console.log(
+      chalk.yellow(
+        `⚠️  Already configured (${existing.source}): ${existing.spreadsheetId} (${existing.authType || "service-account"})`
+      )
+    );
+    const { overwrite } = await inquirer.prompt([
+      {
+        type: "confirm",
+        name: "overwrite",
+        message: "Overwrite existing configuration?",
+        default: false,
+      },
+    ]);
+    if (!overwrite) {
+      console.log(chalk.gray("  Setup cancelled."));
+      return;
+    }
+    console.log();
+  }
+
+  // Step 1: Google Sheet URL
+  console.log(chalk.bold("Step 1/4: Google Sheet"));
+  const { sheetUrl } = await inquirer.prompt([
+    {
+      type: "input",
+      name: "sheetUrl",
+      message: "Paste Google Sheet URL:",
+      validate: (input) => {
+        const id = extractSpreadsheetId(input);
+        if (!id)
+          return "Invalid Google Sheet URL. Expected: https://docs.google.com/spreadsheets/d/<ID>/edit";
+        return true;
+      },
+    },
+  ]);
+  const spreadsheetId = extractSpreadsheetId(sheetUrl);
+  console.log(chalk.green(`  ✅ Extracted ID: ${spreadsheetId}`));
+  console.log();
+
+  if (isOAuth) {
+    // ─── OAuth2 Flow ──────────────────────────────────────────────────────
+    await setupOAuth2(spreadsheetId);
+  } else {
+    // ─── Service Account Flow (default) ───────────────────────────────────
+    await setupServiceAccount(spreadsheetId);
+  }
+}
+
+/**
+ * Service Account setup.
+ */
+async function setupServiceAccount(spreadsheetId) {
+  console.log(chalk.bold("Step 2/4: Service Account Key"));
+  console.log(
+    chalk.gray("  If you haven't created one yet, see: docs/setup-google.md")
+  );
+  const { credentialsPath } = await inquirer.prompt([
+    {
+      type: "input",
+      name: "credentialsPath",
+      message: "Path to service account JSON key:",
+      default: "./credentials.json",
+    },
+  ]);
+  console.log(chalk.green(`  ✅ Credentials: ${credentialsPath}`));
+  console.log();
+
+  // Step 3: Verify connection
+  console.log(chalk.bold("Step 3/4: Verify connection"));
+  const spinner = ora("Connecting to Google Sheets...").start();
+
+  try {
+    const sheets = createServiceAccountSheetsClient({ credentialsPath });
+    const res = await sheets.spreadsheets.get({
+      spreadsheetId,
+      fields: "properties.title,sheets.properties",
+    });
+
+    const title = res.data.properties.title;
+    const sheetList = (res.data.sheets ?? []).map(
+      (s) => s.properties?.title || "(unnamed)"
+    );
+
+    spinner.succeed(`Connected to "${chalk.bold(title)}"`);
+    console.log(
+      chalk.green(
+        `  Found ${sheetList.length} sheet(s): ${sheetList.join(", ")}`
+      )
+    );
+    console.log();
+
+    // Save config
+    const configPath = saveConfig({
+      spreadsheetId,
+      authType: "service-account",
+      credentialsPath,
+      sheets: sheetList,
+    });
+
+    printSuccess(configPath, sheetList);
+  } catch (err) {
+    spinner.fail(`Connection failed: ${err.message}`);
+    printServiceAccountTroubleshooting();
+  }
+}
+
+/**
+ * OAuth2 setup flow.
+ */
+async function setupOAuth2(spreadsheetId) {
+  console.log(chalk.bold("Step 2/4: OAuth2 Credentials"));
+  console.log(
+    chalk.gray(
+      "  Get these from Google Cloud Console → APIs & Services → Credentials → Create OAuth client ID → Desktop app."
+    )
+  );
+
+  const { clientId, clientSecret } = await inquirer.prompt([
+    {
+      type: "input",
+      name: "clientId",
+      message: "Client ID:",
+      validate: (input) =>
+        input.length > 10
+          ? true
+          : "Invalid Client ID. Should be a long string ending with .apps.googleusercontent.com",
+    },
+    {
+      type: "input",
+      name: "clientSecret",
+      message: "Client Secret:",
+      validate: (input) =>
+        input.length > 5 ? true : "Invalid Client Secret.",
+    },
+  ]);
+
+  console.log(chalk.green(`  ✅ Credentials accepted`));
+  console.log();
+
+  // Step 3: Browser OAuth flow
+  console.log(chalk.bold("Step 3/4: Authorize Access"));
+
+  const authUrl = generateAuthUrl(clientId, clientSecret);
+  console.log();
+  console.log(
+    chalk.white("  1. Open this URL in your browser:")
+  );
+  console.log(chalk.cyan(`     ${authUrl}`));
+  console.log();
+  console.log(
+    chalk.white(
+      "  2. Sign in with your Google account"
+    )
+  );
+  console.log(
+    chalk.white(
+      "  3. Grant access to Google Sheets"
+    )
+  );
+  console.log(
+    chalk.white(
+      "  4. You'll be redirected to localhost — copy the 'code' parameter from the URL"
+    )
+  );
+  console.log();
+
+  // Try to auto-capture the code via local HTTP server
+  const code = await captureOAuthCode();
+
+  if (!code) {
+    // Fallback: manual entry
+    const { manualCode } = await inquirer.prompt([
+      {
+        type: "input",
+        name: "manualCode",
+        message:
+          "Paste the authorization code from the redirect URL (?code=...):",
+        validate: (input) =>
+          input.length > 5 ? true : "Code seems too short.",
+      },
+    ]);
+    return await completeOAuthSetup(spreadsheetId, clientId, clientSecret, manualCode);
+  }
+
+  return await completeOAuthSetup(spreadsheetId, clientId, clientSecret, code);
+}
+
+/**
+ * Start a local HTTP server to capture the OAuth redirect.
+ * Returns the authorization code or null (if user wants manual entry).
+ */
+function captureOAuthCode() {
+  return new Promise((resolve) => {
+    const server = http.createServer((req, res) => {
+      const parsed = new URL(req.url, "http://localhost:3000");
+      const code = parsed.searchParams.get("code");
+
+      if (code) {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(`
+          <html>
+          <body style="font-family: sans-serif; text-align: center; padding-top: 60px;">
+            <h1>✅ Authorization Successful</h1>
+            <p>You can close this tab and return to the terminal.</p>
+          </body>
+          </html>
+        `);
+        server.close();
+        resolve(code);
+      } else {
+        const error = parsed.searchParams.get("error");
+        res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(`
+          <html>
+          <body style="font-family: sans-serif; text-align: center; padding-top: 60px;">
+            <h1>❌ Authorization Failed</h1>
+            <p>Error: ${error || "unknown"}</p>
+          </body>
+          </html>
+        `);
+        server.close();
+        resolve(null);
+      }
+    });
+
+    server.listen(3000, () => {
+      console.log(
+        chalk.gray("  Waiting for browser redirect on http://localhost:3000 ...")
+      );
+    });
+
+    // Timeout after 2 minutes
+    setTimeout(() => {
+      server.close();
+      resolve(null);
+    }, 120_000);
+  });
+}
+
+/**
+ * Exchange code for tokens and test connection.
+ */
+async function completeOAuthSetup(spreadsheetId, clientId, clientSecret, code) {
+  console.log();
+  const exchangeSpinner = ora("Exchanging code for tokens...").start();
+
+  let tokens;
+  try {
+    tokens = await exchangeCodeForTokens(clientId, clientSecret, code);
+    exchangeSpinner.succeed("Tokens obtained");
+  } catch (err) {
+    exchangeSpinner.fail(`Failed: ${err.message}`);
+    console.log(
+      chalk.yellow(
+        "  The authorization code may have expired. Run the init command again."
+      )
+    );
+    return;
+  }
+
+  if (!tokens.refresh_token) {
+    console.log(
+      chalk.red(
+        "  ❌ No refresh token returned. Try again — make sure to approve all permissions."
+      )
+    );
+    return;
+  }
+
+  console.log(
+    chalk.green(
+      `  ✅ Refresh token: ${tokens.refresh_token.substring(0, 12)}...`
+    )
+  );
+  console.log();
+
+  // Step 4: Test connection
+  console.log(chalk.bold("Step 4/4: Verify connection"));
+  const spinner = ora("Connecting to Google Sheets...").start();
+
+  try {
+    const oauth2Config = {
+      client_id: clientId,
+      client_secret: clientSecret,
+      refresh_token: tokens.refresh_token,
+    };
+
+    const sheets = createOAuth2SheetsClient({ oauth2: oauth2Config });
+    const res = await sheets.spreadsheets.get({
+      spreadsheetId,
+      fields: "properties.title,sheets.properties",
+    });
+
+    const title = res.data.properties.title;
+    const sheetList = (res.data.sheets ?? []).map(
+      (s) => s.properties?.title || "(unnamed)"
+    );
+
+    spinner.succeed(`Connected to "${chalk.bold(title)}" (as you)`);
+    console.log(
+      chalk.green(
+        `  Found ${sheetList.length} sheet(s): ${sheetList.join(", ")}`
+      )
+    );
+    console.log();
+
+    // Save config
+    const configPath = saveConfig({
+      spreadsheetId,
+      authType: "oauth2",
+      oauth2: oauth2Config,
+      sheets: sheetList,
+    });
+
+    printSuccess(configPath, sheetList);
+  } catch (err) {
+    spinner.fail(`Connection failed: ${err.message}`);
+    printOAuthTroubleshooting();
+  }
+}
+
+function printSuccess(configPath, sheetList) {
+  console.log(chalk.green(`✅ Configuration saved to ${configPath}`));
+  console.log();
+
+  console.log(chalk.bold("🚀 You're ready!"));
+  console.log();
+  console.log("  Test connection:");
+  console.log(chalk.cyan("    npx google-sheet-mcp test"));
+  console.log();
+  console.log("  Check token health (OAuth2 only):");
+  console.log(chalk.cyan("    npx google-sheet-mcp token-status"));
+  console.log();
+  console.log("  List sheets:");
+  console.log(chalk.cyan("    npx google-sheet-mcp list"));
+  console.log();
+  console.log("  Read data:");
+  console.log(
+    chalk.cyan(`    npx google-sheet-mcp read -s "${sheetList[0]}"`)
+  );
+  console.log();
+
+  showMCPConfig();
+}
+
+function printServiceAccountTroubleshooting() {
+  console.log();
+  console.log(chalk.yellow("Common issues:"));
+  console.log("  1. Did you share the sheet with the service account email?");
+  console.log(
+    "  2. Is the Sheets API enabled in your Google Cloud project?"
+  );
+  console.log("  3. Is the JSON key file path correct?");
+  console.log();
+  console.log(chalk.gray("  Run the command again to retry."));
+}
+
+function printOAuthTroubleshooting() {
+  console.log();
+  console.log(chalk.yellow("Common issues:"));
+  console.log("  1. Do you have access to this spreadsheet?");
+  console.log("  2. Did you grant the full spreadsheets scope?");
+  console.log(
+    "  3. Is the Sheets API enabled in your Google Cloud project?"
+  );
+  console.log("  4. Try running `npx google-sheet-mcp token-status`");
+  console.log();
+  console.log(chalk.gray("  Run the command again to retry."));
+}

package/src/cli/commands/list.mjs

@@ -0,0 +1,50 @@
+/**
+ * list — Display all sheets in the connected spreadsheet.
+ */
+
+import chalk from "chalk";
+import ora from "ora";
+import { loadConfig } from "../../config/config.mjs";
+import { createSheetsClientFromConfig } from "../../server/sheets-client.mjs";
+
+export async function listCommand() {
+  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("Fetching sheets...").start();
+
+  try {
+    const sheets = createSheetsClientFromConfig(config);
+    const res = await sheets.spreadsheets.get({
+      spreadsheetId: config.spreadsheetId,
+      fields: "properties.title,sheets.properties",
+    });
+
+    spinner.succeed(`"${res.data.properties.title}"`);
+    console.log();
+
+    const sheetList = res.data.sheets ?? [];
+    sheetList.forEach((s) => {
+      const p = s.properties || {};
+      const title = p.title || "(unnamed)";
+      const rows = p.gridProperties?.rowCount || "?";
+      const cols = p.gridProperties?.columnCount || "?";
+      console.log(
+        chalk.green(`  📄 ${title}`) +
+          chalk.gray(`  ${rows}r × ${cols}c`)
+      );
+    });
+
+    console.log();
+    console.log(chalk.gray(`  Total: ${sheetList.length} sheet(s)`));
+    console.log();
+    console.log(`  Read data: ${chalk.cyan(`npx google-sheet-mcp read -s "${sheetList[0]?.properties?.title || 'Sheet1'}"`)}`);
+
+  } catch (err) {
+    spinner.fail(`Failed: ${err.message}`);
+    process.exit(1);
+  }
+}

package/src/cli/commands/read.mjs

@@ -0,0 +1,64 @@
+/**
+ * read — Read data from a specific sheet.
+ */
+
+import chalk from "chalk";
+import ora from "ora";
+import { loadConfig } from "../../config/config.mjs";
+import { createSheetsClientFromConfig } from "../../server/sheets-client.mjs";
+
+export async function readCommand(options) {
+  const config = loadConfig();
+  if (!config) {
+    console.error(chalk.red("❌ No configuration found. Run `npx google-sheet-mcp init` first."));
+    process.exit(1);
+  }
+
+  const range = options.range
+    ? `${options.sheet}!${options.range}`
+    : `${options.sheet}`;
+
+  const spinner = ora(`Reading "${range}"...`).start();
+
+  try {
+    const sheets = createSheetsClientFromConfig(config);
+    const res = await sheets.spreadsheets.values.get({
+      spreadsheetId: config.spreadsheetId,
+      range,
+      valueRenderOption: "FORMATTED_VALUE",
+      dateTimeRenderOption: "FORMATTED_STRING",
+    });
+
+    const rows = res.data.values || [];
+    spinner.succeed(`Read ${rows.length} rows from "${range.split("!")[0]}"`);
+
+    if (rows.length === 0) {
+      console.log(chalk.yellow("  (empty sheet)"));
+      return;
+    }
+
+    if (options.raw) {
+      // Raw 2D array
+      rows.forEach((row) => {
+        console.log(JSON.stringify(row));
+      });
+    } else {
+      // First row = headers, rest = objects
+      const [headers, ...data] = rows;
+      data.forEach((row) => {
+        const obj = {};
+        headers.forEach((h, j) => {
+          obj[h] = row[j] ?? "";
+        });
+        console.log(JSON.stringify(obj));
+      });
+    }
+
+    console.log();
+    console.log(chalk.gray(`  Total: ${options.raw ? rows.length : rows.length - 1} data row(s)`));
+
+  } catch (err) {
+    spinner.fail(`Failed to read: ${err.message}`);
+    process.exit(1);
+  }
+}

package/src/cli/commands/test.mjs

@@ -0,0 +1,99 @@
+/**
+ * test — Verify connection to the configured sheet.
+ */
+
+import chalk from "chalk";
+import ora from "ora";
+import { loadConfig } from "../../config/config.mjs";
+import { createSheetsClientFromConfig } from "../../server/sheets-client.mjs";
+
+export async function testCommand(options) {
+  const config = loadConfig();
+  if (!config) {
+    console.error(
+      chalk.red(
+        "❌ No configuration found.\n" +
+          '   Run "npx google-sheet-mcp init" first, or set env vars:\n' +
+          "   Service Account: GOOGLE_SPREADSHEET_ID + GOOGLE_APPLICATION_CREDENTIALS\n" +
+          "   OAuth2:          GOOGLE_SPREADSHEET_ID + GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET + GOOGLE_REFRESH_TOKEN"
+      )
+    );
+    process.exit(1);
+  }
+
+  console.log(chalk.bold.cyan("\n🔗 Google Sheet MCP — Connection Test\n"));
+  console.log(chalk.gray(`  Config source: ${config.source}`));
+  console.log(chalk.gray(`  Spreadsheet ID: ${config.spreadsheetId}`));
+  console.log(chalk.gray(`  Auth type:     ${config.authType || "service-account"}`));
+  if (config.authType === "service-account") {
+    console.log(chalk.gray(`  Key file:      ${config.credentialsPath}`));
+  } else {
+    console.log(chalk.gray(`  Client ID:     ${config.oauth2?.client_id?.substring(0, 16)}...`));
+  }
+  console.log();
+
+  const spinner = ora("Testing connection...").start();
+
+  try {
+    const sheets = createSheetsClientFromConfig(config);
+    const res = await sheets.spreadsheets.get({
+      spreadsheetId: config.spreadsheetId,
+      fields: "properties.title,sheets.properties",
+    });
+
+    const title = res.data.properties.title;
+    const sheetList = (res.data.sheets ?? []).map(
+      (s) => ({
+        title: s.properties?.title || "(unnamed)",
+        rows: s.properties?.gridProperties?.rowCount,
+        cols: s.properties?.gridProperties?.columnCount,
+      })
+    );
+
+    spinner.succeed(`Connected to "${chalk.bold(title)}"`);
+    console.log();
+
+    // If --sheet option, try reading it
+    if (options.sheet) {
+      const readSpinner = ora(`Reading sheet "${options.sheet}"...`).start();
+      try {
+        const data = await sheets.spreadsheets.values.get({
+          spreadsheetId: config.spreadsheetId,
+          range: `${options.sheet}!A1:Z5`,
+        });
+        const rows = data.data.values || [];
+        readSpinner.succeed(`Read ${rows.length} rows from "${options.sheet}"`);
+        console.log();
+        console.log(chalk.bold("  Preview:"));
+        rows.slice(0, 5).forEach((row, i) => {
+          console.log(chalk.gray(`  ${i === 0 ? "→" : " "} ${row.slice(0, 6).join(" | ")}`));
+        });
+      } catch (e) {
+        readSpinner.fail(`Cannot read "${options.sheet}": ${e.message}`);
+      }
+    } else {
+      // List all sheets
+      console.log(chalk.bold("Sheets:"));
+      sheetList.forEach((s) => {
+        console.log(chalk.green(`  ✓ ${s.title}`) + chalk.gray(`  (${s.rows} rows × ${s.cols} cols)`));
+      });
+    }
+
+    console.log();
+    console.log(chalk.green("✅ Connection OK — ready to use from AI agents!"));
+
+  } catch (err) {
+    spinner.fail(`Connection failed: ${err.message}`);
+    console.log();
+    console.log(chalk.yellow("Troubleshooting:"));
+    if (config.authType === "oauth2") {
+      console.log("  1. Run: npx google-sheet-mcp token-status  (check token health)");
+      console.log("  2. Re-run: npx google-sheet-mcp init --auth oauth  (replace token)");
+    } else {
+      console.log("  1. Is the service account email added as Editor on the sheet?");
+      console.log("  2. Is the Sheets API enabled?");
+    }
+    console.log("  3. Run: npx google-sheet-mcp config  (to verify settings)");
+    process.exit(1);
+  }
+}