gcs-google-mcp-server 0.1.9 → 0.1.11

package/build/healthcheck.js

@@ -0,0 +1,47 @@
+import { logInfo } from '../shared/logging.js';
+/**
+ * Thrown when a constrained bucket cannot be reached (does not exist or the
+ * service account lacks object-read access to it).
+ */
+export class BucketNotAccessibleError extends Error {
+    constructor(bucket, cause) {
+        const causeMessage = cause instanceof Error ? cause.message : cause !== undefined ? String(cause) : undefined;
+        super(`Constrained bucket "${bucket}" does not exist or is not accessible` +
+            (causeMessage ? `: ${causeMessage}` : ''));
+        this.name = 'BucketNotAccessibleError';
+    }
+}
+/**
+ * Validate GCS credentials and connectivity.
+ *
+ * - When constrained to a single bucket (`GCS_BUCKET`), probe ONLY that bucket
+ *   with an object-scoped list (`storage.objects.list`). This is the exact
+ *   permission the server actually exercises for the constrained bucket, and a
+ *   least-privilege, bucket-scoped service account is granted it. This path must
+ *   NOT call `listBuckets()` (project-level `storage.buckets.list`) NOR a
+ *   bucket-metadata probe like `headBucket`/`getMetadata` (bucket-level
+ *   `storage.buckets.get`): a correctly scoped read-only SA can be denied BOTH
+ *   of those while still being able to read objects in the bucket.
+ * - Without a constraint, validate by listing buckets, which legitimately
+ *   requires project-level access.
+ *
+ * Throws on failure; callers decide how to surface it.
+ */
+export async function validateGcsCredentials(client, constrainedBucket) {
+    if (constrainedBucket) {
+        try {
+            // A single object-list request validates `storage.objects.list` on the
+            // bucket without requiring any project- or bucket-level metadata
+            // permission. maxResults:1 keeps the probe cheap.
+            await client.listObjects(constrainedBucket, { maxResults: 1 });
+        }
+        catch (error) {
+            throw new BucketNotAccessibleError(constrainedBucket, error);
+        }
+        logInfo('healthcheck', `Constrained bucket "${constrainedBucket}" verified`);
+    }
+    else {
+        await client.listBuckets();
+        logInfo('healthcheck', 'GCS credentials validated successfully');
+    }
+}

package/build/index.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'url';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createMCPServer, GoogleCloudStorageClient } from '../shared/index.js';
 import { logServerStart, logError, logWarning, logInfo } from '../shared/logging.js';
+import { validateGcsCredentials } from './healthcheck.js';
 // Read version from package.json
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageJsonPath = join(__dirname, '..', 'package.json');
@@ -108,18 +109,12 @@ async function performHealthChecks() {
             keyFilePath,
             keyFileContents,
         });
-        // Try to list buckets to validate credentials
-        await client.listBuckets();
-        logInfo('healthcheck', 'GCS credentials validated successfully');
-        // If GCS_BUCKET is set, verify it exists and is accessible
-        if (constrainedBucket) {
-            const bucketExists = await client.headBucket(constrainedBucket);
-            if (!bucketExists) {
-                logError('healthcheck', `Constrained bucket "${constrainedBucket}" does not exist or is not accessible`);
-                process.exit(1);
-            }
-            logInfo('healthcheck', `Constrained bucket "${constrainedBucket}" verified`);
-        }
+        // Validate credentials. When constrained to a single bucket, this probes
+        // only that bucket via an object-scoped list (storage.objects.list) and
+        // never touches project-level (storage.buckets.list) or bucket-metadata
+        // (storage.buckets.get) permissions, so a least-privilege, bucket-scoped
+        // read-only service account can start.
+        await validateGcsCredentials(client, constrainedBucket);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcs-google-mcp-server",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "MCP server for Google Cloud Storage operations with fine-grained tool access control",
   "mcpName": "com.pulsemcp/gcs",
   "main": "build/index.js",