@google-cloud/cloud-run-mcp 1.0.0 → 1.3.0

package/.github/workflows/local-tests.yml

@@ -0,0 +1,17 @@
+name: Run Local Tests
+
+on:
+  push:
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm test

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

@@ -0,0 +1,23 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      # Now configure with the publish service for install.
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://wombat-dressing-room.appspot.com/
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.NODE_AUTH_TOKEN}}

package/CONTRIBUTING.md

@@ -105,3 +105,17 @@ npm run test:deploy
 ```
 
 This script requires an existing Google Cloud Project ID to be provided when prompted or as a command-line argument.
+
+## Publishing to npm
+
+To update the [npm package]https://www.npmjs.com/package/@google-cloud/cloud-run-mcp)
+
+Run the following:
+
+* `git checkout -b new-release`
+* `npm test`
+* `npm version minor`
+* `git push --follow-tags`
+* On GitHub, [create a new release](https://github.com/GoogleCloudPlatform/cloud-run-mcp/releases/new) for this tag.
+
+Then a [GitHub Action]https://github.com/GoogleCloudPlatform/cloud-run-mcp/blob/main/.github/workflows/npm-publish.yml) automatically publishes to npm when new releases are pushes.

package/README.md

@@ -6,7 +6,7 @@ Enable MCP-compatible AI agents to deploy apps to Cloud Run.
 "mcpServers":{
   "cloud-run": {
     "command": "npx",
-    "args": ["-y", "https://github.com/GoogleCloudPlatform/cloud-run-mcp"]
+    "args": ["-y", "@google-cloud/cloud-run-mcp"]
   }
 }
 ```
@@ -72,7 +72,7 @@ Then configure the MCP server using either Node.js or Docker:
    ```json
       "cloud-run": {
         "command": "npx",
-        "args": ["-y", "https://github.com/GoogleCloudPlatform/cloud-run-mcp"]
+        "args": ["-y", "@google-cloud/cloud-run-mcp"]
       }
    ```
 
@@ -81,7 +81,7 @@ Then configure the MCP server using either Node.js or Docker:
    ```json
       "cloud-run": {
          "command": "npx",
-         "args": ["-y", "https://github.com/GoogleCloudPlatform/cloud-run-mcp"],
+         "args": ["-y", "@google-cloud/cloud-run-mcp"],
          "env": {
                "GOOGLE_CLOUD_PROJECT": "PROJECT_NAME",
                "GOOGLE_CLOUD_REGION": "PROJECT_REGION",
@@ -118,13 +118,14 @@ See Docker's [MCP catalog](https://hub.docker.com/mcp/server/cloud-run-mcp/overv
       }
    ```
 
-## Use as a `gemini-cli` extension
+## Use as a Gemini CLI extension
 
