gcs-google-mcp-server 0.1.0

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

@@ -0,0 +1,131 @@
+export function createIntegrationMockGCSClient(mockData = {}) {
+    // Default mock data
+    const buckets = mockData.buckets || [
+        { name: 'test-bucket', creationDate: new Date('2024-01-01') },
+        { name: 'another-bucket', creationDate: new Date('2024-02-01') },
+    ];
+    // Deep clone objects to avoid mutation issues
+    const objects = structuredClone(mockData.objects || {});
+    return {
+        async listBuckets() {
+            return { buckets };
+        },
+        async listObjects(bucket, options = {}) {
+            const bucketObjects = objects?.[bucket] || {};
+            let keys = Object.keys(bucketObjects);
+            // Apply prefix filter
+            if (options.prefix) {
+                keys = keys.filter((key) => key.startsWith(options.prefix));
+            }
+            // Handle delimiter for common prefixes
+            const commonPrefixes = [];
+            if (options.delimiter) {
+                const prefixSet = new Set();
+                keys = keys.filter((key) => {
+                    const afterPrefix = options.prefix ? key.slice(options.prefix.length) : key;
+                    const delimiterIndex = afterPrefix.indexOf(options.delimiter);
+                    if (delimiterIndex >= 0) {
+                        const prefix = (options.prefix || '') + afterPrefix.slice(0, delimiterIndex + 1);
+                        prefixSet.add(prefix);
+                        return false;
+                    }
+                    return true;
+                });
+                commonPrefixes.push(...prefixSet);
+            }
+            // Apply maxResults limit
+            const maxResults = options.maxResults || 1000;
+            const isTruncated = keys.length > maxResults;
+            keys = keys.slice(0, maxResults);
+            return {
+                objects: keys.map((key) => ({
+                    key,
+                    size: bucketObjects[key]?.content?.length || 0,
+                    lastModified: bucketObjects[key]?.lastModified || new Date(),
+                    storageClass: 'STANDARD',
+                    etag: '"mock-etag"',
+                })),
+                commonPrefixes,
+                isTruncated,
+                nextPageToken: isTruncated ? 'mock-token' : undefined,
+            };
+        },
+        async getObject(bucket, key) {
+            const bucketObjects = objects?.[bucket];
+            if (!bucketObjects || !bucketObjects[key]) {
+                throw new Error(`Object not found: ${bucket}/${key}`);
+            }
+            const obj = bucketObjects[key];
+            return {
+                content: obj.content,
+                contentType: obj.contentType || 'text/plain',
+                contentLength: obj.content.length,
+                lastModified: obj.lastModified || new Date(),
+                etag: '"mock-etag"',
+                metadata: obj.metadata || {},
+            };
+        },
+        async putObject(bucket, key, content, putOptions = {}) {
+            if (!objects) {
+                throw new Error('Mock data not initialized');
+            }
+            if (!objects[bucket]) {
+                objects[bucket] = {};
+            }
+            objects[bucket][key] = {
+                content,
+                contentType: putOptions.contentType,
+                metadata: putOptions.metadata,
+                lastModified: new Date(),
+            };
+            return {
+                etag: '"mock-etag"',
+                generation: undefined,
+            };
+        },
+        async deleteObject(bucket, key) {
+            if (objects?.[bucket]) {
+                delete objects[bucket][key];
+            }
+        },
+        async createBucket(bucket) {
+            if (buckets.some((b) => b.name === bucket)) {
+                throw new Error(`Bucket already exists: ${bucket}`);
+            }
+            buckets.push({ name: bucket, creationDate: new Date() });
+            if (objects) {
+                objects[bucket] = {};
+            }
+        },
+        async deleteBucket(bucket) {
+            const index = buckets.findIndex((b) => b.name === bucket);
+            if (index === -1) {
+                throw new Error(`Bucket not found: ${bucket}`);
+            }
+            if (objects?.[bucket] && Object.keys(objects[bucket]).length > 0) {
+                throw new Error(`Bucket is not empty: ${bucket}`);
+            }
+            buckets.splice(index, 1);
+            if (objects) {
+                delete objects[bucket];
+            }
+        },
+        async headBucket(bucket) {
+            return buckets.some((b) => b.name === bucket);
+        },
+        async copyObject(sourceBucket, sourceKey, destBucket, destKey) {
+            const sourceObj = objects?.[sourceBucket]?.[sourceKey];
+            if (!sourceObj) {
+                throw new Error(`Source object not found: ${sourceBucket}/${sourceKey}`);
+            }
+            if (!objects?.[destBucket]) {
+                throw new Error(`Destination bucket not found: ${destBucket}`);
+            }
+            objects[destBucket][destKey] = { ...sourceObj, lastModified: new Date() };
+            return {
+                etag: '"mock-etag"',
+                generation: undefined,
+            };
+        },
+    };
+}

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

