terra-mcp-google 0.1.13 → 0.1.15

package/README.md

@@ -18,8 +18,57 @@ terra-mcp client codex        # print safe (read-only) MCP config
 | `auth login` / `logout` / `status` | sign in / out / show account, scopes, expiry |
 | `setup` | check config dir + auth, print MCP config for all clients |
 | `client [codex\|claude\|copilot\|kiro\|all]` | print MCP config with **mutating tools disabled** (`--include-dangerous` keeps them) |
+| `admin` | open the web console to manage which resources the agent may access (`-p` port, `--no-open`) |
 | *(no command)* | start the stdio server |
 
+## Configuration
+
+Set these in your MCP client's `env` block (or the launching shell):
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `TERRA_MCP_DIR` | `~/.terra-mcp` | Directory holding the OAuth client config + cached token |
+| `GOOGLE_OAUTH_CREDENTIALS` | `<TERRA_MCP_DIR>/client_secret.json` | Google OAuth client JSON; overrides the embedded client |
+| `GOOGLE_OAUTH_TOKEN` | `<TERRA_MCP_DIR>/token.json` | Cached access/refresh token |
+| `TERRA_MCP_SAFE_MODE` | unset | `1` → register **only read-only tools**; drop every mutating tool |
+| `TERRA_MCP_LOCAL_FILE_ROOT` | unset | Only directory `local_path`/`save_path` may touch. Unset = local file up/download disabled |
+| `TERRA_MCP_POLICY_DB` | `<TERRA_MCP_DIR>/policy.db` | SQLite database holding the resource allowlist + policy mode |
+| `TERRA_MCP_POLICY_MODE` | `read_open` | Initial mode before one is chosen in the console: `off` \| `read_open` \| `strict` |
+| `TERRA_MCP_ADMIN_PORT` | `4717` | Port the `admin` web console listens on |
+| `TERRA_MCP_TOKEN_PROXY_URL` | bundled proxy | OAuth token-exchange proxy (advanced; only when self-hosting it) |
+| `TERRA_MCP_PROXY_KEY` | bundled key | Deterrent key sent to the proxy (ships in the package — not a secret) |
+
+**Restricting tools.** Disable the mutating tools server-side with `TERRA_MCP_SAFE_MODE=1`, or
+per-client with `terra-mcp client <agent>` (pass `--include-dangerous` to keep them on). Tools are
+also gated by the **OAuth scopes granted at login** — a Sheets-only grant exposes no `drive_*` tools.
+
+## Permission gate (per-resource allowlist)
+
+Beyond on/off tool gating, the server enforces a **per-resource allowlist**: you decide exactly
+which Drive files/folders and Sheets the agent may touch, and with what power (read / write / delete).
+Every tool call is checked against the allowlist (stored in a small local SQLite database) before it
+runs; created resources are auto-added so the agent can keep working with what it just made.
+
+```bash
+terra-mcp admin        # opens the web console at http://localhost:4717
+```
+
+**Three modes** (switch any time in the console):
+
+| Mode | The agent can… |
+| --- | --- |
+| `off` | …do anything your account can (gate disabled). |
+| `read_open` *(default)* | …**read** anything and **create** new resources, but only **write/delete existing** resources you've granted. Useful out of the box — nothing to configure to start reading. |
+| `strict` | …only **see and use** resources in the allowlist (and inside granted folders). Everything else is invisible, even to list/search. |
+
+**Grants** carry independent read / write / delete flags (new grants default to read-only — the safe
+starting point), and a grant on a **folder cascades** to everything inside it. Manage them — search
+your Drive to pick a file, or paste an ID — in the `admin` console. The console and the running
+server share the same database, so changes take effect on the agent's next call; no restart needed.
+
+> Requires **Node 23.4+** (or Node 22.5+ launched with `--experimental-sqlite`) for the gate. On
+> older Node the server still runs, with the gate disabled.
+
 ## Tools
 
 **Auth** — sign-in/out are CLI-only (`terra-mcp auth login`/`logout`).

package/dist/admin/api.d.ts

@@ -0,0 +1,35 @@
+import type { drive_v3 } from "googleapis";
+import type { PolicyStore } from "../policy/store.js";
+import type { ResourceKind } from "../policy/types.js";
+/** A Drive resource as surfaced to the admin console's "search & pick" flow. */
+export interface DriveItem {
+    id: string;
+    name: string;
+    mimeType: string;
+    kind: ResourceKind;
+}
+/** Collaborators the API routes need, injected so the router stays testable. */
+export interface ApiDeps {
+    store: PolicyStore;
+    searchDrive: (query: string) => Promise<DriveItem[]>;
+    authInfo: () => Promise<{
+        signedIn: boolean;
+        email: string | null;
+    }>;
+}
+/** A plain HTTP-ish response the transport layer serializes. */
+export interface ApiResponse {
+    status: number;
+    body: unknown;
+}
+/** Classify a Drive mimeType into the grant `kind` the gate understands. */
+export declare function kindOfMime(mimeType: string | null | undefined): ResourceKind;
+/** Build the `searchDrive` dependency backed by a live Drive client. */
+export declare function driveSearcher(drive: drive_v3.Drive): (query: string) => Promise<DriveItem[]>;
+/**
+ * The admin console's HTTP surface, as a pure function over (method, path, body)
+ * — no `node:http` objects — so it unit-tests against an in-memory store and
+ * fake deps. Returns `null` for non-`/api` paths so the caller can fall back to
+ * serving the SPA's static assets.
+ */
+export declare function routeApi(method: string, path: string, query: URLSearchParams, body: unknown, deps: ApiDeps): Promise<ApiResponse | null>;