-To install this as a `gemini-cli` extension, run the following command:
+To install this as a [Gemini CLI](https://github.com/google-gemini/gemini-cli) extension, run the following command:
 
 ```bash
-mkdir -p ~/.gemini/extensions/cloud-run && \
-  curl -s -L https://raw.githubusercontent.com/GoogleCloudPlatform/cloud-run-mcp/main/gemini-extension.json > ~/.gemini/extensions/cloud-run/gemini-extension.json
+mkdir -p ~/.gemini/extensions/cloud-run/gemini-extension && \
+  curl -s -L https://raw.githubusercontent.com/GoogleCloudPlatform/cloud-run-mcp/main/gemini-extension.json > ~/.gemini/extensions/cloud-run/gemini-extension.json && \
+  curl -s -L https://raw.githubusercontent.com/GoogleCloudPlatform/cloud-run-mcp/main/gemini-extension/Gemini.md > ~/.gemini/extensions/cloud-run/gemini-extension/Gemini.md
 ```
 
 ## Use as remote MCP server

package/gemini-extension/GEMINI.md

@@ -0,0 +1,57 @@
+# Cloud Run MCP Server
+
+## Code that can be deployed
+
+Only web servers can be deployed using this MCP server.
+The code needs to listen for HTTP reqeusts on the port defined by the $PORT environment variable or 8080.
+
+### Supported languages
+
+- If the code is in Node.js, Python, Go, Java, .NET, PHP, Ruby, a Dockerfile is not needed.
+- If the code is in another language, or has any custom dependency needs, a Dockerfile is needed.
+
+### Static-only apps
+
+To deploy static-only applications, create a Dockerfile that serves these static files. For example using `nginx`:
+
+`Dockerfile`
+
+```
+FROM nginx:stable
+
+COPY ./static /var/www
+COPY ./nginx.conf /etc/nginx/conf.d/default.conf
+
+CMD ["nginx", "-g", "daemon off;"]
+```
+
+`nginx.conf`:
+
+```
+server {
+    listen 8080;
+    server_name _;
+
+    root /var/www/;
+    index index.html;
+
+    # Force all paths to load either itself (js files) or go through index.html.
+    location / {
+        try_files $uri /index.html;
+    }
+}
+```
+
+## Google Cloud pre-requisities
+
+The user must have an existing Google Cloud account with billing set up, and ideally an existing Google Cloud project.
+
+If deployment fails because of an access or IAM error, it is likely that the user doesn't have Google Cloud credentials on the local machine.
+The user mush follow these steps:
+
+1. Install the [Google Cloud SDK](https://cloud.google.com/sdk/docs/install) and authenticate with their Google account.
+
+2. Set up application credentials using the command:
+   ```bash
+   gcloud auth application-default login
+   ```

package/gemini-extension.json

@@ -4,7 +4,8 @@
   "mcpServers": {
     "cloud-run": {
       "command": "npx",
-      "args": ["-y", "https://github.com/GoogleCloudPlatform/cloud-run-mcp"]
+      "args": ["-y", "@google-cloud/cloud-run-mcp"]
     }
-  }
+  },
+  "contextFileName": "gemini-extension/GEMINI.md"
 }

package/lib/cloud-run-deploy.js

@@ -14,6 +14,8 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+import { callWithRetry, ensureApisEnabled } from './gcp-api-helpers.js';
+
 // Configuration
 const REPO_NAME = 'mcp-cloud-run-deployments';
 const ZIP_FILE_NAME = 'source.zip';
@@ -63,50 +65,6 @@ function logAndProgress(message, progressCallback, severity = 'info') {
   }
 }
 
