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

package/.c8rc.json

@@ -0,0 +1,9 @@
+{
+  "all": true,
+  "reporter": ["lcov", "text"],
+  "lines": 43,
+  "functions": 35,
+  "branches": 70,
+  "statements": 43,
+  "exclude": ["**/test/**", "**/coverage/**"]
+}

package/.github/workflows/lint-checker.yml

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

package/.kokoro/kokoro_build.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+# Copyright 2022 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
+#
+#     http://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.
+
+# Code under repo is checked out to ${KOKORO_ARTIFACTS_DIR}/git.
+# The final directory name in this path is determined by the scm name specified
+# in the job configuration.
+
+cd "${KOKORO_ARTIFACTS_DIR}/github/cloud-run-mcp"
+.kokoro/run_tests.sh

package/.kokoro/presubmit.cfg

@@ -0,0 +1,21 @@
+# -*- protobuffer -*-
+# proto-file: google3/devtools/kokoro/config/proto/build.proto
+# proto-message: BuildConfig
+
+# Location of the bash script. Should have value <github_scm.name>/<path_from_repository_root>.
+# github_scm.name is specified in the job configuration (next section).
+build_file: "cloud-run-mcp/.kokoro/kokoro_build.sh"
+
+container_properties {
+  docker_image: "us-central1-docker.pkg.dev/kokoro-container-bakery/kokoro/ubuntu/ubuntu2204/full:next"
+}
+
+env_vars {
+  key: "GOOGLE_CLOUD_PROJECT"
+  value: "cloud-run-mcp-server-testing"
+}
+
+env_vars {
+  key: "GCP_PARENT"
+  value: "folders/138095058155"
+}

package/.kokoro/run_tests.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+#
+# Copyright 2022 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
+#
+#     http://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.
+
+# Fail on any error.
+set -xe
+
+# cd to project root
+cd "$(dirname "$0")"/..
+
+# Install dependencies
+npm install
+
+# Run tests
+npm run test:workflows # Run tests related to all workflows
+npm run test:projects # Run tests related to GCP projects
+npm run test:services # Run tests related to services
+npm run test:deploy # Run tests related to deployments
+npm run test:gcp-auth # Run tests related to GCP authentication

package/CONTRIBUTING.md

@@ -74,7 +74,7 @@ To use remote MCP Server in a MCP client:
 Start the MCP server locally with:
 
 ```bash
-npm run start
+GCP_STDIO=false node /path/to/this/repo/cloud-run-mcp/mcp-server.js
 ```
 
 Then, in your MCP client configuration, use the following:
@@ -84,7 +84,19 @@ Then, in your MCP client configuration, use the following:
   "mcpServers": {
     "cloud-run": {
       "command": "npx",
-      "args": ["mcp-remote", "http://localhost:3000/sse"]
+      "args": ["mcp-remote", "http://localhost:3000/mcp"]
+    }
+  }
+}
+```
+
+or, if your client supports the `url` attribute, you can use:
+
+```
+{
+  "mcpServers": {
+    "cloud-run": {
+      "url": "http://localhost:3000/mcp"
     }
   }
 }
@@ -118,10 +130,13 @@ To update the [npm package]https://www.npmjs.com/package/@google-cloud/cloud-run
 
 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.