@@ -0,0 +1,120 @@
+import { Storage } from '@google-cloud/storage';
+export class GoogleCloudStorageClient {
+    storage;
+    constructor(config) {
+        const storageOptions = {
+            projectId: config.projectId,
+        };
+        if (config.keyFilePath) {
+            storageOptions.keyFilename = config.keyFilePath;
+        }
+        else if (config.keyFileContents) {
+            try {
+                storageOptions.credentials = JSON.parse(config.keyFileContents);
+            }
+            catch {
+                throw new Error('Failed to parse GCS_SERVICE_ACCOUNT_KEY_JSON: invalid JSON. Ensure the value is a valid JSON string.');
+            }
+        }
+        // If neither is provided, uses Application Default Credentials (ADC)
+        this.storage = new Storage(storageOptions);
+    }
+    async listBuckets() {
+        const [buckets] = await this.storage.getBuckets();
+        return {
+            buckets: buckets.map((bucket) => ({
+                name: bucket.name,
+                creationDate: bucket.metadata.timeCreated
+                    ? new Date(bucket.metadata.timeCreated)
+                    : undefined,
+            })),
+        };
+    }
+    async listObjects(bucket, options = {}) {
+        const [files, , apiResponse] = await this.storage.bucket(bucket).getFiles({
+            prefix: options.prefix,
+            maxResults: options.maxResults,
+            pageToken: options.pageToken,
+            delimiter: options.delimiter,
+            autoPaginate: false,
+        });
+        const commonPrefixes = apiResponse?.prefixes?.map((p) => p) || [];
+        const nextPageToken = apiResponse?.nextPageToken;
+        return {
+            objects: files.map((file) => ({
+                key: file.name,
+                size: file.metadata.size ? Number(file.metadata.size) : undefined,
+                lastModified: file.metadata.updated ? new Date(file.metadata.updated) : undefined,
+                storageClass: file.metadata.storageClass,
+                etag: file.metadata.etag,
+            })),
+            commonPrefixes,
+            isTruncated: !!nextPageToken,
+            nextPageToken,
+        };
+    }
+    async getObject(bucket, key) {
+        const file = this.storage.bucket(bucket).file(key);
+        const [content] = await file.download();
+        const [metadata] = await file.getMetadata();
+        return {
+            content: content.toString('utf-8'),
+            contentType: metadata.contentType,
+            contentLength: metadata.size ? Number(metadata.size) : undefined,
+            lastModified: metadata.updated ? new Date(metadata.updated) : undefined,
+            etag: metadata.etag,
+            metadata: metadata.metadata || {},
+        };
+    }
+    async putObject(bucket, key, content, options = {}) {
+        const file = this.storage.bucket(bucket).file(key);
+        await file.save(content, {
+            contentType: options.contentType,
+            metadata: options.metadata,
+        });
+        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();
+    }
+    async createBucket(bucket, location) {
+        await this.storage.createBucket(bucket, {
+            location: location || 'US',
+        });
+    }
+    async deleteBucket(bucket) {
+        await this.storage.bucket(bucket).delete();
+    }
+    async headBucket(bucket) {
+        try {
+            await this.storage.bucket(bucket).getMetadata();
+            return true;
+        }
+        catch (error) {
+            // Only return false for NotFound errors (bucket doesn't exist)
+            // Re-throw permission errors and other failures
+            if (typeof error === 'object' &&
+                error !== null &&
+                'code' in error &&
+                error.code === 404) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    async copyObject(sourceBucket, sourceKey, destBucket, destKey) {
+        const sourceFile = this.storage.bucket(sourceBucket).file(sourceKey);
+        const destFile = this.storage.bucket(destBucket).file(destKey);
+        const [, apiResponse] = await sourceFile.copy(destFile);
+        const resource = apiResponse
+            ?.resource;
+        return {
+            etag: resource?.etag,
+            generation: resource?.generation ? String(resource.generation) : undefined,
+        };
+    }
+}

package/shared/index.d.ts

@@ -0,0 +1,8 @@
+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 { 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';
+//# sourceMappingURL=index.d.ts.map

package/shared/index.js

@@ -0,0 +1,9 @@
+// Core server exports
+export { registerResources } from './resources.js';
+export { createRegisterTools, parseEnabledToolGroups, parseToolFilters, getAllToolNames, } from './tools.js';
+export { createMCPServer, GoogleCloudStorageClient, } from './server.js';
+export { createIntegrationMockGCSClient, } from './gcs-client/gcs-client.integration-mock.js';
+// State management exports
+export { getSelectedResourceId, hasSelectedResource, isResourceLocked, getServerState, setSelectedResourceId, clearSelectedResource, initializeStateFromEnvironment, resetState, } from './state.js';
+// Logging exports (re-exported for convenience)
+export { logServerStart, logError, logWarning, logInfo, logDebug } from './logging.js';

package/shared/logging.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Logging utilities for consistent output across MCP servers
+ */
+/**
+ * Log server startup message
+ */
+export declare function logServerStart(serverName: string, transport?: string): void;
+/**
+ * Log an error with context
+ */
+export declare function logError(context: string, error: unknown): void;
+/**
+ * Log a warning
+ */
+export declare function logWarning(context: string, message: string): void;
+/**
+ * Log an informational message
+ */
+export declare function logInfo(context: string, message: string): void;
+/**
+ * Log debug information (only in development)
+ */
+export declare function logDebug(context: string, message: string): void;
+//# sourceMappingURL=logging.d.ts.map

package/shared/logging.js

@@ -0,0 +1,40 @@
+/**
+ * Logging utilities for consistent output across MCP servers
+ */
+/**
+ * Log server startup message
+ */
+export function logServerStart(serverName, transport = 'stdio') {
+    console.error(`MCP server ${serverName} running on ${transport}`);
+}
+/**
+ * Log an error with context
+ */
+export function logError(context, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+    console.error(`[ERROR] ${context}: ${message}`);
+    if (stack) {
+        console.error(stack);
+    }
+}
+/**
+ * Log a warning
+ */
+export function logWarning(context, message) {
+    console.error(`[WARN] ${context}: ${message}`);
+}
+/**
+ * Log an informational message
+ */
+export function logInfo(context, message) {
+    console.error(`[INFO] ${context}: ${message}`);
+}
+/**
+ * Log debug information (only in development)
+ */
+export function logDebug(context, message) {
+    if (process.env.NODE_ENV === 'development' || process.env.DEBUG) {
+        console.error(`[DEBUG] ${context}: ${message}`);
+    }
+}

package/shared/resources.d.ts

@@ -0,0 +1,3 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+export declare function registerResources(server: Server): void;
+//# sourceMappingURL=resources.d.ts.map

package/shared/resources.js

@@ -0,0 +1,65 @@
+import { ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { getServerState } from './state.js';
+import { getAllToolNames } from './tools.js';
+export function registerResources(server) {
+    // List available resources
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        return {
+            resources: [
+                {
+                    uri: 'gcs://config',
+                    name: 'Server Configuration',
+                    description: 'Current server configuration and status. Shows enabled tool groups and tools.',
+                    mimeType: 'application/json',
+                },
+            ],
+        };
+    });
+    // Read resource contents
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        if (uri === 'gcs://config') {
+            const state = getServerState();
+            const config = {
+                server: {
+                    name: 'gcs-mcp-server',
+                    version: '0.0.0',
+                    transport: 'stdio',
+                },
+                environment: {
+                    GCS_PROJECT_ID: process.env.GCS_PROJECT_ID || 'not set',
+                    GCS_SERVICE_ACCOUNT_KEY_FILE: process.env.GCS_SERVICE_ACCOUNT_KEY_FILE
+                        ? '***configured***'
+                        : 'not set',
+                    GCS_SERVICE_ACCOUNT_KEY_JSON: process.env.GCS_SERVICE_ACCOUNT_KEY_JSON
+                        ? '***configured***'
+                        : 'not set',
+                    GCS_ENABLED_TOOLGROUPS: process.env.GCS_ENABLED_TOOLGROUPS || 'all (default)',
+                    GCS_ENABLED_TOOLS: process.env.GCS_ENABLED_TOOLS || 'not set',
+                    GCS_DISABLED_TOOLS: process.env.GCS_DISABLED_TOOLS || 'not set',
+                    GCS_BUCKET: process.env.GCS_BUCKET || 'not set',
+                    SKIP_HEALTH_CHECKS: process.env.SKIP_HEALTH_CHECKS || 'false',
+                },
+                availableTools: getAllToolNames(),
+                state: {
+                    selectedResourceId: state.selectedResourceId || 'none',
+                    isResourceLocked: state.isResourceLocked,
+                },
+                capabilities: {
+                    tools: true,
+                    resources: true,
+                },
+            };
+            return {
+                contents: [
+                    {
+                        uri: 'gcs://config',
+                        mimeType: 'application/json',
+                        text: JSON.stringify(config, null, 2),
+                    },
+                ],
+            };
+        }
+        throw new Error(`Resource not found: ${uri}`);
+    });
+}