package/dist/admin/api.js

@@ -0,0 +1,106 @@
+import { z } from "zod";
+import { DriveFileAdapter } from "../services/drive/adapter.js";
+const kindSchema = z.enum(["file", "folder", "spreadsheet"]);
+const modeSchema = z.enum(["off", "read_open", "strict"]);
+const createGrantSchema = z.object({
+    kind: kindSchema,
+    googleId: z.string().min(1),
+    name: z.string().nullish(),
+    canRead: z.boolean(),
+    canWrite: z.boolean(),
+    canDelete: z.boolean(),
+});
+const patchGrantSchema = z.object({
+    name: z.string().nullish(),
+    canRead: z.boolean().optional(),
+    canWrite: z.boolean().optional(),
+    canDelete: z.boolean().optional(),
+});
+/** Classify a Drive mimeType into the grant `kind` the gate understands. */
+export function kindOfMime(mimeType) {
+    if (mimeType === "application/vnd.google-apps.folder")
+        return "folder";
+    if (mimeType === "application/vnd.google-apps.spreadsheet")
+        return "spreadsheet";
+    return "file";
+}
+/** Build the `searchDrive` dependency backed by a live Drive client. */
+export function driveSearcher(drive) {
+    return async (query) => {
+        const trimmed = query.trim();
+        // Escape single quotes for the Drive `q` string literal.
+        const q = trimmed ? `name contains '${trimmed.replace(/'/g, "\\'")}'` : undefined;
+        const { files } = await new DriveFileAdapter(drive).listFiles({
+            query: q,
+            pageSize: 25,
+            orderBy: "modifiedTime desc",
+            includeTrashed: false,
+        });
+        return files
+            .filter((f) => typeof f.id === "string")
+            .map((f) => ({
+            id: f.id,
+            name: f.name ?? "(untitled)",
+            mimeType: f.mimeType ?? "application/octet-stream",
+            kind: kindOfMime(f.mimeType),
+        }));
+    };
+}
+/**
+ * The admin console's HTTP surface, as a pure function over (method, path, body)
+ * — no `node:http` objects — so it unit-tests against an in-memory store and
+ * fake deps. Returns `null` for non-`/api` paths so the caller can fall back to
+ * serving the SPA's static assets.
+ */
+export async function routeApi(method, path, query, body, deps) {
+    if (path !== "/api" && !path.startsWith("/api/"))
+        return null;
+    try {
+        if (path === "/api/health" && method === "GET") {
+            const auth = await deps.authInfo();
+            return ok({ ok: true, mode: deps.store.getMode(), ...auth });
+        }
+        if (path === "/api/grants") {
+            if (method === "GET")
+                return ok({ grants: deps.store.listGrants() });
+            if (method === "POST") {
+                const input = createGrantSchema.parse(body);
+                return ok({ grant: deps.store.upsertGrant(input) }, 201);
+            }
+        }
+        const grantId = path.match(/^\/api\/grants\/(\d+)$/);
+        if (grantId) {
+            const id = Number(grantId[1]);
+            if (method === "PATCH") {
+                const patch = patchGrantSchema.parse(body);
+                const grant = deps.store.updateGrant(id, patch);
+                return grant ? ok({ grant }) : fail(404, "Grant not found");
+            }
+            if (method === "DELETE") {
+                return deps.store.deleteGrant(id) ? ok({ ok: true }) : fail(404, "Grant not found");
+            }
+        }
+        if (path === "/api/mode" && method === "PUT") {
+            const { mode } = z.object({ mode: modeSchema }).parse(body);
+            deps.store.setMode(mode);
+            return ok({ mode });
+        }
+        if (path === "/api/drive/search" && method === "GET") {
+            return ok({ files: await deps.searchDrive(query.get("q") ?? "") });
+        }
+        return fail(404, "Not found");
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            return fail(400, error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; "));
+        }
+        return fail(500, error instanceof Error ? error.message : String(error));
+    }
+}
+function ok(body, status = 200) {
+    return { status, body };
+}
+function fail(status, error) {
+    return { status, body: { error } };
+}
+//# sourceMappingURL=api.js.map

package/dist/admin/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/admin/api.ts"],"names":[],"mappings":"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"}

package/dist/admin/server.d.ts