+- `git checkout -b new-release`
+- `npm test`
+- `npm version minor`
+- `git push --set-upstream origin new-release --follow-tags`
+- Create a [pull request for 'new-release' on GitHub](https://github.com/GoogleCloudPlatform/cloud-run-mcp/pull/new/new-release)
+- Get approval
+- Rebase and merge into main
+- 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.
+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

@@ -1,4 +1,4 @@
-# MCP server to deploy code to Google Cloud Run
+# Cloud Run MCP server and Gemini CLI extension
 
 Enable MCP-compatible AI agents to deploy apps to Cloud Run.
 
@@ -11,7 +11,7 @@ Enable MCP-compatible AI agents to deploy apps to Cloud Run.
 }
 ```
 
-Deploy from Gemini CLI and other AI-powered CLI agents:  
+Deploy from Gemini CLI and other AI-powered CLI agents:
 
 <img  src="https://raw.githubusercontent.com/GoogleCloudPlatform/cloud-run-mcp/refs/heads/main/.github/images/deploycli.gif" width="800">
 
@@ -48,19 +48,58 @@ Prompts are natural language commands that can be used to perform common tasks.
 - `deploy`: Deploys the current working directory to Cloud Run. If a service name is not provided, it will use the `DEFAULT_SERVICE_NAME` environment variable, or the name of the current working directory.
 - `logs`: Gets the logs for a Cloud Run service. If a service name is not provided, it will use the `DEFAULT_SERVICE_NAME` environment variable, or the name of the current working directory.
 
+## Environment Variables
+
+The Cloud Run MCP server can be configured using the following environment variables:
+
+| Variable                 | Description                                                                                                                                                                              |
+| :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GOOGLE_CLOUD_PROJECT`   | The default project ID to use for Cloud Run services.                                                                                                                                    |
+| `GOOGLE_CLOUD_REGION`    | The default region to use for Cloud Run services.                                                                                                                                        |
+| `DEFAULT_SERVICE_NAME`   | The default service name to use for Cloud Run services.                                                                                                                                  |
+| `SKIP_IAM_CHECK`         | Controls whether to check for IAM permissions for a Cloud Run service. Set to `false` to enable checks. This is `true` by default which is a recommended way to make the service public. |
+| `ENABLE_HOST_VALIDATION` | Prevents [DNS Rebinding](https://en.wikipedia.org/wiki/DNS_rebinding) attacks by validating the Host header. This is disabled by default.                                                |
+| `ALLOWED_HOSTS`          | Comma-separated list of allowed Host headers (if host validation is enabled). The default value is `localhost,127.0.0.1,::1`.                                                            |
 
 ## Use as a Gemini CLI extension
 
 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/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
-```
+2. Install the extension:
 
+   ```bash
+   gemini extensions install https://github.com/GoogleCloudPlatform/cloud-run-mcp
+   ```
 
-## Use as local MCP server
+3. Log in to your Google Cloud account using the command:
+
+   ```bash
+   gcloud auth login
+   ```
+
+4. Set up application credentials using the command:
+   ```bash
+   gcloud auth application-default login
+   ```
+
+## Use in MCP Clients
+
+### Learn how to configure your MCP client
+
+Most MCP clients require a configuration file to be created or modified to add the MCP server.
+
+The configuration file syntax can be different across clients. Please refer to the following links for the latest expected syntax:
+
+- [**Antigravity**](https://antigravity.google/docs/mcp)
+- [**Windsurf**](https://docs.windsurf.com/windsurf/mcp)
+- [**VSCode**](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
+- [**Claude Desktop**](https://modelcontextprotocol.io/quickstart/user)
+- [**Cursor**](https://docs.cursor.com/context/model-context-protocol)
+
+Once you have identified how to configure your MCP client, select one of these two options to set up the MCP server.
+We recommend setting up as a local MCP server using Node.js.
+
+### Set up as local MCP server
 
 Run the Cloud Run MCP server on your local machine using local Google Cloud credentials. This is best if you are using an AI-assisted IDE (e.g. Cursor) or a desktop AI application (e.g. Claude).
 
@@ -79,7 +118,7 @@ Run the Cloud Run MCP server on your local machine using local Google Cloud cred
 
 Then configure the MCP server using either Node.js or Docker:
 
-### Using Node.js
+#### Using Node.js
 
 0. Install [Node.js](https://nodejs.org/en/download/) (LTS version recommended).
 
@@ -106,7 +145,7 @@ Then configure the MCP server using either Node.js or Docker:
       }
    ```
 
-### Using Docker
+#### Using Docker
 
 See Docker's [MCP catalog](https://hub.docker.com/mcp/server/cloud-run-mcp/overview), or use these manual instructions:
 
@@ -134,7 +173,7 @@ See Docker's [MCP catalog](https://hub.docker.com/mcp/server/cloud-run-mcp/overv
       }
    ```
 
-## Use as remote MCP server
+### Set up as remote MCP server
 
 > [!WARNING]  
 > Do not use the remote MCP server without authentication. In the following instructions, we will use IAM authentication to secure the connection to the MCP server from your local machine. This is important to prevent unauthorized access to your Google Cloud resources.
@@ -195,3 +234,5 @@ With this option, you will only be able to deploy code to the same Google Cloud
         "args": ["-y", "mcp-remote", "http://localhost:3000/sse"]
       }
    ```
