google-sheet-mcp 1.0.0

package/src/cli/commands/token-status.mjs

@@ -0,0 +1,114 @@
+/**
+ * token-status — Check OAuth2 refresh token health.
+ *
+ * Validates the refresh token by attempting to get a fresh access token.
+ * Useful for:
+ *   - Debugging "access denied" errors
+ *   - Checking if token was revoked
+ *   - Pre-flight check before CI/CD usage
+ */
+
+import chalk from "chalk";
+import ora from "ora";
+import { loadConfig } from "../../config/config.mjs";
+import {
+  validateRefreshToken,
+  getTokenInfo,
+} from "../../server/oauth2-client.mjs";
+
+export async function tokenStatusCommand() {
+  console.log(chalk.bold.cyan("\n🔑 Google Sheet MCP — Token Status\n"));
+
+  const config = loadConfig();
+  if (!config) {
+    console.error(
+      chalk.red(
+        "❌ No configuration found. Run `npx google-sheet-mcp init --auth oauth` first."
+      )
+    );
+    process.exit(1);
+  }
+
+  console.log(chalk.gray(`  Config source: ${config.source}`));
+  console.log(chalk.gray(`  Auth type:     ${config.authType || "service-account"}`));
+  console.log();
+
+  if (config.authType !== "oauth2") {
+    console.log(
+      chalk.yellow(
+        "⚠️  Token-status is only relevant for OAuth2 authentication.\n" +
+          "   Service accounts use JSON keys that don't expire."
+      )
+    );
+    return;
+  }
+
+  // Show stored token info
+  const info = getTokenInfo(config.oauth2);
+  console.log(chalk.bold("Stored token:"));
+  console.log(chalk.white(`  Status:      ${info.status}`));
+  if (info.clientId) {
+    console.log(chalk.white(`  Client ID:   ${info.clientId}`));
+  }
+  if (info.refreshTokenPrefix) {
+    console.log(
+      chalk.white(`  Refresh:     ${info.refreshTokenPrefix}`)
+    );
+  }
+  if (info.issues) {
+    for (const issue of info.issues) {
+      console.log(chalk.red(`  ❌ ${issue}`));
+    }
+  }
+  console.log();
+
+  if (info.status !== "configured") {
+    console.log(
+      chalk.red(
+        "❌ Token is incomplete. Run `npx google-sheet-mcp init --auth oauth` to reconfigure."
+      )
+    );
+    process.exit(1);
+  }
+
+  // Validate by refreshing
+  const spinner = ora("Validating refresh token...").start();
+
+  try {
+    const result = await validateRefreshToken(config.oauth2);
+
+    if (result.valid) {
+      spinner.succeed("Token is valid");
+      console.log();
+      console.log(chalk.green("✅ Refresh token is healthy"));
+      console.log(chalk.gray(`  Access token expires: ${result.expiresAt}`));
+      console.log(chalk.gray(`  Scopes: ${result.scopes}`));
+      console.log();
+      console.log(
+        chalk.white(
+          "  AI agents can now access your Google Sheets on your behalf."
+        )
+      );
+    } else {
+      spinner.fail(`Token is invalid: ${result.error}`);
+      console.log();
+      console.log(chalk.yellow(`  Hint: ${result.hint}`));
+      console.log();
+      console.log(
+        chalk.white("  To replace the token, run:")
+      );
+      console.log(
+        chalk.cyan("    npx google-sheet-mcp init --auth oauth")
+      );
+      console.log(
+        chalk.gray(
+          "    This will walk you through the OAuth flow and save a new refresh token."
+        )
+      );
+      process.exit(1);
+    }
+  } catch (err) {
+    spinner.fail(`Validation error: ${err.message}`);
+    process.exit(1);
+  }
+}

package/src/config/config.mjs