@@ -0,0 +1,14 @@
+export interface AdminServerHandle {
+    port: number;
+    url: string;
+    close: () => Promise<void>;
+}
+/**
+ * Start the admin web console: a tiny `node:http` server that exposes the policy
+ * REST API under `/api` and serves the built SPA for everything else. No
+ * framework, no extra runtime dependency.
+ */
+export declare function startAdminServer(opts?: {
+    port?: number;
+    staticDir?: string;
+}): Promise<AdminServerHandle>;

package/dist/admin/server.js

@@ -0,0 +1,138 @@
+import { createServer } from "node:http";
+import { readFile, stat } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, extname, join, normalize, resolve } from "node:path";
+import { ADMIN_PORT, getAdminStaticDir } from "../config/constants.js";
+import { getGoogleClients } from "../google/client.js";
+import { getAuthStatus } from "../google/auth.js";
+import { getPolicyStoreOrThrow } from "../policy/guard.js";
+import { driveSearcher, routeApi } from "./api.js";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const MIME = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".ico": "image/x-icon",
+    ".woff2": "font/woff2",
+    ".woff": "font/woff",
+};
+/** Build the API dependencies from the live policy store + Google clients. */
+function buildDeps() {
+    return {
+        store: getPolicyStoreOrThrow(),
+        searchDrive: async (query) => driveSearcher((await getGoogleClients()).drive)(query),
+        authInfo: async () => {
+            const status = await getAuthStatus().catch(() => ({ authenticated: false, email: null }));
+            return { signedIn: status.authenticated, email: status.email ?? null };
+        },
+    };
+}
+/** First existing candidate directory holding the built SPA, or undefined. */
+async function resolveStaticDir(override) {
+    const candidates = [
+        override,
+        getAdminStaticDir(),
+        join(HERE, "ui"), // production: copied beside the compiled server (dist/admin/ui)
+        join(HERE, "../../admin/dist"), // dev via tsx: the repo's built SPA
+    ].filter((c) => typeof c === "string");
+    const exists = await Promise.all(candidates.map(isDir));
+    return candidates.find((_, index) => exists[index]);
+}
+async function isDir(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function readBody(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(chunk);
+    if (chunks.length === 0)
+        return undefined;
+    const raw = Buffer.concat(chunks).toString("utf8");
+    return raw ? JSON.parse(raw) : undefined;
+}
+function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+    res.end(payload);
+}
+async function serveStatic(res, staticDir, urlPath) {
+    if (!staticDir) {
+        res.writeHead(503, { "content-type": "text/plain; charset=utf-8" });
+        res.end("Admin UI is not built. Run `pnpm admin:build` (or set TERRA_MCP_ADMIN_STATIC_DIR).");
+        return;
+    }
+    // Resolve the request to a file inside staticDir; fall back to index.html so
+    // the single-page app can handle its own routing. Reject path traversal.
+    const relative = normalize(urlPath === "/" ? "/index.html" : urlPath).replace(/^(\.\.[/\\])+/, "");
+    let filePath = resolve(staticDir, "." + relative);
+    if (!filePath.startsWith(resolve(staticDir)))
+        filePath = join(staticDir, "index.html");
+    if (!(await fileExists(filePath)))
+        filePath = join(staticDir, "index.html");
+    try {
+        const data = await readFile(filePath);
+        res.writeHead(200, { "content-type": MIME[extname(filePath)] ?? "application/octet-stream" });
+        res.end(data);
+    }
+    catch {
+        res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+        res.end("Not found");
+    }
+}
+async function fileExists(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Start the admin web console: a tiny `node:http` server that exposes the policy
+ * REST API under `/api` and serves the built SPA for everything else. No
+ * framework, no extra runtime dependency.
+ */
+export async function startAdminServer(opts = {}) {
+    const port = opts.port ?? ADMIN_PORT;
+    const deps = buildDeps();
+    const staticDir = await resolveStaticDir(opts.staticDir);
+    return new Promise((resolvePromise, rejectPromise) => {
+        const server = createServer((req, res) => {
+            void handle(req, res, deps, staticDir);
+        });
+        server.on("error", rejectPromise);
+        server.listen(port, () => {
+            resolvePromise({
+                port,
+                url: `http://localhost:${port}`,
+                close: () => new Promise((done) => server.close(() => done())),
+            });
+        });
+    });
+}
+async function handle(req, res, deps, staticDir) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const method = req.method ?? "GET";
+    try {
+        if (url.pathname === "/api" || url.pathname.startsWith("/api/")) {
+            const body = method === "GET" || method === "DELETE" ? undefined : await readBody(req);
+            const result = await routeApi(method, url.pathname, url.searchParams, body, deps);
+            if (result)
+                return sendJson(res, result.status, result.body);
+        }
+        await serveStatic(res, staticDir, url.pathname);
+    }
+    catch (error) {
+        sendJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/admin/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/admin/server.ts"],"names":[],"mappings":"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"}