gcs-google-mcp-server 0.1.10 → 0.1.11

package/build/healthcheck.js

@@ -1,11 +1,13 @@
 import { logInfo } from '../shared/logging.js';
 /**
  * Thrown when a constrained bucket cannot be reached (does not exist or the
- * service account lacks access to it).
+ * service account lacks object-read access to it).
  */
 export class BucketNotAccessibleError extends Error {
-    constructor(bucket) {
-        super(`Constrained bucket "${bucket}" does not exist or is not accessible`);
+    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';
     }
 }
@@ -13,10 +15,13 @@ export class BucketNotAccessibleError extends Error {
  * Validate GCS credentials and connectivity.
  *
  * - When constrained to a single bucket (`GCS_BUCKET`), probe ONLY that bucket
- *   via `headBucket`, which needs only bucket-level permissions
- *   (`storage.buckets.get`). This path must NOT call `listBuckets()`, because
- *   that requires the project-level `storage.buckets.list` permission, which a
- *   least-privilege, bucket-scoped service account intentionally does not have.
+ *   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.
  *
@@ -24,9 +29,14 @@ export class BucketNotAccessibleError extends Error {
  */
 export async function validateGcsCredentials(client, constrainedBucket) {
     if (constrainedBucket) {
-        const bucketExists = await client.headBucket(constrainedBucket);
-        if (!bucketExists) {
-            throw new BucketNotAccessibleError(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`);
     }

package/build/index.js

@@ -110,8 +110,10 @@ async function performHealthChecks() {
             keyFileContents,
         });
         // Validate credentials. When constrained to a single bucket, this probes
-        // only that bucket and never calls listBuckets(), so a least-privilege,
-        // bucket-scoped service account (without storage.buckets.list) can start.
+        // 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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcs-google-mcp-server",
-  "version": "0.1.10",
+  "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",