gcs-google-mcp-server 0.1.0

package/shared/tools/list-buckets.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+export const ListBucketsSchema = z.object({});
+export function listBucketsTool(_server, clientFactory) {
+    return {
+        name: 'list_buckets',
+        description: `List all GCS buckets in the Google Cloud project.
+
+Returns a list of bucket names and their creation dates.
+
+Example response:
+{
+  "buckets": [
+    {"name": "my-app-data", "creationDate": "2024-01-15T10:30:00Z"},
+    {"name": "logs-archive", "creationDate": "2024-02-20T14:45:00Z"}
+  ]
+}
+
+Use cases:
+- Discover available buckets in the project
+- Audit bucket inventory
+- Find bucket names for subsequent operations`,
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+        handler: async (_args) => {
+            try {
+                const client = clientFactory();
+                const result = await client.listBuckets();
+                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 listing buckets: ${message}` }],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/list-objects.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 ListObjectsSchema: z.ZodObject<{
+    bucket: z.ZodString;
+    prefix: z.ZodOptional<z.ZodString>;
+    maxResults: z.ZodOptional<z.ZodNumber>;
+    pageToken: z.ZodOptional<z.ZodString>;
+    delimiter: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    bucket: string;
+    prefix?: string | undefined;
+    maxResults?: number | undefined;
+    pageToken?: string | undefined;
+    delimiter?: string | undefined;
+}, {
+    bucket: string;
+    prefix?: string | undefined;
+    maxResults?: number | undefined;
+    pageToken?: string | undefined;
+    delimiter?: string | undefined;
+}>;
+export declare function listObjectsTool(_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: "Filter objects by key prefix (e.g., \"logs/2024/\" to list only objects in that folder)";
+            };
+            maxResults: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: "Maximum number of objects to return (1-1000, default: 1000)";
+            };
+            pageToken: {
+                type: string;
+                description: "Token for pagination, returned from previous list request when truncated";
+            };
+            delimiter: {
+                type: string;
+                description: "Character to group keys (e.g., \"/\" to simulate folders). Common prefixes are returned separately.";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=list-objects.d.ts.map

package/shared/tools/list-objects.js

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+const PARAM_DESCRIPTIONS = {
+    bucket: 'The name of the GCS bucket (e.g., "my-app-data")',
+    prefix: 'Filter objects by key prefix (e.g., "logs/2024/" to list only objects in that folder)',
+    maxResults: 'Maximum number of objects to return (1-1000, default: 1000)',
+    pageToken: 'Token for pagination, returned from previous list request when truncated',
+    delimiter: 'Character to group keys (e.g., "/" to simulate folders). Common prefixes are returned separately.',
+};
+export const ListObjectsSchema = z.object({
+    bucket: z.string().min(1).describe(PARAM_DESCRIPTIONS.bucket),
+    prefix: z.string().optional().describe(PARAM_DESCRIPTIONS.prefix),
+    maxResults: z.number().min(1).max(1000).optional().describe(PARAM_DESCRIPTIONS.maxResults),
+    pageToken: z.string().optional().describe(PARAM_DESCRIPTIONS.pageToken),
+    delimiter: z.string().optional().describe(PARAM_DESCRIPTIONS.delimiter),
+});
+export function listObjectsTool(_server, clientFactory) {
+    return {
+        name: 'list_objects',
+        description: `List objects in a GCS bucket with optional prefix filtering and pagination.
+
+Example response:
+{
+  "objects": [
+    {"key": "data/file1.json", "size": 1234, "lastModified": "2024-03-01T10:00:00Z"},
+    {"key": "data/file2.json", "size": 5678, "lastModified": "2024-03-02T11:00:00Z"}
+  ],
+  "commonPrefixes": ["data/subdir/"],
+  "isTruncated": false
+}
+
+Use cases:
+- Browse bucket contents
+- Find files matching a prefix pattern
+- List "folders" using delimiter
+- Paginate through large buckets`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                bucket: { type: 'string', description: PARAM_DESCRIPTIONS.bucket },
+                prefix: { type: 'string', description: PARAM_DESCRIPTIONS.prefix },
+                maxResults: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 1000,
+                    description: PARAM_DESCRIPTIONS.maxResults,
+                },
+                pageToken: { type: 'string', description: PARAM_DESCRIPTIONS.pageToken },
+                delimiter: { type: 'string', description: PARAM_DESCRIPTIONS.delimiter },
+            },
+            required: ['bucket'],
+        },
+        handler: async (args) => {
+            try {
+                const validated = ListObjectsSchema.parse(args);
+                const client = clientFactory();
+                const result = await client.listObjects(validated.bucket, {
+                    prefix: validated.prefix,
+                    maxResults: validated.maxResults,
+                    pageToken: validated.pageToken,
+                    delimiter: validated.delimiter,
+                });
+                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 listing objects: ${message}` }],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/put-object.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 PutObjectSchema: z.ZodObject<{
+    bucket: z.ZodString;
+    key: z.ZodString;
+    content: z.ZodString;
+    contentType: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    bucket: string;
+    key: string;
+    metadata?: Record<string, string> | undefined;
+    contentType?: string | undefined;
+}, {
+    content: string;
+    bucket: string;
+    key: string;
+    metadata?: Record<string, string> | undefined;
+    contentType?: string | undefined;
+}>;
+export declare function putObjectTool(_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., \"data/config.json\")";
+            };
+            content: {
+                type: string;
+                description: "The content to store in the object (text/string data)";
+            };
+            contentType: {
+                type: string;
+                description: "MIME type of the content (e.g., \"application/json\", \"text/plain\"). Defaults to \"text/plain\".";
+            };
+            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.d.ts.map

package/shared/tools/put-object.js

@@ -0,0 +1,81 @@
+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., "data/config.json")',
+    content: 'The content to store in the object (text/string data)',
+    contentType: 'MIME type of the content (e.g., "application/json", "text/plain"). Defaults to "text/plain".',
+    metadata: 'Custom metadata as key-value pairs (e.g., {"author": "system", "version": "1.0"})',
+};
+export const PutObjectSchema = z.object({
+    bucket: z.string().min(1).describe(PARAM_DESCRIPTIONS.bucket),
+    key: z.string().min(1).describe(PARAM_DESCRIPTIONS.key),
+    content: z.string().describe(PARAM_DESCRIPTIONS.content),
+    contentType: z.string().optional().describe(PARAM_DESCRIPTIONS.contentType),
+    metadata: z.record(z.string()).optional().describe(PARAM_DESCRIPTIONS.metadata),
+});
+export function putObjectTool(_server, clientFactory) {
+    return {
+        name: 'put_object',
+        description: `Upload or update an object in GCS.
+
+Creates a new object or overwrites an existing one with the provided content.
+
+Example response:
+{
+  "etag": "\\"abc123def456\\"",
+  "generation": "1234567890"
+}
+
+Use cases:
+- Store configuration files
+- Upload JSON data
+- Create text files
+- Save generated content
+
+Note: This tool handles text content. For binary files, use base64 encoding or a different approach.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                bucket: { type: 'string', description: PARAM_DESCRIPTIONS.bucket },
+                key: { type: 'string', description: PARAM_DESCRIPTIONS.key },
+                content: { type: 'string', description: PARAM_DESCRIPTIONS.content },
+                contentType: { type: 'string', description: PARAM_DESCRIPTIONS.contentType },
+                metadata: {
+                    type: 'object',
+                    additionalProperties: { type: 'string' },
+                    description: PARAM_DESCRIPTIONS.metadata,
+                },
+            },
+            required: ['bucket', 'key', 'content'],
+        },
+        handler: async (args) => {
+            try {
+                const validated = PutObjectSchema.parse(args);
+                const client = clientFactory();
+                const result = await client.putObject(validated.bucket, validated.key, validated.content, {
+                    contentType: validated.contentType,
+                    metadata: validated.metadata,
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: `Object uploaded to gs://${validated.bucket}/${validated.key}`,
+                                ...result,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [{ type: 'text', text: `Error putting object: ${message}` }],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools.d.ts

@@ -0,0 +1,30 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { GCSClientFactory } from './server.js';
+/**
+ * Available tool groups for GCS operations.
+ * - 'readonly': Read-only operations (list, get, head)
+ * - 'readwrite': Write operations (put, copy, delete, create)
+ */
+export type ToolGroup = 'readonly' | 'readwrite';
+/**
+ * Parse enabled tool groups from environment variable.
+ * @param enabledGroupsParam - Comma-separated list of groups (e.g., "readonly,readwrite")
+ * @returns Array of enabled tool groups
+ */
+export declare function parseEnabledToolGroups(enabledGroupsParam?: string): ToolGroup[];
+/**
+ * Parse enabled/disabled tools from environment variables.
+ */
+export declare function parseToolFilters(enabledToolsParam?: string, disabledToolsParam?: string): {
+    enabledTools: Set<string> | null;
+    disabledTools: Set<string>;
+};
+/**
+ * Get all tool names for documentation/help purposes.
+ */
+export declare function getAllToolNames(): string[];
+/**
+ * Creates a function to register all tools with the server.
+ */
+export declare function createRegisterTools(clientFactory: GCSClientFactory, enabledGroups?: ToolGroup[]): (server: Server) => void;
+//# sourceMappingURL=tools.d.ts.map

package/shared/tools.js

@@ -0,0 +1,154 @@
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { listBucketsTool } from './tools/list-buckets.js';
+import { listObjectsTool } from './tools/list-objects.js';
+import { getObjectTool } from './tools/get-object.js';
+import { putObjectTool } from './tools/put-object.js';
+import { deleteObjectTool } from './tools/delete-object.js';
+import { createBucketTool } from './tools/create-bucket.js';
+import { deleteBucketTool } from './tools/delete-bucket.js';
+import { copyObjectTool } from './tools/copy-object.js';
+import { headBucketTool } from './tools/head-bucket.js';
+import { logWarning, logInfo } from './logging.js';
+const ALL_TOOL_GROUPS = ['readonly', 'readwrite'];
+/**
+ * Parse enabled tool groups from environment variable.
+ * @param enabledGroupsParam - Comma-separated list of groups (e.g., "readonly,readwrite")
+ * @returns Array of enabled tool groups
+ */
+export function parseEnabledToolGroups(enabledGroupsParam) {
+    if (!enabledGroupsParam) {
+        return ALL_TOOL_GROUPS; // All groups enabled by default
+    }
+    const requestedGroups = enabledGroupsParam.split(',').map((g) => g.trim().toLowerCase());
+    const validGroups = requestedGroups.filter((g) => ALL_TOOL_GROUPS.includes(g));
+    if (validGroups.length === 0) {
+        logWarning('parseEnabledToolGroups', `No valid tool groups found in "${enabledGroupsParam}". Valid groups: ${ALL_TOOL_GROUPS.join(', ')}. Using all groups.`);
+        return ALL_TOOL_GROUPS;
+    }
+    return validGroups;
+}
+/**
+ * Parse enabled/disabled tools from environment variables.
+ */
+export function parseToolFilters(enabledToolsParam, disabledToolsParam) {
+    const enabledTools = enabledToolsParam
+        ? new Set(enabledToolsParam.split(',').map((t) => t.trim()))
+        : null;
+    const disabledTools = new Set(disabledToolsParam ? disabledToolsParam.split(',').map((t) => t.trim()) : []);
+    return { enabledTools, disabledTools };
+}
+/**
+ * All available GCS tools with their group assignments.
+ */
+const ALL_TOOLS = [
+    // Read-only operations
+    { factory: listBucketsTool, groups: ['readonly'], bucketLevelOnly: true },
+    { factory: listObjectsTool, groups: ['readonly'], bucketParams: ['bucket'] },
+    { factory: getObjectTool, groups: ['readonly'], bucketParams: ['bucket'] },
+    { factory: headBucketTool, groups: ['readonly'], bucketLevelOnly: true },
+    // Write operations
+    { factory: putObjectTool, groups: ['readwrite'], bucketParams: ['bucket'] },
+    { factory: deleteObjectTool, groups: ['readwrite'], bucketParams: ['bucket'] },
+    { factory: copyObjectTool, groups: ['readwrite'], bucketParams: ['sourceBucket', 'destBucket'] },
+    { factory: createBucketTool, groups: ['readwrite'], bucketLevelOnly: true },
+    { factory: deleteBucketTool, groups: ['readwrite'], bucketLevelOnly: true },
+];
+/**
+ * Get all tool names for documentation/help purposes.
+ */
+export function getAllToolNames() {
+    const mockServer = { setRequestHandler: () => { } };
+    const mockFactory = (() => { });
+    return ALL_TOOLS.map((def) => def.factory(mockServer, mockFactory).name);
+}
+/**
+ * Wraps a tool to inject bucket parameter(s) when GCS_BUCKET is set.
+ */
+function wrapToolForBucketConstraint(tool, bucketParams, constrainedBucket) {
+    // Modify input schema to remove bucket params (they're injected automatically)
+    const newProperties = { ...tool.inputSchema.properties };
+    const newRequired = (tool.inputSchema.required || []).filter((r) => !bucketParams.includes(r));
+    for (const param of bucketParams) {
+        delete newProperties[param];
+    }
+    // Update description to indicate bucket constraint
+    const constraintNote = `\n\n**Note:** Operations are constrained to bucket "${constrainedBucket}".`;
+    return {
+        ...tool,
+        description: tool.description + constraintNote,
+        inputSchema: {
+            type: 'object',
+            properties: newProperties,
+            required: newRequired.length > 0 ? newRequired : undefined,
+        },
+        handler: async (args) => {
+            // Inject the constrained bucket into the args
+            const argsWithBucket = { ...args };
+            for (const param of bucketParams) {
+                argsWithBucket[param] = constrainedBucket;
+            }
+            return await tool.handler(argsWithBucket);
+        },
+    };
+}
+/**
+ * Creates a function to register all tools with the server.
+ */
+export function createRegisterTools(clientFactory, enabledGroups) {
+    const groups = enabledGroups || parseEnabledToolGroups(process.env.GCS_ENABLED_TOOLGROUPS);
+    const constrainedBucket = process.env.GCS_BUCKET;
+    // Parse individual tool filters
+    const { enabledTools, disabledTools } = parseToolFilters(process.env.GCS_ENABLED_TOOLS, process.env.GCS_DISABLED_TOOLS);
+    return (server) => {
+        // Filter tools by enabled groups first
+        let filteredToolDefs = ALL_TOOLS.filter((def) => def.groups.some((g) => groups.includes(g)));
+        // If GCS_BUCKET is set, filter out bucket-level-only tools
+        if (constrainedBucket) {
+            filteredToolDefs = filteredToolDefs.filter((def) => !def.bucketLevelOnly);
+            logInfo('config', `Bucket constraint active: ${constrainedBucket}`);
+        }
+        // Create tool instances
+        let tools = filteredToolDefs.map((def) => {
+            const tool = def.factory(server, clientFactory);
+            // If bucket is constrained and this tool has bucket params, wrap it
+            if (constrainedBucket && def.bucketParams && def.bucketParams.length > 0) {
+                return wrapToolForBucketConstraint(tool, def.bucketParams, constrainedBucket);
+            }
+            return tool;
+        });
+        // Apply individual tool filters
+        if (enabledTools) {
+            tools = tools.filter((tool) => enabledTools.has(tool.name));
+        }
+        tools = tools.filter((tool) => !disabledTools.has(tool.name));
+        // Log configuration for debugging
+        if (process.env.GCS_ENABLED_TOOLGROUPS) {
+            logWarning('config', `Tool groups enabled: ${groups.join(', ')}`);
+        }
+        if (enabledTools) {
+            logWarning('config', `Enabled tools filter: ${[...enabledTools].join(', ')}`);
+        }
+        if (disabledTools.size > 0) {
+            logWarning('config', `Disabled tools: ${[...disabledTools].join(', ')}`);
+        }
+        // List available tools
+        server.setRequestHandler(ListToolsRequestSchema, async () => {
+            return {
+                tools: tools.map((tool) => ({
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema,
+                })),
+            };
+        });
+        // Handle tool calls
+        server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            const tool = tools.find((t) => t.name === name);
+            if (!tool) {
+                throw new Error(`Unknown tool: ${name}`);
+            }
+            return await tool.handler(args);
+        });
+    };
+}

package/shared/types.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=types.d.ts.map

package/shared/types.js

@@ -0,0 +1,6 @@
+"use strict";
+// =============================================================================
+// SHARED TYPE DEFINITIONS
+// =============================================================================
+// Common types used across the GCS MCP server.
+// =============================================================================