-/**
- * Ensures that the specified Google Cloud APIs are enabled for the given project.
- * If an API is not enabled, it attempts to enable it.
- * Throws an error if an API cannot be enabled.
- *
- * @async
- * @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.
- * The first argument is the message, the optional second argument is the type ('error', 'warning', 'info').
- * @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.
- */
-async function ensureApisEnabled(projectId, apis, progressCallback) {
-  const { ServiceUsageClient } = await import('@google-cloud/service-usage');
-  const serviceUsageClient = new ServiceUsageClient({ projectId });
-  logAndProgress('Checking and enabling required APIs...', progressCallback);
-
-  for (const api of apis) {
-    const serviceName = `projects/${projectId}/services/${api}`;
-    try {
-      const [service] = await serviceUsageClient.getService({
-        name: serviceName,
-      });
-      if (service.state !== 'ENABLED') {
-        logAndProgress(
-          `API [${api}] is not enabled. Enabling...`,
-          progressCallback
-        );
-        const [operation] = await serviceUsageClient.enableService({
-          name: serviceName,
-        });
-        await operation.promise();
-      }
-    } catch (error) {
-      const errorMessage = `Failed to ensure API [${api}] is enabled. Please check manually.`;
-      console.error(errorMessage, error);
-      logAndProgress(errorMessage, progressCallback, 'error');
-      throw new Error(errorMessage);
-    }
-  }
-  logAndProgress('All required APIs are enabled.', progressCallback);
-}
-
 /**
  * Checks if a Cloud Run service already exists.
  *
@@ -127,7 +85,10 @@ async function checkCloudRunServiceExists(
   const parent = runClient.locationPath(projectId, location);
   const servicePath = runClient.servicePath(projectId, location, serviceId);
   try {
-    await runClient.getService({ name: servicePath });
+    await callWithRetry(
+      () => runClient.getService({ name: servicePath }),
+      `getService ${serviceId}`
+    );
     logAndProgress(
       `Cloud Run service ${serviceId} already exists.`,
       progressCallback
@@ -208,17 +169,25 @@ async function deployToCloudRun(
 
       if (exists) {
         dryRunServiceConfig.name = servicePath;
-        await runClient.updateService({
-          service: dryRunServiceConfig,
-          validateOnly: true,
-        });
+        await callWithRetry(
+          () =>
+            runClient.updateService({
+              service: dryRunServiceConfig,
+              validateOnly: true,
+            }),
+          `updateService (dry run) ${serviceId}`
+        );
       } else {
-        await runClient.createService({
-          parent: parent,
-          service: dryRunServiceConfig,
-          serviceId: serviceId,
-          validateOnly: true,
-        });
+        await callWithRetry(
+          () =>
+            runClient.createService({
+              parent: parent,
+              service: dryRunServiceConfig,
+              serviceId: serviceId,
+              validateOnly: true,
+            }),
+          `createService (dry run) ${serviceId}`
+        );
       }
       logAndProgress(
         `Dry run successful for ${serviceId} with current configuration.`,
@@ -261,14 +230,21 @@ async function deployToCloudRun(
         progressCallback
       );
       service.name = servicePath;
-      [operation] = await runClient.updateService({ service });
+      [operation] = await callWithRetry(
+        () => runClient.updateService({ service }),
+        `updateService ${serviceId}`
+      );
     } else {
       logAndProgress(`Creating new service ${serviceId}...`, progressCallback);
-      [operation] = await runClient.createService({
-        parent: parent,
-        service: service, // 'service' object might have invokerIamDisabled removed
-        serviceId: serviceId,
-      });
+      [operation] = await callWithRetry(
+        () =>
+          runClient.createService({
+            parent: parent,
+            service: service, // 'service' object might have invokerIamDisabled removed
+            serviceId: serviceId,
+          }),
+        `createService ${serviceId}`
+      );
     }
 
     logAndProgress(`Deploying ${serviceId} to Cloud Run...`, progressCallback);
@@ -305,7 +281,10 @@ async function ensureStorageBucketExists(
 ) {
   const bucket = storage.bucket(bucketName);
   try {
-    const [exists] = await bucket.exists();
+    const [exists] = await callWithRetry(
+      () => bucket.exists(),
+      `storage.bucket.exists ${bucketName}`
+    );
     if (exists) {
       logAndProgress(`Bucket ${bucketName} already exists.`, progressCallback);
       return bucket;
@@ -315,9 +294,10 @@ async function ensureStorageBucketExists(
         progressCallback
       );
       try {
-        const [createdBucket] = await storage.createBucket(bucketName, {
-          location: location,
-        });
+        const [createdBucket] = await callWithRetry(
+          () => storage.createBucket(bucketName, { location: location }),
+          `storage.createBucket ${bucketName}`
+        );
         logAndProgress(
           `Storage bucket ${createdBucket.name} created successfully in ${location}.`,
           progressCallback
@@ -441,7 +421,10 @@ async function uploadToStorageBucket(
       `Uploading buffer to gs://${bucket.name}/${destinationBlobName}...`,
       progressCallback
     );
-    await bucket.file(destinationBlobName).save(buffer);
+    await callWithRetry(
+      () => bucket.file(destinationBlobName).save(buffer),
+      `storage.bucket.file.save ${destinationBlobName}`
+    );
     logAndProgress(
       `File ${destinationBlobName} uploaded successfully to gs://${bucket.name}/${destinationBlobName}.`,
       progressCallback
@@ -483,9 +466,10 @@ async function ensureArtifactRegistryRepoExists(
   );
 
   try {
-    const [repository] = await artifactRegistryClient.getRepository({
-      name: repoPath,
-    });
+    const [repository] = await callWithRetry(
+      () => artifactRegistryClient.getRepository({ name: repoPath }),
+      `artifactRegistry.getRepository ${repositoryId}`
+    );
     logAndProgress(
       `Repository ${repositoryId} already exists in ${location}.`,
       progressCallback
@@ -500,31 +484,26 @@ async function ensureArtifactRegistryRepoExists(
       const repositoryToCreate = {
         format: format,
       };
-      try {
-        const [operation] = await artifactRegistryClient.createRepository({
-          parent: parent,
-          repository: repositoryToCreate,
-          repositoryId: repositoryId,
-        });
-        logAndProgress(
-          `Creating Artifact Registry repository ${repositoryId}...`,
-          progressCallback
-        );
-        const [result] = await operation.promise();
-        logAndProgress(
-          `Artifact Registry repository ${result.name} created successfully.`,
-          progressCallback
-        );
-        return result;
-      } catch (createError) {
-        const errorMessage = `Failed to create Artifact Registry repository ${repositoryId}. Error details: ${createError.message}`;
-        console.error(
-          `Failed to create Artifact Registry repository ${repositoryId}. Error details:`,
-          createError
-        );
-        logAndProgress(errorMessage, progressCallback, 'error');
-        throw createError;
-      }
+
+      const [operation] = await callWithRetry(
+        () =>
+          artifactRegistryClient.createRepository({
+            parent: parent,
+            repository: repositoryToCreate,
+            repositoryId: repositoryId,
+          }),
+        `artifactRegistry.createRepository ${repositoryId}`
+      );
+      logAndProgress(
+        `Creating Artifact Registry repository ${repositoryId}...`,
+        progressCallback
+      );
+      const [result] = await operation.promise();
+      logAndProgress(
+        `Artifact Registry repository ${result.name} created successfully.`,
+        progressCallback
+      );
+      return result;
     } else {
       const errorMessage = `Error checking/creating repository ${repositoryId}: ${error.message}`;
       console.error(
@@ -605,19 +584,19 @@ async function triggerCloudBuild(
     `Initiating Cloud Build for gs://${sourceBucketName}/${sourceBlobName} in ${location}...`,
     progressCallback
   );
-  const [operation] = await cloudBuildClient.createBuild({
-    projectId: projectId,
-    build: build,
-  });
+  const [operation] = await callWithRetry(
+    () => cloudBuildClient.createBuild({ projectId: projectId, build: build }),
+    'cloudBuild.createBuild'
+  );
 
   logAndProgress(`Cloud Build job started...`, progressCallback);
   const buildId = operation.metadata.build.id;
   let completedBuild;
   while (true) {
-    const [getBuildOperation] = await cloudBuildClient.getBuild({
-      projectId: projectId,
-      id: buildId,
-    });
+    const [getBuildOperation] = await callWithRetry(
+      () => cloudBuildClient.getBuild({ projectId: projectId, id: buildId }),
+      `cloudBuild.getBuild ${buildId}`
+    );
     if (
       ['SUCCESS', 'FAILURE', 'INTERNAL_ERROR', 'TIMEOUT', 'CANCELLED'].includes(
         getBuildOperation.status
@@ -668,11 +647,15 @@ async function triggerCloudBuild(
       );
 
       // Fetch the most recent N log entries
-      const [entries] = await loggingClient.getEntries({
-        filter: logFilter,
-        orderBy: 'timestamp desc', // Get latest logs first
-        pageSize: BUILD_LOGS_LINES_TO_FETCH,
-      });
+      const [entries] = await callWithRetry(
+        () =>
+          loggingClient.getEntries({
+            filter: logFilter,
+            orderBy: 'timestamp desc', // Get latest logs first
+            pageSize: BUILD_LOGS_LINES_TO_FETCH,
+          }),
+        `logging.getEntries for build ${buildId}`
+      );
 
       if (entries && entries.length > 0) {
         // Entries are newest first, reverse for chronological order of the snippet

package/lib/cloud-run-services.js

@@ -15,6 +15,7 @@ limitations under the License.
 */
 
 import protofiles from 'google-proto-files';
