@google-cloud/cloud-run-mcp 1.9.0 → 1.11.0

package/lib/util/helpers.js

@@ -14,6 +14,11 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+import { getProjectsClient } from '../clients.js';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
 /**
  * Helper function to log a message and call the progress callback.
  * @param {string} message - The message to log.
@@ -52,3 +57,107 @@ export function extractAccessToken(authorizationHeader) {
   }
   return authorizationHeader.split(' ')[1];
 }
+
+/**
+ * Gets the project number for a given project ID.
+ * @param {string} projectId - The Google Cloud project ID.
+ * @param {string} accessToken - Access token for authentication.
+ * @returns {Promise<string>} The project number.
+ */
+export async function getProjectNumber(projectId, accessToken) {
+  const projectsClient = await getProjectsClient(accessToken);
+  const [project] = await projectsClient.getProject({
+    name: `projects/${projectId}`,
+  });
+  // project.name is in the format "projects/123456"
+  const parts = project.name.split('/');
+  return parts.length > 1 ? parts[1] : project.projectNumber;
+}
+
+/**
+ * Calculates a SHA256 fingerprint of a directory.
+ * Matches the logic in gcloud run compose builder.py.
+ * @param {string} dirPath - The directory to fingerprint.
+ * @returns {Promise<string>} The SHA256 hex digest.
+ */
+export async function calculateSourceFingerprint(dirPath) {
+  const hash = crypto.createHash('sha256');
+
+  // Helper for recursive walk matching Python's deterministic order
+  async function walk(currentDir) {
+    const entries = await fs.promises.readdir(currentDir, {
+      withFileTypes: true,
+    });
+
+    // Sort entries to match deterministic order (dirs and files sorted)
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+
+    // Handle files first (matching filenames.sort() in builder.py's walk)
+    for (const entry of entries) {
+      if (entry.isFile()) {
+        const filePath = path.join(currentDir, entry.name);
+        const relPath = path.relative(dirPath, filePath);
+
+        // Update hash with relative path
+        hash.update(relPath);
+
+        // Update hash with file content
+        const content = await fs.promises.readFile(filePath);
+        hash.update(content);
+      }
+    }
+
+    // Then recurse into directories
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        await walk(path.join(currentDir, entry.name));
+      }
+    }
+  }
+
+  await walk(dirPath);
+  return hash.digest('hex');
+}
+
+/**
+ * Sanitizes a string for use as a Cloud Run service name.
+ * Only lowercase, digits, and hyphens are allowed.
+ * Must begin with a letter and cannot end with a hyphen.
+ * @param {string} name - The name to sanitize.
+ * @returns {string} The sanitized name.
+ */
+export function sanitizeCloudRunServiceName(name) {
+  let sanitized = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-') // Replace non-alphanumeric with hyphen
+    .replace(/^-+|-+$/g, ''); // Remove leading/trailing hyphens
+
+  // Ensure it starts with a letter if possible
+  if (sanitized.length > 0 && !/^[a-z]/.test(sanitized)) {
+    sanitized = 's-' + sanitized;
+  }
+
+  // Cap at 49 characters (Cloud Run limit is usually 50-63 depending on API, 49 is safe)
+  return sanitized.slice(0, 49).replace(/-$/, '');
+}
+
+/**
+ * Sanitizes a string to be a valid GCP label value.
+ * Label values must be:
+ * - <= 63 characters.
+ * - Contain only lowercase letters, numbers, underscores, and dashes.
+ * @param {string} value - The string to sanitize.
+ * @returns {string} A valid GCP label value string.
+ */
+export function sanitizeLabelValue(value) {
+  if (value === undefined || value === null) {
+    return '';
+  }
+  const stringValue = String(value);
+  if (stringValue === '') {
+    return '';
+  }
+  let sanitized = stringValue.toLowerCase();
+  sanitized = sanitized.replace(/[^a-z0-9_-]/g, '-');
+  return sanitized.slice(0, 63);
+}

package/mcp-server.js

@@ -69,6 +69,8 @@ const envProjectId = process.env.GOOGLE_CLOUD_PROJECT || undefined;
 const envRegion = process.env.GOOGLE_CLOUD_REGION;
 const defaultServiceName = process.env.DEFAULT_SERVICE_NAME;
 const skipIamCheck = process.env.SKIP_IAM_CHECK !== 'false';
