gcs-google-mcp-server 0.1.11 → 0.1.13

package/README.md

@@ -20,19 +20,21 @@ MCP server for Google Cloud Storage operations with fine-grained tool access con
 
 ### Tools
 
-| Tool              | Group     | Description                                                      |
-| ----------------- | --------- | ---------------------------------------------------------------- |
-| `list_buckets`    | readonly  | List all GCS buckets in the Google Cloud project                 |
-| `list_objects`    | readonly  | List objects in a bucket with prefix and pagination              |
-| `get_object`      | readonly  | Get object contents as text                                      |
-| `download_object` | readonly  | Download a single object to a local file (binary-safe)           |
-| `download_prefix` | readonly  | Recursively download a prefix to a local directory (binary-safe) |
-| `head_bucket`     | readonly  | Check if a bucket exists and is accessible                       |
-| `put_object`      | readwrite | Upload or update an object                                       |
-| `copy_object`     | readwrite | Copy an object within or across buckets                          |
-| `create_bucket`   | readwrite | Create a new GCS bucket                                          |
-| `delete_object`   | delete    | Delete an object from a bucket                                   |
-| `delete_bucket`   | delete    | Delete an empty GCS bucket                                       |
+| Tool                   | Group     | Description                                                                     |
+| ---------------------- | --------- | ------------------------------------------------------------------------------- |
+| `list_buckets`         | readonly  | List all GCS buckets in the Google Cloud project                                |
+| `list_objects`         | readonly  | List objects in a bucket with prefix and pagination                             |
+| `get_object`           | readonly  | Get object contents as text                                                     |
+| `download_object`      | readonly  | Download a single object to a local file (binary-safe)                          |
+| `download_prefix`      | readonly  | Recursively download a prefix to a local directory (binary-safe)                |
+| `head_bucket`          | readonly  | Check if a bucket exists and is accessible                                      |
+| `put_object`           | readwrite | Upload or update an object from inline string content                           |
+| `put_object_from_path` | readwrite | Upload a single local file by streaming from disk (binary-safe, context-free)   |
+| `upload_prefix`        | readwrite | Recursively upload a local directory tree from disk (binary-safe, context-free) |
+| `copy_object`          | readwrite | Copy an object within or across buckets                                         |
+| `create_bucket`        | readwrite | Create a new GCS bucket                                                         |
+| `delete_object`        | delete    | Delete an object from a bucket                                                  |
+| `delete_bucket`        | delete    | Delete an empty GCS bucket                                                      |
 
 ### Downloading to Local Disk
 
@@ -56,6 +58,30 @@ MCP server for Google Cloud Storage operations with fine-grained tool access con
 
   The inline `files` list is capped (`maxInlineEntries`, default 100), but `objectCount` and `totalBytes` always reflect the full download. When `destinationDir` is omitted it defaults to a unique folder under the OS temp directory.
 
+### Uploading from Local Disk
+
+`put_object` takes the object content inline as a string argument, which routes every byte through the model context and requires base64 for binary data — impractical for large files or bulk uploads. For uploading files or folders **without consuming context**, use the local-path upload tools instead. Both stream **raw bytes** directly from disk to GCS server-side, returning only metadata. They belong to the `readwrite` toolgroup, so read-only deployments never gain them.
+
+- **`put_object_from_path`** — upload a single local file by streaming it from a filesystem path. Content type is auto-detected from the file extension (override with `contentType`). Binary files (images, archives) work without base64. Returns `{ bucket, key, sourcePath, size, etag, generation }`.
+- **`upload_prefix`** — recursively upload every file under a local directory, preserving the directory structure as key paths beneath a destination prefix. Symbolic links to files are followed and uploaded (links to directories are skipped to avoid cycles), per-file failures are collected without aborting the batch, and it returns a manifest:
+
+  ```json
+  {
+    "bucket": "my-bucket",
+    "sourceDir": "/tmp/exports",
+    "destPrefix": "uploads/",
+    "objectCount": 1234,
+    "totalBytes": 5678901,
+    "files": [
+      { "localPath": "/tmp/exports/01/data.json", "key": "uploads/01/data.json", "size": 1234 }
+    ],
+    "filesTruncated": true,
+    "errors": []
+  }
+  ```
+
+  The inline `files` list is capped (`maxInlineEntries`, default 100), but `objectCount` and `totalBytes` always reflect the full upload. When `destPrefix` is omitted, files upload to the bucket root.
+
 ### Resources
 
 | Resource       | Description                                     |