+import { callWithRetry, ensureApisEnabled } from './gcp-api-helpers.js';
 
 let runClient;
 let loggingClient;
@@ -32,13 +33,19 @@ export async function listServices(projectId, location) {
     const { ServicesClient } = v2;
     runClient = new ServicesClient({ projectId });
   }
+
+  await ensureApisEnabled(projectId, ['run.googleapis.com']);
+
   const parent = runClient.locationPath(projectId, location);
 
   try {
     console.log(
       `Listing Cloud Run services in project ${projectId}, location ${location}...`
     );
-    const [services] = await runClient.listServices({ parent });
+    const [services] = await callWithRetry(
+      () => runClient.listServices({ parent }),
+      'listServices'
+    );
     return services;
   } catch (error) {
     console.error(`Error listing Cloud Run services:`, error);
@@ -66,7 +73,10 @@ export async function getService(projectId, location, serviceId) {
     console.log(
       `Getting details for Cloud Run service ${serviceId} in project ${projectId}, location ${location}...`
     );
-    const [service] = await runClient.getService({ name: servicePath });
+    const [service] = await callWithRetry(
+      () => runClient.getService({ name: servicePath }),
+      'getService'
+    );
     return service;
   } catch (error) {
     console.error(
@@ -123,8 +133,10 @@ export async function getServiceLogs(
     console.log(`Request options: ${JSON.stringify(options)}`);
 
     // getEntries returns the entries and the full API response
-    const [entries, nextRequestOptions, apiResponse] =
-      await loggingClient.getEntries(options);
+    const [entries, nextRequestOptions, apiResponse] = await callWithRetry(
+      () => loggingClient.getEntries(options),
+      'getEntries'
+    );
 
     const formattedLogLines = entries
       .map((entry) => formatLogEntry(entry))

package/lib/gcp-api-helpers.js

@@ -0,0 +1,143 @@
+/*
+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.
+*/
+
+/**
+ * Calls a function with retry logic for GCP API calls.
+ * Retries on gRPC error code 7 (PERMISSION_DENIED).
+ * @param {Function} fn The function to call.
+ * @param {string} description A description of the function being called, for logging.
+ * @returns {Promise<any>} The result of the function.
+ */
+export async function callWithRetry(fn, description) {
+  const maxRetries = 7;
+  const initialBackoff = 1000; // 1 second
+  let retries = 0;
+
+  while (true) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (error.code === 7 && retries < maxRetries) {
+        retries++;
+        let backoff;
+        if (retries === 1) {
+          backoff = 15000; // 15 seconds for the first retry
+        } else {
+          backoff = initialBackoff * Math.pow(2, retries - 2);
+        }
+        console.warn(
+          `API call "${description}" failed with PERMISSION_DENIED. Retrying in ${
+            backoff / 1000
+          }s... (attempt ${retries}/${maxRetries})`
+        );
+        await new Promise((resolve) => setTimeout(resolve, backoff));
+      } else {
+        throw error;
+      }
+    }
+  }
+}
+
+/**
+ * Checks if a single Google Cloud API is enabled and enables it if not.
+ *
+ * @param {object} serviceUsageClient - The Service Usage client.
+ * @param {string} serviceName - The full name of the service (e.g., 'projects/my-project/services/run.googleapis.com').
+ * @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.
+ */
+async function checkAndEnableApi(
+  serviceUsageClient,
+  serviceName,
+  api,
+  progressCallback
+) {
+  const [service] = await callWithRetry(
+    () => serviceUsageClient.getService({ name: serviceName }),
+    `getService ${api}`
+  );
+  if (service.state !== 'ENABLED') {
+    const message = `API [${api}] is not enabled. Enabling...`;
+    console.log(message);
+    if (progressCallback) progressCallback({ level: 'info', data: message });
+
+    const [operation] = await callWithRetry(
+      () => serviceUsageClient.enableService({ name: serviceName }),
+      `enableService ${api}`
+    );
+    await operation.promise();
+  }
+}
+
+/**
+ * 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 {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.
+ * The first argument is the message, the optional second argument is the type ('error', 'warning', 'info').
+ * @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(projectId, apis, progressCallback) {
+  const { ServiceUsageClient } = await import('@google-cloud/service-usage');
+  const serviceUsageClient = new ServiceUsageClient({ projectId });
+  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(
+        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);
+      }
+    }
+  }
+  const successMsg = 'All required APIs are enabled.';
+  console.log(successMsg);
+  if (progressCallback) progressCallback({ level: 'info', data: successMsg });
+}