package/shared/server.d.ts

@@ -0,0 +1,46 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { type IGCSClient, GoogleCloudStorageClient, type GCSClientConfig } from './gcs-client/gcs-client.js';
+export type { IGCSClient, GCSClientConfig };
+export { GoogleCloudStorageClient };
+export type GCSClientFactory = () => IGCSClient;
+export interface CreateMCPServerOptions {
+    version: string;
+}
+export declare function createMCPServer(options: CreateMCPServerOptions): {
+    server: Server<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    registerHandlers: (server: Server, clientFactory?: GCSClientFactory) => Promise<void>;
+};
+//# sourceMappingURL=server.d.ts.map

package/shared/server.js

@@ -0,0 +1,37 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { registerResources } from './resources.js';
+import { createRegisterTools } from './tools.js';
+import { GoogleCloudStorageClient, } from './gcs-client/gcs-client.js';
+export { GoogleCloudStorageClient };
+export function createMCPServer(options) {
+    const server = new Server({
+        name: 'gcs-mcp-server',
+        version: options.version,
+    }, {
+        capabilities: {
+            resources: {},
+            tools: {},
+        },
+    });
+    const registerHandlers = async (server, clientFactory) => {
+        // Use provided factory or create default client from environment variables
+        const factory = clientFactory ||
+            (() => {
+                const projectId = process.env.GCS_PROJECT_ID;
+                const keyFilePath = process.env.GCS_SERVICE_ACCOUNT_KEY_FILE;
+                const keyFileContents = process.env.GCS_SERVICE_ACCOUNT_KEY_JSON;
+                if (!projectId) {
+                    throw new Error('GCS_PROJECT_ID environment variable must be configured');
+                }
+                return new GoogleCloudStorageClient({
+                    projectId,
+                    keyFilePath,
+                    keyFileContents,
+                });
+            });
+        registerResources(server);
+        const registerTools = createRegisterTools(factory);
+        registerTools(server);
+    };
+    return { server, registerHandlers };
+}

