gogcli-mcp 1.0.0

package/docs/superpowers/specs/2026-04-12-gogcli-mcp-design.md

@@ -0,0 +1,102 @@
+# gogcli-mcp Design Spec
+
+**Date:** 2026-04-12
+**Status:** Approved
+
+## Overview
+
+An MCP server that wraps the `gog` CLI (gogcli), exposing Google service operations as typed MCP tools. Sheets is implemented first; the architecture is scaffolded for easy addition of other services (Gmail, Calendar, Drive, etc.).
+
+## Architecture
+
+### Project Structure
+
+```
+gogcli-mcp/
+├── src/
+│   ├── index.ts          — MCP server entry point; registers all service tools
+│   ├── runner.ts         — Core executor: spawns gog, handles auth & errors
+│   └── tools/
+│       └── sheets.ts     — Sheets curated tools + escape hatch
+├── package.json
+├── tsconfig.json
+└── .mcp.json             — MCP server config for Claude Code
+```
+
+### Key Principle
+
+No service tool file touches `child_process` directly. All execution goes through `runner.ts`. Adding a new service means creating `src/tools/<service>.ts` and registering it in `index.ts`.
+
+## Components
+
+### `runner.ts`
+
+Exports a single `run(service, subcommand, args, options)` function:
+
+- Prepends global flags: `--json`, `--no-input`, `--color=never`
+- Injects `--account <email>` from `options.account` → `GOG_ACCOUNT` env var → omit
+- Spawns `gog` as a child process, capturing stdout and stderr separately
+- On exit code 0: returns parsed JSON (or raw stdout if not valid JSON)
+- On non-zero exit: throws an error with stderr content as the message (gogcli stderr is human-readable)
+
+### `src/tools/sheets.ts`
+
+Exports `registerSheetsTools(server: McpServer)`. Implements:
+
+| Tool | gog command | Notes |
+|------|-------------|-------|
+| `gog_sheets_get` | `gog sheets get <id> <range>` | Read-only hint |
+| `gog_sheets_update` | `gog sheets update <id> <range> <values>` | Values as JSON array of arrays |
+| `gog_sheets_append` | `gog sheets append <id> <range> <values>` | Values as JSON array of arrays |
+| `gog_sheets_clear` | `gog sheets clear <id> <range>` | Destructive hint |
+| `gog_sheets_metadata` | `gog sheets metadata <id>` | Returns tabs, named ranges, etc. |
+| `gog_sheets_create` | `gog sheets create <title>` | Returns new spreadsheet ID |
+| `gog_sheets_find_replace` | `gog sheets find-replace <id> <find> <replace>` | |
+| `gog_sheets_run` | `gog sheets <subcommand> [args...]` | Escape hatch for any other sheets op |
+
+All tools accept an optional `account` string parameter to override the default account.
+
+### `src/index.ts`
+
+Creates the `McpServer`, calls `registerSheetsTools(server)` (and future service registrations), connects via `StdioServerTransport`.
+
+### `.mcp.json`
+
+Documents `GOG_ACCOUNT` as the environment variable for the default Google account. Used by Claude Code to configure the server.
+
+## Auth Flow
+
+Account resolution order (most specific wins):
+
+1. Tool-level `account` parameter (per-call override)
+2. `GOG_ACCOUNT` environment variable (session default)
+3. No `--account` flag (gogcli uses its own configured default)
+
+## Error Handling
+
+- Runner captures stdout and stderr as separate streams
+- Non-zero exit: throw `Error(stderr)` — gogcli error messages are already user-readable
+- The MCP tool catches the error and returns it as text content so the model sees it
+
+## Testing
+
+- **Unit tests** (vitest): mock `child_process.spawn` to assert correct argument construction for each tool without executing gogcli
+- **No integration tests**: real-world validation is done by running the server against live gogcli
+
+## Adding Future Services
+
+To add a new service (e.g., Gmail):
+
+1. Create `src/tools/gmail.ts` with `registerGmailTools(server)`
+2. Implement curated tools for common operations + a `gog_gmail_run` escape hatch
+3. Import and call `registerGmailTools(server)` in `src/index.ts`
+4. No changes to `runner.ts` required
+
+## Stack
+
+- **Language:** TypeScript (ES2022, NodeNext modules)
+- **MCP SDK:** `@modelcontextprotocol/sdk`
+- **Schema validation:** Zod
+- **Build:** esbuild (single bundled output)
+- **Tests:** vitest
+- **Pattern:** Mirrors ofw-mcp structure

