@google-cloud/cloud-run-mcp 1.6.0 → 1.8.0

package/.github/workflows/npm-publish.yml

@@ -2,7 +2,7 @@ name: Publish to npm
 
 on:
   release:
-    types: [created]
+    types: [published]
 
 jobs:
   publish-npm:

package/CONTRIBUTING.md

@@ -126,7 +126,7 @@ This script requires an existing Google Cloud Project ID to be provided when pro
 
 ## Publishing to npm
 
-To update the [npm package]https://www.npmjs.com/package/@google-cloud/cloud-run-mcp)
+To update the [npm package](https://www.npmjs.com/package/@google-cloud/cloud-run-mcp)
 
 Run the following:
 

package/lib/clients.js

@@ -0,0 +1,222 @@
+/*
+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.
+*/
+
+const AUTHORIZATION_HEADER = 'Authorization';
+const BEARER_PREFIX = 'Bearer';
+const GCLOUD_AUTH = 'gcloud_auth';
+
+function keyGenerator(projectId, accessToken) {
+  return accessToken !== GCLOUD_AUTH ? projectId + accessToken : projectId;
+}
+
+const clients = {
+  run: new Map(),
+  builds: new Map(),
+  serviceUsage: new Map(),
+  storage: new Map(),
+  cloudBuild: new Map(),
+  artifactRegistry: new Map(),
+  logging: new Map(),
+  billing: new Map(),
+  projects: new Map(),
+};
+
+function getAuthClient(accessToken) {
+  return {
+    getRequestHeaders: () => {
+      const headers = new Map();
+      headers.set(AUTHORIZATION_HEADER, `${BEARER_PREFIX} ${accessToken}`);
+      return headers;
+    },
+  };
+}
+
+export async function getClient(
+  service,
+  key,
+  loadClient,
+  options = {},
+  accessToken = null
+) {
+  if (!clients[service].has(key)) {
+    const ClientClass = await loadClient();
+    const finalOptions = { ...options };
+    if (accessToken && accessToken !== GCLOUD_AUTH) {
+      finalOptions.authClient = getAuthClient(accessToken);
+    }
+    clients[service].set(key, new ClientClass(finalOptions));
+  }
+  return clients[service].get(key);
+}
+
+/**
+ * Gets a Cloud Run Services Client for the specified project.
+ * @param {string} projectId - The Google Cloud project ID.
+ * @returns {Promise<import('@google-cloud/run').v2.ServicesClient>}
+ */
+export async function getRunClient(projectId, accessToken = GCLOUD_AUTH) {
+  const key = keyGenerator(projectId, accessToken);
+  return getClient(
+    'run',
+    key,
+    async () => (await import('@google-cloud/run')).v2.ServicesClient,
+    { projectId },
+    accessToken
+  );
+}
+
+/**
+ * Gets a Cloud Run Build Client for the specified project.
+ * @param {string} projectId - The Google Cloud project ID.
+ * @returns {Promise<import('@google-cloud/run').v2.BuildsClient>}
+ */
+export async function getBuildsClient(projectId, accessToken = GCLOUD_AUTH) {
+  const key = keyGenerator(projectId, accessToken);
+  return getClient(
+    'builds',
+    key,
+    async () => (await import('@google-cloud/run')).v2.BuildsClient,
+    { projectId },
+    accessToken
+  );
+}
+
+/**
+ * Gets a Service Usage Client for the specified project.
+ * @param {string} projectId - The Google Cloud project ID.
+ * @returns {Promise<import('@google-cloud/service-usage').ServiceUsageClient>}
+ */
+export async function getServiceUsageClient(
+  projectId,
+  accessToken = GCLOUD_AUTH
+) {
+  const key = keyGenerator(projectId, accessToken);
+  return getClient(
+    'serviceUsage',
+    key,
+    async () =>
+      (await import('@google-cloud/service-usage')).ServiceUsageClient,
+    { projectId },
+    accessToken
+  );
+}
+
+/**
+ * Gets a Storage Client for the specified project.
+ * @param {string} projectId - The Google Cloud project ID.
+ * @returns {Promise<import('@google-cloud/storage').Storage>}
+ */
+export async function getStorageClient(projectId, accessToken = GCLOUD_AUTH) {
+  const key = keyGenerator(projectId, accessToken);
+  return getClient(
+    'storage',
+    key,
+    async () => (await import('@google-cloud/storage')).Storage,
+    { projectId },
+    accessToken
+  );
+}
+
+/**
+ * Gets a Cloud Build Client for the specified project.
+ * @param {string} projectId - The Google Cloud project ID.
+ * @returns {Promise<import('@google-cloud/cloudbuild').CloudBuildClient>}
+ */
+export async function getCloudBuildClient(
+  projectId,
+  accessToken = GCLOUD_AUTH
+) {
+  const key = keyGenerator(projectId, accessToken);
+  return getClient(
+    'cloudBuild',
+    key,
+    async () => (await import('@google-cloud/cloudbuild')).CloudBuildClient,
+    { projectId },
+    accessToken
+  );
+}
+
+/**
+ * Gets an Artifact Registry Client for the specified project.
+ * @param {string} projectId - The Google Cloud project ID.
+ * @returns {Promise<import('@google-cloud/artifact-registry').ArtifactRegistryClient>}
+ */
+export async function getArtifactRegistryClient(
+  projectId,
+  accessToken = GCLOUD_AUTH
+) {
+  const key = keyGenerator(projectId, accessToken);
+  return getClient(
+    'artifactRegistry',
+    key,
+    async () =>
+      (await import('@google-cloud/artifact-registry')).ArtifactRegistryClient,
+    { projectId },
+    accessToken
+  );
+}
+
+/**
+ * Gets a Logging Client for the specified project.
+ * @param {string} projectId - The Google Cloud project ID.
+ * @returns {Promise<import('@google-cloud/logging').Logging>}
+ */
+export async function getLoggingClient(projectId, accessToken = GCLOUD_AUTH) {
+  const key = keyGenerator(projectId, accessToken);
+  return getClient(
+    'logging',
+    key,
+    async () => (await import('@google-cloud/logging')).Logging,
+    { projectId },
+    accessToken
+  );
+}
+
+/**
+ * Gets a Billing Client for the specified project.
+ * Note: BillingClient usually doesn't take projectId in constructor for listing accounts,
+ * but might for project billing info. We will cache by projectId anyway or 'global' if projectId is null.
+ * @param {string} [projectId] - The Google Cloud project ID (optional).
+ * @returns {Promise<import('@google-cloud/billing').CloudBillingClient>}
+ */
+export async function getBillingClient(
+  projectId = 'global',
+  accessToken = GCLOUD_AUTH
+) {
+  const key = keyGenerator(projectId, accessToken);
+  return getClient(
+    'billing',
+    key,
+    async () => (await import('@google-cloud/billing')).CloudBillingClient,
+    projectId !== 'global' ? { projectId } : {},
+    accessToken
+  );
+}
+
+/**
+ * Gets a Projects Client (Resource Manager).
+ * @returns {Promise<import('@google-cloud/resource-manager').ProjectsClient>}
+ */
+export async function getProjectsClient(accessToken = GCLOUD_AUTH) {
+  const key = keyGenerator('global', accessToken);
+  return getClient(
+    'projects',
+    key,
+    async () => (await import('@google-cloud/resource-manager')).ProjectsClient,
+    {},
+    accessToken
+  );
+}

package/lib/cloud-api/billing.js

@@ -14,6 +14,15 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+/**
+ * Lists all accessible Google Cloud Billing Accounts.
+ * @async
+ * @function listBillingAccounts
+ * @returns {Promise<Array<{name: string, displayName: string, open: boolean}>>} A promise that resolves to an array of billing account objects,
+ * each with 'name', 'displayName', and 'open' status. Returns an empty array on error.
+ */
+import { getBillingClient } from '../clients.js';
+
 /**
  * Lists all accessible Google Cloud Billing Accounts.
  * @async
@@ -22,8 +31,7 @@ limitations under the License.
  * each with 'name', 'displayName', and 'open' status. Returns an empty array on error.
  */
 export async function listBillingAccounts() {
-  const { CloudBillingClient } = await import('@google-cloud/billing');
-  const client = new CloudBillingClient();
+  const client = await getBillingClient();
   try {
     const [accounts] = await client.listBillingAccounts();
     if (!accounts || accounts.length === 0) {
@@ -53,8 +61,7 @@ export async function attachProjectToBillingAccount(
   projectId,
   billingAccountName
 ) {
-  const { CloudBillingClient } = await import('@google-cloud/billing');
-  const client = new CloudBillingClient();
+  const client = await getBillingClient();
   const projectName = `projects/${projectId}`;
 
   if (!projectId) {
@@ -96,3 +103,82 @@ export async function attachProjectToBillingAccount(
     return null;
   }
 }
+
+/**
+ * Checks if billing is enabled for a given project.
+ * @async
+ * @function isBillingEnabled
+ * @param {string} projectId - The ID of the project to check.
+ * @returns {Promise<boolean>} A promise that resolves to true if billing is enabled, false otherwise.
+ */
+export async function isBillingEnabled(projectId) {
+  const client = await getBillingClient();
+  const projectName = `projects/${projectId}`;
+  try {
+    // getProjectBillingInfo requires cloudbilling.googleapis.com API to check billing status
+    // https://docs.cloud.google.com/billing/docs/reference/rest/v1/projects/getBillingInfo
+    const [billingInfo] = await client.getProjectBillingInfo({
+      name: projectName,
+    });
+    return billingInfo.billingEnabled;
+  } catch (error) {
+    console.error(
+      `Error checking billing status for project ${projectId}:`,
+      error.message || error
+    );
+    return false;
+  }
+}
+
+/**
+ * Ensures billing is enabled for a project. If not, attempts to enable it
+ * by attaching the single open billing account if one is found.
+ * @param {string} projectId The project ID to check billing for.
+ * @param {function} progressCallback A callback function for progress updates.
+ */
+export async function ensureBillingEnabled(projectId, progressCallback) {
+  if (!(await isBillingEnabled(projectId))) {
+    // Billing is disabled, try to fix it.
+    const accounts = await listBillingAccounts();
+
+    if (accounts && accounts.length === 1 && accounts[0].open) {
+      // Exactly one open account found, try to attach it.
+      const account = accounts[0];
+      const attemptMessage = `Billing is not enabled for project ${projectId}. Found one open billing account: ${account.displayName} (${account.name}). Attempting to attach it...`;
+      console.log(attemptMessage);
+      if (progressCallback)
+        progressCallback({ level: 'info', data: attemptMessage });
+
+      const attachmentResult = await attachProjectToBillingAccount(
+        projectId,
+        account.name
+      );
+
+      if (!attachmentResult || !attachmentResult.billingEnabled) {
+        const attachFailMessage = `Failed to automatically attach project ${projectId} to billing account ${account.name}. Please enable billing manually: https://console.cloud.google.com/billing/linkedaccount?project=${projectId}`;
+        if (progressCallback)
+          progressCallback({ level: 'error', data: attachFailMessage });
+        throw new Error(attachFailMessage);
+      }
+      const attachSuccessMessage = `Successfully attached project ${projectId} to billing account ${account.name}.`;
+      console.log(attachSuccessMessage);
+      if (progressCallback)
+        progressCallback({ level: 'info', data: attachSuccessMessage });
+      // If we get here, billing is now enabled, and we can proceed to API checks.
+    } else {
+      // Cannot auto-attach. Throw error.
+      let reason;
+      if (!accounts || accounts.length === 0) {
+        reason = 'no billing accounts were found';
+      } else if (accounts.length > 1) {
+        reason = 'multiple billing accounts were found';
+      } else {
+        reason = `the only available billing account '${accounts[0].displayName}' is not open`;
+      }
+      const errorMessage = `Billing is not enabled for project ${projectId}, and it could not be enabled automatically because ${reason}. Please enable billing to use Google Cloud services: https://console.cloud.google.com/billing/linkedaccount?project=${projectId}`;
+      if (progressCallback)
+        progressCallback({ level: 'error', data: errorMessage });
+      throw new Error(errorMessage);
+    }
+  }
+}

package/lib/cloud-api/build.js

@@ -14,8 +14,15 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+import {
+  getCloudBuildClient,
+  getLoggingClient,
+  getRunClient,
+  getBuildsClient,
+} from '../clients.js';
 import { callWithRetry } from './helpers.js';
 import { logAndProgress } from '../util/helpers.js';
+import { checkCloudRunServiceExists } from './run.js';
 
 const DELAY_WAIT_FOR_BUILD_LOGS = 10000; // 10 seconds delay to allow logs to propagate
 const BUILD_LOGS_LINES_TO_FETCH = 100; // Number of log lines to fetch for build logs snippet
@@ -23,10 +30,10 @@ const BUILD_LOGS_LINES_TO_FETCH = 100; // Number of log lines to fetch for build
 /**
  * Triggers a Google Cloud Build job to build a container image from source code in a GCS bucket.
  * It uses either a Dockerfile found in the source or Google Cloud Buildpacks if no Dockerfile is present.
+ * It performs a dry-run deployment check before starting the build.
  * Waits for the build to complete and returns the build result.
  *
  * @async
- * @param {object} context - The context object containing clients and other parameters.
  * @param {string} projectId - The Google Cloud project ID.
  * @param {string} location - The Google Cloud region for the build.
  * @param {string} sourceBucketName - The GCS bucket name where the source code (zip) is stored.
@@ -39,7 +46,6 @@ const BUILD_LOGS_LINES_TO_FETCH = 100; // Number of log lines to fetch for build
  * @throws {Error} If the Cloud Build job fails, times out, or encounters an error during initiation or execution.
  */
 export async function triggerCloudBuild(
-  context,
   projectId,
   location,
   sourceBucketName,
@@ -49,65 +55,107 @@ export async function triggerCloudBuild(
   hasDockerfile,
   progressCallback
 ) {
+  const serviceName = targetImageUrl.split('/').pop().split(/[:@]/)[0];
+  const parent = `projects/${projectId}/locations/${location}`;
+  const serviceFullName = `${parent}/services/${serviceName}`;
+  const buildsClient = await getBuildsClient(projectId);
+  const runClient = await getRunClient(projectId);
+  const serviceExists = await checkCloudRunServiceExists(
+    projectId,
+    location,
+    serviceName,
+    progressCallback
+  );
+  const cloudBuildClient = await getCloudBuildClient(projectId);
+  const loggingClient = await getLoggingClient(projectId);
   let buildSteps;
 
-  if (hasDockerfile) {
-    buildSteps = [
-      {
-        name: 'gcr.io/cloud-builders/docker',
-        args: ['build', '-t', targetImageUrl, '.'],
-        dir: '/workspace',
-      },
-    ];
-  } else {
-    buildSteps = [
-      {
-        name: 'gcr.io/k8s-skaffold/pack',
-        entrypoint: 'pack',
-        args: [
-          'build',
-          targetImageUrl,
-          '--builder',
-          'gcr.io/buildpacks/builder:latest',
-        ],
-        dir: '/workspace',
-      },
-    ];
+  const servicePatch = {
+    template: {
+      containers: [{ image: targetImageUrl }],
+    },
+  };
+
+  try {
+    if (serviceExists) {
+      await logAndProgress(
+        `Performing dry-run update for service ${serviceName}...`,
+        progressCallback
+      );
+      servicePatch.name = serviceFullName;
+      await callWithRetry(
+        () =>
+          runClient.updateService({
+            service: servicePatch,
+            validateOnly: true,
+          }),
+        'run.updateService-dryrun'
+      );
+    } else {
+      await logAndProgress(
+        `Performing dry-run creation for service ${serviceName}...`,
+        progressCallback
+      );
+      await callWithRetry(
+        () =>
+          runClient.createService({
+            parent: parent,
+            service: servicePatch,
+            serviceId: serviceName,
+            validateOnly: true,
+          }),
+        'run.createService-dryrun'
+      );
+    }
+    await logAndProgress(
+      `Dry-run validation successful.`,
+      progressCallback,
+      'debug'
+    );
+  } catch (err) {
+    await logAndProgress(
+      `Dry-run validation failed for service ${serviceName}.`,
+      progressCallback,
+      'error'
+    );
+    throw new Error(`Dry-run deployment failed: ${err.message}`);
   }
 
-  const build = {
-    source: {
-      storageSource: {
-        bucket: sourceBucketName,
-        object: sourceBlobName,
-      },
+  const request = {
+    parent: `projects/${projectId}/locations/${location}`,
+    storageSource: {
+      bucket: sourceBucketName,
+      object: sourceBlobName,
     },
-    steps: buildSteps,
-    images: [targetImageUrl],
+    imageUri: targetImageUrl,
+    client: 'cloud-run-mcp',
   };
+  if (hasDockerfile) {
+    request.dockerBuild = {};
+  } else {
+    request.buildpackBuild = {};
+  }
 
   await logAndProgress(
     `Initiating Cloud Build for gs://${sourceBucketName}/${sourceBlobName} in ${location}...`,
     progressCallback
   );
-  const [operation] = await callWithRetry(
-    () =>
-      context.cloudBuildClient.createBuild({
-        projectId: projectId,
-        build: build,
-      }),
-    'cloudBuild.createBuild'
-  );
 
+  const [submitBuildResponse] = await callWithRetry(
+    () => buildsClient.submitBuild(request),
+    'builds.submitBuild'
+  );
   await logAndProgress(`Cloud Build job started...`, progressCallback);
-  const buildId = operation.metadata.build.id;
+  const encodedBuildId = submitBuildResponse.buildOperation.name
+    .split('/')
+    .pop();
+  const buildId = Buffer.from(encodedBuildId, 'base64').toString('ascii');
   let completedBuild;
   while (true) {
     const [getBuildOperation] = await callWithRetry(
       () =>
-        context.cloudBuildClient.getBuild({
-          projectId: projectId,
-          id: buildId,
+        cloudBuildClient.getBuild({
+          name: `projects/${projectId}/locations/${location}/builds/${buildId}`,
         }),
       `cloudBuild.getBuild ${buildId}`
     );
@@ -132,10 +180,9 @@ export async function triggerCloudBuild(
       `Cloud Build job ${buildId} completed successfully.`,
       progressCallback
     );
-    await logAndProgress(
-      `Image built: ${completedBuild.results.images[0].name}`,
-      progressCallback
-    );
+    const builtImage = completedBuild.results.images[0].name;
+    await logAndProgress(`Image built: ${builtImage}`, progressCallback);
+
     return completedBuild;
   } else {
     const failureMessage = `Cloud Build job ${buildId} failed with status: ${completedBuild.status}`;
@@ -160,7 +207,7 @@ export async function triggerCloudBuild(
       // Fetch the most recent N log entries
       const [entries] = await callWithRetry(
         () =>
-          context.loggingClient.getEntries({
+          loggingClient.getEntries({
             filter: logFilter,
             orderBy: 'timestamp desc', // Get latest logs first
             pageSize: BUILD_LOGS_LINES_TO_FETCH,

package/lib/cloud-api/helpers.js

@@ -14,6 +14,14 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+import { getServiceUsageClient } from '../clients.js';
+import { ensureBillingEnabled } from './billing.js';
+
+const PREREQUISITE_APIS = [
+  'serviceusage.googleapis.com',
+  'cloudbilling.googleapis.com',
+];
+
 /**
  * Calls a function with retry logic for GCP API calls.
  * Retries on gRPC error code 7 (PERMISSION_DENIED).
@@ -84,13 +92,55 @@ async function checkAndEnableApi(
   }
 }
 
+/**
+ * Enables a single Google Cloud API with retry logic.
+ * @param {string} projectId - The Google Cloud project ID.
+ * @param {string} api - The API identifier (e.g., 'run.googleapis.com').
+ * @param {function(string, string=): void} progressCallback - A function to call with progress updates.
+ * @returns {Promise<void>} A promise that resolves when the API is enabled.
+ * @throws {Error} If the API fails to enable or if there's an issue checking its status.
+ */
+export async function enableApiWithRetry(projectId, api, progressCallback) {
+  const serviceUsageClient = await getServiceUsageClient(projectId);
+  const serviceName = `projects/${projectId}/services/${api}`;
+  try {
+    await checkAndEnableApi(
+      serviceUsageClient,
+      serviceName,
+      api,
+      progressCallback
+    );
+  } catch (error) {
+    // First attempt failed, log a warning and retry once after a delay.
+    const warnMsg = `Failed to check/enable ${api}, retrying in 1s...`;
+    console.warn(warnMsg);
+    if (progressCallback) progressCallback({ level: 'warn', data: warnMsg });
+
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    try {
+      await checkAndEnableApi(
+        serviceUsageClient,
+        serviceName,
+        api,
+        progressCallback
+      );
+    } catch (retryError) {
+      // If the retry also fails, throw an error.
+      const errorMessage = `Failed to ensure API [${api}] is enabled after retry. Please check manually.`;
+      console.error(errorMessage, retryError);
+      if (progressCallback)
+        progressCallback({ level: 'error', data: errorMessage });
+      throw new Error(errorMessage);
+    }
+  }
+}
+
 /**
  * Ensures that the specified Google Cloud APIs are enabled for the given project.
  * If an API is not enabled, it attempts to enable it.  Retries any failure once after 1s.
  * Throws an error if an API cannot be enabled.
  *
  * @async
- * @param {object} context - The context object containing clients and other parameters.
  * @param {string} projectId - The Google Cloud project ID.
  * @param {string[]} apis - An array of API identifiers to check and enable (e.g., 'run.googleapis.com').
  * @param {function(string, string=): void} progressCallback - A function to call with progress updates.
@@ -98,48 +148,20 @@ async function checkAndEnableApi(
  * @throws {Error} If an API fails to enable or if there's an issue checking its status.
  * @returns {Promise<void>} A promise that resolves when all specified APIs are enabled.
  */
-export async function ensureApisEnabled(
-  context,
-  projectId,
-  apis,
-  progressCallback
-) {
+export async function ensureApisEnabled(projectId, apis, progressCallback) {
+  for (const api of PREREQUISITE_APIS) {
+    await enableApiWithRetry(projectId, api, progressCallback);
+  }
+
+  // Before enabling other APIs, ensure billing is enabled.
+  await ensureBillingEnabled(projectId, progressCallback);
+
   const message = 'Checking and enabling required APIs...';
   console.log(message);
   if (progressCallback) progressCallback({ level: 'info', data: message });
 
   for (const api of apis) {
-    const serviceName = `projects/${projectId}/services/${api}`;
-    try {
-      await checkAndEnableApi(
-        context.serviceUsageClient,
-        serviceName,
-        api,
-        progressCallback
-      );
-    } catch (error) {
-      // First attempt failed, log a warning and retry once after a delay.
-      const warnMsg = `Failed to check/enable ${api}, retrying in 1s...`;
-      console.warn(warnMsg);
-      if (progressCallback) progressCallback({ level: 'warn', data: warnMsg });
-
-      await new Promise((resolve) => setTimeout(resolve, 1000));
-      try {
-        await checkAndEnableApi(
-          context.serviceUsageClient,
-          serviceName,
-          api,
-          progressCallback
-        );
-      } catch (retryError) {
-        // If the retry also fails, throw an error.
-        const errorMessage = `Failed to ensure API [${api}] is enabled after retry. Please check manually.`;
-        console.error(errorMessage, retryError);
-        if (progressCallback)
-          progressCallback({ level: 'error', data: errorMessage });
-        throw new Error(errorMessage);
-      }
-    }
+    await enableApiWithRetry(projectId, api, progressCallback);
   }
   const successMsg = 'All required APIs are enabled.';
   console.log(successMsg);