@@ -101,7 +127,38 @@ When set:
 - The `bucket` parameter is automatically injected and hidden from tool inputs
 - For `copy_object`, both source and destination are constrained to the specified bucket
 
-This is useful for restricting access to a single bucket without giving broader GCS permissions.
+This lets you grant a least-privilege service account that has only **object-level** access to one bucket, without project-level bucket-listing permission. The startup healthcheck honors this: when `GCS_BUCKET` is set it validates credentials with an object-scoped probe (`storage.objects.list` on that bucket) and never calls the project-level bucket list or a bucket-metadata probe. See [Required IAM permissions](#required-iam-permissions) for the exact permissions per mode.
+
+## Required IAM permissions
+
+The minimal IAM permissions depend on whether the server is constrained to a single bucket (`GCS_BUCKET`) and which tool groups you enable. The startup healthcheck validates credentials within these bounds — it does **not** require any permission beyond what the table below lists for your mode.
+
+### Startup healthcheck
+
+| Mode                                 | Permission the healthcheck needs                 | Notes                                                                                                                                                                                                                  |
+| ------------------------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Single bucket** (`GCS_BUCKET` set) | `storage.objects.list` on the constrained bucket | Probes `list_objects` with `maxResults: 1`. Does **not** require project-level `storage.buckets.list` or bucket-metadata `storage.buckets.get`, so a correctly least-privilege, object-only service account can start. |
+| **Unconstrained** (no `GCS_BUCKET`)  | project-level `storage.buckets.list`             | Validates by listing buckets in the project.                                                                                                                                                                           |
+
+Set `SKIP_HEALTH_CHECKS=true` to bypass startup validation entirely (disables **all** credential checks — not recommended).
+
+### Per-tool permissions
+
+Beyond the healthcheck, each tool needs the corresponding GCS permission at runtime. Grant only what the tool groups you enable require:
+
+| Tool / group                                                                     | Permission                                                                                                                                                                                       |
+| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `list_objects` (readonly)                                                        | `storage.objects.list`                                                                                                                                                                           |
+| `get_object`, `download_object` (readonly)                                       | `storage.objects.get`                                                                                                                                                                            |
+| `download_prefix` (readonly)                                                     | `storage.objects.list`, `storage.objects.get`                                                                                                                                                    |
+| `list_buckets` (readonly)                                                        | `storage.buckets.list`                                                                                                                                                                           |
+| `head_bucket` (readonly)                                                         | `storage.buckets.get`                                                                                                                                                                            |
+| `put_object`, `put_object_from_path`, `upload_prefix`, `copy_object` (readwrite) | `storage.objects.create`, `storage.objects.get` (these tools read each object's metadata back after writing to return its `etag`/`generation`; `copy_object` additionally reads the copy source) |
+| `create_bucket` (readwrite)                                                      | `storage.buckets.create`                                                                                                                                                                         |
+| `delete_object` (delete)                                                         | `storage.objects.delete`                                                                                                                                                                         |
+| `delete_bucket` (delete)                                                         | `storage.buckets.delete`                                                                                                                                                                         |
+
+For a read-only, single-bucket service account, the `roles/storage.objectViewer` role on the bucket (or a custom role with `storage.objects.list` + `storage.objects.get`) is sufficient — no project-level or bucket-metadata permissions are needed.
 
 ## Quick Start
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcs-google-mcp-server",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "MCP server for Google Cloud Storage operations with fine-grained tool access control",
   "mcpName": "com.pulsemcp/gcs",
   "main": "build/index.js",
@@ -37,7 +37,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.10.6",
-    "tsx": "^4.19.4",
+    "tsx": "^4.22.4",
     "typescript": "^5.7.3"
   },
   "keywords": [

package/shared/gcs-client/gcs-client.d.ts

@@ -59,6 +59,7 @@ export interface IGCSClient {
     getObject(bucket: string, key: string): Promise<GetObjectResult>;
     getObjectBytes(bucket: string, key: string): Promise<GetObjectBytesResult>;
     putObject(bucket: string, key: string, content: string, options?: PutObjectOptions): Promise<PutObjectResult>;
+    uploadFile(bucket: string, sourcePath: string, key: string, options?: PutObjectOptions): Promise<PutObjectResult>;
     deleteObject(bucket: string, key: string): Promise<void>;
     createBucket(bucket: string, location?: string): Promise<void>;
     deleteBucket(bucket: string): Promise<void>;
@@ -73,6 +74,7 @@ export declare class GoogleCloudStorageClient implements IGCSClient {
     getObject(bucket: string, key: string): Promise<GetObjectResult>;
     getObjectBytes(bucket: string, key: string): Promise<GetObjectBytesResult>;
     putObject(bucket: string, key: string, content: string, options?: PutObjectOptions): Promise<PutObjectResult>;
+    uploadFile(bucket: string, sourcePath: string, key: string, options?: PutObjectOptions): Promise<PutObjectResult>;
     deleteObject(bucket: string, key: string): Promise<void>;
     createBucket(bucket: string, location?: string): Promise<void>;
     deleteBucket(bucket: string): Promise<void>;

package/shared/gcs-client/gcs-client.integration-mock.d.ts

@@ -5,7 +5,7 @@ export interface MockGCSData {
         creationDate?: Date;
     }>;
     objects?: Record<string, Record<string, {
-        content: string;
+        content: string | Buffer;
         contentType?: string;
         metadata?: Record<string, string>;
         lastModified?: Date;

package/shared/gcs-client/gcs-client.integration-mock.js

@@ -1,3 +1,4 @@
+import { readFile } from 'fs/promises';
 export function createIntegrationMockGCSClient(mockData = {}) {
     // Default mock data
     const buckets = mockData.buckets || [
@@ -40,7 +41,7 @@ export function createIntegrationMockGCSClient(mockData = {}) {
             return {
                 objects: keys.map((key) => ({
                     key,
-                    size: bucketObjects[key]?.content?.length || 0,
+                    size: bucketObjects[key]?.content ? Buffer.byteLength(bucketObjects[key].content) : 0,
                     lastModified: bucketObjects[key]?.lastModified || new Date(),
                     storageClass: 'STANDARD',
                     etag: '"mock-etag"',
@@ -56,10 +57,11 @@ export function createIntegrationMockGCSClient(mockData = {}) {
                 throw new Error(`Object not found: ${bucket}/${key}`);
             }
             const obj = bucketObjects[key];
+            const contentStr = Buffer.isBuffer(obj.content) ? obj.content.toString('utf-8') : obj.content;
             return {
-                content: obj.content,
+                content: contentStr,
                 contentType: obj.contentType || 'text/plain',
-                contentLength: obj.content.length,
+                contentLength: Buffer.byteLength(obj.content),
                 lastModified: obj.lastModified || new Date(),
                 etag: '"mock-etag"',
                 metadata: obj.metadata || {},
@@ -70,7 +72,8 @@ export function createIntegrationMockGCSClient(mockData = {}) {
             if (!bucketObjects || !bucketObjects[key]) {
                 throw new Error(`Object not found: ${bucket}/${key}`);
             }
-            const content = Buffer.from(bucketObjects[key].content);
+            const stored = bucketObjects[key].content;
+            const content = Buffer.isBuffer(stored) ? stored : Buffer.from(stored);
             return {
                 content,
                 contentType: bucketObjects[key].contentType || 'text/plain',
@@ -95,6 +98,28 @@ export function createIntegrationMockGCSClient(mockData = {}) {
                 generation: undefined,
             };
         },
+        async uploadFile(bucket, sourcePath, key, uploadOptions = {}) {
+            if (!objects) {
+                throw new Error('Mock data not initialized');
+            }
+            if (!objects[bucket]) {
+                objects[bucket] = {};
+            }
+            // Read the raw bytes from disk so the upload path is exercised end-to-end
+            // and binary content is preserved faithfully (mirrors the real client,
+            // which streams bytes directly from disk without any text decoding).
+            const content = await readFile(sourcePath);
+            objects[bucket][key] = {
+                content,
+                contentType: uploadOptions.contentType,
+                metadata: uploadOptions.metadata,
+                lastModified: new Date(),
+            };
+            return {
+                etag: '"mock-etag"',
+                generation: undefined,
+            };
+        },
         async deleteObject(bucket, key) {
             if (objects?.[bucket]) {
                 delete objects[bucket][key];

package/shared/gcs-client/gcs-client.js

@@ -86,6 +86,29 @@ export class GoogleCloudStorageClient {
             generation: metadata.generation ? String(metadata.generation) : undefined,
         };
     }
+    async uploadFile(bucket, sourcePath, key, options = {}) {
+        // bucket.upload streams the file directly from local disk to GCS — the bytes
+        // never pass through the caller, so this is binary-safe and avoids loading
+        // the file into the MCP tool-call payload.
+        const uploadOptions = { destination: key };
+        const fileMetadata = {};
+        if (options.contentType) {
+            fileMetadata.contentType = options.contentType;
+        }
+        if (options.metadata) {
+            fileMetadata.metadata = options.metadata;
+        }
+        if (Object.keys(fileMetadata).length > 0) {
+            uploadOptions.metadata = fileMetadata;
+        }
+        // When contentType is omitted, the SDK auto-detects it from the file extension.
+        const [file] = await this.storage.bucket(bucket).upload(sourcePath, uploadOptions);
+        const [metadata] = await file.getMetadata();
+        return {
+            etag: metadata.etag,
+            generation: metadata.generation ? String(metadata.generation) : undefined,
+        };
+    }
     async deleteObject(bucket, key) {
         await this.storage.bucket(bucket).file(key).delete();
     }

package/shared/tools/put-object-from-path.d.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { GCSClientFactory } from '../server.js';
+export declare const PutObjectFromPathSchema: z.ZodObject<{
+    bucket: z.ZodString;
+    key: z.ZodString;
+    sourcePath: z.ZodString;
+    contentType: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    bucket: string;
+    key: string;
+    sourcePath: string;
+    metadata?: Record<string, string> | undefined;
+    contentType?: string | undefined;
+}, {
+    bucket: string;
+    key: string;
+    sourcePath: string;
+    metadata?: Record<string, string> | undefined;
+    contentType?: string | undefined;
+}>;
+export declare function putObjectFromPathTool(_server: Server, clientFactory: GCSClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            bucket: {
+                type: string;
+                description: "The name of the GCS bucket (e.g., \"my-app-data\")";
+            };
+            key: {
+                type: string;
+                description: "The destination object key (path) within the bucket (e.g., \"exports/archive.tar.gz\")";
+            };
+            sourcePath: {
+                type: string;
+                description: "Local file path to upload. The file is streamed directly from disk to GCS — its bytes never pass through this tool call, so it is binary-safe and avoids loading large files into the model context.";
+            };
+            contentType: {
+                type: string;
+                description: "MIME type of the object (e.g., \"image/png\"). If omitted, it is auto-detected from the file extension.";
+            };
+            metadata: {
+                type: string;
+                additionalProperties: {
+                    type: string;
+                };
+                description: "Custom metadata as key-value pairs (e.g., {\"author\": \"system\", \"version\": \"1.0\"})";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=put-object-from-path.d.ts.map

package/shared/tools/put-object-from-path.js

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+import { stat } from 'fs/promises';
+import path from 'path';
+const PARAM_DESCRIPTIONS = {
+    bucket: 'The name of the GCS bucket (e.g., "my-app-data")',
+    key: 'The destination object key (path) within the bucket (e.g., "exports/archive.tar.gz")',
+    sourcePath: 'Local file path to upload. The file is streamed directly from disk to GCS — its bytes never pass through this tool call, so it is binary-safe and avoids loading large files into the model context.',
+    contentType: 'MIME type of the object (e.g., "image/png"). If omitted, it is auto-detected from the file extension.',
+    metadata: 'Custom metadata as key-value pairs (e.g., {"author": "system", "version": "1.0"})',
+};
+export const PutObjectFromPathSchema = z.object({
+    bucket: z.string().min(1).describe(PARAM_DESCRIPTIONS.bucket),
+    key: z.string().min(1).describe(PARAM_DESCRIPTIONS.key),
+    sourcePath: z.string().min(1).describe(PARAM_DESCRIPTIONS.sourcePath),
+    contentType: z.string().optional().describe(PARAM_DESCRIPTIONS.contentType),
+    metadata: z.record(z.string()).optional().describe(PARAM_DESCRIPTIONS.metadata),
+});
+export function putObjectFromPathTool(_server, clientFactory) {
+    return {
+        name: 'put_object_from_path',
+        description: `Upload a single local file to GCS by streaming it directly from disk (binary-safe).
+
+Unlike put_object (which takes the object content inline as a string argument — routing every byte through the model context and requiring base64 for binary data), this tool reads from a local filesystem path and streams the bytes to GCS server-side. It is the right tool for uploading images, archives, or any large/binary file without blowing through context.
+
+Example response:
+{
+  "bucket": "my-bucket",
+  "key": "exports/archive.tar.gz",
+  "sourcePath": "/tmp/archive.tar.gz",
+  "size": 1048576,
+  "etag": "\\"abc123def456\\"",
+  "generation": "1234567890"
+}
+
+Notes:
+- The content type is auto-detected from the file extension unless contentType is supplied.
+- To upload an entire directory tree, use upload_prefix instead.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                bucket: { type: 'string', description: PARAM_DESCRIPTIONS.bucket },
+                key: { type: 'string', description: PARAM_DESCRIPTIONS.key },
+                sourcePath: { type: 'string', description: PARAM_DESCRIPTIONS.sourcePath },
+                contentType: { type: 'string', description: PARAM_DESCRIPTIONS.contentType },
+                metadata: {
+                    type: 'object',
+                    additionalProperties: { type: 'string' },
+                    description: PARAM_DESCRIPTIONS.metadata,
+                },
+            },
+            required: ['bucket', 'key', 'sourcePath'],
+        },
+        handler: async (args) => {
+            try {
+                const validated = PutObjectFromPathSchema.parse(args);
+                const client = clientFactory();
+                const resolvedSource = path.resolve(validated.sourcePath);
+                const stats = await stat(resolvedSource);
+                if (!stats.isFile()) {
+                    throw new Error(`Source path "${validated.sourcePath}" is not a regular file. Use upload_prefix to upload a directory.`);
+                }
+                const result = await client.uploadFile(validated.bucket, resolvedSource, validated.key, {
+                    contentType: validated.contentType,
+                    metadata: validated.metadata,
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: `Uploaded ${resolvedSource} to gs://${validated.bucket}/${validated.key}`,
+                                bucket: validated.bucket,
+                                key: validated.key,
+                                sourcePath: resolvedSource,
+                                size: stats.size,
+                                ...result,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [{ type: 'text', text: `Error uploading object from path: ${message}` }],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/upload-prefix.d.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { GCSClientFactory } from '../server.js';
+export declare const UploadPrefixSchema: z.ZodObject<{
+    bucket: z.ZodString;
+    sourceDir: z.ZodString;
+    destPrefix: z.ZodOptional<z.ZodString>;
+    maxInlineEntries: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    bucket: string;
+    sourceDir: string;
+    maxInlineEntries?: number | undefined;
+    destPrefix?: string | undefined;
+}, {
+    bucket: string;
+    sourceDir: string;
+    maxInlineEntries?: number | undefined;
+    destPrefix?: string | undefined;
+}>;
+/**
+ * Build the GCS object key for a file at `relPath` (relative to the upload root),
+ * placed beneath `destPrefix`. The OS path separator is normalized to "/" so
+ * keys are well-formed regardless of platform.
+ *
+ * Example: destPrefix="uploads/", relPath="01/data.json" -> "uploads/01/data.json"
+ */
+export declare function keyForLocalFile(relPath: string, destPrefix: string): string;
+export declare function uploadPrefixTool(_server: Server, clientFactory: GCSClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            bucket: {
+                type: string;
+                description: "The name of the GCS bucket (e.g., \"my-app-data\")";
+            };
+            sourceDir: {
+                type: string;
+                description: "Local directory to upload recursively. Every file under it is streamed directly from disk to GCS — the bytes never pass through this tool call, so it is binary-safe and avoids loading files into the model context.";
+            };
+            destPrefix: {
+                type: string;
+                description: "The destination key prefix in the bucket (e.g., \"uploads/2024/\"). The directory tree under sourceDir is preserved beneath this prefix. Use an empty string to upload to the bucket root.";
+            };
+            maxInlineEntries: {
+                type: string;
+                minimum: number;
+                description: "Maximum number of file entries to include inline in the response manifest (default: 100). Counts and totals always reflect the full set regardless of this cap.";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=upload-prefix.d.ts.map

package/shared/tools/upload-prefix.js

@@ -0,0 +1,172 @@
+import { z } from 'zod';
+import { readdir, stat } from 'fs/promises';
+import path from 'path';
+const PARAM_DESCRIPTIONS = {
+    bucket: 'The name of the GCS bucket (e.g., "my-app-data")',
+    sourceDir: 'Local directory to upload recursively. Every file under it is streamed directly from disk to GCS — the bytes never pass through this tool call, so it is binary-safe and avoids loading files into the model context.',
+    destPrefix: 'The destination key prefix in the bucket (e.g., "uploads/2024/"). The directory tree under sourceDir is preserved beneath this prefix. Use an empty string to upload to the bucket root.',
+    maxInlineEntries: 'Maximum number of file entries to include inline in the response manifest (default: 100). Counts and totals always reflect the full set regardless of this cap.',
+};
+// Cap how many object paths are echoed back inline so that uploading thousands
+// of files does not produce an enormous tool response.
+const DEFAULT_MAX_INLINE_ENTRIES = 100;
+export const UploadPrefixSchema = z.object({
+    bucket: z.string().min(1).describe(PARAM_DESCRIPTIONS.bucket),
+    sourceDir: z.string().min(1).describe(PARAM_DESCRIPTIONS.sourceDir),
+    destPrefix: z.string().optional().describe(PARAM_DESCRIPTIONS.destPrefix),
+    maxInlineEntries: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe(PARAM_DESCRIPTIONS.maxInlineEntries),
+});
+/**
+ * Build the GCS object key for a file at `relPath` (relative to the upload root),
+ * placed beneath `destPrefix`. The OS path separator is normalized to "/" so
+ * keys are well-formed regardless of platform.
+ *
+ * Example: destPrefix="uploads/", relPath="01/data.json" -> "uploads/01/data.json"
+ */
+export function keyForLocalFile(relPath, destPrefix) {
+    const normalizedRel = relPath.split(path.sep).join('/').replace(/^\/+/, '');
+    if (!destPrefix) {
+        return normalizedRel;
+    }
+    const cleanPrefix = destPrefix.replace(/\/+$/, '');
+    return `${cleanPrefix}/${normalizedRel}`;
+}
+/**
+ * Recursively collect absolute paths of every regular file under `dir`.
+ *
+ * Symbolic links that resolve to regular files are followed and uploaded, so a
+ * tree of symlinked files is not silently dropped. Symbolic links that resolve
+ * to directories are skipped — following them risks walking out of the tree or
+ * into cycles. Broken/unresolvable symlinks are skipped here; if one happens to
+ * be a real file path the per-file upload loop will surface the failure in the
+ * manifest's `errors`.
+ */
+async function collectFiles(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await collectFiles(fullPath)));
+        }
+        else if (entry.isFile()) {
+            files.push(fullPath);
+        }
+        else if (entry.isSymbolicLink()) {
+            // stat() follows the link to its target; lstat (via withFileTypes) does not.
+            try {
+                const target = await stat(fullPath);
+                if (target.isFile()) {
+                    files.push(fullPath);
+                }
+            }
+            catch {
+                // Broken symlink — skip silently.
+            }
+        }
+    }
+    return files;
+}
+export function uploadPrefixTool(_server, clientFactory) {
+    return {
+        name: 'upload_prefix',
+        description: `Recursively upload every file under a local directory to GCS, preserving the directory structure as key paths beneath a destination prefix.
+
+Unlike put_object (which takes content inline as a string and routes every byte through the model context), this tool streams each file directly from disk to GCS server-side. It is the right tool for bulk-uploading many files or folders — including binary files like images — without blowing through context.
+
+Returns a manifest:
+{
+  "bucket": "my-bucket",
+  "sourceDir": "/tmp/exports",
+  "destPrefix": "uploads/",
+  "objectCount": 1234,
+  "totalBytes": 5678901,
+  "files": [
+    { "localPath": "/tmp/exports/01/data.json", "key": "uploads/01/data.json", "size": 1234 }
+  ],
+  "filesTruncated": true,
+  "errors": []
+}
+
+Notes:
+- Content types are auto-detected from each file's extension.
+- Symbolic links to files are followed and uploaded; symbolic links to directories are skipped (to avoid following links out of the tree or into cycles).
+- Per-file upload failures are collected in "errors" without aborting the whole batch.
+- The "files" list is capped (see maxInlineEntries); "objectCount" and "totalBytes" always reflect the full upload.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                bucket: { type: 'string', description: PARAM_DESCRIPTIONS.bucket },
+                sourceDir: { type: 'string', description: PARAM_DESCRIPTIONS.sourceDir },
+                destPrefix: { type: 'string', description: PARAM_DESCRIPTIONS.destPrefix },
+                maxInlineEntries: {
+                    type: 'number',
+                    minimum: 0,
+                    description: PARAM_DESCRIPTIONS.maxInlineEntries,
+                },
+            },
+            required: ['bucket', 'sourceDir'],
+        },
+        handler: async (args) => {
+            try {
+                const validated = UploadPrefixSchema.parse(args);
+                const client = clientFactory();
+                const maxInlineEntries = validated.maxInlineEntries ?? DEFAULT_MAX_INLINE_ENTRIES;
+                const destPrefix = validated.destPrefix ?? '';
+                const resolvedRoot = path.resolve(validated.sourceDir);
+                const rootStats = await stat(resolvedRoot);
+                if (!rootStats.isDirectory()) {
+                    throw new Error(`Source path "${validated.sourceDir}" is not a directory. Use put_object_from_path to upload a single file.`);
+                }
+                const localFiles = await collectFiles(resolvedRoot);
+                const files = [];
+                const errors = [];
+                let totalBytes = 0;
+                for (const localPath of localFiles) {
+                    const rel = path.relative(resolvedRoot, localPath);
+                    const key = keyForLocalFile(rel, destPrefix);
+                    try {
+                        const fileStats = await stat(localPath);
+                        await client.uploadFile(validated.bucket, localPath, key);
+                        totalBytes += fileStats.size;
+                        files.push({ localPath, key, size: fileStats.size });
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        errors.push({ localPath, error: message });
+                    }
+                }
+                const manifest = {
+                    bucket: validated.bucket,
+                    sourceDir: resolvedRoot,
+                    destPrefix,
+                    objectCount: files.length,
+                    totalBytes,
+                    files: files.slice(0, maxInlineEntries),
+                    filesTruncated: files.length > maxInlineEntries,
+                    errors,
+                };
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(manifest, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [{ type: 'text', text: `Error uploading prefix: ${message}` }],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools.js

@@ -5,6 +5,8 @@ import { getObjectTool } from './tools/get-object.js';
 import { downloadPrefixTool } from './tools/download-prefix.js';
 import { downloadObjectTool } from './tools/download-object.js';
 import { putObjectTool } from './tools/put-object.js';
+import { putObjectFromPathTool } from './tools/put-object-from-path.js';
+import { uploadPrefixTool } from './tools/upload-prefix.js';
 import { deleteObjectTool } from './tools/delete-object.js';
 import { createBucketTool } from './tools/create-bucket.js';
 import { deleteBucketTool } from './tools/delete-bucket.js';
@@ -52,6 +54,8 @@ const ALL_TOOLS = [
     { factory: headBucketTool, groups: ['readonly'], bucketLevelOnly: true },
     // Write operations (non-destructive)
     { factory: putObjectTool, groups: ['readwrite'], bucketParams: ['bucket'] },
+    { factory: putObjectFromPathTool, groups: ['readwrite'], bucketParams: ['bucket'] },
+    { factory: uploadPrefixTool, groups: ['readwrite'], bucketParams: ['bucket'] },
     { factory: copyObjectTool, groups: ['readwrite'], bucketParams: ['sourceBucket', 'destBucket'] },
     { factory: createBucketTool, groups: ['readwrite'], bucketLevelOnly: true },
     // Delete operations