package/manifest.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://raw.githubusercontent.com/anthropics/dxt/main/dist/mcpb-manifest.schema.json",
+  "manifest_version": "0.3",
+  "name": "gogcli-mcp",
+  "display_name": "gogcli",
+  "version": "1.0.0",
+  "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
+  "author": {
+    "name": "Chris Hall",
+    "email": "chris.c.hall@gmail.com",
+    "url": "https://github.com/chrischall"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chrischall/gogcli-mcp"
+  },
+  "homepage": "https://github.com/chrischall/gogcli-mcp",
+  "support": "https://github.com/chrischall/gogcli-mcp/issues",
+  "license": "MIT",
+  "keywords": [
+    "google",
+    "sheets",
+    "spreadsheet",
+    "gmail",
+    "calendar",
+    "drive",
+    "gogcli",
+    "gog"
+  ],
+  "server": {
+    "type": "node",
+    "entry_point": "dist/index.js",
+    "mcp_config": {
+      "command": "node",
+      "args": [
+        "${__dirname}/dist/index.js"
+      ],
+      "env": {
+        "GOG_ACCOUNT": "${user_config.gog_account}"
+      }
+    }
+  },
+  "user_config": {
+    "gog_account": {
+      "type": "string",
+      "title": "Google Account",
+      "description": "Default Google account email (optional — uses gogcli's configured default if omitted)",
+      "required": false
+    }
+  },
+  "tools": [
+    {
+      "name": "gog_sheets_get",
+      "description": "Read values from a Google Sheets range"
+    },
+    {
+      "name": "gog_sheets_update",
+      "description": "Write values to a Google Sheets range"
+    },
+    {
+      "name": "gog_sheets_append",
+      "description": "Append rows to a Google Sheet"
+    },
+    {
+      "name": "gog_sheets_clear",
+      "description": "Clear values in a Google Sheets range"
+    },
+    {
+      "name": "gog_sheets_metadata",
+      "description": "Get spreadsheet metadata (title, tabs, named ranges)"
+    },
+    {
+      "name": "gog_sheets_create",
+      "description": "Create a new Google Spreadsheet"
+    },
+    {
+      "name": "gog_sheets_find_replace",
+      "description": "Find and replace text across a spreadsheet"
+    },
+    {
+      "name": "gog_sheets_run",
+      "description": "Run any gog sheets subcommand (escape hatch)"
+    }
+  ],
+  "compatibility": {
+    "platforms": [
+      "darwin",
+      "linux",
+      "win32"
+    ],
+    "runtimes": {
+      "node": ">=18.0.0"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "gogcli-mcp",
+  "version": "1.0.0",
+  "description": "MCP server wrapping gogcli for Google service access",
+  "type": "module",
+  "bin": {
+    "gogcli-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc --noEmit && npm run bundle",
+    "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "@vitest/coverage-v8": "^4.1.2",
+    "esbuild": "^0.28.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}

package/skills/gogcli/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: gogcli-mcp
+description: Use when the user asks to read, write, or manage Google Sheets. Also triggers for requests involving Google Sheets data like "read my spreadsheet", "update a cell", "append rows", "create a spreadsheet", or "find and replace in Sheets". Broader Google service support (Gmail, Calendar, Drive) can be added via future service modules.
+---
+
+# gogcli-mcp
+
+MCP server wrapping [gogcli](https://github.com/steipete/gogcli) — provides Claude with access to Google Sheets (and a scaffold for Gmail, Calendar, Drive, and more).
+
+- **Source:** [github.com/chrischall/gogcli-mcp](https://github.com/chrischall/gogcli-mcp)
+
+## Requirements
+
+- [gogcli](https://github.com/steipete/gogcli) installed and authenticated (`gog --help` works in your shell)
+- Node.js 18 or later
+
+## Setup
+
+### Option A — Claude Code (direct MCP)
+
+Add to `.mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "gogcli": {
+      "command": "node",
+      "args": ["/path/to/gogcli-mcp/dist/index.js"],
+      "cwd": "/path/to/gogcli-mcp",
+      "env": {
+        "GOG_ACCOUNT": "you@gmail.com"
+      }
+    }
+  }
+}
+```
+
+### Option B — npx
+
+```json
+{
+  "mcpServers": {
+    "gogcli": {
+      "command": "npx",
+      "args": ["-y", "gogcli-mcp"],
+      "env": {
+        "GOG_ACCOUNT": "you@gmail.com"
+      }
+    }
+  }
+}
+```
+
+`GOG_ACCOUNT` is optional — omit it to use gogcli's configured default account. Pass it per-tool-call to target a specific account dynamically.
+
+## Available Tools
+
+| Tool | What it does |
+|------|-------------|
+| `gog_sheets_get` | Read values from a range |
+| `gog_sheets_update` | Write values to a range |
+| `gog_sheets_append` | Append rows after existing data |
+| `gog_sheets_clear` | Clear values in a range |
+| `gog_sheets_metadata` | Get title, tabs, named ranges |
+| `gog_sheets_create` | Create a new spreadsheet |
+| `gog_sheets_find_replace` | Find and replace across a spreadsheet |
+| `gog_sheets_run` | Run any `gog sheets` subcommand (escape hatch) |
+
+All tools accept an optional `account` parameter to override the default Google account for that call.

package/src/index.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerSheetsTools } from './tools/sheets.js';
+
+const server = new McpServer({ name: 'gogcli', version: '1.0.0' });
+
+registerSheetsTools(server);
+
+// To add more services: import registerXxxTools and call them here.
+// Example: registerGmailTools(server);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/runner.ts

@@ -0,0 +1,61 @@
+import { spawn } from 'node:child_process';
+import type { ChildProcess } from 'node:child_process';
+
+export type Spawner = (
+  command: string,
+  args: string[],
+  options: { env: NodeJS.ProcessEnv },
+) => ChildProcess;
+
+export interface RunOptions {
+  account?: string;
+  spawner?: Spawner;
+}
+
+const TIMEOUT_MS = 30_000;
+
+export async function run(args: string[], options: RunOptions = {}): Promise<string> {
+  const { account, spawner = spawn as unknown as Spawner } = options;
+
+  const effectiveAccount = account ?? process.env.GOG_ACCOUNT;
+
+  const fullArgs = ['--json', '--no-input', '--color=never'];
+  if (effectiveAccount) {
+    fullArgs.push('--account', effectiveAccount);
+  }
+  fullArgs.push(...args);
+
+  return new Promise((resolve, reject) => {
+    const child = spawner('gog', fullArgs, { env: process.env });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+
+    const timer = setTimeout(() => {
+      settled = true;
+      child.kill();
+      reject(new Error(`gog timed out after ${TIMEOUT_MS}ms`));
+    }, TIMEOUT_MS);
+
+    child.stdout!.on('data', (chunk: Buffer) => { stdout += chunk.toString(); });
+    child.stderr!.on('data', (chunk: Buffer) => { stderr += chunk.toString(); });
+
+    child.on('close', (code: number | null) => {
+      clearTimeout(timer);
+      if (settled) return;
+      settled = true;
+      if (code === 0) {
+        resolve(stdout);
+      } else {
+        reject(new Error(stderr.trim() || `gog exited with code ${code}`));
+      }
+    });
+
+    child.on('error', (err: Error) => {
+      clearTimeout(timer);
+      if (settled) return;
+      settled = true;
+      reject(err);
+    });
+  });
+}

package/src/tools/sheets.ts

@@ -0,0 +1,151 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { run } from '../runner.js';
+
+const accountParam = z.string().optional().describe(
+  'Google account email to use (overrides GOG_ACCOUNT env var)',
+);
+
+function toText(output: string): { content: [{ type: 'text'; text: string }] } {
+  return { content: [{ type: 'text' as const, text: output }] };
+}
+
+function toError(err: unknown): { content: [{ type: 'text'; text: string }] } {
+  return toText(err instanceof Error ? `Error: ${err.message}` : String(err));
+}
+
+export function registerSheetsTools(server: McpServer): void {
+  server.registerTool('gog_sheets_get', {
+    description: 'Read values from a Google Sheets range. Returns a JSON object with a "values" array of rows.',
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      spreadsheetId: z.string().describe('Spreadsheet ID (from the URL)'),
+      range: z.string().describe('Range in A1 notation, e.g. Sheet1!A1:B10 or a named range'),
+      account: accountParam,
+    },
+  }, async ({ spreadsheetId, range, account }) => {
+    try {
+      return toText(await run(['sheets', 'get', spreadsheetId, range], { account }));
+    } catch (err) {
+      return toError(err);
+    }
+  });
+
+  server.registerTool('gog_sheets_update', {
+    description: 'Write values to a Google Sheets range, overwriting existing content.',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      spreadsheetId: z.string().describe('Spreadsheet ID (from the URL)'),
+      range: z.string().describe('Top-left cell or range in A1 notation, e.g. Sheet1!A1'),
+      values: z.array(z.array(z.string())).describe('2D array of values: outer array is rows, inner is columns'),
+      account: accountParam,
+    },
+  }, async ({ spreadsheetId, range, values, account }) => {
+    try {
+      return toText(await run(
+        ['sheets', 'update', spreadsheetId, range, `--values-json=${JSON.stringify(values)}`],
+        { account },
+      ));
+    } catch (err) {
+      return toError(err);
+    }
+  });
+
+  server.registerTool('gog_sheets_append', {
+    description: 'Append rows to a Google Sheet after the last row with data in the given range.',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      spreadsheetId: z.string().describe('Spreadsheet ID (from the URL)'),
+      range: z.string().describe('Range indicating which sheet/columns to append to, e.g. Sheet1!A:C'),
+      values: z.array(z.array(z.string())).describe('2D array of rows to append'),
+      account: accountParam,
+    },
+  }, async ({ spreadsheetId, range, values, account }) => {
+    try {
+      return toText(await run(
+        ['sheets', 'append', spreadsheetId, range, `--values-json=${JSON.stringify(values)}`],
+        { account },
+      ));
+    } catch (err) {
+      return toError(err);
+    }
+  });
+
+  server.registerTool('gog_sheets_clear', {
+    description: 'Clear all values in a Google Sheets range (formatting is preserved).',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      spreadsheetId: z.string().describe('Spreadsheet ID'),
+      range: z.string().describe('Range in A1 notation to clear'),
+      account: accountParam,
+    },
+  }, async ({ spreadsheetId, range, account }) => {
+    try {
+      return toText(await run(['sheets', 'clear', spreadsheetId, range], { account }));
+    } catch (err) {
+      return toError(err);
+    }
+  });
+
+  server.registerTool('gog_sheets_metadata', {
+    description: 'Get spreadsheet metadata: title, sheet tabs, named ranges, and other properties.',
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      spreadsheetId: z.string().describe('Spreadsheet ID'),
+      account: accountParam,
+    },
+  }, async ({ spreadsheetId, account }) => {
+    try {
+      return toText(await run(['sheets', 'metadata', spreadsheetId], { account }));
+    } catch (err) {
+      return toError(err);
+    }
+  });
+
+  server.registerTool('gog_sheets_create', {
+    description: 'Create a new Google Spreadsheet. Returns JSON with the new spreadsheetId and URL.',
+    inputSchema: {
+      title: z.string().describe('Title for the new spreadsheet'),
+      account: accountParam,
+    },
+  }, async ({ title, account }) => {
+    try {
+      return toText(await run(['sheets', 'create', title], { account }));
+    } catch (err) {
+      return toError(err);
+    }
+  });
+
+  server.registerTool('gog_sheets_find_replace', {
+    description: 'Find and replace text across an entire Google Spreadsheet.',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      spreadsheetId: z.string().describe('Spreadsheet ID'),
+      find: z.string().describe('Text to find'),
+      replace: z.string().describe('Replacement text'),
+      account: accountParam,
+    },
+  }, async ({ spreadsheetId, find, replace, account }) => {
+    try {
+      return toText(await run(['sheets', 'find-replace', spreadsheetId, find, replace], { account }));
+    } catch (err) {
+      return toError(err);
+    }
+  });
+
+  server.registerTool('gog_sheets_run', {
+    description: 'Run any gog sheets subcommand not covered by the other tools. See `gog sheets --help` for the full list of subcommands and their flags.',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      subcommand: z.string().describe('The gog sheets subcommand to run, e.g. "freeze", "add-tab", "rename-tab"'),
+      args: z.array(z.string()).describe('Additional positional args and flags, e.g. ["<spreadsheetId>", "--rows=1"]'),
+      account: accountParam,
+    },
+  }, async ({ subcommand, args, account }) => {
+    try {
+      return toText(await run(['sheets', subcommand, ...args], { account }));
+    } catch (err) {
+      return toError(err);
+    }
+  });
+}