gogcli-mcp 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,35 @@
+{
+  "permissions": {
+    "allow": [
+      "Read(//Users/chris/git/ofw-mcp/**)",
+      "Read(//Users/chris/git/**)",
+      "Bash(gog --help)",
+      "Bash(gog agent:*)",
+      "Bash(gog schema:*)",
+      "Bash(python3 -c \"import json,sys; d=json.load\\(sys.stdin\\); cmds=[c['name'] for c in d['command'].get\\('subcommands',[]\\)]; print\\('\\\\n'.join\\(cmds\\)\\)\")",
+      "Bash(python3 -c ':*)",
+      "Bash(gog sheets:*)",
+      "Bash(git add:*)",
+      "Bash(git commit -m ':*)",
+      "Bash(xargs cat:*)",
+      "Bash(git:*)",
+      "Bash(npm install:*)",
+      "Bash(npm list:*)",
+      "Bash(npm --version)",
+      "Bash(python3 -c \"import json,sys; d=json.load\\(sys.stdin\\); print\\('lockfileVersion:', d.get\\('lockfileVersion'\\)\\); pkgs=d.get\\('packages',{}\\); mcp=pkgs.get\\('node_modules/@modelcontextprotocol/sdk',{}\\); zod=pkgs.get\\('node_modules/zod',{}\\); ts=pkgs.get\\('node_modules/typescript',{}\\); vitest=pkgs.get\\('node_modules/vitest',{}\\); esbuild=pkgs.get\\('node_modules/esbuild',{}\\); print\\('MCP SDK resolved:', mcp.get\\('version'\\)\\); print\\('zod resolved:', zod.get\\('version'\\)\\); print\\('typescript resolved:', ts.get\\('version'\\)\\); print\\('vitest resolved:', vitest.get\\('version'\\)\\); print\\('esbuild resolved:', esbuild.get\\('version'\\)\\)\")",
+      "Bash(npm test:*)",
+      "Bash(npx tsc:*)",
+      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\(d.get\\('version','?'\\)\\)\")",
+      "Bash(node_modules/.bin/tsc --version)",
+      "Bash(node_modules/.bin/tsc --noEmit)",
+      "Bash(cat /Users/chris/git/gogcli-mcp/vitest.config.*)",
+      "Bash(node:*)",
+      "Bash(npm run:*)",
+      "Bash(tsc:*)",
+      "Bash(ls /Users/chris/git/gogcli-mcp/*.json)",
+      "Bash(ls /Users/chris/git/gogcli-mcp/*.md)",
+      "Bash(python3 -c \"import json,sys; d=json.load\\(sys.stdin\\); print\\(json.dumps\\(d, indent=2\\)\\)\")",
+      "Bash(gh repo:*)"
+    ]
+  }
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+
+      - uses: actions/setup-node@v6.3.0
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci
+      - run: npm run build
+      - run: npm test

package/.github/workflows/release.yml

@@ -0,0 +1,76 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  release:
+    needs: ci
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v6.0.2
+
+      - uses: actions/setup-node@v6.3.0
+        with:
+          node-version: 24
+          cache: npm
+          registry-url: https://registry.npmjs.org
+
+      # Strip always-auth from .npmrc (set by setup-node, deprecated in npm 11)
+      - run: sed -i '/always-auth/d' "$NPM_CONFIG_USERCONFIG"
+
+      - run: npm ci
+      - run: npm run build
+
+      - name: Extract version
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          echo "VERSION=${VERSION}" >> "$GITHUB_ENV"
+
+      # Package the .skill file
+      - name: Package skill
+        run: |
+          python3 - <<'EOF'
+          import zipfile, pathlib, os
+
+          version = os.environ["VERSION"]
+          skill_name = "gogcli-mcp"
+          out = pathlib.Path(f"{skill_name}-{version}.skill")
+
+          with zipfile.ZipFile(out, "w", zipfile.ZIP_DEFLATED) as zf:
+              zf.write(pathlib.Path("SKILL.md"), f"{skill_name}/SKILL.md")
+
+          print(f"Packaged {out} ({out.stat().st_size} bytes)")
+          EOF
+
+      # Sync manifest.json version from package.json and build .mcpb
+      - name: Build .mcpb bundle
+        run: |
+          node -e "
+            const fs = require('fs');
+            const m = JSON.parse(fs.readFileSync('manifest.json', 'utf8'));
+            m.version = '$VERSION';
+            fs.writeFileSync('manifest.json', JSON.stringify(m, null, 2) + '\n');
+          "
+          npx @anthropic-ai/mcpb pack
+          mv gogcli-mcp.mcpb "gogcli-mcp-${VERSION}.mcpb"
+
+      - name: Publish to npm
+        run: npm publish --access public --provenance
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v3.0.0
+        with:
+          files: |
+            gogcli-mcp-${{ env.VERSION }}.skill
+            gogcli-mcp-${{ env.VERSION }}.mcpb
+          generate_release_notes: true

package/.github/workflows/tag-and-bump.yml

@@ -0,0 +1,67 @@
+name: Tag & Bump
+
+on:
+  workflow_dispatch:
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  tag-and-bump:
+    needs: ci
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v6.0.2
+        with:
+          # PAT required — GITHUB_TOKEN pushes don't trigger other workflows
+          token: ${{ secrets.RELEASE_PAT }}
+
+      - uses: actions/setup-node@v6.3.0
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      # Tag the current commit with the current version
+      - name: Tag current version
+        run: |
+          CURRENT=$(node -p "require('./package.json').version")
+          git tag "v${CURRENT}"
+          echo "TAGGED_VERSION=${CURRENT}" >> "$GITHUB_ENV"
+
+      # Bump patch version in all four locations
+      - name: Bump patch version
+        run: |
+          npm version patch --no-git-tag-version
+          NEXT=$(node -p "require('./package.json').version")
+          echo "NEXT_VERSION=${NEXT}" >> "$GITHUB_ENV"
+
+          # src/index.ts — MCP server version
+          sed -i "s/version: '${TAGGED_VERSION}'/version: '${NEXT}'/" src/index.ts
+
+          # manifest.json
+          node -e "
+            const fs = require('fs');
+            const m = JSON.parse(fs.readFileSync('manifest.json', 'utf8'));
+            m.version = '${NEXT}';
+            fs.writeFileSync('manifest.json', JSON.stringify(m, null, 2) + '\n');
+          "
+
+      - name: Rebuild
+        run: npm run build
+
+      - name: Commit and push
+        run: |
+          git add -A
+          git commit -m "chore: bump version to v${NEXT_VERSION}"
+          git push origin main
+          git push origin "v${TAGGED_VERSION}"

package/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "gogcli": {
+      "command": "node",
+      "args": ["dist/index.js"],
+      "cwd": "/Users/chris/git/gogcli-mcp",
+      "env": {
+        "GOG_ACCOUNT": "${GOG_ACCOUNT}"
+      }
+    }
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,61 @@
+# gogcli-mcp
+
+MCP server wrapping [gogcli](https://github.com/steipete/gogcli) — provides Claude with read/write access to Google Sheets, with a scaffold for Gmail, Calendar, Drive, and more.
+
+## Build & Test
+
+```bash
+npm run build        # tsc --noEmit (type check) + esbuild bundle → dist/index.js
+npm test             # vitest run (all tests)
+npm run test:watch   # vitest in watch mode
+npm run test:coverage  # vitest with 100% coverage enforcement
+npm run typecheck    # tsc --noEmit only
+```
+
+## Versioning
+
+Version appears in FOUR places — all must match:
+
+1. `package.json` → `"version"`
+2. `package-lock.json` → run `npm install --package-lock-only` after changing package.json
+3. `src/index.ts` → `McpServer` constructor `version` field
+4. `manifest.json` → `"version"`
+
+### Release workflow
+
+Main is always one version ahead of the latest tag. To release, run the **Tag & Bump** GitHub Action (`tag-and-bump.yml`) which:
+
+1. Runs CI (build + test)
+2. Tags the current commit with the current version
+3. Bumps patch in all four files
+4. Rebuilds, commits, and pushes main + tag
+5. The tag push triggers the **Release** workflow (CI + npm publish + .mcpb + .skill + GitHub release)
+
+Do NOT manually bump versions or create tags unless the user explicitly asks.
+
+## Architecture
+
+- `src/runner.ts` — only module touching `child_process`. Exports `run(args, options)` with `Spawner` DI for testing. Injects `--json --no-input --color=never`, handles `--account` from `options.account` → `GOG_ACCOUNT` env var → omit. 30-second timeout kills stalled processes.
+- `src/tools/sheets.ts` — registers 8 Sheets MCP tools via `registerSheetsTools(server)`. Imports `run()` from runner. Errors are caught and returned as text content so the model can read gogcli's error messages.
+- `src/index.ts` — MCP server entry point. Creates `McpServer`, calls `registerXxxTools(server)` for each service, connects via `StdioServerTransport`.
+- `tests/runner.test.ts` — unit tests for runner using mock `Spawner` DI (no real processes)
+- `tests/tools/sheets.test.ts` — unit tests for sheets tools, runner mocked via `vi.mock`
+
+## Adding a New Google Service
+
+To add Gmail, Calendar, Drive, etc.:
+
+1. Create `src/tools/<service>.ts` — export `registerXxxTools(server: McpServer)`
+2. Implement curated tools for common ops + a `gog_<service>_run` escape hatch (see `sheets.ts` for the pattern)
+3. Create `tests/tools/<service>.test.ts` — mock `runner.run` via `vi.mock('../../src/runner.js')`
+4. In `src/index.ts`, import and call `registerXxxTools(server)`
+5. Add tools to `manifest.json` tools list
+6. No changes to `runner.ts` or `.mcp.json` required
+
+## gogcli Notes
+
+- `gog schema --json` outputs machine-readable command/flag schema for all subcommands
+- `gog sheets update` and `gog sheets append` accept `--values-json=<JSON 2D array>` for structured input
+- All commands support `--account <email>` for multi-account targeting
+- `--no-input` prevents interactive prompts; `--json` ensures parseable output; `--color=never` strips ANSI codes
+- `gog agent exit-codes` documents stable exit codes for automation

package/README.md

@@ -0,0 +1,165 @@
+# gogcli-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that gives Claude natural-language access to Google Sheets (and more) via [gogcli](https://github.com/steipete/gogcli).
+
+> [!WARNING]
+> **AI-developed project.** This codebase was entirely built and is actively maintained by [Claude Sonnet 4.6](https://www.anthropic.com/claude). No human has audited the implementation. Review all code and tool permissions before use.
+
+## What you can do
+
+Ask Claude things like:
+
+- *"Read the data in Sheet1!A1:D20 of my budget spreadsheet"*
+- *"Append this week's expenses to my tracking sheet"*
+- *"Create a new spreadsheet called Q2 Planning"*
+- *"Find all instances of 'TBD' in my project sheet and replace with 'Done'"*
+- *"What tabs are in spreadsheet ID xyz?"*
+
+## Requirements
+
+- [gogcli](https://github.com/steipete/gogcli) installed and authenticated (`gog --help` works)
+- [Claude Desktop](https://claude.ai/download) or [Claude Code](https://claude.ai/code)
+- Node.js 18 or later
+
+Install gogcli via Homebrew:
+
+```bash
+brew install gogcli
+```
+
+Then authenticate:
+
+```bash
+gog auth add
+```
+
+## Installation
+
+### 1. Clone and build
+
+```bash
+git clone https://github.com/chrischall/gogcli-mcp.git
+cd gogcli-mcp
+npm install
+npm run build
+```
+
+### 2. Add to Claude Desktop
+
+Edit your Claude Desktop config file:
+
+- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+Add the `gogcli` entry inside `"mcpServers"`:
+
+```json
+{
+  "mcpServers": {
+    "gogcli": {
+      "command": "node",
+      "args": ["/absolute/path/to/gogcli-mcp/dist/index.js"],
+      "env": {
+        "GOG_ACCOUNT": "you@gmail.com"
+      }
+    }
+  }
+}
+```
+
+Replace `/absolute/path/to/gogcli-mcp` with the actual path. On Mac, run `pwd` inside the cloned directory to get it.
+
+`GOG_ACCOUNT` is optional — omit it to use gogcli's configured default account.
+
+### 3. Add to Claude Code
+
+The repo includes `.mcp.json`. From the project directory:
+
+```bash
+# The .mcp.json is already configured — just set your account
+export GOG_ACCOUNT=you@gmail.com
+```
+
+Or add `GOG_ACCOUNT` to your shell profile.
+
+## Tools
+
+Read-only tools run automatically. Write tools ask for confirmation first.
+
+| Tool | What it does | Permission |
+|------|-------------|------------|
+| `gog_sheets_get` | Read values from a range | Auto |
+| `gog_sheets_metadata` | Get title, tabs, and named ranges | Auto |
+| `gog_sheets_update` | Write values to a range | Confirm |
+| `gog_sheets_append` | Append rows after existing data | Confirm |
+| `gog_sheets_clear` | Clear values in a range | Confirm |
+| `gog_sheets_create` | Create a new spreadsheet | Confirm |
+| `gog_sheets_find_replace` | Find and replace across a spreadsheet | Confirm |
+| `gog_sheets_run` | Run any `gog sheets` subcommand (escape hatch) | Confirm |
+
+All tools accept an optional `account` parameter to target a specific Google account for that call, overriding `GOG_ACCOUNT`.
+
+## Multiple Accounts
+
+If you use multiple Google accounts with gogcli, you can target a specific account per-call:
+
+```
+Read Sheet1!A1:D10 from spreadsheet abc123 using my work account work@company.com
+```
+
+Claude will pass `account: "work@company.com"` to the tool, which adds `--account work@company.com` to the gogcli command.
+
+## Troubleshooting
+
+**"gog not found"** — gogcli is not installed or not in your PATH. Run `gog --help` in your terminal to verify. Install with `brew install gogcli`.
+
+**"not authenticated"** — run `gog auth add` to authenticate. Run `gog auth list` to see configured accounts.
+
+**"Spreadsheet not found"** — verify the spreadsheet ID (the long string in the URL between `/d/` and `/edit`).
+
+**Tools not appearing in Claude Desktop** — go to **Settings → Developer** to see connected servers. Fully quit and relaunch after editing the config.
+
+**Can't find the config file on Mac** — in Finder press Cmd+Shift+G and paste `~/Library/Application Support/Claude/`.
+
+## Security
+
+- `GOG_ACCOUNT` is optional and only selects which authenticated account to use
+- No credentials are stored or passed by this server — authentication is handled entirely by gogcli's own keyring
+- All gogcli invocations use `--no-input` to prevent interactive prompts
+- All arguments are passed as arrays to `child_process.spawn` — no shell injection risk
+
+## Development
+
+```bash
+npm test                # run the test suite (33 tests, 100% coverage)
+npm run build           # compile TypeScript → dist/index.js
+npm run test:coverage   # run with coverage report
+```
+
+### Project structure
+
+```
+src/
+  runner.ts       gog CLI executor (auth injection, timeout, error handling)
+  index.ts        MCP server entry point
+  tools/
+    sheets.ts     8 Google Sheets tools
+tests/
+  runner.test.ts
+  tools/
+    sheets.test.ts
+```
+
+### Adding more Google services
+
+gogcli supports Gmail, Calendar, Drive, Contacts, Tasks, Docs, Slides, Chat, and more. To add a service:
+
+1. Create `src/tools/<service>.ts` with `registerXxxTools(server: McpServer)`
+2. Create `tests/tools/<service>.test.ts` (mock runner via `vi.mock`)
+3. Call `registerXxxTools(server)` in `src/index.ts`
+
+See `CLAUDE.md` for the full pattern.
+
+## License
+
+MIT

package/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.