@@ -0,0 +1,166 @@
+/**
+ * Configuration management.
+ *
+ * Supports two auth types:
+ *   1. Service Account:  GOOGLE_SPREADSHEET_ID + GOOGLE_APPLICATION_CREDENTIALS
+ *   2. OAuth2:           GOOGLE_SPREADSHEET_ID + GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET + GOOGLE_REFRESH_TOKEN
+ *
+ * Resolution order:
+ *   1. ENV vars
+ *   2. .google-sheet-mcp.json in CWD
+ *   3. ~/.google-sheet-mcp.json (global)
+ */
+
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { homedir } from "os";
+import { join, resolve } from "path";
+
+const CONFIG_FILENAME = ".google-sheet-mcp.json";
+
+/**
+ * Detect auth type from env vars.
+ */
+function detectAuthFromEnv() {
+  const spreadsheetId = process.env.GOOGLE_SPREADSHEET_ID;
+  if (!spreadsheetId) return null;
+
+  // Service account
+  const saCreds = process.env.GOOGLE_APPLICATION_CREDENTIALS;
+  if (saCreds) {
+    return {
+      spreadsheetId,
+      authType: "service-account",
+      credentialsPath: saCreds,
+      source: "env",
+    };
+  }
+
+  // OAuth2
+  const clientId = process.env.GOOGLE_CLIENT_ID;
+  const clientSecret = process.env.GOOGLE_CLIENT_SECRET;
+  const refreshToken = process.env.GOOGLE_REFRESH_TOKEN;
+  if (clientId && clientSecret && refreshToken) {
+    return {
+      spreadsheetId,
+      authType: "oauth2",
+      oauth2: {
+        client_id: clientId,
+        client_secret: clientSecret,
+        refresh_token: refreshToken,
+      },
+      source: "env",
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Validate a config object has all required fields.
+ */
+function isValidConfig(config) {
+  if (!config || !config.spreadsheetId) return false;
+
+  if (config.authType === "service-account") {
+    return !!config.credentialsPath;
+  }
+
+  if (config.authType === "oauth2") {
+    return !!(
+      config.oauth2?.client_id &&
+      config.oauth2?.client_secret &&
+      config.oauth2?.refresh_token
+    );
+  }
+
+  return false;
+}
+
+/**
+ * Load config from local file, global file, or env vars.
+ */
+export function loadConfig() {
+  // 1. ENV vars — highest priority
+  const envConfig = detectAuthFromEnv();
+  if (envConfig) return envConfig;
+
+  // 2. Local config (.google-sheet-mcp.json in CWD)
+  const localPath = resolve(process.cwd(), CONFIG_FILENAME);
+  if (existsSync(localPath)) {
+    const config = JSON.parse(readFileSync(localPath, "utf-8"));
+    if (isValidConfig(config)) {
+      config._path = localPath;
+      config.source = "local";
+      return config;
+    }
+  }
+
+  // 3. Global config (~/.google-sheet-mcp.json)
+  const globalPath = join(homedir(), CONFIG_FILENAME);
+  if (existsSync(globalPath)) {
+    const config = JSON.parse(readFileSync(globalPath, "utf-8"));
+    if (isValidConfig(config)) {
+      config._path = globalPath;
+      config.source = "global";
+      return config;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Save config to local file (CWD) or global (~/).
+ *
+ * Config shape:
+ *   Service Account: { spreadsheetId, authType: "service-account", credentialsPath, sheets }
+ *   OAuth2:          { spreadsheetId, authType: "oauth2", oauth2: { client_id, client_secret, refresh_token }, sheets }
+ */
+export function saveConfig(
+  { spreadsheetId, authType, credentialsPath, oauth2, sheets },
+  global = false
+) {
+  const configPath = global
+    ? join(homedir(), CONFIG_FILENAME)
+    : resolve(process.cwd(), CONFIG_FILENAME);
+
+  const existing = existsSync(configPath)
+    ? JSON.parse(readFileSync(configPath, "utf-8"))
+    : {};
+
+  const config = {
+    ...existing,
+    spreadsheetId,
+    authType: authType || existing.authType || "service-account",
+    sheets: sheets || existing.sheets || [],
+  };
+
+  if (authType === "oauth2" || existing.authType === "oauth2") {
+    config.oauth2 = oauth2 || existing.oauth2 || {};
+    delete config.credentialsPath;
+  } else {
+    config.credentialsPath = credentialsPath || existing.credentialsPath;
+    delete config.oauth2;
+  }
+
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  return configPath;
+}
+
+/**
+ * Extract spreadsheetId from Google Sheets URL.
+ */
+export function extractSpreadsheetId(url) {
+  // Formats:
+  // https://docs.google.com/spreadsheets/d/<ID>/edit
+  // https://docs.google.com/spreadsheets/d/<ID>/edit#gid=0
+  const match = url.match(
+    /\/spreadsheets\/d\/([a-zA-Z0-9_-]+)/
+  );
+  if (match) return match[1];
+
+  // Maybe it's already a raw ID
+  if (/^[a-zA-Z0-9_-]{20,}$/.test(url)) return url;
+
+  return null;
+}

package/src/server/oauth2-client.mjs

@@ -0,0 +1,155 @@
+/**
+ * OAuth2 Google Sheets client.
+ *
+ * Uses refresh token — no browser login needed after initial setup.
+ * Token auto-refreshes via googleapis library.
+ *
+ * Setup flow (one-time):
+ *   1. Create OAuth2 credentials in Google Cloud Console
+ *   2. Run `npx google-sheet-mcp init --auth oauth`
+ *   3. Follow browser OAuth flow
+ *   4. Refresh token is saved and auto-refreshed forever
+ *
+ * Token health:
+ *   - `npx google-sheet-mcp token-status` — check if token is valid
+ *   - Invalid token → run `npx google-sheet-mcp init --auth oauth` again
+ */
+
+import { google } from "googleapis";
+
+/**
+ * Create OAuth2 client from stored refresh token.
+ * Automatically refreshes access token if expired.
+ */
+export function createOAuth2Client(credentials) {
+  const { client_id, client_secret, refresh_token } = credentials;
+
+  if (!client_id || !client_secret) {
+    throw new Error(
+      "Missing OAuth2 credentials: client_id and client_secret are required.\n" +
+        "Get them from Google Cloud Console → APIs & Services → Credentials → Create OAuth client ID."
+    );
+  }
+
+  if (!refresh_token) {
+    throw new Error(
+      "Missing refresh_token. Run `npx google-sheet-mcp init --auth oauth` to complete OAuth2 setup."
+    );
+  }
+
+  const auth = new google.auth.OAuth2(client_id, client_secret);
+  auth.setCredentials({ refresh_token });
+
+  // Auto-refresh: googleapis handles this transparently.
+  // Every API call checks if the access token is expired and refreshes if needed.
+
+  return auth;
+}
+
+/**
+ * Create sheets client using OAuth2.
+ */
+export function createOAuth2SheetsClient(credentials) {
+  const auth = createOAuth2Client(credentials);
+  return google.sheets({ version: "v4", auth });
+}
+
+/**
+ * Generate the OAuth2 authorization URL.
+ * User visits this URL, grants access, gets a code.
+ */
+export function generateAuthUrl(client_id, client_secret) {
+  const auth = new google.auth.OAuth2(
+    client_id,
+    client_secret,
+    "http://localhost:3000/oauth2callback"
+  );
+
+  return auth.generateAuthUrl({
+    access_type: "offline", // ← CRITICAL: forces refresh_token to be returned
+    prompt: "consent",       // ← CRITICAL: always show consent (ensures refresh_token every time)
+    scope: ["https://www.googleapis.com/auth/spreadsheets"],
+  });
+}
+
+/**
+ * Exchange authorization code for tokens.
+ * Returns { access_token, refresh_token, expiry_date }.
+ */
+export async function exchangeCodeForTokens(
+  client_id,
+  client_secret,
+  code
+) {
+  const auth = new google.auth.OAuth2(
+    client_id,
+    client_secret,
+    "http://localhost:3000/oauth2callback"
+  );
+
+  const { tokens } = await auth.getToken(code);
+  return tokens;
+}
+
+/**
+ * Validate a refresh token by trying to get a fresh access token.
+ *
+ * Returns { valid: true } or { valid: false, error: string }.
+ */
+export async function validateRefreshToken(credentials) {
+  const { client_id, client_secret, refresh_token } = credentials;
+
+  if (!client_id || !client_secret || !refresh_token) {
+    return {
+      valid: false,
+      error: "Missing credentials (client_id, client_secret, or refresh_token).",
+    };
+  }
+
+  try {
+    const auth = new google.auth.OAuth2(client_id, client_secret);
+    auth.setCredentials({ refresh_token });
+
+    // Force token refresh — this will fail if the refresh_token is invalid
+    const { credentials: newCreds } = await auth.refreshAccessToken();
+
+    return {
+      valid: true,
+      expiresAt: newCreds.expiry_date
+        ? new Date(newCreds.expiry_date).toISOString()
+        : "unknown",
+      scopes: newCreds.scope || "unknown",
+    };
+  } catch (err) {
+    return {
+      valid: false,
+      error: err.message,
+      hint:
+        "The refresh token is invalid or revoked. Run `npx google-sheet-mcp init --auth oauth` to re-authenticate.",
+    };
+  }
+}
+
+/**
+ * Get token info without making an API call.
+ * Just checks if the stored token exists and looks valid.
+ */
+export function getTokenInfo(credentials) {
+  const { client_id, client_secret, refresh_token } = credentials;
+
+  const issues = [];
+
+  if (!client_id) issues.push("Missing client_id");
+  if (!client_secret) issues.push("Missing client_secret");
+  if (!refresh_token) issues.push("Missing refresh_token");
+
+  if (issues.length > 0) {
+    return { status: "missing", issues };
+  }
+
+  return {
+    status: "configured",
+    clientId: `${client_id.substring(0, 12)}...`,
+    refreshTokenPrefix: `${refresh_token.substring(0, 12)}...`,
+  };
+}