@google-cloud/storage-mcp 0.2.0 → 0.3.0

package/README.md

@@ -23,6 +23,18 @@ bucket and object management. With the Storage MCP server you can:
 
   <img src="./assets/easy_access_3x.gif" width="80%" alt="Easy Access Demo">
 
+- **Perform analytical and aggregation queries on your objects and buckets.** Perform
+  aggregations and compute statistics on entire storage inventory using [Storage Insights
+  Datasets](https://cloud.google.com/storage/docs/insights/datasets)
+
+  <img src="./assets/storage_insights_aggregation.gif" width="80%" alt="Easy Access Demo">
+
+- **Run advanced filters and searches on your data.** Search and filter your objects
+  by file type, size and other metadata fields using [Storage Insights
+  Datasets](https://cloud.google.com/storage/docs/insights/datasets)
+
+  <img src="./assets/storage_insights_filter.gif" width="80%" alt="Easy Access Demo">
+
 ## 🚀 Getting Started
 
 ### Prerequisites
@@ -126,21 +138,24 @@ accidental data loss.
 Safe tools are read-only or only create new objects without affecting existing
 ones. They will never modify or delete existing data in GCS.
 
-| Tool                    | Description                                                                     |
-| :---------------------- | :------------------------------------------------------------------------------ |
-| `list_buckets`          | Lists all buckets in a project.                                                 |
-| `get_bucket_metadata`   | Gets comprehensive metadata for a specific bucket.                              |
-| `get_bucket_location`   | Gets the location of a bucket.                                                  |
-| `view_iam_policy`       | Views the IAM policy for a bucket.                                              |
-| `check_iam_permissions` | Tests IAM permissions for a bucket.                                             |
-| `create_bucket`         | Creates a new bucket. Fails if the bucket already exists.                       |
-| `list_objects`          | Lists objects in a GCS bucket.                                                  |
-| `read_object_metadata`  | Reads comprehensive metadata for a specific object.                             |
-| `read_object_content`   | Reads the content of a specific object.                                         |
-| `download_object`       | Downloads an object from GCS to a local file.                                   |
-| `write_object_new`      | Writes a new object. Fails if the object already exists.                        |
-| `upload_object_new`     | Uploads a file to a new object. Fails if the object already exists.             |
-| `copy_object_new`       | Copies an object to a new destination. Fails if the destination already exists. |
+| Tool                        | Description                                                                                                                 |
+| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
+| `list_buckets`              | Lists all buckets in a project.                                                                                             |
+| `get_bucket_metadata`       | Gets comprehensive metadata for a specific bucket.                                                                          |
+| `get_bucket_location`       | Gets the location of a bucket.                                                                                              |
+| `view_iam_policy`           | Views the IAM policy for a bucket.                                                                                          |
+| `check_iam_permissions`     | Tests IAM permissions for a bucket.                                                                                         |
+| `create_bucket`             | Creates a new bucket. Fails if the bucket already exists.                                                                   |
+| `list_objects`              | Lists objects in a GCS bucket.                                                                                              |
+| `read_object_metadata`      | Reads comprehensive metadata for a specific object.                                                                         |
+| `read_object_content`       | Reads the content of a specific object.                                                                                     |
+| `download_object`           | Downloads an object from GCS to a local file.                                                                               |
+| `write_object_new`          | Writes a new object. Fails if the object already exists.                                                                    |
+| `upload_object_new`         | Uploads a file to a new object. Fails if the object already exists.                                                         |
+| `copy_object_new`           | Copies an object to a new destination. Fails if the destination already exists.                                             |
+| `get_metadata_table_schema` | Checks if GCS insights service is enabled and returns the BigQuery table schema for a given insights dataset configuration. |
+| `execute_insights_query`    | Executes a BigQuery SQL query against an insights dataset and returns the result.                                           |
+| `list_insights_configs`     | Lists the names of all Storage Insights dataset configurations for a given project.                                         |
 
 ### Destructive Tools
 
@@ -179,7 +194,7 @@ We welcome contributions! Whether you're fixing bugs, sharing feedback, or
 improving documentation, your contributions are welcome. Please read our
 [Contributing Guide](CONTRIBUTING.md) to get started.
 
-## 🎬 Demo
+## 🎬 Demos
 
 <p align="center"><b>Click to watch the Storage MCP demo</b><br/>
 <a href="./assets/storage_mcp_demo.mp4" title="Click to play demo">
@@ -187,6 +202,12 @@ improving documentation, your contributions are welcome. Please read our
 </a>
 </p>
 
+<p align="center"><b>Click to watch the Storage MCP demo powered by Storage Insights</b><br/>
+<a href="./assets/storage_insights_demo.mp4" title="Click to play demo">
+<img width="80%" alt="Storage Insights MCP Demo Video" src="./assets/storage_insights_demo_thumbnail.png">
+</a>
+</p>
+
 ## 📄 Important Notes
 
 This repository is currently in preview and may see breaking changes. This

package/dist/bundle.js

@@ -13675,11 +13675,11 @@ var McpServer = class {
     this._registeredPrompts[name] = registeredPrompt;
     return registeredPrompt;
   }
-  _createRegisteredTool(name, title, description, inputSchema22, outputSchema, annotations, callback) {
+  _createRegisteredTool(name, title, description, inputSchema25, outputSchema, annotations, callback) {
     const registeredTool = {
       title,
       description,
-      inputSchema: inputSchema22 === void 0 ? void 0 : external_exports.object(inputSchema22),
+      inputSchema: inputSchema25 === void 0 ? void 0 : external_exports.object(inputSchema25),
       outputSchema: outputSchema === void 0 ? void 0 : external_exports.object(outputSchema),
       annotations,
       callback,
@@ -13721,7 +13721,7 @@ var McpServer = class {
       throw new Error(`Tool ${name} is already registered`);
     }
     let description;
-    let inputSchema22;
+    let inputSchema25;
     let outputSchema;
     let annotations;
     if (typeof rest[0] === "string") {
@@ -13730,7 +13730,7 @@ var McpServer = class {
     if (rest.length > 1) {
       const firstArg = rest[0];
       if (isZodRawShape(firstArg)) {
-        inputSchema22 = rest.shift();
+        inputSchema25 = rest.shift();
         if (rest.length > 1 && typeof rest[0] === "object" && rest[0] !== null && !isZodRawShape(rest[0])) {
           annotations = rest.shift();
         }
@@ -13739,7 +13739,7 @@ var McpServer = class {
       }
     }
     const callback = rest[0];
-    return this._createRegisteredTool(name, void 0, description, inputSchema22, outputSchema, annotations, callback);
+    return this._createRegisteredTool(name, void 0, description, inputSchema25, outputSchema, annotations, callback);
   }
   /**
    * Registers a tool with a config object and callback.
@@ -13748,8 +13748,8 @@ var McpServer = class {
     if (this._registeredTools[name]) {
       throw new Error(`Tool ${name} is already registered`);
     }
-    const { title, description, inputSchema: inputSchema22, outputSchema, annotations } = config;
-    return this._createRegisteredTool(name, title, description, inputSchema22, outputSchema, annotations, cb);
+    const { title, description, inputSchema: inputSchema25, outputSchema, annotations } = config;
+    return this._createRegisteredTool(name, title, description, inputSchema25, outputSchema, annotations, cb);
   }
   prompt(name, ...rest) {
     if (this._registeredPrompts[name]) {
@@ -13851,10 +13851,16 @@ var EMPTY_COMPLETION_RESULT = {
 };
 
 // src/utility/api_client_factory.ts
+import { BigQuery } from "@google-cloud/bigquery";
 import { Storage } from "@google-cloud/storage";
+import { ServiceUsageClient } from "@google-cloud/service-usage";
+import { StorageInsightsClient } from "@google-cloud/storageinsights";
 var ApiClientFactory = class _ApiClientFactory {
   static instance;
   storageClient;
+  serviceUsageClient;
+  storageInsightsClient;
+  bigqueryClient;
   constructor() {
   }
   static getInstance() {
@@ -13869,6 +13875,24 @@ var ApiClientFactory = class _ApiClientFactory {
     }
     return this.storageClient;
   }
+  getServiceUsageClient() {
+    if (!this.serviceUsageClient) {
+      this.serviceUsageClient = new ServiceUsageClient();
+    }
+    return this.serviceUsageClient;
+  }
+  getStorageInsightsClient() {
+    if (!this.storageInsightsClient) {
+      this.storageInsightsClient = new StorageInsightsClient();
+    }
+    return this.storageInsightsClient;
+  }
+  getBigQueryClient() {
+    if (!this.bigqueryClient) {
+      this.bigqueryClient = new BigQuery();
+    }
+    return this.bigqueryClient;
+  }
 };
 var apiClientFactory = ApiClientFactory.getInstance();
 
@@ -15588,6 +15612,443 @@ var registerWriteObjectSafeTool = (server) => {
   );
 };
 
+// src/tools/insights/get_metadata_table_schema.ts
+var serviceName = "storageinsights.googleapis.com";
+var inputSchema22 = {
+  datasetConfigName: external_exports.string().describe("The name of the dataset configuration."),
+  datasetConfigLocation: external_exports.string().describe("The location of the dataset configuration."),
+  projectId: external_exports.string().optional().describe("The project ID to check Storage Insights availability for.")
+};
+async function getMetadataTableSchema(params) {
+  const bigqueryClient = apiClientFactory.getBigQueryClient();
+  const storageInsightsClient = apiClientFactory.getStorageInsightsClient();
+  const serviceUsageClient = apiClientFactory.getServiceUsageClient();
+  const projectId = params.projectId || process.env["GOOGLE_CLOUD_PROJECT"] || process.env["GCP_PROJECT_ID"];
+  if (!projectId) {
+    throw new Error(
+      "Project ID not specified. Please specify via the projectId parameter or GOOGLE_CLOUD_PROJECT or GCP_PROJECT_ID environment variable."
+    );
+  }
+  const [services] = await serviceUsageClient.listServices({
+    parent: `projects/${projectId}`,
+    filter: "state:ENABLED"
+  });
+  const isEnabled = services.some(
+    (service) => service.config?.name === serviceName
+  );
+  if (!isEnabled) {
+    throw new Error(
+      `Storage Insights API is not enabled for project ${projectId}. Please enable it to proceed.`
+    );
+  }
+  let config;
+  try {
+    [config] = await storageInsightsClient.getDatasetConfig({
+      name: `projects/${projectId}/locations/${params.datasetConfigLocation}/datasetConfigs/${params.datasetConfigName}`
+    });
+  } catch (error) {
+    const err = error instanceof Error ? error : void 0;
+    logger.error("Error getting dataset config:", err);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: "Failed to retrieve dataset configuration",
+            details: err?.message
+          })
+        }
+      ]
+    };
+  }
+  const objectHints = /* @__PURE__ */ new Map([
+    ["snapshotTime", "The snapshot time of the object metadata in RFC 3339 format."],
+    ["bucket", "The name of the bucket containing this object."],
+    ["location", "The location of the source bucket."],
+    [
+      "componentCount",
+      "Returned for composite objects only. Number of non-composite objects in the composite object."
+    ],
+    ["contentDisposition", "Content-Disposition of the object data."],
+    ["contentEncoding", "Content-Encoding of the object data."],
+    ["contentLanguage", "Content-Language of the object data."],
+    [
+      "contentType",
+      "Content-Type of the object data. If an object is stored without a Content-Type, it is served as application/octet-stream."
+    ],
+    [
+      "crc32c",
+      "CRC32c checksum, as described in RFC 4960, Appendix B; encoded using base64 in big-endian byte order."
+    ],
+    ["customTime", "A user-specified timestamp for the object in RFC 3339 format."],
+    ["etag", "HTTP 1.1 Entity tag for the object."],
+    ["eventBasedHold", "Whether or not the object is subject to an event-based hold."],
+    ["generation", "The content generation of this object. Used for object versioning."],
+    [
+      "md5Hash",
+      "MD5 hash of the data, encoded using base64. This field is not present for composite objects."
+    ],
+    ["mediaLink", "A URL for downloading the object's data."],
+    ["metadata", "User-provided metadata, in key/value pairs."],
+    ["metadata.key", "An individual metadata entry key."],
+    ["metadata.value", "An individual metadata entry value."],
+    ["metageneration", "The version of the metadata for this object at this generation."],
+    ["name", "The name of the object."],
+    ["selfLink", "A URL for this object."],
+    ["size", "Content-Length of the data in bytes."],
+    ["storageClass", "Storage class of the object."],
+    ["temporaryHold", "Whether or not the object is subject to a temporary hold."],
+    ["timeCreated", "The creation time of the object in RFC 3339 format."],
+    [
+      "timeDeleted",
+      "The deletion time of the object in RFC 3339 format. Returned if and only if this version of the object is no longer a live version, but remains in the bucket as a noncurrent version."
+    ],
+    ["updated", "The modification time of the object metadata in RFC 3339 format."],
+    ["timeStorageClassUpdated", "The time at which the object's storage class was last changed."],
+    [
+      "retentionExpirationTime",
+      "The earliest time that the object can be deleted, in RFC 3339 format."
+    ],
+    [
+      "softDeleteTime",
+      "If this object has been soft-deleted, this is the time at which it became soft-deleted."
+    ],
+    [
+      "hardDeleteTime",
+      "This is the time (in the future) when the object will no longer be restorable."
+    ],
+    ["project", "The project number of the project the bucket belongs to."]
+  ]);
+  const bucketHints = /* @__PURE__ */ new Map([
+    ["snapshotTime", "The snapshot time of the metadata in RFC 3339 format."],
+    ["name", "The name of the source bucket."],
+    ["location", 'The location of the source bucket (e.g., "US", "EU", "ASIA-EAST1").'],
+    ["project", "The project number of the project the bucket belongs to."],
+    [
+      "storageClass",
+      `The bucket's default storage class (e.g., "STANDARD", "NEARLINE", "COLDLINE").`
+    ],
+    [
+      "public.bucketPolicyOnly",
+      "Deprecated field. Whether to enforcement uniform bucket-level access. This concept is now represented by iamConfiguration.uniformBucketLevelAccess.enabled."
+    ],
+    [
+      "public.publicAccessPrevention",
+      `The bucket's public access prevention status ("inherited" or "enforced"). This is the same setting as iamConfiguration.publicAccessPrevention.`
+    ],
+    ["autoclass.enabled", "Whether Autoclass is enabled for the bucket."],
+    ["autoclass.toggleTime", "The time Autoclass was last enabled or disabled."],
+    ["versioning", "Boolean indicating if Object Versioning is enabled for the bucket."],
+    [
+      "lifecycle",
+      "Boolean indicating if the bucket has an Object Lifecycle Management configuration."
+    ],
+    ["metageneration", "The metadata generation of this bucket."],
+    [
+      "timeCreated",
+      "The creation time of the bucket in RFC 3339 format. To perform date calculations, use DATE_SUB or DATE_ADD with CURRENT_DATE()"
+    ],
+    ["tags.tagMap.key", "The key of a tag."],
+    ["tags.tagMap.value", "The value of a tag."],
+    ["tags.lastUpdatedTime", "The last updated time for the tags."],
+    ["labels.key", "An individual label entry key."],
+    ["labels.value", "An individual label entry value."],
+    [
+      "softDeletePolicy.retentionDurationSeconds",
+      "The duration in seconds that soft-deleted objects will be retained."
+    ],
+    [
+      "softDeletePolicy.effectiveTime",
+      "The time from which the soft delete policy became effective."
+    ],
+    [
+      "iamConfiguration.uniformBucketLevelAccess.enabled",
+      "If True, Uniform bucket-level access is enabled, disabling object-level ACLs. This replaces the legacy public.bucketPolicyOnly field."
+    ],
+    [
+      "iamConfiguration.publicAccessPrevention",
+      `The bucket's public access prevention status ("inherited" or "enforced"). This is the same setting as public.publicAccessPrevention.`
+    ],
+    [
+      "resourceTags",
+      "This field appears to be redundant. Bucket resource tags are properly represented under the tags field."
+    ],
+    [
+      "objectCount",
+      "Total number of objects in the bucket. This is a recent addition for aggregated bucket metrics."
+    ],
+    [
+      "totalSize",
+      "Total size of the bucket in bytes. This is a recent addition for aggregated bucket metrics."
+    ]
+  ]);
+  try {
+    const linkedDataset = config.link?.dataset;
+    if (linkedDataset) {
+      const parts = linkedDataset.split("/");
+      const datasetId = parts[parts.length - 1];
+      if (!datasetId) {
+        throw new Error("Could not extract dataset ID from linked dataset.");
+      }
+      const bucketViewId = "bucket_attributes_latest_snapshot_view";
+      const objectViewId = "object_attributes_latest_snapshot_view";
+      const [bucketViewMetadata] = await bigqueryClient.dataset(datasetId).table(bucketViewId).getMetadata();
+      const [objectViewMetadata] = await bigqueryClient.dataset(datasetId).table(objectViewId).getMetadata();
+      const bucketViewFields = bucketViewMetadata.schema.fields.map(
+        (field) => {
+          const fieldWithHint = { ...field };
+          if (field.name && bucketHints.has(field.name)) {
+            fieldWithHint.hint = bucketHints.get(field.name);
+          }
+          return fieldWithHint;
+        }
+      );
+      const objectViewFields = objectViewMetadata.schema.fields.map(
+        (field) => {
+          const fieldWithHint = { ...field };
+          if (field.name && objectHints.has(field.name)) {
+            fieldWithHint.hint = objectHints.get(field.name);
+          }
+          return fieldWithHint;
+        }
+      );
+      const result = {
+        [`${datasetId}.${bucketViewId}`]: bucketViewFields,
+        [`${datasetId}.${objectViewId}`]: objectViewFields,
+        ...config
+      };
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result)
+          }
+        ]
+      };
+    }
+    throw new Error("Configuration does not have a linked dataset.");
+  } catch (error) {
+    const err = error instanceof Error ? error : void 0;
+    logger.error("Error getting metadata table schema:", err);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: "Failed to get metadata table schema",
+            details: err?.message
+          })
+        }
+      ]
+    };
+  }
+}
+var registerGetMetadataTableSchemaTool = (server) => {
+  server.registerTool(
+    "get_metadata_table_schema",
+    {
+      description: "Checks if GCS insights service is enabled and returns the BigQuery table schema for a given insights dataset configuration in JSON format. Also returns hints for each column in the table",
+      inputSchema: inputSchema22,
+      annotations: {
+        displayOutput: false
+      }
+    },
+    getMetadataTableSchema
+  );
+};
+
+// src/tools/insights/execute_insights_query.ts
+var inputSchema23 = {
+  config: external_exports.string().describe(
+    "The JSON object of the BigQuery table schema for a given insights dataset configuration."
+  ),
+  query: external_exports.string().describe("The BigQuery SQL query to execute."),
+  jobTimeoutMs: external_exports.number().optional().default(2e4).describe("The maximum amount of time for the job to run on the server.")
+};
+async function executeInsightsQuery(params) {
+  const bigqueryClient = apiClientFactory.getBigQueryClient();
+  try {
+    let config;
+    try {
+      config = JSON.parse(params.config);
+    } catch (_e) {
+      throw new Error("Invalid configuration provided. Expected a JSON object or a JSON string.");
+    }
+    if (typeof config !== "object" || config === null) {
+      throw new Error("Invalid configuration provided. Expected a JSON object.");
+    }
+    const linkedDataset = config.link?.dataset;
+    if (!linkedDataset) {
+      throw new Error("The provided configuration is missing the `link.dataset` property.");
+    }
+    const nameParts = config.name?.split("/");
+    if (!nameParts || nameParts.length < 4) {
+      throw new Error(
+        "Invalid configuration name format. Expected `projects/{projectId}/locations/{locationId}/datasetConfigs/{datasetConfigId}`."
+      );
+    }
+    const projectId = nameParts[1];
+    const datasetId = linkedDataset.split("/").pop();
+    const location = nameParts[3];
+    if (!location) {
+      throw new Error("Could not extract location from the configuration name.");
+    }
+    if (!datasetId) {
+      throw new Error("Could not extract datasetId from the linked dataset.");
+    }
+    const baseQueryOptions = {
+      query: params.query,
+      jobTimeoutMs: params.jobTimeoutMs,
+      location
+    };
+    const options = {};
+    if (projectId) {
+      options.projectId = projectId;
+    }
+    logger.info(`Executing query with location: ${location}`);
+    logger.info(`Executing query with datasetId: ${datasetId}`);
+    logger.info(`Executing query with projectId: ${projectId}`);
+    logger.info("Performing BigQuery dry run...");
+    try {
+      const [dryRunJob] = await bigqueryClient.dataset(datasetId, options).createQueryJob({
+        ...baseQueryOptions,
+        dryRun: true
+      });
+      logger.info(`Dry run successful for query. Job ID: ${dryRunJob.id}`);
+    } catch (error) {
+      const err = error;
+      logger.error("BigQuery dry run failed:", err);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              error: "Validation failed: Invalid BigQuery SQL or access error during dry run",
+              error_type: "QueryValidationError",
+              details: err?.message
+            })
+          }
+        ]
+      };
+    }
+    logger.info("Dry run passed. Executing BigQuery query...");
+    const [job] = await bigqueryClient.dataset(datasetId, options).createQueryJob(baseQueryOptions);
+    logger.info(`Job ${job.id} started.`);
+    const [rows] = await job.getQueryResults();
+    logger.info(`Successfully executed query.`);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(rows)
+        }
+      ]
+    };
+  } catch (error) {
+    const err = error;
+    logger.error("Error executing insights query:", err);
+    let errorType = "Unknown";
+    if (err.message.includes("Job timed out")) {
+      errorType = "Timeout";
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: "Failed to execute insights query",
+            error_type: errorType,
+            details: err?.message
+          })
+        }
+      ]
+    };
+  }
+}
+var registerExecuteInsightsQueryTool = (server) => {
+  server.registerTool(
+    "execute_insights_query",
+    {
+      description: "Executes a BigQuery SQL query against an insights dataset and returns the result.",
+      inputSchema: inputSchema23
+    },
+    executeInsightsQuery
+  );
+};
+
+// src/tools/insights/list_insights_configs.ts
+var serviceName2 = "storageinsights.googleapis.com";
+var inputSchema24 = {
+  projectId: external_exports.string().optional().describe("The project ID to list Storage Insights dataset configurations for.")
+};
+async function listInsightsConfigs(params) {
+  const storageInsightsClient = apiClientFactory.getStorageInsightsClient();
+  const serviceUsageClient = apiClientFactory.getServiceUsageClient();
+  const projectId = params.projectId || process.env["GOOGLE_CLOUD_PROJECT"] || process.env["GCP_PROJECT_ID"];
+  if (!projectId) {
+    throw new Error(
+      "Project ID not specified. Please specify via the projectId parameter or GOOGLE_CLOUD_PROJECT or GCP_PROJECT_ID environment variable."
+    );
+  }
+  const [services] = await serviceUsageClient.listServices({
+    parent: `projects/${projectId}`,
+    filter: "state:ENABLED"
+  });
+  const isEnabled = services.some(
+    (service) => service.config?.name === serviceName2
+  );
+  if (!isEnabled) {
+    throw new Error(
+      `Storage Insights API is not enabled for project ${projectId}. Please enable it to proceed.`
+    );
+  }
+  try {
+    const parent = `projects/${projectId}/locations/-`;
+    const iterable = storageInsightsClient.listDatasetConfigsAsync({ parent });
+    const configNames = [];
+    for await (const config of iterable) {
+      if (config.name) {
+        configNames.push(config.name);
+      }
+    }
+    logger.info(`Successfully listed ${configNames.length} dataset config names.`);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            configurations: configNames
+          })
+        }
+      ]
+    };
+  } catch (error) {
+    const err = error instanceof Error ? error : void 0;
+    logger.error("Error listing dataset configs:", err);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: "Failed to list dataset configurations",
+            details: err?.message
+          })
+        }
+      ]
+    };
+  }
+}
+var registerListInsightsConfigsTool = (server) => {
+  server.registerTool(
+    "list_insights_configs",
+    {
+      description: "Lists the names of all Storage Insights dataset configurations for a given project.",
+      inputSchema: inputSchema24
+    },
+    listInsightsConfigs
+  );
+};
+
 // src/tools/index.ts
 var commonSafeTools = [
   registerListBucketsTool,
@@ -15600,7 +16061,10 @@ var commonSafeTools = [
   registerReadObjectContentTool,
   registerReadObjectMetadataTool,
   registerDownloadObjectTool,
-  registerDeleteObjectTool
+  registerDeleteObjectTool,
+  registerGetMetadataTableSchemaTool,
+  registerExecuteInsightsQueryTool,
+  registerListInsightsConfigsTool
 ];
 var safeWriteTools = [
   registerWriteObjectSafeTool,
@@ -15717,7 +16181,7 @@ var StdioServerTransport = class {
 // package.json
 var package_default = {
   name: "@google-cloud/storage-mcp",
-  version: "0.2.0",
+  version: "0.3.0",
   type: "module",
   main: "dist/bundle.js",
   bin: {
@@ -15777,7 +16241,10 @@ var package_default = {
     vitest: "^3.2.4"
   },
   dependencies: {
+    "@google-cloud/bigquery": "^7.0.0",
+    "@google-cloud/service-usage": "^4.2.0",
     "@google-cloud/storage": "^7.17.1",
+    "@google-cloud/storageinsights": "^2.2.0",
     "@modelcontextprotocol/sdk": "^1.17.1",
     "@types/yargs": "^17.0.33",
     chardet: "^2.1.0",
@@ -21141,6 +21608,18 @@ For example, you can use the tools to:
 
 - **Clarify Ambiguity:** Do not guess or assume values for required parameters like bucket names. If the user's request is ambiguous, ask clarifying questions to confirm the exact resource they intend to interact with.
 - **Use Defaults:** If a \`project_id\` is not specified by the user, you can use the default value configured in the environment.
+- **Terminology Grounding:** When users ask for "insights datasets," they are referring to BigQuery datasets populated by Storage Insights Configurations.
+  Do NOT confuse this with legacy "Inventory Reports" (which export CSV/Parquet files to GCS).
+- **Insights Intent Identification:** There is a set of 3 tools called Insights tool which you have to use whenever you detect an Storage Insights intent.
+  To identify "Storage Insights Intent" queries, look for prompts focused on analyzing Google Cloud Storage configuration metadata. These requests typically stem from cost optimization, security auditing, or data governance needs. Users ask to aggregate, filter, or or analyze "buckets" and "objects" based on attributes like "size," "age," "location," and "storage class." Key indicators include checks on configurations such as "public access prevention," "versioning," and "lifecycle policies." The queries often involve complex operations, including statistical analysis (correlations, percentiles), ranking, and filtering based on user-defined "tags" or "labels" across projects and regions.
+- **Insights Intent Handling:** Queries identified to have a "Storage Insights Intent" MUST be handled by generating BigQuery SQL queries against Storage Insights datasets. Example: "What is the total size of my storage?", "Which bucket has the most objects?", "Show the distribution of my storage classes."
+  If the intent is classified as " Storage Insights Intent", proceed to execute the below steps in order:
+
+1. Check if the user provided the \`config_name\` and \`config_location\` of the dataset configuration. If not then ask the user for the \`config_name\` and \`config_location\` of the dataset configuration they would like to use and remember it.
+2. If the dataset configuration is available then pass this dataset configuration name and location to get_metadata_table_schema which will return the schema with some hints. If the dataset config name is returned as incorrect, call the list_insights_configs tool and then ask the user to select the correct dataset configuration name and location again and don't list the available configs unless user explicitly asks for it and retry getting the metadata table schema. Remember the schema for the remaining session unless user asks to change the dataset.
+3. Once you have the dataset table schema, use it to draft query/queries and call the execute_insights_query tool get relevant data. If the query fails due to some reason, correct it and retry.
+   **Note on BigQuery Table References:** When constructing BigQuery SQL queries, ensure that table references are fully qualified with the project ID. The format should be \`project_id.dataset_id.table_id\`. For example, if the project ID is \`my-gcp-project\`, the dataset ID is \`my_dataset\`, and the table ID is \`my_table\`, the reference in the query should be \`my-gcp-project.my_dataset.my_table\`.
+4. Based on the query results, answer the users query.
 
 ## GCS Reference Documentation