+
+The Google Cloud Platform Terms of Service (available at https://cloud.google.com/terms/) and the Data Processing and Security Terms (available at https://cloud.google.com/terms/data-processing-terms) do not apply to any component of the Cloud Run MCP Server software.

package/REVIEWING.md

@@ -0,0 +1,20 @@
+# Reviewing Pull Requests
+
+This document provides guidelines for reviewing Pull Requests.
+
+## Guidelines
+
+### Presubmit Tests
+
+Running presubmit tests is a mandatory requirement for Pull Requests to be eligible for submission.
+
+**Before triggering tests:**
+Review the code changes, especially new or modified tests, to ensure they do not contain any malicious or harmful code that could unnecessarily consume or harm Google's resources during test execution. In particular, ensure the tests:
+
+- **Do not modify environment variables:** The tests should not modify environment variables in an unexpected or harmful way.
+- **Do not consume excessive resources:** Ensure tests do not create an excessive number of Google Cloud projects or other high-cost resources.
+- **Do not contain hardcoded credentials:** Credentials should not be present in the code.
+- **Do not rely on untrusted external dependencies:** Any new external dependencies should be reviewed for trustworthiness.
+
+**Triggering tests:**
+If the code is safe to run, trigger presubmit tests by adding a comment with `kokoro:run` to the Pull Request. Tests are run via Kokoro.

package/gemini-extension/GEMINI.md

@@ -3,7 +3,7 @@
 ## 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.
+The code needs to listen for HTTP requests on the port defined by the $PORT environment variable or 8080.
 
 ### Supported languages
 

package/lib/cloud-api/build.js

@@ -0,0 +1,200 @@
+/*
+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 { callWithRetry } from './helpers.js';
+import { logAndProgress } from '../util/helpers.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
+
+/**
+ * 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.
+ * 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.
+ * @param {string} sourceBlobName - The GCS blob name (the zip file) for the source code.
+ * @param {string} targetRepoName - The name of the target Artifact Registry repository (used for context, not directly in build steps).
+ * @param {string} targetImageUrl - The full Artifact Registry URL for the image to be built (e.g., `location-docker.pkg.dev/project/repo/image:tag`).
+ * @param {boolean} hasDockerfile - Indicates whether a Dockerfile is present in the source to guide the build process.
+ * @param {function(object): void} [progressCallback] - Optional callback for progress updates.
+ * @returns {Promise<object>} A promise that resolves with the completed Cloud Build object.
+ * @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,
+  sourceBlobName,
+  targetRepoName,
+  targetImageUrl,
+  hasDockerfile,
+  progressCallback
+) {
+  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 build = {
+    source: {
+      storageSource: {
+        bucket: sourceBucketName,
+        object: sourceBlobName,
+      },
+    },
+    steps: buildSteps,
+    images: [targetImageUrl],
+  };
+
+  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'
+  );
+
+  await logAndProgress(`Cloud Build job started...`, progressCallback);
+  const buildId = operation.metadata.build.id;
+  let completedBuild;
+  while (true) {
+    const [getBuildOperation] = await callWithRetry(
+      () =>
+        context.cloudBuildClient.getBuild({
+          projectId: projectId,
+          id: buildId,
+        }),
+      `cloudBuild.getBuild ${buildId}`
+    );
+    if (
+      ['SUCCESS', 'FAILURE', 'INTERNAL_ERROR', 'TIMEOUT', 'CANCELLED'].includes(
+        getBuildOperation.status
+      )
+    ) {
+      completedBuild = getBuildOperation;
+      break;
+    }
+    await logAndProgress(
+      `Build status: ${getBuildOperation.status}. Waiting...`,
+      progressCallback,
+      'debug'
+    );
+    await new Promise((resolve) => setTimeout(resolve, 5000));
+  }
+
+  if (completedBuild.status === 'SUCCESS') {
+    await logAndProgress(
+      `Cloud Build job ${buildId} completed successfully.`,
+      progressCallback
+    );
+    await logAndProgress(
+      `Image built: ${completedBuild.results.images[0].name}`,
+      progressCallback
+    );
+    return completedBuild;
+  } else {
+    const failureMessage = `Cloud Build job ${buildId} failed with status: ${completedBuild.status}`;
+    await logAndProgress(failureMessage, progressCallback, 'error');
+    const logsMessage = `Build logs: ${completedBuild.logUrl}`;
+    await logAndProgress(logsMessage, progressCallback); // Log URL is info, failure is error
+
+    let buildLogsSnippet = `\n\nRefer to Log URL for full details: ${completedBuild.logUrl}`; // Default snippet
+    try {
+      const logFilter = `resource.type="build" AND resource.labels.build_id="${buildId}"`;
+      await logAndProgress(
+        `Attempting to fetch last ${BUILD_LOGS_LINES_TO_FETCH} log lines for build ${buildId}...`,
+        progressCallback,
+        'debug'
+      );
+
+      // Wait for a short period to allow logs to propagate
+      await new Promise((resolve) =>
+        setTimeout(resolve, DELAY_WAIT_FOR_BUILD_LOGS)
+      );
+
+      // Fetch the most recent N log entries
+      const [entries] = await callWithRetry(
+        () =>
+          context.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
+        const logLines = entries.reverse().map((entry) => entry.data || '');
+        if (logLines.length > 0) {
+          buildLogsSnippet = `\n\nLast ${logLines.length} log lines from build ${buildId}:\n${logLines.join('\n')}`;
+          await logAndProgress(
+            `Successfully fetched snippet of build logs for ${buildId}.`,
+            progressCallback,
+            'info'
+          );
+        }
+      } else {
+        await logAndProgress(
+          `No specific log entries retrieved for build ${buildId}. ${buildLogsSnippet}`,
+          progressCallback,
+          'warn'
+        );
+      }
+    } catch (logError) {
+      console.error(`Error fetching build logs for ${buildId}:`, logError);
+      await logAndProgress(
+        `Failed to fetch build logs snippet: ${logError.message}. ${buildLogsSnippet}`,
+        progressCallback,
+        'warn'
+      );
+      // buildLogsSnippet already contains the Log URL as a fallback
+    }
+    throw new Error(`Build ${buildId} failed.${buildLogsSnippet}`);
+  }
+}

package/lib/{gcp-api-helpers.js → cloud-api/helpers.js}

@@ -90,6 +90,7 @@ async function checkAndEnableApi(
  * 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.
@@ -97,19 +98,21 @@ 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(projectId, apis, progressCallback) {
-  const { ServiceUsageClient } = await import('@google-cloud/service-usage');
-  const serviceUsageClient = new ServiceUsageClient({ projectId });
+export async function ensureApisEnabled(
+  context,
+  projectId,
+  apis,
+  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(
-        serviceUsageClient,
+        context.serviceUsageClient,
         serviceName,
         api,
         progressCallback
@@ -123,7 +126,7 @@ export async function ensureApisEnabled(projectId, apis, progressCallback) {
       await new Promise((resolve) => setTimeout(resolve, 1000));
       try {
         await checkAndEnableApi(
-          serviceUsageClient,
+          context.serviceUsageClient,
           serviceName,
           api,
           progressCallback
@@ -132,7 +135,8 @@ export async function ensureApisEnabled(projectId, apis, progressCallback) {
         // 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 });
+        if (progressCallback)
+          progressCallback({ level: 'error', data: errorMessage });
         throw new Error(errorMessage);
       }
     }
@@ -140,4 +144,4 @@ export async function ensureApisEnabled(projectId, apis, progressCallback) {
   const successMsg = 'All required APIs are enabled.';
   console.log(successMsg);
   if (progressCallback) progressCallback({ level: 'info', data: successMsg });
-}
+}