Cloud Run MCP Server

Instructions

Implementation Reference

• tools/register-tools.js:152-190 (handler)

  The core handler function executed when the 'list_services' tool is called. It validates the project input, fetches services using listServices helper, formats output by region with service names and URLs, and returns structured content or error.

  gcpTool(options.gcpCredentialsAvailable, async ({ project }) => {
    if (typeof project !== 'string') {
      return {
        content: [
          {
            type: 'text',
            text: 'Error: Project ID must be provided and be a non-empty string.',
          },
        ],
      };
    }
    try {
      const allServices = await listServices(project);
      const content = [];
      for (const region of Object.keys(allServices)) {
        const serviceList = allServices[region];
        const servicesText = serviceList
          .map((s) => {
            const serviceName = s.name.split('/').pop();
            return `- ${serviceName} (URL: ${s.uri})`;
          })
          .join('\n');
        content.push({
          type: 'text',
          text: `Services in project ${project} (location ${region}):\n${servicesText}`,
        });
      }
      return { content };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error listing services for project ${project}: ${error.message}`,
          },
        ],
      };
    }
  })

• tools/register-tools.js:143-151 (schema)

  Input schema definition for the 'list_services' tool using Zod, specifying the optional 'project' parameter with description and default value.

  {
    description: 'Lists all Cloud Run services in a given project.',
    inputSchema: {
      project: z
        .string()
        .describe('Google Cloud project ID')
        .default(options.defaultProjectId),
    },
  },

• tools/tools.js:33-33 (registration)

  Invocation of registerListServicesTool during main tool registration in the application setup.

  registerListServicesTool(server, options);

• lib/cloud-api/run.js:52-86 (helper)

  Helper function listServices that initializes clients, ensures API enabled, lists Cloud Run locations, and fetches services from each location using Google Cloud Run API, returning object keyed by region.

  export async function listServices(projectId) {
    if (!runClient) {
      const { v2 } = await import('@google-cloud/run');
      const { ServicesClient } = v2;
      const { ServiceUsageClient } = await import('@google-cloud/service-usage');
      runClient = new ServicesClient({ projectId });
      serviceUsageClient = new ServiceUsageClient({ projectId });
    }
    const context = {
      runClient: runClient,
      serviceUsageClient: serviceUsageClient,
    };
    await ensureApisEnabled(context, projectId, ['run.googleapis.com']);
    const locations = await listCloudRunLocations(projectId);
  
    const allServices = {};
    for (const location of locations) {
      const parent = runClient.locationPath(projectId, location);
  
      try {
        console.log(
          `Listing Cloud Run services in project ${projectId}, location ${location}...`
        );
        const [services] = await callWithRetry(
          () => runClient.listServices({ parent }),
          'listServices'
        );
        allServices[location] = services;
      } catch (error) {
        console.error(`Error listing Cloud Run services:`, error);
        throw error;
      }
    }
    return allServices;
  }

• tools/register-tools.js:140-192 (registration)

  The registration function registerListServicesTool that defines and registers the 'list_services' tool on the MCP server, including name, schema, and wrapped handler.

  function registerListServicesTool(server, options) {
    server.registerTool(
      'list_services',
      {
        description: 'Lists all Cloud Run services in a given project.',
        inputSchema: {
          project: z
            .string()
            .describe('Google Cloud project ID')
            .default(options.defaultProjectId),
        },
      },
      gcpTool(options.gcpCredentialsAvailable, async ({ project }) => {
        if (typeof project !== 'string') {
          return {
            content: [
              {
                type: 'text',
                text: 'Error: Project ID must be provided and be a non-empty string.',
              },
            ],
          };
        }
        try {
          const allServices = await listServices(project);
          const content = [];
          for (const region of Object.keys(allServices)) {
            const serviceList = allServices[region];
            const servicesText = serviceList
              .map((s) => {
                const serviceName = s.name.split('/').pop();
                return `- ${serviceName} (URL: ${s.uri})`;
              })
              .join('\n');
            content.push({
              type: 'text',
              text: `Services in project ${project} (location ${region}):\n${servicesText}`,
            });
          }
          return { content };
        } catch (error) {
          return {
            content: [
              {
                type: 'text',
                text: `Error listing services for project ${project}: ${error.message}`,
              },
            ],
          };
        }
      })
    );
  }