gcs-google-mcp-server 0.1.0

package/shared/tools/copy-object.js

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+const PARAM_DESCRIPTIONS = {
+    sourceBucket: 'The source bucket name (e.g., "source-bucket")',
+    sourceKey: 'The source object key (e.g., "path/to/source-file.txt")',
+    destBucket: 'The destination bucket name (e.g., "dest-bucket")',
+    destKey: 'The destination object key (e.g., "path/to/dest-file.txt")',
+};
+export const CopyObjectSchema = z.object({
+    sourceBucket: z.string().min(1).describe(PARAM_DESCRIPTIONS.sourceBucket),
+    sourceKey: z.string().min(1).describe(PARAM_DESCRIPTIONS.sourceKey),
+    destBucket: z.string().min(1).describe(PARAM_DESCRIPTIONS.destBucket),
+    destKey: z.string().min(1).describe(PARAM_DESCRIPTIONS.destKey),
+});
+export function copyObjectTool(_server, clientFactory) {
+    return {
+        name: 'copy_object',
+        description: `Copy an object within GCS (same bucket or across buckets).
+
+Copies an object from one location to another. Can be used to rename objects or move them between buckets.
+
+Example response:
+{
+  "success": true,
+  "message": "Object copied from gs://source-bucket/file.txt to gs://dest-bucket/file.txt",
+  "etag": "\\"abc123\\"",
+  "generation": "1234567890"
+}
+
+Use cases:
+- Create backups of files
+- Move files between buckets
+- Rename objects (copy then delete original)
+- Organize files into different paths`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sourceBucket: { type: 'string', description: PARAM_DESCRIPTIONS.sourceBucket },
+                sourceKey: { type: 'string', description: PARAM_DESCRIPTIONS.sourceKey },
+                destBucket: { type: 'string', description: PARAM_DESCRIPTIONS.destBucket },
+                destKey: { type: 'string', description: PARAM_DESCRIPTIONS.destKey },
+            },
+            required: ['sourceBucket', 'sourceKey', 'destBucket', 'destKey'],
+        },
+        handler: async (args) => {
+            try {
+                const validated = CopyObjectSchema.parse(args);
+                const client = clientFactory();
+                const result = await client.copyObject(validated.sourceBucket, validated.sourceKey, validated.destBucket, validated.destKey);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: `Object copied from gs://${validated.sourceBucket}/${validated.sourceKey} to gs://${validated.destBucket}/${validated.destKey}`,
+                                ...result,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [{ type: 'text', text: `Error copying object: ${message}` }],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/create-bucket.d.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { GCSClientFactory } from '../server.js';
+export declare const CreateBucketSchema: z.ZodObject<{
+    bucket: z.ZodEffects<z.ZodString, string, string>;
+    location: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    bucket: string;
+    location?: string | undefined;
+}, {
+    bucket: string;
+    location?: string | undefined;
+}>;
+export declare function createBucketTool(_server: Server, clientFactory: GCSClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            bucket: {
+                type: string;
+                description: "The name of the bucket to create. Must be globally unique, 3-63 characters, lowercase letters, numbers, and hyphens only.";
+            };
+            location: {
+                type: string;
+                description: "GCS location for the bucket (e.g., \"US\", \"EU\", \"us-central1\", \"europe-west1\"). Defaults to \"US\".";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=create-bucket.d.ts.map

package/shared/tools/create-bucket.js

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+const PARAM_DESCRIPTIONS = {
+    bucket: 'The name of the bucket to create. Must be globally unique, 3-63 characters, lowercase letters, numbers, and hyphens only.',
+    location: 'GCS location for the bucket (e.g., "US", "EU", "us-central1", "europe-west1"). Defaults to "US".',
+};
+export const CreateBucketSchema = z.object({
+    bucket: z
+        .string()
+        .min(3)
+        .max(63)
+        // GCS bucket naming rules:
+        // - Start and end with lowercase letter or number
+        // - Can contain lowercase letters, numbers, hyphens, underscores, and dots
+        // - No consecutive dots or periods next to hyphens
+        .regex(/^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$/)
+        .refine((val) => !/^\d+\.\d+\.\d+\.\d+$/.test(val), {
+        message: 'Bucket name cannot be formatted as an IP address',
+    })
+        .describe(PARAM_DESCRIPTIONS.bucket),
+    location: z.string().optional().describe(PARAM_DESCRIPTIONS.location),
+});
+export function createBucketTool(_server, clientFactory) {
+    return {
+        name: 'create_bucket',
+        description: `Create a new GCS bucket.
+
+Creates an empty bucket with the specified name in the given location.
+
+Example response:
+{
+  "success": true,
+  "message": "Bucket created: my-new-bucket",
+  "bucket": "my-new-bucket"
+}
+
+Bucket naming rules:
+- Must be globally unique across all Google Cloud projects
+- 3-63 characters long
+- Only lowercase letters, numbers, hyphens, underscores, and dots
+- Must start and end with a letter or number
+- Cannot be formatted as an IP address
+
+Use cases:
+- Set up storage for a new project
+- Create buckets for different environments
+- Provision storage infrastructure`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                bucket: { type: 'string', description: PARAM_DESCRIPTIONS.bucket },
+                location: { type: 'string', description: PARAM_DESCRIPTIONS.location },
+            },
+            required: ['bucket'],
+        },
+        handler: async (args) => {
+            try {
+                const validated = CreateBucketSchema.parse(args);
+                const client = clientFactory();
+                await client.createBucket(validated.bucket, validated.location);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: `Bucket created: ${validated.bucket}`,
+                                bucket: validated.bucket,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [{ type: 'text', text: `Error creating bucket: ${message}` }],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/delete-bucket.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { GCSClientFactory } from '../server.js';
+export declare const DeleteBucketSchema: z.ZodObject<{
+    bucket: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    bucket: string;
+}, {
+    bucket: string;
+}>;
+export declare function deleteBucketTool(_server: Server, clientFactory: GCSClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            bucket: {
+                type: string;
+                description: "The name of the bucket to delete (e.g., \"my-old-bucket\")";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=delete-bucket.d.ts.map

package/shared/tools/delete-bucket.js

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+const PARAM_DESCRIPTIONS = {
+    bucket: 'The name of the bucket to delete (e.g., "my-old-bucket")',
+};
+export const DeleteBucketSchema = z.object({
+    bucket: z.string().min(1).describe(PARAM_DESCRIPTIONS.bucket),
+});
+export function deleteBucketTool(_server, clientFactory) {
+    return {
+        name: 'delete_bucket',
+        description: `Delete a GCS bucket.
+
+Permanently removes the specified bucket. The bucket must be empty before deletion.
+
+Example response:
+{
+  "success": true,
+  "message": "Bucket deleted: my-old-bucket"
+}
+
+Use cases:
+- Clean up unused buckets
+- Remove test/temporary buckets
+- Decommission old storage
+
+Note: The bucket must be completely empty (no objects) before it can be deleted.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                bucket: { type: 'string', description: PARAM_DESCRIPTIONS.bucket },
+            },
+            required: ['bucket'],
+        },
+        handler: async (args) => {
+            try {
+                const validated = DeleteBucketSchema.parse(args);
+                const client = clientFactory();
+                await client.deleteBucket(validated.bucket);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: `Bucket deleted: ${validated.bucket}`,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [{ type: 'text', text: `Error deleting bucket: ${message}` }],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

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

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { GCSClientFactory } from '../server.js';
+export declare const DeleteObjectSchema: z.ZodObject<{
+    bucket: z.ZodString;
+    key: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    bucket: string;
+    key: string;
+}, {
+    bucket: string;
+    key: string;
+}>;
+export declare function deleteObjectTool(_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) to delete (e.g., \"logs/2024/01/old-data.json\")";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=delete-object.d.ts.map

package/shared/tools/delete-object.js

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+const PARAM_DESCRIPTIONS = {
+    bucket: 'The name of the GCS bucket (e.g., "my-app-data")',
+    key: 'The object key (path) to delete (e.g., "logs/2024/01/old-data.json")',
+};
+export const DeleteObjectSchema = z.object({
+    bucket: z.string().min(1).describe(PARAM_DESCRIPTIONS.bucket),
+    key: z.string().min(1).describe(PARAM_DESCRIPTIONS.key),
+});
+export function deleteObjectTool(_server, clientFactory) {
+    return {
+        name: 'delete_object',
+        description: `Delete an object from GCS.
+
+Permanently removes the specified object from the bucket.
+
+Example response:
+{
+  "success": true,
+  "message": "Object deleted: gs://my-bucket/path/to/file.txt"
+}
+
+Use cases:
+- Remove outdated files
+- Clean up temporary data
+- Delete processed files
+- Remove incorrect uploads
+
+Note: This operation is irreversible. For versioned buckets, this creates a delete marker.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                bucket: { type: 'string', description: PARAM_DESCRIPTIONS.bucket },
+                key: { type: 'string', description: PARAM_DESCRIPTIONS.key },
+            },
+            required: ['bucket', 'key'],
+        },
+        handler: async (args) => {
+            try {
+                const validated = DeleteObjectSchema.parse(args);
+                const client = clientFactory();
+                await client.deleteObject(validated.bucket, validated.key);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: `Object deleted: gs://${validated.bucket}/${validated.key}`,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [{ type: 'text', text: `Error deleting object: ${message}` }],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

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

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { GCSClientFactory } from '../server.js';
+export declare const GetObjectSchema: z.ZodObject<{
+    bucket: z.ZodString;
+    key: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    bucket: string;
+    key: string;
+}, {
+    bucket: string;
+    key: string;
+}>;
+export declare function getObjectTool(_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., \"logs/2024/01/data.json\")";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=get-object.d.ts.map

package/shared/tools/get-object.js

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+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., "logs/2024/01/data.json")',
+};
+export const GetObjectSchema = z.object({
+    bucket: z.string().min(1).describe(PARAM_DESCRIPTIONS.bucket),
+    key: z.string().min(1).describe(PARAM_DESCRIPTIONS.key),
+});
+export function getObjectTool(_server, clientFactory) {
+    return {
+        name: 'get_object',
+        description: `Get the contents of an object from GCS.
+
+Returns the object content as text along with metadata.
+
+Example response:
+{
+  "content": "{\\"name\\": \\"example\\", \\"value\\": 123}",
+  "contentType": "application/json",
+  "contentLength": 35,
+  "lastModified": "2024-03-01T10:00:00Z",
+  "etag": "\\"abc123\\"",
+  "metadata": {"custom-key": "custom-value"}
+}
+
+Use cases:
+- Read configuration files
+- Retrieve JSON data
+- Download text files
+- Access log files
+
+Note: This tool reads objects as UTF-8 text. Binary files may not display correctly.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                bucket: { type: 'string', description: PARAM_DESCRIPTIONS.bucket },
+                key: { type: 'string', description: PARAM_DESCRIPTIONS.key },
+            },
+            required: ['bucket', 'key'],
+        },
+        handler: async (args) => {
+            try {
+                const validated = GetObjectSchema.parse(args);
+                const client = clientFactory();
+                const result = await client.getObject(validated.bucket, validated.key);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [{ type: 'text', text: `Error getting object: ${message}` }],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/head-bucket.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { GCSClientFactory } from '../server.js';
+export declare const HeadBucketSchema: z.ZodObject<{
+    bucket: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    bucket: string;
+}, {
+    bucket: string;
+}>;
+export declare function headBucketTool(_server: Server, clientFactory: GCSClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            bucket: {
+                type: string;
+                description: "The name of the bucket to check (e.g., \"my-bucket\")";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=head-bucket.d.ts.map

package/shared/tools/head-bucket.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+const PARAM_DESCRIPTIONS = {
+    bucket: 'The name of the bucket to check (e.g., "my-bucket")',
+};
+export const HeadBucketSchema = z.object({
+    bucket: z.string().min(1).describe(PARAM_DESCRIPTIONS.bucket),
+});
+export function headBucketTool(_server, clientFactory) {
+    return {
+        name: 'head_bucket',
+        description: `Check if a GCS bucket exists and is accessible.
+
+Returns whether the bucket exists and the caller has permission to access it.
+
+Example response:
+{
+  "exists": true,
+  "bucket": "my-bucket"
+}
+
+Use cases:
+- Verify bucket exists before operations
+- Check bucket accessibility
+- Validate bucket names`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                bucket: { type: 'string', description: PARAM_DESCRIPTIONS.bucket },
+            },
+            required: ['bucket'],
+        },
+        handler: async (args) => {
+            try {
+                const validated = HeadBucketSchema.parse(args);
+                const client = clientFactory();
+                const exists = await client.headBucket(validated.bucket);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                exists,
+                                bucket: validated.bucket,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [{ type: 'text', text: `Error checking bucket: ${message}` }],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/list-buckets.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { GCSClientFactory } from '../server.js';
+export declare const ListBucketsSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare function listBucketsTool(_server: Server, clientFactory: GCSClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {};
+        required: string[];
+    };
+    handler: (_args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=list-buckets.d.ts.map