package/shared/state.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Server state interface.
+ */
+interface ServerState {
+    /** Currently selected resource ID (e.g., workspace, project, app) */
+    selectedResourceId: string | null;
+    /** Whether the resource ID is locked (e.g., from environment variable) */
+    isResourceLocked: boolean;
+}
+/**
+ * Get the currently selected resource ID.
+ */
+export declare function getSelectedResourceId(): string | null;
+/**
+ * Check if a resource is currently selected.
+ */
+export declare function hasSelectedResource(): boolean;
+/**
+ * Check if the resource selection is locked (e.g., from environment variable).
+ */
+export declare function isResourceLocked(): boolean;
+/**
+ * Get the full server state (useful for debugging/config resource).
+ */
+export declare function getServerState(): Readonly<ServerState>;
+/**
+ * Set the selected resource ID.
+ */
+export declare function setSelectedResourceId(resourceId: string, locked?: boolean): void;
+/**
+ * Clear the selected resource (only if not locked).
+ */
+export declare function clearSelectedResource(): void;
+/**
+ * Initialize state from environment variables.
+ */
+export declare function initializeStateFromEnvironment(): void;
+/**
+ * Reset all state (useful for testing).
+ */
+export declare function resetState(): void;
+export {};
+//# sourceMappingURL=state.d.ts.map

