gcs-google-mcp-server 0.1.7 → 0.1.9

package/README.md

@@ -20,17 +20,41 @@ 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                         |
-| `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                                       |
+| `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
+
+`get_object` returns an object's contents inline as UTF-8 text, which is lossy for binary data and impractical for large files or many files at once. For local data-wrangling, use the download tools instead — both stream **raw bytes** to disk and belong to the `readonly` toolgroup:
+
+- **`download_object`** — download a single object to a local file path. Defaults to a unique file under the OS temp directory.
+- **`download_prefix`** — recursively download every object under a prefix to a local directory, preserving the key path structure as subdirectories. Paginates through the full listing, skips directory-placeholder objects (keys ending in `/`), collects per-object errors without aborting the batch, and returns a manifest:
+
+  ```json
+  {
+    "destinationDir": "/tmp/gcs-download-my-bucket-1700000000000",
+    "objectCount": 1234,
+    "totalBytes": 5678901,
+    "files": [
+      { "key": "logs/2024/01/data.json", "localPath": "/tmp/.../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 download. When `destinationDir` is omitted it defaults to a unique folder under the OS temp directory.
 
 ### Resources
 

package/package.json

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

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

@@ -35,6 +35,12 @@ export interface GetObjectResult {
     etag?: string;
     metadata?: Record<string, string>;
 }
+export interface GetObjectBytesResult {
+    /** Raw object bytes. Unlike getObject, this is NOT decoded to UTF-8, so it is binary-safe. */
+    content: Buffer;
+    contentType?: string;
+    contentLength?: number;
+}
 export interface PutObjectOptions {
     contentType?: string;
     metadata?: Record<string, string>;
@@ -51,6 +57,7 @@ export interface IGCSClient {
     listBuckets(): Promise<ListBucketsResult>;
     listObjects(bucket: string, options?: ListObjectsOptions): Promise<ListObjectsResult>;
     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>;
     deleteObject(bucket: string, key: string): Promise<void>;
     createBucket(bucket: string, location?: string): Promise<void>;
@@ -64,6 +71,7 @@ export declare class GoogleCloudStorageClient implements IGCSClient {
     listBuckets(): Promise<ListBucketsResult>;
     listObjects(bucket: string, options?: ListObjectsOptions): Promise<ListObjectsResult>;
     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>;
     deleteObject(bucket: string, key: string): Promise<void>;
     createBucket(bucket: string, location?: string): Promise<void>;

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

@@ -65,6 +65,18 @@ export function createIntegrationMockGCSClient(mockData = {}) {
                 metadata: obj.metadata || {},
             };
         },
+        async getObjectBytes(bucket, key) {
+            const bucketObjects = objects?.[bucket];
+            if (!bucketObjects || !bucketObjects[key]) {
+                throw new Error(`Object not found: ${bucket}/${key}`);
+            }
+            const content = Buffer.from(bucketObjects[key].content);
+            return {
+                content,
+                contentType: bucketObjects[key].contentType || 'text/plain',
+                contentLength: content.length,
+            };
+        },
         async putObject(bucket, key, content, putOptions = {}) {
             if (!objects) {
                 throw new Error('Mock data not initialized');

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

@@ -66,6 +66,14 @@ export class GoogleCloudStorageClient {
             metadata: metadata.metadata || {},
         };
     }
+    async getObjectBytes(bucket, key) {
+        const file = this.storage.bucket(bucket).file(key);
+        const [content] = await file.download();
+        return {
+            content,
+            contentLength: content.length,
+        };
+    }
     async putObject(bucket, key, content, options = {}) {
         const file = this.storage.bucket(bucket).file(key);
         await file.save(content, {

package/shared/index.d.ts

@@ -1,7 +1,7 @@
 export { registerResources } from './resources.js';
 export { createRegisterTools, type ToolGroup, parseEnabledToolGroups, parseToolFilters, getAllToolNames, } from './tools.js';
 export { createMCPServer, type CreateMCPServerOptions, type GCSClientFactory, type IGCSClient, type GCSClientConfig, GoogleCloudStorageClient, } from './server.js';
-export { type ListBucketsResult, type ListObjectsOptions, type ListObjectsResult, type GetObjectResult, type PutObjectOptions, type PutObjectResult, type CopyObjectResult, } from './gcs-client/gcs-client.js';
+export { type ListBucketsResult, type ListObjectsOptions, type ListObjectsResult, type GetObjectResult, type GetObjectBytesResult, type PutObjectOptions, type PutObjectResult, type CopyObjectResult, } from './gcs-client/gcs-client.js';
 export { createIntegrationMockGCSClient, type MockGCSData, } from './gcs-client/gcs-client.integration-mock.js';
 export { getSelectedResourceId, hasSelectedResource, isResourceLocked, getServerState, setSelectedResourceId, clearSelectedResource, initializeStateFromEnvironment, resetState, } from './state.js';
 export { logServerStart, logError, logWarning, logInfo, logDebug } from './logging.js';

package/shared/tools/download-object.d.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { GCSClientFactory } from '../server.js';
+export declare const DownloadObjectSchema: z.ZodObject<{
+    bucket: z.ZodString;
+    key: z.ZodString;
+    destinationPath: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    bucket: string;
+    key: string;
+    destinationPath?: string | undefined;
+}, {
+    bucket: string;
+    key: string;
+    destinationPath?: string | undefined;
+}>;
+export declare function downloadObjectTool(_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 object key (path) within the bucket (e.g., \"exports/archive.tar.gz\")";
+            };
+            destinationPath: {
+                type: string;
+                description: "Absolute or relative local file path to write the object to. Defaults to a unique file under the OS temp directory, preserving the key path (e.g., \"/tmp/gcs-download-<bucket>-<timestamp>/<key>\").";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=download-object.d.ts.map

package/shared/tools/download-object.js

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+import { mkdir, writeFile } from 'fs/promises';
+import os from 'os';
+import path from 'path';
+const PARAM_DESCRIPTIONS = {
+    bucket: 'The name of the GCS bucket (e.g., "my-app-data")',
+    key: 'The object key (path) within the bucket (e.g., "exports/archive.tar.gz")',
+    destinationPath: 'Absolute or relative local file path to write the object to. Defaults to a unique file under the OS temp directory, preserving the key path (e.g., "/tmp/gcs-download-<bucket>-<timestamp>/<key>").',
+};
+export const DownloadObjectSchema = z.object({
+    bucket: z.string().min(1).describe(PARAM_DESCRIPTIONS.bucket),
+    key: z.string().min(1).describe(PARAM_DESCRIPTIONS.key),
+    destinationPath: z.string().min(1).optional().describe(PARAM_DESCRIPTIONS.destinationPath),
+});
+export function downloadObjectTool(_server, clientFactory) {
+    return {
+        name: 'download_object',
+        description: `Download a single object to a local file path, writing raw bytes (binary-safe).
+
+Unlike get_object (which returns content inline as UTF-8 text and is lossy for binary or large files), this tool streams the object to disk and returns the local path.
+
+Example response:
+{
+  "bucket": "my-bucket",
+  "key": "exports/archive.tar.gz",
+  "localPath": "/tmp/gcs-download-my-bucket-1700000000000/exports/archive.tar.gz",
+  "size": 1048576
+}`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                bucket: { type: 'string', description: PARAM_DESCRIPTIONS.bucket },
+                key: { type: 'string', description: PARAM_DESCRIPTIONS.key },
+                destinationPath: { type: 'string', description: PARAM_DESCRIPTIONS.destinationPath },
+            },
+            required: ['bucket', 'key'],
+        },
+        handler: async (args) => {
+            try {
+                const validated = DownloadObjectSchema.parse(args);
+                const client = clientFactory();
+                let localPath;
+                if (validated.destinationPath) {
+                    // The caller chose an explicit path; writing there is their intent.
+                    localPath = path.resolve(validated.destinationPath);
+                }
+                else {
+                    // The destination is derived from the (untrusted) object key, so confine
+                    // the resolved path to the temp root to prevent path-traversal escapes.
+                    const root = path.resolve(os.tmpdir(), `gcs-download-${validated.bucket}-${Date.now()}`);
+                    localPath = path.resolve(root, validated.key);
+                    if (localPath !== root && !localPath.startsWith(root + path.sep)) {
+                        throw new Error(`Object key "${validated.key}" resolves outside the destination directory`);
+                    }
+                }
+                const { content } = await client.getObjectBytes(validated.bucket, validated.key);
+                await mkdir(path.dirname(localPath), { recursive: true });
+                await writeFile(localPath, content);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                bucket: validated.bucket,
+                                key: validated.key,
+                                localPath,
+                                size: content.length,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [{ type: 'text', text: `Error downloading object: ${message}` }],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

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

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { GCSClientFactory } from '../server.js';
+export declare const DownloadPrefixSchema: z.ZodObject<{
+    bucket: z.ZodString;
+    prefix: z.ZodString;
+    destinationDir: z.ZodOptional<z.ZodString>;
+    maxInlineEntries: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    prefix: string;
+    bucket: string;
+    destinationDir?: string | undefined;
+    maxInlineEntries?: number | undefined;
+}, {
+    prefix: string;
+    bucket: string;
+    destinationDir?: string | undefined;
+    maxInlineEntries?: number | undefined;
+}>;
+/**
+ * Compute the path of an object key relative to the downloaded prefix, so the
+ * directory structure under the prefix is preserved on disk.
+ *
+ * Example: prefix="logs/2024/", key="logs/2024/01/data.json" -> "01/data.json"
+ */
+export declare function relativeKeyForPrefix(key: string, prefix: string): string;
+export declare function downloadPrefixTool(_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\")";
+            };
+            prefix: {
+                type: string;
+                description: "The key prefix to download recursively (e.g., \"logs/2024/\"). All objects under this prefix are downloaded. Use an empty string to download the entire bucket.";
+            };
+            destinationDir: {
+                type: string;
+                description: "Local directory to download into. Created if it does not exist. Defaults to a unique folder under the OS temp directory (e.g., \"/tmp/gcs-download-<bucket>-<timestamp>\").";
+            };
+            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=download-prefix.d.ts.map

package/shared/tools/download-prefix.js

@@ -0,0 +1,169 @@
+import { z } from 'zod';
+import { mkdir, writeFile } from 'fs/promises';
+import os from 'os';
+import path from 'path';
+const PARAM_DESCRIPTIONS = {
+    bucket: 'The name of the GCS bucket (e.g., "my-app-data")',
+    prefix: 'The key prefix to download recursively (e.g., "logs/2024/"). All objects under this prefix are downloaded. Use an empty string to download the entire bucket.',
+    destinationDir: 'Local directory to download into. Created if it does not exist. Defaults to a unique folder under the OS temp directory (e.g., "/tmp/gcs-download-<bucket>-<timestamp>").',
+    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 downloading thousands
+// of objects does not produce an enormous tool response.
+const DEFAULT_MAX_INLINE_ENTRIES = 100;
+// Safety guard against a misbehaving paginator returning the same token forever.
+const MAX_LIST_PAGES = 100_000;
+export const DownloadPrefixSchema = z.object({
+    bucket: z.string().min(1).describe(PARAM_DESCRIPTIONS.bucket),
+    prefix: z.string().describe(PARAM_DESCRIPTIONS.prefix),
+    destinationDir: z.string().min(1).optional().describe(PARAM_DESCRIPTIONS.destinationDir),
+    maxInlineEntries: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe(PARAM_DESCRIPTIONS.maxInlineEntries),
+});
+/**
+ * Compute the path of an object key relative to the downloaded prefix, so the
+ * directory structure under the prefix is preserved on disk.
+ *
+ * Example: prefix="logs/2024/", key="logs/2024/01/data.json" -> "01/data.json"
+ */
+export function relativeKeyForPrefix(key, prefix) {
+    let rel = key;
+    if (prefix && key.startsWith(prefix)) {
+        rel = key.slice(prefix.length);
+    }
+    // Strip any leading slashes left over when the prefix did not end in "/".
+    rel = rel.replace(/^\/+/, '');
+    // A key identical to a prefix that points directly at an object leaves an
+    // empty relative path — fall back to the key's basename.
+    return rel === '' ? path.posix.basename(key) : rel;
+}
+/** A GCS key is a "directory placeholder" when it ends with a slash. */
+function isDirectoryPlaceholder(key) {
+    return key.endsWith('/');
+}
+export function downloadPrefixTool(_server, clientFactory) {
+    return {
+        name: 'download_prefix',
+        description: `Recursively download every object under a prefix to a local directory, preserving the key path structure as subdirectories.
+
+Unlike get_object (which returns a single object inline as UTF-8 text), this tool streams raw bytes to disk and is binary-safe. It is the right tool for bulk-fetching a sub-prefix so you can run local data-wrangling over the files.
+
+Returns a manifest:
+{
+  "destinationDir": "/tmp/gcs-download-my-bucket-1700000000000",
+  "objectCount": 1234,
+  "totalBytes": 5678901,
+  "files": [
+    { "key": "logs/2024/01/data.json", "localPath": "/tmp/.../01/data.json", "size": 1234 }
+  ],
+  "filesTruncated": true,
+  "errors": []
+}
+
+Notes:
+- Directory placeholder objects (keys ending in "/") are skipped.
+- Per-object download failures are collected in "errors" without aborting the whole batch.
+- The "files" list is capped (see maxInlineEntries); "objectCount" and "totalBytes" always reflect the full download.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                bucket: { type: 'string', description: PARAM_DESCRIPTIONS.bucket },
+                prefix: { type: 'string', description: PARAM_DESCRIPTIONS.prefix },
+                destinationDir: { type: 'string', description: PARAM_DESCRIPTIONS.destinationDir },
+                maxInlineEntries: {
+                    type: 'number',
+                    minimum: 0,
+                    description: PARAM_DESCRIPTIONS.maxInlineEntries,
+                },
+            },
+            required: ['bucket', 'prefix'],
+        },
+        handler: async (args) => {
+            try {
+                const validated = DownloadPrefixSchema.parse(args);
+                const client = clientFactory();
+                const maxInlineEntries = validated.maxInlineEntries ?? DEFAULT_MAX_INLINE_ENTRIES;
+                const destinationDir = validated.destinationDir ??
+                    path.join(os.tmpdir(), `gcs-download-${validated.bucket}-${Date.now()}`);
+                const resolvedRoot = path.resolve(destinationDir);
+                await mkdir(resolvedRoot, { recursive: true });
+                // Collect every object key under the prefix, paginating until exhausted.
+                // No delimiter is passed so the listing recurses into all sub-prefixes.
+                const keys = [];
+                let pageToken;
+                const seenTokens = new Set();
+                let pages = 0;
+                do {
+                    const page = await client.listObjects(validated.bucket, {
+                        prefix: validated.prefix,
+                        maxResults: 1000,
+                        pageToken,
+                    });
+                    for (const obj of page.objects) {
+                        if (!isDirectoryPlaceholder(obj.key)) {
+                            keys.push({ key: obj.key, size: obj.size });
+                        }
+                    }
+                    pageToken = page.isTruncated ? page.nextPageToken : undefined;
+                    if (pageToken && seenTokens.has(pageToken)) {
+                        // Paginator is looping on the same token; stop to avoid an infinite loop.
+                        break;
+                    }
+                    if (pageToken)
+                        seenTokens.add(pageToken);
+                } while (pageToken && ++pages < MAX_LIST_PAGES);
+                const files = [];
+                const errors = [];
+                let totalBytes = 0;
+                for (const { key } of keys) {
+                    const rel = relativeKeyForPrefix(key, validated.prefix);
+                    const localPath = path.resolve(resolvedRoot, rel);
+                    // Defense in depth: never write outside the destination root, even if a
+                    // key contains ".." segments.
+                    if (localPath !== resolvedRoot && !localPath.startsWith(resolvedRoot + path.sep)) {
+                        errors.push({ key, error: 'Resolved path escapes destination directory; skipped' });
+                        continue;
+                    }
+                    try {
+                        const { content } = await client.getObjectBytes(validated.bucket, key);
+                        await mkdir(path.dirname(localPath), { recursive: true });
+                        await writeFile(localPath, content);
+                        totalBytes += content.length;
+                        files.push({ key, localPath, size: content.length });
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        errors.push({ key, error: message });
+                    }
+                }
+                const manifest = {
+                    destinationDir: resolvedRoot,
+                    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 downloading prefix: ${message}` }],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools.js

@@ -2,6 +2,8 @@ import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprot
 import { listBucketsTool } from './tools/list-buckets.js';
 import { listObjectsTool } from './tools/list-objects.js';
 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 { deleteObjectTool } from './tools/delete-object.js';
 import { createBucketTool } from './tools/create-bucket.js';
@@ -45,6 +47,8 @@ const ALL_TOOLS = [
     { factory: listBucketsTool, groups: ['readonly'], bucketLevelOnly: true },
     { factory: listObjectsTool, groups: ['readonly'], bucketParams: ['bucket'] },
     { factory: getObjectTool, groups: ['readonly'], bucketParams: ['bucket'] },
+    { factory: downloadObjectTool, groups: ['readonly'], bucketParams: ['bucket'] },
+    { factory: downloadPrefixTool, groups: ['readonly'], bucketParams: ['bucket'] },
     { factory: headBucketTool, groups: ['readonly'], bucketLevelOnly: true },
     // Write operations (non-destructive)
     { factory: putObjectTool, groups: ['readwrite'], bucketParams: ['bucket'] },