Integration guide for Elvison OS
================================
Goal: a single "Activate Sheet MCP" button on the Elvison OS "new jobs" page that starts the Google Sheets MCP server, runs auth if needed, and confirms readiness.
Prereqs
- Install this repo as a dependency in Elvison OS (either `"google-sheets-mcp": "file:../google-sheets-mcp"` for local dev, or a git ref).
- Place your Google OAuth client JSON at `~/.config/google-sheets-mcp/gcp-oauth.keys.json` (or set `GSHEETS_OAUTH_PATH`).
- Credentials will be written/read at `~/.config/google-sheets-mcp/credentials.json` by default (override with `GSHEETS_CREDENTIALS_PATH`).
Server start command (SSE mode for a web client)
```
MCP_TRANSPORT=sse PORT=3325 HOST=127.0.0.1 \
GSHEETS_CONFIG_DIR=$HOME/.config/google-sheets-mcp \
npx google-sheets-mcp
```
- On first run (no credentials), a browser window pops for Google login and saves refreshed tokens.
- You can also inject JSON via env instead of files: `GSHEETS_OAUTH_JSON` and/or `GSHEETS_CREDENTIALS_JSON` (plain JSON or base64-encoded).
Button wiring (high level)
1) Add a backend endpoint in Elvison OS: `POST /api/mcp/google-sheets/activate`.
- If a server process is already running (health check `GET http://127.0.0.1:3325/health`), return 200.
- Otherwise spawn the command above (child process, detached/background). Log stdout/stderr.
2) After spawn, poll `/health` until it returns 200 or times out; if the server prints "Launching auth flow...", show the Google auth URL in the UI (or let the default browser open).
3) Frontend "Activate Sheet MCP" button calls this endpoint; show spinner/status until health passes, then mark tool as ready.
4) Configure the agent builder workflow to point the MCP client at `http://127.0.0.1:3325/sse` for transport, `POST /messages` for writes.
Optional quick health check tool call (from the agent)
- Call `list_sheets` with a known spreadsheet ID or `read_headings` on a test sheet. Use failures to prompt `refresh_auth`.
Recovery/re-auth
- If the refresh token is revoked/expired, rerun the activate button; the server will trigger the browser auth and overwrite `credentials.json`.
Important
- Keep the config dir out of git. Do not commit credential files.
- If Elvison OS runs in a sandbox/container, mount the config dir and pass the same env vars to the process.