package/shared/state.js

@@ -0,0 +1,67 @@
+// In-memory state (reset on server restart)
+let state = {
+    selectedResourceId: null,
+    isResourceLocked: false,
+};
+/**
+ * Get the currently selected resource ID.
+ */
+export function getSelectedResourceId() {
+    return state.selectedResourceId;
+}
+/**
+ * Check if a resource is currently selected.
+ */
+export function hasSelectedResource() {
+    return state.selectedResourceId !== null;
+}
+/**
+ * Check if the resource selection is locked (e.g., from environment variable).
+ */
+export function isResourceLocked() {
+    return state.isResourceLocked;
+}
+/**
+ * Get the full server state (useful for debugging/config resource).
+ */
+export function getServerState() {
+    return { ...state };
+}
+/**
+ * Set the selected resource ID.
+ */
+export function setSelectedResourceId(resourceId, locked = false) {
+    if (state.isResourceLocked && state.selectedResourceId !== resourceId) {
+        throw new Error(`Cannot change resource: current selection is locked to "${state.selectedResourceId}"`);
+    }
+    state.selectedResourceId = resourceId;
+    state.isResourceLocked = locked;
+}
+/**
+ * Clear the selected resource (only if not locked).
+ */
+export function clearSelectedResource() {
+    if (state.isResourceLocked) {
+        throw new Error('Cannot clear resource: selection is locked');
+    }
+    state.selectedResourceId = null;
+}
+/**
+ * Initialize state from environment variables.
+ */
+export function initializeStateFromEnvironment() {
+    const envResourceId = process.env.GCS_PROJECT_ID;
+    if (envResourceId) {
+        state.selectedResourceId = envResourceId;
+        state.isResourceLocked = true;
+    }
+}
+/**
+ * Reset all state (useful for testing).
+ */
+export function resetState() {
+    state = {
+        selectedResourceId: null,
+        isResourceLocked: false,
+    };
+}

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

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { GCSClientFactory } from '../server.js';
+export declare const CopyObjectSchema: z.ZodObject<{
+    sourceBucket: z.ZodString;
+    sourceKey: z.ZodString;
+    destBucket: z.ZodString;
+    destKey: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    sourceBucket: string;
+    sourceKey: string;
+    destBucket: string;
+    destKey: string;
+}, {
+    sourceBucket: string;
+    sourceKey: string;
+    destBucket: string;
+    destKey: string;
+}>;
+export declare function copyObjectTool(_server: Server, clientFactory: GCSClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            sourceBucket: {
+                type: string;
+                description: "The source bucket name (e.g., \"source-bucket\")";
+            };
+            sourceKey: {
+                type: string;
+                description: "The source object key (e.g., \"path/to/source-file.txt\")";
+            };
+            destBucket: {
+                type: string;
+                description: "The destination bucket name (e.g., \"dest-bucket\")";
+            };
+            destKey: {
+                type: string;
+                description: "The destination object key (e.g., \"path/to/dest-file.txt\")";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=copy-object.d.ts.map