get_api_reference

Instructions

Implementation Reference

• src/index.ts:912-1016 (handler)

  The handler function that executes the get_api_reference tool. It maps services to API reference paths, fetches documentation using fetchGoogleCloudDoc, and returns structured JSON with API details, resources, and content.

  async function getApiReference(
    service: string,
    resource?: string
  ): Promise<string> {
    const serviceLower = service.toLowerCase();
    const product = GOOGLE_CLOUD_PRODUCTS[serviceLower];
  
    if (!product) {
      return JSON.stringify({
        error: `Unknown service: ${service}`,
        availableServices: Object.keys(GOOGLE_CLOUD_PRODUCTS),
        suggestion:
          'Use "list_google_cloud_products" to see all available services.',
      });
    }
  
    // API reference paths for common services
    const apiPaths: Record<string, { rest: string; resources: string[] }> = {
      compute: {
        rest: "compute/docs/reference/rest/v1",
        resources: [
          "instances",
          "disks",
          "networks",
          "firewalls",
          "images",
          "machineTypes",
        ],
      },
      storage: {
        rest: "storage/docs/json_api/v1",
        resources: ["buckets", "objects", "notifications"],
      },
      bigquery: {
        rest: "bigquery/docs/reference/rest",
        resources: ["datasets", "tables", "jobs", "routines"],
      },
      pubsub: {
        rest: "pubsub/docs/reference/rest",
        resources: ["topics", "subscriptions", "snapshots"],
      },
      sql: {
        rest: "sql/docs/mysql/admin-api/rest/v1",
        resources: ["instances", "databases", "users", "backupRuns"],
      },
      kubernetes: {
        rest: "kubernetes-engine/docs/reference/rest",
        resources: ["clusters", "nodePools", "operations"],
      },
      functions: {
        rest: "functions/docs/reference/rest/v2",
        resources: ["functions", "operations", "locations"],
      },
      run: {
        rest: "run/docs/reference/rest",
        resources: ["services", "configurations", "routes", "revisions"],
      },
      iam: {
        rest: "iam/docs/reference/rest",
        resources: ["roles", "serviceAccounts", "policies"],
      },
    };
  
    const apiInfo = apiPaths[serviceLower];
  
    if (!apiInfo) {
      return JSON.stringify({
        service: product.name,
        docsUrl: `https://cloud.google.com/${product.docsPath}`,
        apiReference: `https://cloud.google.com/${product.docsPath}/reference`,
        note: "API reference path not pre-configured. Try fetching the docs URL directly.",
      });
    }
  
    const apiUrl = resource
      ? `https://cloud.google.com/${apiInfo.rest}/${resource}`
      : `https://cloud.google.com/${apiInfo.rest}`;
  
    // Fetch the actual API reference page
    try {
      const docContent = await fetchGoogleCloudDoc(apiInfo.rest);
      const parsedContent = JSON.parse(docContent);
  
      return JSON.stringify({
        service: product.name,
        description: product.description,
        apiReferenceUrl: apiUrl,
        availableResources: apiInfo.resources,
        selectedResource: resource || "overview",
        documentation: parsedContent,
        usage: resource
          ? `Viewing API reference for ${resource}`
          : `Use "get_api_reference" with a resource parameter to get specific resource documentation. Available: ${apiInfo.resources.join(", ")}`,
      });
    } catch {
      return JSON.stringify({
        service: product.name,
        description: product.description,
        apiReferenceUrl: apiUrl,
        availableResources: apiInfo.resources,
        selectedResource: resource || "overview",
        fetchCommand: `Use fetch_google_cloud_doc with path: "${resource ? `${apiInfo.rest}/${resource}` : apiInfo.rest}"`,
      });
    }
  }

• src/index.ts:156-207 (schema)

  The tool registration including name, detailed description, and input schema definition (service required, resource optional) used by the MCP server for listing and validating tool calls.

      name: "get_api_reference",
      description: `Get REST API reference documentation for a specific Google Cloud service.
  
  **WHEN TO USE**: Use this tool when:
  - User needs API endpoints, methods, or parameters
  - User is developing integrations with GCP APIs
  - User asks about REST API for a specific GCP service
  - User needs to know available API resources for a service
  
  **INPUT**:
  - service (required): GCP service name (compute, storage, bigquery, pubsub, sql, kubernetes, functions, run, iam)
  - resource (optional): Specific API resource (instances, buckets, datasets, topics, etc.)
  
  **SUPPORTED SERVICES & RESOURCES**:
  - compute: instances, disks, networks, firewalls, images, machineTypes
  - storage: buckets, objects, notifications
  - bigquery: datasets, tables, jobs, routines
  - pubsub: topics, subscriptions, snapshots
  - sql: instances, databases, users, backupRuns
  - kubernetes: clusters, nodePools, operations
  - functions: functions, operations, locations
  - run: services, configurations, routes, revisions
  - iam: roles, serviceAccounts, policies
  
  **OUTPUT**: Returns JSON with:
  - service: Service name
  - description: Service description
  - apiReferenceUrl: Full URL to API reference
  - availableResources: List of available resources for this service
  - documentation: Actual API documentation content (if available)
  
  **EXAMPLE USAGE**:
  - Get Compute Engine API overview: service="compute"
  - Get Storage buckets API: service="storage", resource="buckets"
  - Get BigQuery datasets API: service="bigquery", resource="datasets"`,
      inputSchema: {
        type: "object" as const,
        properties: {
          service: {
            type: "string",
            description:
              "The Google Cloud service name (e.g., 'compute', 'storage', 'bigquery', 'pubsub', 'sql', 'kubernetes', 'functions', 'run', 'iam')",
          },
          resource: {
            type: "string",
            description:
              "Optional: Specific API resource (e.g., 'instances', 'buckets', 'datasets', 'topics')",
          },
        },
        required: ["service"],
      },
    },

• src/index.ts:1065-1074 (registration)

  The switch case that handles incoming 'get_api_reference' tool calls, extracts parameters, invokes the handler, and returns the result as MCP content.

  case "get_api_reference": {
    const { service, resource } = args as {
      service: string;
      resource?: string;
    };
    const result = await getApiReference(service, resource);
    return {
      content: [{ type: "text", text: result }],
    };
  }