@google-cloud/cloud-run-mcp 1.0.0 → 1.2.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,15 @@ 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:
+
+* `npm test`
+* `npm version minor`
+* `git push --follow-tags`
+
+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

@@ -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

@@ -6,5 +6,6 @@
       "command": "npx",
       "args": ["-y", "https://github.com/GoogleCloudPlatform/cloud-run-mcp"]
     }
-  }
+  },
+  "contextFileName": "gemini-extension/GEMINI.md"
 }

package/lib/cloud-run-deploy.js

@@ -63,9 +63,40 @@ function logAndProgress(message, progressCallback, severity = 'info') {
   }
 }
 
+/**
+ * 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 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();
+  }
+}
+
 /**
  * Ensures that the specified Google Cloud APIs are enabled for the given project.
- * If an API is not enabled, it attempts to enable it.
+ * 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
@@ -84,24 +115,34 @@ async function ensureApisEnabled(projectId, 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...`,
+      await checkAndEnableApi(
+        serviceUsageClient,
+        serviceName,
+        api,
+        progressCallback
+      );
+    } catch (error) {
+      // First attempt failed, log a warning and retry once after a delay.
+      logAndProgress(
+        `Failed to check/enable ${api}, retrying in 1s...`,
+        progressCallback,
+        'warn'
+      );
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+      try {
+        await checkAndEnableApi(
+          serviceUsageClient,
+          serviceName,
+          api,
           progressCallback
         );
-        const [operation] = await serviceUsageClient.enableService({
-          name: serviceName,
-        });
-        await operation.promise();
+      } 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);
+        logAndProgress(errorMessage, progressCallback, 'error');
+        throw new Error(errorMessage);
       }
-    } 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);
@@ -500,30 +541,45 @@ 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 maxRetries = 3;
+      const retryDelay = 10000; // 10s
+
+      for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        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) {
+          // PERMISSION_DENIED is code 7 for gRPC. Retry on this error.
+          if (createError.code === 7 && attempt < maxRetries) {
+            logAndProgress(
+              `Attempt ${attempt} to create repository failed. This can happen on new projects. Retrying in 10s...`,
+              progressCallback,
+              'warn'
+            );
+            await new Promise((resolve) => setTimeout(resolve, retryDelay));
+          } else {
+            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;
+          }
+        }
       }
     } else {
       const errorMessage = `Error checking/creating repository ${repositoryId}: ${error.message}`;

package/lib/gcp-auth-check.js

@@ -19,10 +19,9 @@ import { GoogleAuth } from 'google-auth-library';
 /**
  * Checks for the presence of properly setup Google Cloud Platform (GCP) authentication
  * using the official Google Auth Library for Node.js. If GCP auth is not found, it logs an
- * error message and exits the process, instructing the user on how to set them up.
- * This check is primarily for local/stdio environments where explicit setup is often needed.
+ * error message and returns false.
  * @async
- * @returns {Promise<void>} A promise that resolves if GCP auth are found, or rejects and exits the process if not.
+ * @returns {Promise<boolean>} A promise that resolves to true if GCP auth are found, and false otherwise.
  */
 export async function ensureGCPCredentials() {
   console.error('Checking for Google Cloud Application Default Credentials...');
@@ -35,6 +34,7 @@ export async function ensureGCPCredentials() {
     await client.getAccessToken();
 
     console.log('Application Default Credentials found.');
+    return true;
   } catch (error) {
     console.error(
       'ERROR: Google Cloud Application Default Credentials are not set up.'
@@ -74,6 +74,6 @@ export async function ensureGCPCredentials() {
     if (error.stack) {
       console.error('Error stack:', error.stack);
     }
-    // process.exit(1);
+    return false;
   }
 }

package/mcp-server.js

@@ -30,6 +30,7 @@ import { ensureGCPCredentials } from './lib/gcp-auth-check.js';
 import 'dotenv/config';
 
 const gcpInfo = await checkGCP();
+let gcpCredentialsAvailable = false;
 
 /**
  * Ensure that console.log and console.error are compatible with stdio.
@@ -52,7 +53,6 @@ function shouldStartStdio() {
 
 if (shouldStartStdio()) {
   makeLoggingCompatibleWithStdio();
-  await ensureGCPCredentials();
 }
 
 // Read default configurations from environment variables
@@ -88,6 +88,7 @@ async function getServer() {
       defaultRegion: effectiveRegion,
       defaultServiceName,
       skipIamCheck,
+      gcpCredentialsAvailable,
     });
   } else {
     console.log(
@@ -99,6 +100,7 @@ async function getServer() {
       defaultRegion: effectiveRegion,
       defaultServiceName,
       skipIamCheck,
+      gcpCredentialsAvailable,
     });
   }
 
@@ -110,13 +112,14 @@ async function getServer() {
 
 // stdio
 if (shouldStartStdio()) {
+  gcpCredentialsAvailable = await ensureGCPCredentials();
   const stdioTransport = new StdioServerTransport();
   const server = await getServer();
   await server.connect(stdioTransport);
   console.log('Cloud Run MCP server stdio transport connected');
 } else {
   console.log('Running on GCP, stdio transport will not be started.');
-  await ensureGCPCredentials();
+  gcpCredentialsAvailable = await ensureGCPCredentials();
   const app = express();
   app.use(express.json());
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@google-cloud/cloud-run-mcp",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "Cloud Run MCP deployment tool",
   "main": "mcp-server.js",
@@ -9,14 +9,14 @@
   },
   "scripts": {
     "deploy": "gcloud run deploy cloud-run-mcp --source . --no-invoker-iam-check",
-    "test:deploy": "node test/test-deploy.js",
-    "test:create-project": "node test/test-create-project.js",
-    "test:service-logs": "node test/test-service-logs.js",
-    "test:gcp-auth": "node test/test-gcp-auth.js",
-    "test:prompts": "node --test test/test-prompts.js",
-    "test:mcp": "node --test test/test-mcp-server.js",
-    "test:tools": "node --test test/test-tools.js",
-    "test": "node test/run-all-tests.js",
+    "test:deploy": "node test/need-gcp/cloud-run-deploy.test.js",
+    "test:create-project": "node test/need-gcp/gcp-projects.test.js",
+    "test:service-logs": "node test/need-gcp/cloud-run-services.test.js",
+    "test:gcp-auth": "node test/need-gcp/gcp-auth-check.test.js",
+    "test:prompts": "node --test test/local/prompts.test.js",
+    "test:mcp": "node --test test/local/mcp-server.test.js",
+    "test:tools": "node --test test/local/tools.test.js",
+    "test": "node --test test/local/*.test.js",
     "mcp-inspector": "npx @modelcontextprotocol/inspector node mcp-server.js",
     "start": "node mcp-server.js",
     "lint:check": "prettier --check .",

package/test/{test-prompts.js → local/prompts.test.js}

@@ -16,7 +16,7 @@ limitations under the License.
 
 import assert from 'node:assert/strict';
 import { describe, it, mock } from 'node:test';
-import { registerPrompts } from '../prompts.js';
+import { registerPrompts } from '../../prompts.js';
 
 describe('registerPrompts', () => {
   it('should register deploy and logs prompts', () => {

package/test/{test-tools.js → local/tools.test.js}

@@ -8,7 +8,7 @@ describe('registerTools', () => {
       registerTool: mock.fn(),
     };
 
-    const { registerTools } = await esmock('../tools.js', {});
+    const { registerTools } = await esmock('../../tools.js', {});
 
     registerTools(server);
 
@@ -38,14 +38,14 @@ describe('registerTools', () => {
         registerTool: mock.fn(),
       };
 
-      const { registerTools } = await esmock('../tools.js', {
-        '../lib/gcp-projects.js': {
+      const { registerTools } = await esmock('../../tools.js', {
+        '../../lib/gcp-projects.js': {
           listProjects: () =>
             Promise.resolve([{ id: 'project1' }, { id: 'project2' }]),
         },
       });
 
-      registerTools(server);
+      registerTools(server, { gcpCredentialsAvailable: true });
 
       const handler = server.registerTool.mock.calls.find(
         (call) => call.arguments[0] === 'list_projects'
@@ -69,8 +69,8 @@ describe('registerTools', () => {
         registerTool: mock.fn(),
       };
 
-      const { registerTools } = await esmock('../tools.js', {
-        '../lib/gcp-projects.js': {
+      const { registerTools } = await esmock('../../tools.js', {
+        '../../lib/gcp-projects.js': {
           createProjectAndAttachBilling: (projectId) =>
             Promise.resolve({
               projectId: projectId,
@@ -79,7 +79,7 @@ describe('registerTools', () => {
         },
       });
 
-      registerTools(server);
+      registerTools(server, { gcpCredentialsAvailable: true });
 
       const handler = server.registerTool.mock.calls.find(
         (call) => call.arguments[0] === 'create_project'
@@ -101,8 +101,8 @@ describe('registerTools', () => {
         registerTool: mock.fn(),
       };
 
-      const { registerTools } = await esmock('../tools.js', {
-        '../lib/gcp-projects.js': {
+      const { registerTools } = await esmock('../../tools.js', {
+        '../../lib/gcp-projects.js': {
           createProjectAndAttachBilling: () =>
             Promise.resolve({
               projectId: 'generated-project',
@@ -111,7 +111,7 @@ describe('registerTools', () => {
         },
       });
 
-      registerTools(server);
+      registerTools(server, { gcpCredentialsAvailable: true });
 
       const handler = server.registerTool.mock.calls.find(
         (call) => call.arguments[0] === 'create_project'
@@ -135,8 +135,8 @@ describe('registerTools', () => {
         registerTool: mock.fn(),
       };
 
-      const { registerTools } = await esmock('../tools.js', {
-        '../lib/cloud-run-services.js': {
+      const { registerTools } = await esmock('../../tools.js', {
+        '../../lib/cloud-run-services.js': {
           listServices: () =>
             Promise.resolve([
               { name: 'service1', uri: 'uri1' },
@@ -145,7 +145,7 @@ describe('registerTools', () => {
         },
       });
 
-      registerTools(server);
+      registerTools(server, { gcpCredentialsAvailable: true });
 
       const handler = server.registerTool.mock.calls.find(
         (call) => call.arguments[0] === 'list_services'
@@ -172,8 +172,8 @@ describe('registerTools', () => {
         registerTool: mock.fn(),
       };
 
-      const { registerTools } = await esmock('../tools.js', {
-        '../lib/cloud-run-services.js': {
+      const { registerTools } = await esmock('../../tools.js', {
+        '../../lib/cloud-run-services.js': {
           getService: () =>
             Promise.resolve({
               name: 'my-service',
@@ -183,7 +183,7 @@ describe('registerTools', () => {
         },
       });
 
-      registerTools(server);
+      registerTools(server, { gcpCredentialsAvailable: true });
 
       const handler = server.registerTool.mock.calls.find(
         (call) => call.arguments[0] === 'get_service'
@@ -223,13 +223,13 @@ describe('registerTools', () => {
         return Promise.resolve({ logs: 'log3\nlog4', requestOptions: null });
       };
 
-      const { registerTools } = await esmock('../tools.js', {
-        '../lib/cloud-run-services.js': {
+      const { registerTools } = await esmock('../../tools.js', {
+        '../../lib/cloud-run-services.js': {
           getServiceLogs: getServiceLogs,
         },
       });
 
-      registerTools(server);
+      registerTools(server, { gcpCredentialsAvailable: true });
 
       const handler = server.registerTool.mock.calls.find(
         (call) => call.arguments[0] === 'get_service_log'
@@ -257,13 +257,13 @@ describe('registerTools', () => {
         registerTool: mock.fn(),
       };
 
-      const { registerTools } = await esmock('../tools.js', {
-        '../lib/cloud-run-deploy.js': {
+      const { registerTools } = await esmock('../../tools.js', {
+        '../../lib/cloud-run-deploy.js': {
           deploy: () => Promise.resolve({ uri: 'my-uri' }),
         },
       });
 
-      registerTools(server);
+      registerTools(server, { gcpCredentialsAvailable: true });
 
       const handler = server.registerTool.mock.calls.find(
         (call) => call.arguments[0] === 'deploy_local_files'
@@ -292,13 +292,13 @@ describe('registerTools', () => {
         registerTool: mock.fn(),
       };
 
-      const { registerTools } = await esmock('../tools.js', {
-        '../lib/cloud-run-deploy.js': {
+      const { registerTools } = await esmock('../../tools.js', {
+        '../../lib/cloud-run-deploy.js': {
           deploy: () => Promise.resolve({ uri: 'my-uri' }),
         },
       });
 
-      registerTools(server);
+      registerTools(server, { gcpCredentialsAvailable: true });
 
       const handler = server.registerTool.mock.calls.find(
         (call) => call.arguments[0] === 'deploy_local_folder'
@@ -327,13 +327,13 @@ describe('registerTools', () => {
         registerTool: mock.fn(),
       };
 
-      const { registerTools } = await esmock('../tools.js', {
-        '../lib/cloud-run-deploy.js': {
+      const { registerTools } = await esmock('../../tools.js', {
+        '../../lib/cloud-run-deploy.js': {
           deploy: () => Promise.resolve({ uri: 'my-uri' }),
         },
       });
 
-      registerTools(server);
+      registerTools(server, { gcpCredentialsAvailable: true });
 
       const handler = server.registerTool.mock.calls.find(
         (call) => call.arguments[0] === 'deploy_file_contents'
@@ -362,13 +362,13 @@ describe('registerTools', () => {
         registerTool: mock.fn(),
       };
 
-      const { registerTools } = await esmock('../tools.js', {
-        '../lib/cloud-run-deploy.js': {
+      const { registerTools } = await esmock('../../tools.js', {
+        '../../lib/cloud-run-deploy.js': {
           deployImage: () => Promise.resolve({ uri: 'my-uri' }),
         },
       });
 
-      registerTools(server);
+      registerTools(server, { gcpCredentialsAvailable: true });
 
       const handler = server.registerTool.mock.calls.find(
         (call) => call.arguments[0] === 'deploy_container_image'
@@ -390,4 +390,35 @@ describe('registerTools', () => {
       });
     });
   });
+
+  describe('when gcp credentials are not available', () => {
+    it('should return an error for all tools', async () => {
+      const server = {
+        registerTool: mock.fn(),
+      };
+
+      const { registerTools } = await esmock('../../tools.js', {});
+
+      registerTools(server, { gcpCredentialsAvailable: false });
+
+      const toolNames = server.registerTool.mock.calls.map(
+        (call) => call.arguments[0]
+      );
+
+      for (const toolName of toolNames) {
+        const handler = server.registerTool.mock.calls.find(
+          (call) => call.arguments[0] === toolName
+        ).arguments[2];
+        const result = await handler({});
+        assert.deepStrictEqual(result, {
+          content: [
+            {
+              type: 'text',
+              text: 'GCP credentials are not available. Please configure your environment.',
+            },
+          ],
+        });
+      }
+    });
+  });
 });

package/test/{test-deploy.js → need-gcp/cloud-run-deploy.test.js}

@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-import { deploy, deployImage } from '../lib/cloud-run-deploy.js';
+import { deploy, deployImage } from '../../lib/cloud-run-deploy.js';
 import readline from 'readline/promises';
 import { stdin as input, stdout as output } from 'process';
 import fs from 'fs/promises';

package/test/{test-service-logs.js → need-gcp/cloud-run-services.test.js}

@@ -16,7 +16,7 @@ limitations under the License.
 
 import readline from 'readline/promises';
 import { stdin as input, stdout as output } from 'process';
-import { getServiceLogs } from '../lib/cloud-run-services.js';
+import { getServiceLogs } from '../../lib/cloud-run-services.js';
 
 /**
  * Prompts the user for required service information