google-tools-mcp 1.2.11 → 2.0.0

package/dist/httpAuth.js

@@ -0,0 +1,296 @@
+// Application-level authentication and origin guarding for the shared HTTP
+// transport (PR #36 review).
+//
+// The HTTP transport exposes the full authenticated Google Workspace tool
+// surface (Gmail, Drive, Calendar, Docs, ...) over a local URL. Even bound to
+// loopback, that URL is reachable by any other process on the machine and — via
+// a browser POST or a DNS-rebinding attack — potentially by untrusted web
+// content. Protocol-level session isolation does not authorize the caller.
+//
+// This module adds two gates, applied only in HTTP mode:
+//   1. A bearer token. Required by default; auto-generated and logged if the
+//      operator did not set one. This defeats untrusted local processes and any
+//      browser-delivered request that lacks the token.
+//   2. Origin validation. Browser-originated cross-site requests always carry
+//      an Origin header; native MCP clients do not. Requests whose Origin is not
+//      loopback (or explicitly allow-listed) are rejected — the MCP spec's
+//      recommended DNS-rebinding protection.
+//
+// FastMCP's `authenticate(request)` runs before any tool executes and, in HTTP
+// mode, a thrown error is turned into an HTTP 401 by the underlying transport.
+// In stdio mode `authenticate` is invoked with no request, so these gates are
+// inert there and the default transport is byte-for-byte unaffected.
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import http from 'node:http';
+
+/**
+ * Resolve HTTP auth configuration from the environment. Pure — no side effects.
+ * Does not validate the combination of `noAuth` and `host` — call
+ * `assertSafeHttpBinding` on the result before starting the HTTP transport.
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function resolveHttpAuthConfig(env = process.env) {
+    const explicitToken = (env.GOOGLE_MCP_HTTP_TOKEN || '').trim();
+    const noAuth = /^(1|true|yes|on)$/i.test((env.GOOGLE_MCP_HTTP_NO_AUTH || '').trim());
+    const host = (env.GOOGLE_MCP_HTTP_HOST || '127.0.0.1').trim();
+    const allowedOrigins = (env.GOOGLE_MCP_HTTP_ALLOWED_ORIGINS || '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return { explicitToken, noAuth, host, allowedOrigins };
+}
+
+/**
+ * Refuse configurations that would expose the authenticated Google Workspace
+ * tool surface (Gmail, Drive, Calendar, Docs, ...) with no way to keep out an
+ * unauthenticated remote caller.
+ *
+ * Two things are unsafe on their own and must stop startup, not just log a
+ * warning after the fact:
+ *   1. `GOOGLE_MCP_HTTP_NO_AUTH=1` (no bearer token) combined with a bind host
+ *      that is not strictly loopback (e.g. `0.0.0.0`, `::`, a LAN IP, or a
+ *      hostname). That is a remotely reachable server with zero
+ *      authentication.
+ *   2. An empty or whitespace-only host after trimming. `env.HOST || '...'`
+ *      treats a whitespace string as truthy, so `GOOGLE_MCP_HTTP_HOST="  "`
+ *      previously resolved to `''`, which Node's http server can bind as "all
+ *      interfaces" instead of the intended loopback default.
+ *
+ * @param {{ host: string, noAuth: boolean }} config result of resolveHttpAuthConfig
+ * @throws {Error} with an operator-facing message if the combination is unsafe
+ */
+export function assertSafeHttpBinding({ host, noAuth }) {
+    const trimmedHost = typeof host === 'string' ? host.trim() : '';
+    if (!trimmedHost) {
+        throw new Error(
+            'GOOGLE_MCP_HTTP_HOST resolved to an empty value after trimming. Refusing to start: ' +
+            'an empty host can make the HTTP server bind to all interfaces instead of loopback. ' +
+            'Unset GOOGLE_MCP_HTTP_HOST to use the 127.0.0.1 default, or set it to a real host.'
+        );
+    }
+    if (noAuth && !isLoopbackHost(trimmedHost)) {
+        throw new Error(
+            `Refusing to start: GOOGLE_MCP_HTTP_NO_AUTH is set and GOOGLE_MCP_HTTP_HOST is ` +
+            `'${trimmedHost}', which is not loopback. That combination starts a remotely ` +
+            'reachable server with zero authentication in front of every Google Workspace tool ' +
+            '(Gmail, Drive, Docs, Calendar, ...). Either remove GOOGLE_MCP_HTTP_NO_AUTH so the ' +
+            'bearer token stays required, or bind to a loopback host (127.0.0.1, localhost, ::1).'
+        );
+    }
+}
+
+/** Generate a high-entropy URL-safe token. */
+export function generateToken() {
+    return randomBytes(24).toString('base64url');
+}
+
+/** True if `hostname` is a loopback address. */
+export function isLoopbackHost(hostname) {
+    return (
+        hostname === 'localhost' ||
+        hostname === '127.0.0.1' ||
+        hostname === '::1' ||
+        hostname === '[::1]'
+    );
+}
+
+/**
+ * Decide whether a request's Origin header is acceptable.
+ * Absent Origin (native, non-browser clients) is allowed. A present Origin must
+ * be loopback or in the explicit allow-list.
+ * @param {string|undefined|null} origin
+ * @param {string[]} allowedOrigins
+ */
+export function isOriginAllowed(origin, allowedOrigins = []) {
+    if (!origin) return true; // native MCP clients don't send Origin
+    if (allowedOrigins.includes(origin)) return true;
+    try {
+        const u = new URL(origin);
+        return isLoopbackHost(u.hostname);
+    } catch {
+        return false;
+    }
+}
+
+function firstHeader(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+
+/**
+ * Pull a bearer token from an incoming request. Accepts
+ * `Authorization: Bearer <token>` or an `X-MCP-Token: <token>` header.
+ * @param {import('node:http').IncomingMessage} request
+ * @returns {string|null}
+ */
+export function extractBearerToken(request) {
+    const headers = request?.headers || {};
+    const authHeader = firstHeader(headers['authorization'] ?? headers['Authorization']);
+    if (typeof authHeader === 'string') {
+        const m = /^Bearer\s+(.+)$/i.exec(authHeader.trim());
+        if (m) return m[1].trim();
+    }
+    const alt = firstHeader(headers['x-mcp-token']);
+    if (typeof alt === 'string' && alt.trim()) return alt.trim();
+    return null;
+}
+
+/** Constant-time string comparison that won't throw on length mismatch. */
+export function tokensMatch(a, b) {
+    if (typeof a !== 'string' || typeof b !== 'string' || a.length === 0) return false;
+    const ab = Buffer.from(a, 'utf8');
+    const bb = Buffer.from(b, 'utf8');
+    if (ab.length !== bb.length) return false;
+    return timingSafeEqual(ab, bb);
+}
+
+/**
+ * Build the FastMCP `authenticate(request)` function for HTTP mode.
+ * Throws (→ HTTP 401) on a disallowed origin or a missing/invalid token.
+ * Returns a session auth object on success.
+ *
+ * @param {{ token?: string, noAuth?: boolean, allowedOrigins?: string[] }} config
+ * @param {{ warn?: Function }} [logger]
+ */
+export function createHttpAuthenticate(config, logger) {
+    return async function authenticate(request) {
+        // stdio transport calls authenticate() with no request — nothing to guard.
+        if (!request) return {};
+
+        const result = checkHttpAuth(request.headers, config);
+        if (!result.ok) {
+            logger?.warn?.(result.reason);
+            throw new Error(result.message);
+        }
+
+        return { authenticated: true };
+    };
+}
+
+/**
+ * Apply the origin and token gates to a plain headers object.
+ *
+ * Both the FastMCP `authenticate` hook and the transport middleware call this,
+ * so there is one definition of what an acceptable request looks like and the
+ * two cannot drift apart.
+ *
+ * @param {Record<string, string|string[]|undefined>} headers
+ * @param {{ token?: string, noAuth?: boolean, allowedOrigins?: string[] }} config
+ * @returns {{ok: true} | {ok: false, status: number, message: string, reason: string}}
+ */
+export function checkHttpAuth(headers, config) {
+    const { token, noAuth = false, allowedOrigins = [] } = config || {};
+
+    const origin = firstHeader(headers?.origin ?? headers?.Origin);
+    if (!isOriginAllowed(origin, allowedOrigins)) {
+        return {
+            ok: false,
+            status: 403,
+            message: 'Forbidden: request Origin is not allowed',
+            reason: `Rejected HTTP request from disallowed Origin: ${origin}`,
+        };
+    }
+
+    if (!noAuth) {
+        const provided = extractBearerToken({ headers });
+        if (!tokensMatch(provided, token)) {
+            return {
+                ok: false,
+                status: 401,
+                message: 'Unauthorized: missing or invalid authentication token',
+                reason: 'Rejected HTTP request: missing or invalid authentication token.',
+            };
+        }
+    }
+
+    return { ok: true };
+}
+
+/**
+ * Build a request guard that applies the same gates to every HTTP method and
+ * every route the underlying listener can dispatch to, not just the
+ * configured streamable-HTTP endpoint.
+ *
+ * FastMCP's `authenticate` hook is only reached on session creation. In the
+ * pinned mcp-proxy that means POST to the streamable endpoint: its GET branch
+ * (attaching to a session's event stream) and DELETE branch (terminating a
+ * session) dispatch on the Mcp-Session-Id header alone and never call the
+ * hook. Anyone who learned a session id could read from or kill that session
+ * without presenting a token, while the README promises every request is
+ * bearer-protected.
+ *
+ * That gap is not limited to the configured endpoint (normally `/mcp`).
+ * FastMCP's call into mcp-proxy's `startHTTPServer` never passes
+ * `sseEndpoint`, so mcp-proxy's default of `/sse` (plus its companion POST
+ * `/messages` route) is always live alongside the streamable endpoint,
+ * whatever `GOOGLE_MCP_ENDPOINT` is set to, and there is no supported FastMCP
+ * option to turn that legacy SSE compatibility transport off. Guarding only
+ * the configured endpoint would leave `/sse` and `/messages` completely
+ * unauthenticated, so this guard instead applies to every path except the two
+ * that must stay open for the protocol to work at all.
+ *
+ * Returns true when it has already written a rejection, false to let the
+ * request continue.
+ *
+ * OPTIONS is let through: browsers never attach Authorization to a preflight,
+ * and the real request behind it is still gated. `GET /ping` is let through:
+ * it is mcp-proxy's own unauthenticated health check, carries no session data
+ * and no tool surface, and is documented as staying open.
+ *
+ * @param {{ token?: string, noAuth?: boolean, allowedOrigins?: string[] }} config
+ * @param {{ warn?: Function }} [logger]
+ */
+export function createHttpRequestGuard(config, logger) {
+    return function guardRequest(req, res) {
+        if (req.method === 'OPTIONS') return false;
+
+        let pathname;
+        try {
+            pathname = new URL(req.url ?? '/', 'http://localhost').pathname;
+        } catch {
+            return false;
+        }
+        if (req.method === 'GET' && pathname === '/ping') return false;
+
+        const result = checkHttpAuth(req.headers, config);
+        if (result.ok) return false;
+
+        logger?.warn?.(`${result.reason} (${req.method} ${pathname})`);
+        res.setHeader('Content-Type', 'application/json');
+        res.writeHead(result.status).end(JSON.stringify({ error: result.message }));
+        return true;
+    };
+}
+
+/**
+ * Run `start` with every HTTP server it creates wrapped in `guard`.
+ *
+ * There is no supported way to reach mcp-proxy's request listener: FastMCP does
+ * not accept middleware for the stream transport, its Hono app is not what
+ * serves this endpoint, and startHTTPServer returns only a close function. So
+ * we substitute http.createServer for the duration of startup, wrap whatever
+ * listener gets handed to it, and put the original back before returning. The
+ * substitution is confined to that window and never touches anything the caller
+ * creates before or after.
+ *
+ * @param {() => Promise<void>} start
+ * @param {(req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => boolean} guard
+ */
+export async function startWithRequestGuard(start, guard) {
+    const originalCreateServer = http.createServer;
+    http.createServer = function patchedCreateServer(...args) {
+        const listenerIndex = args.findIndex((arg) => typeof arg === 'function');
+        if (listenerIndex !== -1) {
+            const listener = args[listenerIndex];
+            args[listenerIndex] = function guardedListener(req, res) {
+                if (guard(req, res)) return undefined;
+                return listener.call(this, req, res);
+            };
+        }
+        return originalCreateServer.apply(this, args);
+    };
+    try {
+        return await start();
+    } finally {
+        http.createServer = originalCreateServer;
+    }
+}

package/dist/index.js

@@ -8,9 +8,22 @@
 //   google-tools-mcp          Start the MCP server (default)
 //   google-tools-mcp auth     Run the interactive OAuth flow
 //   google-tools-mcp setup    Guided setup: enable APIs, create credentials, authenticate
+import { createRequire } from 'module';
 import { FastMCP } from 'fastmcp';
 import { registerAllTools } from './tools/index.js';
 import { logger } from './logger.js';
+import { getConfigDir } from './auth.js';
+import { checkForUpdate } from './updateCheck.js';
+import { resolveHttpAuthConfig, assertSafeHttpBinding, generateToken, createHttpAuthenticate, createHttpRequestGuard, startWithRequestGuard } from './httpAuth.js';
+import { clearSession } from './readTracker.js';
+
+// Read our own published version straight from package.json rather than
+// hardcoding it. `files: ["dist"]` in package.json only restricts what npm
+// packs; package.json itself always ships at the package root (npm
+// includes it unconditionally), so this resolves the same way both in this
+// checkout and once installed globally.
+const require = createRequire(import.meta.url);
+const { version: packageVersion } = require('../package.json');
 
 // --- Setup subcommand ---
 if (process.argv[2] === 'setup') {
@@ -37,6 +50,54 @@ if (process.argv[2] === 'auth') {
     }
 }
 
+// --- Transport selection ---
+// Default is stdio (one server spawned per MCP client, the classic model).
+// Set GOOGLE_MCP_TRANSPORT=http to run a single long-lived HTTP server that
+// many clients share over a localhost URL — one process instead of one per
+// session. Accepts "http" or "httpStream" (both map to FastMCP httpStream).
+const transportEnv = (process.env.GOOGLE_MCP_TRANSPORT || 'stdio').toLowerCase();
+const useHttp = transportEnv === 'http' || transportEnv === 'httpstream';
+const httpPort = Number(process.env.GOOGLE_MCP_PORT) || 3939;
+const httpEndpoint = process.env.GOOGLE_MCP_ENDPOINT || '/mcp';
+
+// --- HTTP security ---
+// The HTTP transport exposes the authenticated Google tool surface over a local
+// URL. Gate it behind a bearer token + Origin validation and bind to loopback
+// by default so it isn't reachable by untrusted local processes, browser-
+// delivered requests, or the network. (PR #36 review)
+const httpAuth = resolveHttpAuthConfig(process.env);
+if (useHttp) {
+    // Refuse to start rather than log a warning after the fact: a non-loopback
+    // host combined with GOOGLE_MCP_HTTP_NO_AUTH=1 is a remotely reachable,
+    // completely unauthenticated server in front of Gmail/Drive/Docs/Calendar,
+    // and an empty host after trimming can make Node bind to all interfaces.
+    // Written straight to stderr (not the logger) so LOG_LEVEL=error/silent
+    // can't hide the reason the process refused to start.
+    try {
+        assertSafeHttpBinding(httpAuth);
+    } catch (configError) {
+        process.stderr.write(`FATAL: ${configError.message}\n`);
+        process.exit(1);
+    }
+}
+let httpToken = httpAuth.explicitToken;
+if (useHttp && !httpAuth.noAuth && !httpToken) {
+    // No token configured — generate a one-time one so the server is never
+    // unauthenticated by accident. Log it prominently; the operator should set
+    // GOOGLE_MCP_HTTP_TOKEN to a fixed value to keep it stable across restarts.
+    httpToken = generateToken();
+    // Write straight to stderr rather than through the logger. LOG_LEVEL=error
+    // and LOG_LEVEL=silent are both documented settings, and either one would
+    // swallow a warn-level message — starting a server that demands a token
+    // nobody ever saw, so every client gets rejected with no way to recover.
+    process.stderr.write(
+        'GOOGLE_MCP_HTTP_TOKEN is not set — generated a one-time token for this run.\n' +
+        `  Token: ${httpToken}\n` +
+        '  Clients must send:  Authorization: Bearer <token>\n' +
+        '  Set GOOGLE_MCP_HTTP_TOKEN to keep this stable across restarts.\n'
+    );
+}
+
 // --- Process lifecycle logging ---
 process.on('uncaughtException', (error) => {
     logger.error('Uncaught Exception:', error);
@@ -55,31 +116,121 @@ process.on('SIGTERM', () => {
 // Exit when the MCP client closes the stdio pipe.
 // This is the primary shutdown path for stdio MCP servers — SIGTERM is not
 // reliably delivered on Windows when a parent process exits.
-process.stdin.on('close', () => {
-    logger.info('stdin closed — MCP client disconnected. Shutting down.');
-    process.exit(0);
-});
-process.stdin.on('end', () => {
-    logger.info('stdin ended — MCP client disconnected. Shutting down.');
-    process.exit(0);
-});
+//
+// IMPORTANT: only wire these in stdio mode. In HTTP mode the server is a
+// detached daemon whose stdin ends/closes immediately at launch — attaching
+// these there would make the daemon exit the instant it starts.
+if (!useHttp) {
+    process.stdin.on('close', () => {
+        logger.info('stdin closed — MCP client disconnected. Shutting down.');
+        process.exit(0);
+    });
+    process.stdin.on('end', () => {
+        logger.info('stdin ended — MCP client disconnected. Shutting down.');
+        process.exit(0);
+    });
+}
 process.on('exit', (code) => {
     logger.info(`Process exiting with code ${code}.`);
 });
 
 // --- Server startup ---
-const server = new FastMCP({
+const serverOptions = {
     name: 'google-tools-mcp',
     version: '1.0.0',
+};
+if (useHttp) {
+    // authenticate() runs before any tool; a throw becomes an HTTP 401. It is
+    // only attached in HTTP mode, so stdio behavior is unchanged.
+    serverOptions.authenticate = createHttpAuthenticate(
+        { token: httpToken, noAuth: httpAuth.noAuth, allowedOrigins: httpAuth.allowedOrigins },
+        logger,
+    );
+}
+const server = new FastMCP(serverOptions);
+
+// Free per-session tracker state when an HTTP client disconnects, so a long-
+// lived shared server doesn't accumulate it indefinitely.
+server.on('disconnect', ({ session }) => {
+    try {
+        const key = session?.sessionId;
+        if (key) clearSession(key);
+    } catch (cleanupError) {
+        logger.warn(`Session cleanup failed: ${cleanupError.message || cleanupError}`);
+    }
 });
 
 await registerAllTools(server);
 
 try {
     logger.info('Starting google-tools-mcp server...');
-    await server.start({ transportType: 'stdio' });
-    logger.info('MCP Server running using stdio. Awaiting client connection...');
+    // process.uptime() covers the whole life of this node process, including
+    // module load time, so a slow number here means the server itself is
+    // slow to boot. If this is fast (~1s) but the MCP client still reports a
+    // long time-to-connect, the delay is happening before this process even
+    // started — e.g. npx re-resolving the dependency tree on every launch.
+    // See https://github.com/karthikcsq/google-tools-mcp/issues/46
+    //
+    // Measured inside each branch rather than once before them, so the number
+    // covers the transport actually being brought up: binding a port is not
+    // the same work as attaching to a stdio pipe.
+    let readyMs;
+    if (useHttp) {
+        // authenticate() above only runs on session creation (POST). The guard
+        // covers every method and every route mcp-proxy can dispatch to
+        // (including the legacy /sse and /messages compatibility endpoints
+        // FastMCP always stands up alongside the configured streamable
+        // endpoint), so GET stream attachment and DELETE session termination
+        // have to present the same token instead of riding on a session id
+        // alone.
+        const guard = createHttpRequestGuard(
+            { token: httpToken, noAuth: httpAuth.noAuth, allowedOrigins: httpAuth.allowedOrigins },
+            logger,
+        );
+        await startWithRequestGuard(() => server.start({
+            transportType: 'httpStream',
+            httpStream: { port: httpPort, endpoint: httpEndpoint, host: httpAuth.host },
+        }), guard);
+        readyMs = Math.round(process.uptime() * 1000);
+        logger.info(`MCP Server running over HTTP at http://${httpAuth.host}:${httpPort}${httpEndpoint} in ${readyMs}ms.`);
+        logger.info(`Auth: ${httpAuth.noAuth ? 'DISABLED (GOOGLE_MCP_HTTP_NO_AUTH) — do not use on a shared machine' : 'bearer token required'}; bound to ${httpAuth.host}.`);
+        logger.info('Shared mode: point every client at this URL instead of spawning per-session stdio servers.');
+    } else {
+        await server.start({ transportType: 'stdio' });
+        readyMs = Math.round(process.uptime() * 1000);
+        logger.info(`MCP Server running using stdio in ${readyMs}ms. Awaiting client connection...`);
+    }
+    if (readyMs > 5000) {
+        logger.warn(`Startup took ${readyMs}ms. If the MCP client also reports a long connection time, ` +
+            'this process itself is slow — check for antivirus/disk contention. If this number is small ' +
+            'but the client-reported connect time is much larger (e.g. near 30000ms), the delay is happening ' +
+            'before this process starts (commonly npx re-resolving the dependency tree on every launch); ' +
+            'see the README troubleshooting section for a fix.');
+    }
     logger.info('Google auth will run automatically on first tool call.');
+
+    // Best-effort update nudge. This runs AFTER the transport above is
+    // already established, and is deliberately not awaited: a slow or
+    // unreachable registry can never delay or block the MCP handshake this
+    // way. checkForUpdate() is itself time-boxed and caches its result, so
+    // most launches don't even make a network call. See updateCheck.js for
+    // why this exists: pointing MCP clients at a fixed global-install path
+    // (see setup.js) fixed the npx timeout race but also means nothing else
+    // ever re-runs `npm install -g` to pick up new releases.
+    checkForUpdate({ currentVersion: packageVersion, configDir: getConfigDir() })
+        .then((result) => {
+            if (result?.updateAvailable) {
+                logger.warn(
+                    `A newer version of google-tools-mcp is available: ${result.latestVersion} ` +
+                    `(currently running ${packageVersion}). Update with: npm install -g google-tools-mcp@latest`
+                );
+            }
+        })
+        .catch(() => {
+            // checkForUpdate() already swallows its own errors; this catch
+            // only guards against a truly unexpected throw so it can never
+            // surface as an unhandled rejection.
+        });
 } catch (startError) {
     logger.error('FATAL: Server failed to start:', startError.message || startError);
     process.exit(1);

package/dist/logger.js

@@ -1,87 +1,87 @@
-// Centralized logger with LOG_LEVEL support.
-// All log output goes to stderr (stdout reserved for MCP protocol).
-// If GOOGLE_MCP_LOG_FILE is set, logs are also appended to that file.
-import * as fs from 'fs';
-import * as path from 'path';
-import * as os from 'os';
-
-const LOG_LEVELS = {
-    debug: 0,
-    info: 1,
-    warn: 2,
-    error: 3,
-    silent: 4,
-};
-function resolveLevel() {
-    const env = process.env.LOG_LEVEL?.toLowerCase();
-    if (env && env in LOG_LEVELS) {
-        return env;
-    }
-    return 'info';
-}
-let currentLevel = resolveLevel();
-export function refreshLogLevel() {
-    currentLevel = resolveLevel();
-}
-function shouldLog(level) {
-    return LOG_LEVELS[level] >= LOG_LEVELS[currentLevel];
-}
-
-// --- File logging ---
-let logStream = null;
-
-function getDefaultLogPath() {
-    const xdg = process.env.XDG_CONFIG_HOME;
-    const base = xdg || path.join(os.homedir(), '.config');
-    const baseDir = path.join(base, 'google-tools-mcp');
-    const profile = process.env.GOOGLE_MCP_PROFILE;
-    const dir = profile ? path.join(baseDir, profile) : baseDir;
-    return path.join(dir, 'server.log');
-}
-
-function initLogFile() {
-    if (logStream) return;
-    const logPath = process.env.GOOGLE_MCP_LOG_FILE === '1'
-        ? getDefaultLogPath()
-        : process.env.GOOGLE_MCP_LOG_FILE;
-    if (!logPath) return;
-    try {
-        fs.mkdirSync(path.dirname(logPath), { recursive: true });
-        logStream = fs.createWriteStream(logPath, { flags: 'a' });
-    } catch {
-        // If we can't open the log file, continue without file logging
-    }
-}
-initLogFile();
-
-function timestamp() {
-    return new Date().toISOString();
-}
-
-function formatArgs(args) {
-    return args.map(a => {
-        if (a instanceof Error) return a.stack || a.message;
-        if (typeof a === 'object') {
-            try { return JSON.stringify(a); } catch { return String(a); }
-        }
-        return String(a);
-    }).join(' ');
-}
-
-function log(level, args) {
-    if (!shouldLog(level)) return;
-    const tag = level.toUpperCase();
-    const ts = timestamp();
-    const msg = formatArgs(args);
-    console.error(`${ts} [${tag}] ${msg}`);
-    if (logStream) {
-        logStream.write(`${ts} [${tag}] ${msg}\n`);
-    }
-}
-
-export const logger = {
-    debug(...args) { log('debug', args); },
-    info(...args) { log('info', args); },
-    warn(...args) { log('warn', args); },
-    error(...args) { log('error', args); },
-};
+// Centralized logger with LOG_LEVEL support.
+// All log output goes to stderr (stdout reserved for MCP protocol).
+// If GOOGLE_MCP_LOG_FILE is set, logs are also appended to that file.
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4,
+};
+function resolveLevel() {
+    const env = process.env.LOG_LEVEL?.toLowerCase();
+    if (env && env in LOG_LEVELS) {
+        return env;
+    }
+    return 'info';
+}
+let currentLevel = resolveLevel();
+export function refreshLogLevel() {
+    currentLevel = resolveLevel();
+}
+function shouldLog(level) {
+    return LOG_LEVELS[level] >= LOG_LEVELS[currentLevel];
+}
+
+// --- File logging ---
+let logStream = null;
+
+function getDefaultLogPath() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    const base = xdg || path.join(os.homedir(), '.config');
+    const baseDir = path.join(base, 'google-tools-mcp');
+    const profile = process.env.GOOGLE_MCP_PROFILE;
+    const dir = profile ? path.join(baseDir, profile) : baseDir;
+    return path.join(dir, 'server.log');
+}
+
+function initLogFile() {
+    if (logStream) return;
+    const logPath = process.env.GOOGLE_MCP_LOG_FILE === '1'
+        ? getDefaultLogPath()
+        : process.env.GOOGLE_MCP_LOG_FILE;
+    if (!logPath) return;
+    try {
+        fs.mkdirSync(path.dirname(logPath), { recursive: true });
+        logStream = fs.createWriteStream(logPath, { flags: 'a' });
+    } catch {
+        // If we can't open the log file, continue without file logging
+    }
+}
+initLogFile();
+
+function timestamp() {
+    return new Date().toISOString();
+}
+
+function formatArgs(args) {
+    return args.map(a => {
+        if (a instanceof Error) return a.stack || a.message;
+        if (typeof a === 'object') {
+            try { return JSON.stringify(a); } catch { return String(a); }
+        }
+        return String(a);
+    }).join(' ');
+}
+
+function log(level, args) {
+    if (!shouldLog(level)) return;
+    const tag = level.toUpperCase();
+    const ts = timestamp();
+    const msg = formatArgs(args);
+    console.error(`${ts} [${tag}] ${msg}`);
+    if (logStream) {
+        logStream.write(`${ts} [${tag}] ${msg}\n`);
+    }
+}
+
+export const logger = {
+    debug(...args) { log('debug', args); },
+    info(...args) { log('info', args); },
+    warn(...args) { log('warn', args); },
+    error(...args) { log('error', args); },
+};