gcs-google-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,241 @@
+# GCS MCP Server
+
+> **Note**: This package is part of the [MCP Servers](https://github.com/pulsemcp/mcp-servers) monorepo. For the latest updates and full source code, visit the [GCS MCP Server directory](https://github.com/pulsemcp/mcp-servers/tree/main/experimental/gcs).
+
+
+MCP server for Google Cloud Storage operations with fine-grained tool access control. Supports read/write operations on GCS buckets and objects, with configurable tool groups for security and permission management.
+
+## Highlights
+
+- Full GCS bucket and object management (list, get, put, copy, delete)
+- Fine-grained access control with tool groups (readonly, readwrite)
+- Individual tool enable/disable via environment variables
+- Multiple authentication methods (service account key file, inline JSON, ADC)
+- GCS credential validation with health checks
+- Single bucket constraint mode
+- TypeScript with strict type checking
+- Comprehensive testing (functional, integration, manual)
+
+## Capabilities
+
+### 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                          |
+| `delete_object` | readwrite | Delete an object from a bucket                      |
+| `copy_object`   | readwrite | Copy an object within or across buckets             |
+| `create_bucket` | readwrite | Create a new GCS bucket                             |
+| `delete_bucket` | readwrite | Delete an empty GCS bucket                          |
+
+### Resources
+
+| Resource       | Description                                     |
+| -------------- | ----------------------------------------------- |
+| `gcs://config` | Server configuration and status (for debugging) |
+
+### Tool Groups
+
+Control which tools are available via the `GCS_ENABLED_TOOLGROUPS` environment variable:
+
+| Group       | Description                                  |
+| ----------- | -------------------------------------------- |
+| `readonly`  | Read-only operations (list, get, head)       |
+| `readwrite` | Write operations (put, delete, copy, create) |
+
+**Examples:**
+
+- `GCS_ENABLED_TOOLGROUPS="readonly"` - Only read operations
+- `GCS_ENABLED_TOOLGROUPS="readonly,readwrite"` - All operations
+- Not set - All tools enabled (default)
+
+### Individual Tool Control
+
+Fine-grained control over specific tools:
+
+- `GCS_ENABLED_TOOLS="list_buckets,get_object"` - Only enable these tools
+- `GCS_DISABLED_TOOLS="delete_bucket,delete_object"` - Disable these tools
+
+### Single Bucket Mode
+
+Constrain all operations to a specific bucket using `GCS_BUCKET`:
+
+```bash
+GCS_BUCKET="my-bucket"
+```
+
+When set:
+
+- All object operations are automatically scoped to this bucket
+- Bucket-level tools (`list_buckets`, `create_bucket`, `delete_bucket`, `head_bucket`) are hidden
+- The `bucket` parameter is automatically injected and hidden from tool inputs
+- For `copy_object`, both source and destination are constrained to the specified bucket
+
+This is useful for restricting access to a single bucket without giving broader GCS permissions.
+
+## Quick Start
+
+### Configuration
+
+#### Environment Variables
+
+| Variable                       | Required | Description                                | Default     |
+| ------------------------------ | -------- | ------------------------------------------ | ----------- |
+| `GCS_PROJECT_ID`               | Yes      | Google Cloud project ID                    | -           |
+| `GCS_SERVICE_ACCOUNT_KEY_FILE` | No       | Path to service account key JSON file      | -           |
+| `GCS_SERVICE_ACCOUNT_KEY_JSON` | No       | Service account key JSON contents (inline) | -           |
+| `GCS_BUCKET`                   | No       | Constrain operations to single bucket      | -           |
+| `GCS_ENABLED_TOOLGROUPS`       | No       | Comma-separated tool groups                | All enabled |
+| `GCS_ENABLED_TOOLS`            | No       | Specific tools to enable                   | -           |
+| `GCS_DISABLED_TOOLS`           | No       | Specific tools to disable                  | -           |
+| `SKIP_HEALTH_CHECKS`           | No       | Skip credential validation                 | `false`     |
+
+#### Authentication
+
+The server supports three authentication methods (in order of precedence):
+
+1. **Service Account Key File**: Set `GCS_SERVICE_ACCOUNT_KEY_FILE` to the path of a JSON key file
+2. **Inline Service Account Key**: Set `GCS_SERVICE_ACCOUNT_KEY_JSON` with the JSON contents directly
+3. **Application Default Credentials (ADC)**: No additional env vars needed - uses `gcloud auth application-default login`
+
+### Claude Desktop Configuration
+
+If this is your first time using MCP Servers, make sure you have the [Claude Desktop application](https://claude.ai/download) and follow the [official MCP setup instructions](https://modelcontextprotocol.io/quickstart/user).
+
+macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "gcs": {
+      "command": "npx",
+      "args": ["-y", "gcs-google-mcp-server"],
+      "env": {
+        "GCS_PROJECT_ID": "your-project-id",
+        "GCS_SERVICE_ACCOUNT_KEY_FILE": "/path/to/service-account-key.json",
+        "GCS_ENABLED_TOOLGROUPS": "readonly"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop and you should be ready to go!
+
+### Read-Only Mode
+
+For safer exploration, enable only read operations:
+
+```json
+{
+  "env": {
+    "GCS_ENABLED_TOOLGROUPS": "readonly"
+  }
+}
+```
+
+### Using Application Default Credentials
+
+If you have `gcloud` CLI configured locally:
+
+```bash
+gcloud auth application-default login
+```
+
+Then configure without key file:
+
+```json
+{
+  "env": {
+    "GCS_PROJECT_ID": "your-project-id"
+  }
+}
+```
+
+## Development
+
+### Install Dependencies
+
+```bash
+npm run install-all
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Running in Development Mode
+
+```bash
+npm run dev
+```
+
+### Testing
+
+```bash
+# Run functional tests
+npm run test:run
+
+# Run integration tests (full MCP protocol)
+npm run test:integration
+
+# Run manual tests (real GCS - requires .env)
+npm run test:manual:setup  # First time only
+npm run test:manual
+
+# Run all automated tests
+npm run test:all
+```
+
+### Manual Testing Setup
+
+Create a `.env` file in the gcs directory:
+
+```bash
+GCS_PROJECT_ID=your-project-id
+GCS_SERVICE_ACCOUNT_KEY_FILE=/path/to/service-account-key.json
+```
+
+Then run:
+
+```bash
+npm run test:manual
+```
+
+## Project Structure
+
+```
+gcs/
+├── local/                 # Local server implementation
+│   ├── src/
+│   │   ├── index.ts      # Main entry point with env validation
+│   │   └── index.integration-with-mock.ts
+│   └── package.json
+├── shared/               # Shared business logic
+│   ├── src/
+│   │   ├── server.ts     # Server factory with DI
+│   │   ├── tools.ts      # Tool registration with grouping
+│   │   ├── tools/        # Individual tool implementations
+│   │   ├── resources.ts  # Resource implementations
+│   │   ├── gcs-client/   # Google Cloud Storage client wrapper
+│   │   └── logging.ts
+│   └── package.json
+├── tests/                # Test suite
+│   ├── functional/       # Unit tests with mocks
+│   ├── integration/      # MCP protocol tests
+│   ├── manual/          # Real API tests
+│   └── mocks/           # Mock implementations
+└── package.json         # Root workspace config
+```
+
+## License
+
+MIT

package/build/index.integration-with-mock.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * Integration Test Server Entry Point with Mock Client Factory
+ *
+ * This file is used for integration testing with a mocked GCS Client.
+ * It uses the real MCP server but injects a mock client factory.
+ *
+ * Mock data is passed via the GCS_MOCK_DATA environment variable.
+ */
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+// Import from shared module via symlink (created by setup-dev.js)
+import { createMCPServer, createIntegrationMockGCSClient } from '../shared/index.js';
+// Read version from package.json
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+const VERSION = packageJson.version;
+async function main() {
+    const transport = new StdioServerTransport();
+    // Parse mock data from environment variable
+    let mockData = {};
+    if (process.env.GCS_MOCK_DATA) {
+        try {
+            mockData = JSON.parse(process.env.GCS_MOCK_DATA);
+        }
+        catch (e) {
+            console.error('Failed to parse GCS_MOCK_DATA:', e);
+        }
+    }
+    // Create client factory that returns our mock
+    const clientFactory = () => createIntegrationMockGCSClient(mockData);
+    const { server, registerHandlers } = createMCPServer({ version: VERSION });
+    await registerHandlers(server, clientFactory);
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});

package/build/index.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createMCPServer, GoogleCloudStorageClient } from '../shared/index.js';
+import { logServerStart, logError, logWarning, logInfo } from '../shared/logging.js';
+// Read version from package.json
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+const VERSION = packageJson.version;
+// =============================================================================
+// ENVIRONMENT VALIDATION
+// =============================================================================
+function validateEnvironment() {
+    const required = [
+        {
+            name: 'GCS_PROJECT_ID',
+            description: 'Google Cloud project ID',
+            example: 'my-project-id',
+        },
+    ];
+    const optional = [
+        {
+            name: 'GCS_SERVICE_ACCOUNT_KEY_FILE',
+            description: 'Path to service account key JSON file',
+        },
+        {
+            name: 'GCS_SERVICE_ACCOUNT_KEY_JSON',
+            description: 'Service account key JSON contents (inline)',
+        },
+        {
+            name: 'GCS_ENABLED_TOOLGROUPS',
+            description: 'Comma-separated list of tool groups to enable (readonly, readwrite)',
+            defaultValue: 'all groups enabled',
+        },
+        {
+            name: 'GCS_ENABLED_TOOLS',
+            description: 'Comma-separated list of specific tools to enable (overrides groups)',
+        },
+        {
+            name: 'GCS_DISABLED_TOOLS',
+            description: 'Comma-separated list of specific tools to disable',
+        },
+        {
+            name: 'GCS_BUCKET',
+            description: 'Constrain all operations to a single bucket (hides bucket-level tools)',
+        },
+        {
+            name: 'SKIP_HEALTH_CHECKS',
+            description: 'Skip health checks on startup (set to "true" to skip)',
+            defaultValue: 'false',
+        },
+    ];
+    const missing = required.filter(({ name }) => !process.env[name]);
+    if (missing.length > 0) {
+        logError('validateEnvironment', 'Missing required environment variables:');
+        missing.forEach(({ name, description, example }) => {
+            console.error(`  - ${name}: ${description}`);
+            console.error(`    Example: ${example}`);
+        });
+        if (optional.length > 0) {
+            console.error('\nOptional environment variables:');
+            optional.forEach(({ name, description, defaultValue }) => {
+                const defaultStr = defaultValue ? ` (default: ${defaultValue})` : '';
+                console.error(`  - ${name}: ${description}${defaultStr}`);
+            });
+        }
+        console.error('\n----------------------------------------');
+        console.error('Please set the required environment variables and try again.');
+        console.error('\nAuthentication options:');
+        console.error('  1. Set GCS_SERVICE_ACCOUNT_KEY_FILE to a service account key file path');
+        console.error('  2. Set GCS_SERVICE_ACCOUNT_KEY_JSON with inline JSON credentials');
+        console.error('  3. Use Application Default Credentials (gcloud auth application-default login)');
+        console.error('----------------------------------------\n');
+        process.exit(1);
+    }
+    // Log warnings for common configuration issues
+    if (process.env.GCS_ENABLED_TOOLGROUPS) {
+        logWarning('config', `Tool groups filter active: ${process.env.GCS_ENABLED_TOOLGROUPS}`);
+    }
+    if (process.env.GCS_ENABLED_TOOLS) {
+        logWarning('config', `Enabled tools filter active: ${process.env.GCS_ENABLED_TOOLS}`);
+    }
+    if (process.env.GCS_DISABLED_TOOLS) {
+        logWarning('config', `Disabled tools filter active: ${process.env.GCS_DISABLED_TOOLS}`);
+    }
+    if (process.env.GCS_BUCKET) {
+        logInfo('config', `Bucket constraint active: ${process.env.GCS_BUCKET}`);
+    }
+}
+// =============================================================================
+// HEALTH CHECKS
+// =============================================================================
+async function performHealthChecks() {
+    if (process.env.SKIP_HEALTH_CHECKS === 'true') {
+        logWarning('healthcheck', 'Health checks skipped (SKIP_HEALTH_CHECKS=true)');
+        return;
+    }
+    try {
+        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;
+        const constrainedBucket = process.env.GCS_BUCKET;
+        const client = new GoogleCloudStorageClient({
+            projectId,
+            keyFilePath,
+            keyFileContents,
+        });
+        // Try to list buckets to validate credentials
+        await client.listBuckets();
+        logInfo('healthcheck', 'GCS credentials validated successfully');
+        // If GCS_BUCKET is set, verify it exists and is accessible
+        if (constrainedBucket) {
+            const bucketExists = await client.headBucket(constrainedBucket);
+            if (!bucketExists) {
+                logError('healthcheck', `Constrained bucket "${constrainedBucket}" does not exist or is not accessible`);
+                process.exit(1);
+            }
+            logInfo('healthcheck', `Constrained bucket "${constrainedBucket}" verified`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logError('healthcheck', `Failed to validate GCS credentials: ${message}`);
+        logError('healthcheck', 'Please check your GCS_PROJECT_ID and authentication configuration');
+        process.exit(1);
+    }
+}
+// =============================================================================
+// MAIN ENTRY POINT
+// =============================================================================
+async function main() {
+    // Step 1: Validate environment variables
+    validateEnvironment();
+    // Step 2: Perform health checks (validates credentials, connectivity)
+    await performHealthChecks();
+    // Step 3: Create server using factory
+    const { server, registerHandlers } = createMCPServer({ version: VERSION });
+    // Step 4: Register all handlers (resources and tools)
+    await registerHandlers(server);
+    // Step 5: Start server with stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logServerStart('gcs-mcp-server');
+}
+// Run the server
+main().catch((error) => {
+    logError('main', error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "gcs-google-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for Google Cloud Storage operations with fine-grained tool access control",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "gcs-mcp-server": "./build/index.js"
+  },
+  "files": [
+    "build/**/*.js",
+    "build/**/*.d.ts",
+    "shared/**/*.js",
+    "shared/**/*.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && npm run build:integration",
+    "build:integration": "tsc -p tsconfig.integration.json",
+    "start": "node build/index.js",
+    "dev": "tsx src/index.ts",
+    "predev": "cd ../shared && npm run build && cd ../local && node setup-dev.js",
+    "prebuild": "cd ../shared && npm run build && cd ../local && node setup-dev.js",
+    "prepublishOnly": "node prepare-publish.js && node ../scripts/prepare-npm-readme.js",
+    "lint": "eslint . --ext .ts,.tsx",
+    "lint:fix": "eslint . --ext .ts,.tsx --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "stage-publish": "npm version"
+  },
+  "dependencies": {
+    "@google-cloud/storage": "^7.15.0",
+    "@modelcontextprotocol/sdk": "^1.19.1",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.6",
+    "tsx": "^4.19.4",
+    "typescript": "^5.7.3"
+  },
+  "keywords": [
+    "mcp",
+    "gcs",
+    "google-cloud",
+    "google-cloud-storage",
+    "model-context-protocol"
+  ],
+  "author": "PulseMCP",
+  "license": "MIT"
+}

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

@@ -0,0 +1,74 @@
+export interface GCSClientConfig {
+    projectId: string;
+    keyFilePath?: string;
+    keyFileContents?: string;
+}
+export interface ListBucketsResult {
+    buckets: Array<{
+        name: string;
+        creationDate?: Date;
+    }>;
+}
+export interface ListObjectsOptions {
+    prefix?: string;
+    maxResults?: number;
+    pageToken?: string;
+    delimiter?: string;
+}
+export interface ListObjectsResult {
+    objects: Array<{
+        key: string;
+        size?: number;
+        lastModified?: Date;
+        storageClass?: string;
+        etag?: string;
+    }>;
+    commonPrefixes: string[];
+    isTruncated: boolean;
+    nextPageToken?: string;
+}
+export interface GetObjectResult {
+    content: string;
+    contentType?: string;
+    contentLength?: number;
+    lastModified?: Date;
+    etag?: string;
+    metadata?: Record<string, string>;
+}
+export interface PutObjectOptions {
+    contentType?: string;
+    metadata?: Record<string, string>;
+}
+export interface PutObjectResult {
+    etag?: string;
+    generation?: string;
+}
+export interface CopyObjectResult {
+    etag?: string;
+    generation?: string;
+}
+export interface IGCSClient {
+    listBuckets(): Promise<ListBucketsResult>;
+    listObjects(bucket: string, options?: ListObjectsOptions): Promise<ListObjectsResult>;
+    getObject(bucket: string, key: string): Promise<GetObjectResult>;
+    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>;
+    deleteBucket(bucket: string): Promise<void>;
+    headBucket(bucket: string): Promise<boolean>;
+    copyObject(sourceBucket: string, sourceKey: string, destBucket: string, destKey: string): Promise<CopyObjectResult>;
+}
+export declare class GoogleCloudStorageClient implements IGCSClient {
+    private storage;
+    constructor(config: GCSClientConfig);
+    listBuckets(): Promise<ListBucketsResult>;
+    listObjects(bucket: string, options?: ListObjectsOptions): Promise<ListObjectsResult>;
+    getObject(bucket: string, key: string): Promise<GetObjectResult>;
+    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>;
+    deleteBucket(bucket: string): Promise<void>;
+    headBucket(bucket: string): Promise<boolean>;
+    copyObject(sourceBucket: string, sourceKey: string, destBucket: string, destKey: string): Promise<CopyObjectResult>;
+}
+//# sourceMappingURL=gcs-client.d.ts.map

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

@@ -0,0 +1,15 @@
+import type { IGCSClient } from './gcs-client.js';
+export interface MockGCSData {
+    buckets?: Array<{
+        name: string;
+        creationDate?: Date;
+    }>;
+    objects?: Record<string, Record<string, {
+        content: string;
+        contentType?: string;
+        metadata?: Record<string, string>;
+        lastModified?: Date;
+    }>>;
+}
+export declare function createIntegrationMockGCSClient(mockData?: MockGCSData): IGCSClient;
+//# sourceMappingURL=gcs-client.integration-mock.d.ts.map