+// Values for RUN_INGRESS_POLICY could be: "INGRESS_TRAFFIC_ALL", "INGRESS_TRAFFIC_INTERNAL_ONLY", "INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER"
+const ingress = process.env.RUN_INGRESS_POLICY || undefined;
 const enableHostValidation = process.env.ENABLE_HOST_VALIDATION === 'true';
 const allowedHosts = process.env.ALLOWED_HOSTS
   ? process.env.ALLOWED_HOSTS.split(',')
@@ -107,6 +109,7 @@ async function getServer(accessToken = GCLOUD_AUTH) {
       defaultRegion: effectiveRegion,
       defaultServiceName,
       skipIamCheck,
+      ingress,
       gcpCredentialsAvailable,
       accessToken,
     });
@@ -120,6 +123,7 @@ async function getServer(accessToken = GCLOUD_AUTH) {
       defaultRegion: effectiveRegion,
       defaultServiceName,
       skipIamCheck,
+      ingress,
       gcpCredentialsAvailable,
       accessToken,
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@google-cloud/cloud-run-mcp",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "type": "module",
   "description": "Cloud Run MCP deployment tool",
   "main": "mcp-server.js",
@@ -40,19 +40,22 @@
   },
   "homepage": "https://github.com/GoogleCloudPlatform/cloud-run-mcp#readme",
   "dependencies": {
+    "@dotenvx/dotenvx": "^1.52.0",
     "@google-cloud/artifact-registry": "^4.0.1",
     "@google-cloud/billing": "^5.0.1",
     "@google-cloud/cloudbuild": "^5.0.1",
     "@google-cloud/logging": "^11.2.0",
     "@google-cloud/resource-manager": "^6.0.1",
     "@google-cloud/run": "^3.1.0",
+    "@google-cloud/secret-manager": "^6.1.1",
     "@google-cloud/service-usage": "^4.1.0",
     "@google-cloud/storage": "^7.16.0",
     "@modelcontextprotocol/sdk": "^1.24.3",
-    "archiver": "^7.0.1",
-    "@dotenvx/dotenvx": "^1.52.0",
+    "archiver": "^8.0.0",
     "express": "^5.1.0",
     "google-proto-files": "^5.0.0",
+    "googleapis": "^171.4.0",
+    "js-yaml": "^4.1.1",
     "zod": "^3.25.76"
   },
   "devDependencies": {

package/skills/cloud-run/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: cloud-run
+description: 'Manage Cloud Run services and jobs.'
+metadata:
+  version: 0.1.0
+  openclaw:
+    category: 'compute'
+    requires:
+      bins:
+        - gcloud
+    cliHelp: 'gcloud run --help'
+---
+
+# run (v1)
+
+> **PREREQUISITE:** Ensure you have the `gcloud` CLI installed and authenticated with `gcloud auth login`. Set your project with `gcloud config set project [PROJECT_ID]`.
+
+```bash
+gcloud run <resource> <method> [flags]
+```
+
+## Helper Commands
+
+| Command  | Description                                  |
+| -------- | -------------------------------------------- |
+| `deploy` | Create or update a Cloud Run service or job. |
+
+## API Resources
+
+### services
+
+- `list` — List available services in the specified region.
+- `describe` — Obtain details about a given service, such as its URL and configuration.
+- `update` — Update Cloud Run environment variables, concurrency settings, and other configuration.
+- `delete` — Delete a service and its associated revisions.
+- `update-traffic` — Adjust the traffic assignments for a Cloud Run service.
+- `proxy` — Proxy a service to localhost authenticating as the active account.
+- `logs read` — Read logs for a Cloud Run service.
+- `replace` - Create or replace a service from a YAML service specification.
+- `add-iam-policy-binding` — Add IAM policy binding to a Cloud Run service (e.g., to make it public).
+- `remove-iam-policy-binding` - Remove IAM policy binding of a Cloud Run service.
+- `get-iam-policy` - Get the IAM policy for a Cloud Run service.
+- `set-iam-policy` - Set the IAM policy for a Cloud Run service.
+
+### jobs
+
+- `create` — Create a Cloud Run job.
+- `execute` — Start an execution of a Cloud Run job.
+- `list` — List available jobs.
+- `describe` — Obtain details about a given job.
+- `deploy` - Create or update a Cloud Run job
+- `update` — Update a Cloud Run job configuration.
+- `delete` — Delete a Cloud Run job.
+- `replace` - Create or replace a Cloud Run job from a YAML job specification.
+- `executions list` — List executions of a Cloud Run job.
+- `logs read` — Read logs for a Cloud Run job.
+- `add-iam-policy-binding` — Add IAM policy binding to a Cloud Run job.
+- `remove-iam-policy-binding` - Remove IAM policy binding of a Cloud Run job.
+- `get-iam-policy` - Get the IAM policy for a Cloud Run job.
+- `set-iam-policy` - Set the IAM policy for a Cloud Run job.
+
+### domain-mappings
+
+- `list` — List domain mappings.
+- `create` — Create a new domain mapping.
+- `describe` — Obtain details about a domain mapping.
+- `delete` — Delete a domain mapping.
+
+### multi-region-services
+
+- `list` — List multi-region services.
+- `describe` — Obtain details about a multi-region service.
+- `update` — Update settings for multi-region services.
+- `delete` — Delete a multi-region service.
+- `replace` - Create or Update multi-region service from YAML specification.
+
+### revisions
+
+- `list` — List available revisions for a service.
+- `describe` — Obtain details about a specific revision.
+- `delete` — Delete a specific revision.
+
+### regions
+
+- `list` — View available Cloud Run (fully managed) regions.
+
+### compose
+
+- `up` — Deploy to Cloud Run from a compose specification.
+
+## Discovering Commands
+
+Before calling any command, inspect it for help:
+
+```bash
+# Browse resources and methods
+gcloud run --help
+
+# Inspect a specific resource methods
+gcloud run services --help
+
+# Inspect a specific resource's sub-group methods
+gcloud run jobs executions --help
+
+# Inspect a method's specific flags and arguments
+gcloud run deploy --help
+```
+
+Use the output of `--help` to discover available flags like `--image`, `--env-vars`, `--memory`, etc.

package/test/local/archive.test.js

@@ -0,0 +1,88 @@
+/*
+Copyright 2025 Google LLC
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { zipFiles } from '../../lib/util/archive.js';
+
+describe('Archive Utility (zipFiles)', () => {
+  let tempDir;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'archive-test-'));
+  });
+
+  afterEach(() => {
+    if (tempDir && fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  test('creates a valid zip archive in memory from buffer objects', async () => {
+    const files = [
+      { filename: 'file1.txt', content: 'Hello World' },
+      { filename: 'file2.json', content: JSON.stringify({ key: 'value' }) },
+    ];
+
+    const zipBuffer = await zipFiles(files, false);
+    assert.ok(Buffer.isBuffer(zipBuffer));
+    assert.ok(zipBuffer.length > 0);
+  });
+
+  test('creates a valid tar.gz archive in memory from buffer objects', async () => {
+    const files = [{ filename: 'file1.txt', content: 'Hello World Tar' }];
+
+    const tarBuffer = await zipFiles(files, true);
+    assert.ok(Buffer.isBuffer(tarBuffer));
+    assert.ok(tarBuffer.length > 0);
+  });
+
+  test('creates archive from actual file paths on disk', async () => {
+    const testFilePath = path.join(tempDir, 'sample.txt');
+    fs.writeFileSync(testFilePath, 'Sample file content');
+
+    const zipBuffer = await zipFiles([testFilePath], false);
+    assert.ok(Buffer.isBuffer(zipBuffer));
+    assert.ok(zipBuffer.length > 0);
+  });
+
+  test('creates archive from directory path on disk', async () => {
+    const subDir = path.join(tempDir, 'subdir');
+    fs.mkdirSync(subDir);
+    fs.writeFileSync(path.join(subDir, 'nested.txt'), 'Nested content');
+
+    const zipBuffer = await zipFiles([subDir], false);
+    assert.ok(Buffer.isBuffer(zipBuffer));
+    assert.ok(zipBuffer.length > 0);
+  });
+
+  test('throws error if file path does not exist', async () => {
+    const nonExistentPath = path.join(tempDir, 'does-not-exist.txt');
+    await assert.rejects(
+      async () => {
+        await zipFiles([nonExistentPath], false);
+      },
+      {
+        message: new RegExp(
+          `File or directory not found: ${nonExistentPath.replace(/\\/g, '\\\\')}`
+        ),
+      }
+    );
+  });
+});

package/test/local/clients.test.js

@@ -1,6 +1,14 @@
-import { test, describe } from 'node:test';
+import { test, describe, mock, beforeEach } from 'node:test';
 import assert from 'node:assert';
-import { getClient } from '../../lib/clients.js';
+import { google } from 'googleapis';
+import {
+  clients,
+  getClient,
+  getRunV1Client,
+  getCloudRunRegions,
+  resetCachedRegions,
+} from '../../lib/clients.js';
+import { GCLOUD_AUTH } from '../../constants.js';
 
 describe('getClient Helper', () => {
   class MockClient {
@@ -174,3 +182,217 @@ describe('getClient Helper', () => {
     assert.strictEqual(client.options.extraOpt, extraOpt);
   });
 });
+
+describe('getRunV1Client', () => {
+  test('creates new client instance with Application Default Credentials for GCLOUD_AUTH', async () => {
+    // Mock the GoogleAuth class to avoid looking up ADC
+    const originalGoogleAuth = google.auth.GoogleAuth;
+    const authInstances = [];
+    google.auth.GoogleAuth = class MockGoogleAuth {
+      constructor(options) {
+        this.options = options;
+        authInstances.push(this);
+      }
+    };
+
+    const runMock = mock.method(google, 'run', (options) => {
+      return { options };
+    });
+
+    try {
+      const projectId = 'test-project';
+      const client = await getRunV1Client(projectId, GCLOUD_AUTH);
+
+      assert.ok(client);
+      assert.strictEqual(authInstances.length, 1);
+      assert.deepEqual(authInstances[0].options.scopes, [
+        'https://www.googleapis.com/auth/cloud-platform',
+      ]);
+      assert.strictEqual(runMock.mock.calls.length, 1);
+      assert.strictEqual(
+        runMock.mock.calls[0].arguments[0].auth,
+        authInstances[0]
+      );
+    } finally {
+      google.auth.GoogleAuth = originalGoogleAuth;
+      runMock.mock.restore();
+    }
+  });
+
+  test('creates new client instance with OAuth client when access token provided', async () => {
+    const runMock = mock.method(google, 'run', (options) => ({ options }));
+    try {
+      const projectId = 'test-project-oauth';
+      const accessToken = 'fake-access-token';
+      const client = await getRunV1Client(projectId, accessToken);
+
+      assert.ok(client);
+      assert.strictEqual(runMock.mock.calls.length, 1);
+      const lastCall = runMock.mock.calls[0];
+      assert.ok(lastCall.arguments[0].auth);
+      assert.strictEqual(
+        lastCall.arguments[0].auth.credentials.access_token,
+        accessToken
+      );
+    } finally {
+      runMock.mock.restore();
+    }
+  });
+
+  test('sets rootUrl if region is provided', async () => {
+    const originalGoogleAuth = google.auth.GoogleAuth;
+    google.auth.GoogleAuth = class MockGoogleAuth {
+      constructor(options) {
+        this.options = options;
+      }
+    };
+
+    const runMock = mock.method(google, 'run', (options) => ({ options }));
+
+    const projectId = 'test-project-region';
+    const region = 'us-central1';
+    const key = projectId; // If GCLOUD_AUTH, key is just projectId
+
+    // Mock getCloudRunRegions call by injecting into clients.run
+    clients.run.set(key, {
+      async *listLocationsAsync() {
+        yield { locationId: 'us-central1' };
+      },
+    });
+
+    try {
+      await getRunV1Client(projectId, GCLOUD_AUTH, region);
+
+      const lastCall = runMock.mock.calls[0];
+      assert.strictEqual(
+        lastCall.arguments[0].rootUrl,
+        'https://us-central1-run.googleapis.com/'
+      );
+    } finally {
+      google.auth.GoogleAuth = originalGoogleAuth;
+      runMock.mock.restore();
+      clients.run.delete(key);
+    }
+  });
+
+  test('caches client instances by key', async () => {
+    const runMock = mock.method(google, 'run', (options) => ({ options }));
+    try {
+      const projectId = 'test-project-cache';
+      const client1 = await getRunV1Client(projectId, GCLOUD_AUTH);
+      const client2 = await getRunV1Client(projectId, GCLOUD_AUTH);
+
+      assert.strictEqual(client1, client2);
+      assert.strictEqual(runMock.mock.calls.length, 1);
+    } finally {
+      runMock.mock.restore();
+    }
+  });
+
+  test('caches client instances separately for different regions', async () => {
+    resetCachedRegions();
+    const runMock = mock.method(google, 'run', (options) => ({ options }));
+    try {
+      const projectId = 'test-project-region-cache';
+      const region1 = 'us-central1';
+      const region2 = 'europe-west1';
+
+      // Mock getCloudRunRegions for both regions
+      const key = projectId; // GCLOUD_AUTH key for getRunClient/getCloudRunRegions
+      clients.run.set(key, {
+        async *listLocationsAsync() {
+          yield { locationId: region1 };
+          yield { locationId: region2 };
+        },
+      });
+
+      const client1 = await getRunV1Client(projectId, GCLOUD_AUTH, region1);
+      const client2 = await getRunV1Client(projectId, GCLOUD_AUTH, region2);
+
+      assert.notStrictEqual(client1, client2);
+      assert.strictEqual(runMock.mock.calls.length, 2);
+      assert.strictEqual(
+        runMock.mock.calls[0].arguments[0].rootUrl,
+        `https://${region1}-run.googleapis.com/`
+      );
+      assert.strictEqual(
+        runMock.mock.calls[1].arguments[0].rootUrl,
+        `https://${region2}-run.googleapis.com/`
+      );
+    } finally {
+      runMock.mock.restore();
+      clients.run.clear();
+    }
+  });
+});
+
+describe('getCloudRunRegions', () => {
+  beforeEach(() => {
+    resetCachedRegions();
+    // Clear the run map to ensure isolation between tests
+    clients.run.clear();
+  });
+
+  test('returns list of regions using a mock injected into the clients cache', async () => {
+    const projectId = 'test-project-1';
+    const accessToken = 'token-1';
+    // Match the key generation logic
+    const key = projectId + accessToken;
+
+    const mockRunClient = {
+      async *listLocationsAsync() {
+        yield { locationId: 'us-central1' };
+        yield { locationId: 'europe-west1' };
+      },
+    };
+
+    clients.run.set(key, mockRunClient);
+
+    const regions = await getCloudRunRegions(projectId, accessToken);
+    assert.deepStrictEqual(regions, ['us-central1', 'europe-west1']);
+  });
+
+  test('caches the regions after first call', async () => {
+    const projectId = 'test-project-2';
+    const accessToken = 'token-2';
+    const key = projectId + accessToken;
+
+    let callCount = 0;
+    const mockRunClient = {
+      async *listLocationsAsync() {
+        callCount++;
+        yield { locationId: 'us-central1' };
+      },
+    };
+
+    clients.run.set(key, mockRunClient);
+
+    await getCloudRunRegions(projectId, accessToken);
+    const regions = await getCloudRunRegions(projectId, accessToken);
+
+    assert.strictEqual(callCount, 1);
+    assert.deepStrictEqual(regions, ['us-central1']);
+  });
+
+  test('using different accessToken allows isolated client mocks', async () => {
+    const projectId = 'test-project-3';
+
+    clients.run.set(projectId + 'token-a', {
+      async *listLocationsAsync() {
+        yield { locationId: 'region-a' };
+      },
+    });
+    clients.run.set(projectId + 'token-b', {
+      async *listLocationsAsync() {
+        yield { locationId: 'region-b' };
+      },
+    });
+
+    const resA = await getCloudRunRegions(projectId, 'token-a');
+    resetCachedRegions();
+    const resB = await getCloudRunRegions(projectId, 'token-b');
+
+    assert.deepStrictEqual(resA, ['region-a']);
+    assert.deepStrictEqual(resB, ['region-b']);
+  });
+});