@gcnv/gcnv-mcp-server 1.1.5 → 1.1.6

package/GEMINI.md

@@ -34,9 +34,9 @@ Use this link to explain billing and estimate pricing (pair with the Google Clou
 - Never guess resource identifiers. Always collect `projectId`, `location`, and resource-specific IDs explicitly.
 - Validate numeric fields (e.g., `capacityGib`) and repeat key parameters back to the user before running a tool.
 - Validate `location` format:
-  - For most tools, `location` is a **region** (e.g., `us-central1`).
-  - For **FLEX storage pool creation**, `location` may be a **zone** (e.g., `us-central1-a`) to satisfy “zone in location”.
-  - If FLEX pool creation uses a regional `location`, the user must provide `zone` and `replicaZone`.
+  - **Region or zone are both valid.** The API accepts either a **region** (e.g., `us-central1`, `us-west1`) or a **zone** (e.g., `us-central1-a`, `us-west1-b`). Use whichever the user specified—e.g. if they say "list my volumes in us-west1-b", pass `location: "us-west1-b"`; do not correct or reject zones.
+  - For **FLEX storage pool creation** only: if `location` is a **zone** (e.g., `us-central1-a`), that satisfies "zone in location" and you can omit `zone`/`replicaZone`. If `location` is a **region** (e.g., `us-central1`), the user must provide both `zone` and `replicaZone`.
+  - **For list tools (`gcnv_*_list`), `location` is optional.** If the user does not specify a location (e.g. "list my storage pools", "list all volumes"), omit the `location` parameter or pass `-`; the API will return resources from all locations. Do not ask for a location when the user only wants a full list.
 
 ### Request construction
 
@@ -58,6 +58,37 @@ Use this link to explain billing and estimate pricing (pair with the Google Clou
 - Prefer asking clarifying questions over assuming intent.
 - Summaries should be concise but mention important next steps (mount targets, replication follow-ups, etc.).
 
+### List response formatting
+
+- **Always beautify list tool responses in a tabular format.** When you receive results from any `gcnv_*_list` tool (e.g. `gcnv_storage_pool_list`, `gcnv_volume_list`, `gcnv_backup_vault_list`, `gcnv_host_group_list`, etc.), present the data to the user as a **markdown table** instead of raw JSON.
+- **Table structure:**
+  - Use a header row with column names derived from the list item fields (e.g. Name, ID, State, Location, Capacity, Service Level, Create Time—pick the most relevant fields for that resource type).
+  - **Include details that vary between resources.** Add columns for fields that differ across items (e.g. state, capacity, service level, location, protocol, backup state) so the table is informative and each row is distinguishable. Avoid a one-size-fits-all set of columns—tailor columns to the resource type and to what actually varies in the response.
+  - **Include these bare-minimum columns when present in the response** (so the table is always useful). Add any additional columns that vary and are relevant.
+    - **Storage pools:** name/ID, state, serviceLevel, capacityGib, **volumeCapacityGib**, **volumeCount** (or volumecount), **encryptionType**, **allowAutoTiering**, **totalThroughputMibps**, qosType, zone, replicaZone, createTime.
+    - **Volumes:** name/volumeId, state, capacityGib, usedGib, protocols, serviceLevel, **encryptionType**, **throughputMibps** (or availableThroughputMibps), **coldTierSizeGib**, **hotTierSizeUsedGib** (or hotTierSizeGib), tieringPolicy, createTime, storagePool.
+    - **Snapshots:** name/snapshotId, volumeId, state, createTime, description.
+    - **Backups:** backupId, backupVaultId, state, sourceVolume, backupType, volumeUsagebytes, chainStoragebytes, createTime, retentionDays.
+    - **Backup vaults:** backupVaultId, state, backupVaultType, sourceRegion, backupRegion, createTime.
+    - **Backup policies:** backupPolicyId, state, enabled, dailyBackupLimit, weeklyBackupLimit, monthlyBackupLimit, assignedVolumeCount, createTime.
+    - **Host groups:** hostGroupId, type, state, hosts (count or summary), osType, createTime.
+    - **KMS configs:** kmsConfigId, state, cryptoKeyName, stateDetails, createTime.
+    - **Replications:** replicationId, sourceVolume, destinationVolume, state, healthy, lastReplicationTime, createTime.
+    - **Quota rules:** quotaRuleId, target, quotaType, diskLimitMib, state, createTime.
+    - **Operations:** name (or operationId), done, success, target, verb, createTime, statusMessage.
+    - **Active directories:** activeDirectoryId, domain, site, state, createTime.
+  - One row per item; keep cells concise (e.g. short IDs, not full resource names unless needed).
+  - If the list is empty, say so clearly (e.g. "No storage pools found.") instead of showing an empty table.
+- **State column: mark states with icons.** In the State (or equivalent) column, prefix or replace raw state values with a short, clear icon so status is scannable at a glance. Examples:
+  - **Ready / READY / Healthy / Active:** ✅ or 🟢
+  - **Creating / Updating / Pending / In progress:** ⏳ or 🔄
+  - **Error / Failed / Unhealthy:** ❌ or 🔴
+  - **Deleting / Stopping:** 🗑️ or ⏹️
+  - **Unknown / Unspecified:** ⚪ or ❓
+    Use one style consistently (e.g. always emoji) and keep the actual state text next to the icon when helpful (e.g. `✅ READY` or `🟢 Healthy`).
+- **Pagination:** If the response includes `nextPageToken`, mention it below the table (e.g. "More results are available; provide this token to fetch the next page.") and show the token.
+- **Do not** dump the raw tool output unless the user explicitly asks for JSON or full details.
+
 ---
 
 # Tool Overview
@@ -250,4 +281,5 @@ Notes:
 - Ask follow-up questions instead of assuming missing parameters.
 - Keep answers short unless the user asks for details.
 - When returning tool results, highlight only key fields unless the user requests full JSON.
+- **For list tool results:** Always present the items in a **tabular (markdown table) format**—do not show raw JSON by default.
 - Maintain safety-first decision making for all operations.

package/build/tools/active-directory-tools.js

@@ -74,10 +74,13 @@ export const getActiveDirectoryTool = {
 export const listActiveDirectoriesTool = {
     name: 'gcnv_active_directory_list',
     title: 'List Active Directories',
-    description: 'Lists all active directories in the specified location',
+    description: 'Lists all active directories in the specified location (omit location for all locations)',
     inputSchema: {
         projectId: z.string().describe('The ID of the Google Cloud project'),
-        location: z.string().describe('The location to list active directories from'),
+        location: z
+            .string()
+            .optional()
+            .describe('The location to list active directories from; omit or use "-" for all locations'),
         filter: z.string().optional().describe('Filter expression'),
         pageSize: z.number().optional().describe('Maximum number of items to return'),
         pageToken: z.string().optional().describe('Page token from previous request'),

package/build/tools/backup-policy-tools.js

@@ -75,10 +75,13 @@ export const getBackupPolicyTool = {
 export const listBackupPoliciesTool = {
     name: 'gcnv_backup_policy_list',
     title: 'List Backup Policies',
-    description: 'Lists backup policies in a specific project and location',
+    description: 'Lists backup policies in a specific project and location (omit location for all locations)',
     inputSchema: {
         projectId: z.string().describe('The ID of the Google Cloud project'),
-        location: z.string().describe('The location to list backup policies from'),
+        location: z
+            .string()
+            .optional()
+            .describe('The location to list backup policies from; omit or use "-" for all locations'),
         filter: z.string().optional().describe('Filter expression for filtering results'),
         pageSize: z
             .number()

package/build/tools/backup-tools.js

@@ -85,10 +85,13 @@ export const getBackupTool = {
 export const listBackupsTool = {
     name: 'gcnv_backup_list',
     title: 'List Backups',
-    description: 'Lists backups in a specific backup vault',
+    description: 'Lists backups in a specific backup vault (omit location for all locations)',
     inputSchema: {
         projectId: z.string().describe('The ID of the Google Cloud project'),
-        location: z.string().describe('The location to list backups from'),
+        location: z
+            .string()
+            .optional()
+            .describe('The location to list backups from; omit or use "-" for all locations'),
         backupVaultId: z.string().describe('The ID of the backup vault containing the backups'),
         filter: z.string().optional().describe('Filter expression for filtering results'),
         pageSize: z.number().optional().describe('Maximum number of backups to return per page'),

package/build/tools/backup-vault-tools.js

@@ -108,10 +108,13 @@ export const getBackupVaultTool = {
 export const listBackupVaultsTool = {
     name: 'gcnv_backup_vault_list',
     title: 'List Backup Vaults',
-    description: 'Lists backup vaults in a specific project and location',
+    description: 'Lists backup vaults in a specific project and location (omit location for all locations)',
     inputSchema: {
         projectId: z.string().describe('The ID of the Google Cloud project'),
-        location: z.string().describe('The location to list backup vaults from'),
+        location: z
+            .string()
+            .optional()
+            .describe('The location to list backup vaults from; omit or use "-" for all locations'),
         filter: z.string().optional().describe('Filter expression for filtering results'),
         pageSize: z.number().optional().describe('Maximum number of backup vaults to return per page'),
         pageToken: z.string().optional().describe('Page token from a previous list request'),

package/build/tools/handlers/active-directory-handler.js

@@ -180,7 +180,8 @@ export const getActiveDirectoryHandler = async (args) => {
 // List Active Directories Handler
 export const listActiveDirectoriesHandler = async (args) => {
     try {
-        const { projectId, location, filter, pageSize, pageToken } = args;
+        const { projectId, filter, pageSize, pageToken } = args;
+        const location = args.location ?? '-';
         const netAppClient = NetAppClientFactory.createClient();
         const parent = `projects/${projectId}/locations/${location}`;
         const request = { parent };

package/build/tools/handlers/backup-handler.js

@@ -242,10 +242,11 @@ export const getBackupHandler = async (args) => {
 // List Backups Handler
 export const listBackupsHandler = async (args) => {
     try {
-        const { projectId, location, backupVaultId, filter, pageSize, pageToken } = args;
+        const { projectId, backupVaultId, filter, pageSize, pageToken } = args;
+        const location = args.location ?? '-';
         // Create a new NetApp client using the factory
         const netAppClient = NetAppClientFactory.createClient();
-        // Format the parent path for listing backups
+        // Format the parent path for listing backups (use "-" for all locations)
         const parent = `projects/${projectId}/locations/${location}/backupVaults/${backupVaultId}`;
         // List the backups
         const options = {

package/build/tools/handlers/backup-policy-handler.js

@@ -147,9 +147,10 @@ export const getBackupPolicyHandler = async (args) => {
  */
 export const listBackupPoliciesHandler = async (args) => {
     try {
-        const { projectId, location, filter, pageSize, pageToken } = args;
+        const { projectId, filter, pageSize, pageToken } = args;
+        const location = args.location ?? '-';
         const client = NetAppClientFactory.createClient();
-        // Format resource name
+        // Format resource name (use "-" for all locations)
         const parent = `projects/${projectId}/locations/${location}`;
         // Call the API to list backup policies
         const [response] = await client.listBackupPolicies({

package/build/tools/handlers/backup-vault-handler.js

@@ -229,10 +229,11 @@ export const getBackupVaultHandler = async (args) => {
 // List Backup Vaults Handler
 export const listBackupVaultsHandler = async (args) => {
     try {
-        const { projectId, location, filter, pageSize, pageToken } = args;
+        const { projectId, filter, pageSize, pageToken } = args;
+        const location = args.location ?? '-';
         // Create a new NetApp client using the factory
         const netAppClient = NetAppClientFactory.createClient();
-        // Format the parent path for listing backup vaults
+        // Format the parent path for listing backup vaults (use "-" for all locations)
         const parent = `projects/${projectId}/locations/${location}`;
         // List the backup vaults
         const options = {

package/build/tools/handlers/host-group-handler.js

@@ -237,10 +237,10 @@ export const getHostGroupHandler = async (args) => {
 // List Host Groups Handler
 export const listHostGroupsHandler = async (args) => {
     try {
-        const { projectId, location, filter, orderBy, pageSize, pageToken } = args;
+        const { projectId, filter, orderBy, pageSize, pageToken } = args;
+        const location = args.location ?? '-';
         const errors = [];
         validateRequiredString(projectId, 'projectId', errors);
-        validateRequiredString(location, 'location', errors);
         if (errors.length > 0) {
             return {
                 isError: true,

package/build/tools/handlers/kms-config-handler.js

@@ -155,7 +155,8 @@ export const getKmsConfigHandler = async (args) => {
 // List KMS Configs Handler
 export const listKmsConfigsHandler = async (args) => {
     try {
-        const { projectId, location, filter, pageSize, pageToken, orderBy } = args;
+        const { projectId, filter, pageSize, pageToken, orderBy } = args;
+        const location = args.location ?? '-';
         const netAppClient = NetAppClientFactory.createClient();
         const parent = `projects/${projectId}/locations/${location}`;
         const request = { parent };

package/build/tools/handlers/operation-handler.js

@@ -171,7 +171,8 @@ export const cancelOperationHandler = async (args) => {
 // List Operations Handler
 export const listOperationsHandler = async (args) => {
     try {
-        const { projectId, location, filter, pageSize, pageToken } = args;
+        const { projectId, filter, pageSize, pageToken } = args;
+        const location = args.location ?? '-';
         // Create a new NetApp client using the factory
         const netAppClient = NetAppClientFactory.createClient();
         // Make a direct API call using the client's auth credentials
@@ -184,7 +185,7 @@ export const listOperationsHandler = async (args) => {
             params.pageSize = pageSize;
         if (pageToken)
             params.pageToken = pageToken;
-        // Make the API request
+        // Make the API request (use "-" for all locations)
         const response = await axios.request({
             url: `https://netapp.googleapis.com/v1/projects/${projectId}/locations/${location}/operations`,
             method: 'GET',

package/build/tools/handlers/quota-rule-handler.js

@@ -268,7 +268,8 @@ export const getQuotaRuleHandler = async (args) => {
 // List Quota Rules Handler
 export const listQuotaRulesHandler = async (args) => {
     try {
-        const { projectId, location, volumeId, filter, pageSize, pageToken, orderBy } = args;
+        const { projectId, volumeId, filter, pageSize, pageToken, orderBy } = args;
+        const location = args.location ?? '-';
         const errors = validatePathArgs({ projectId, location, volumeId }, false);
         const { value: parsedPageSize, error: pageSizeError } = parseOptionalNumber(pageSize, 'pageSize');
         if (pageSizeError)

package/build/tools/handlers/replication-handler.js

@@ -186,10 +186,11 @@ export const getReplicationHandler = async (args) => {
 // List Replications Handler
 export const listReplicationsHandler = async (args) => {
     try {
-        const { projectId, location, volumeId, filter, pageSize, pageToken } = args;
+        const { projectId, volumeId, filter, pageSize, pageToken } = args;
+        const location = args.location ?? '-';
         // Create a new NetApp client using the factory
         const netAppClient = NetAppClientFactory.createClient();
-        // Format the parent path
+        // Format the parent path (use "-" for all locations)
         const parent = `projects/${projectId}/locations/${location}/volumes/${volumeId}`;
         // Create the list request
         const request = { parent };

package/build/tools/handlers/snapshot-handler.js

@@ -163,10 +163,11 @@ export const getSnapshotHandler = async (args) => {
 // List Snapshots Handler
 export const listSnapshotsHandler = async (args) => {
     try {
-        const { projectId, location, volumeId, filter, pageSize, pageToken } = args;
+        const { projectId, volumeId, filter, pageSize, pageToken } = args;
+        const location = args.location ?? '-';
         // Create a new NetApp client using the factory
         const netAppClient = NetAppClientFactory.createClient();
-        // Format the parent path
+        // Format the parent path (use "-" for all locations)
         const parent = `projects/${projectId}/locations/${location}/volumes/${volumeId}`;
         // Create the request object
         const request = { parent };

package/build/tools/handlers/storage-pool-handler.js

@@ -304,10 +304,11 @@ export const getStoragePoolHandler = async (args) => {
 // List Storage Pools Handler
 export const listStoragePoolsHandler = async (args) => {
     try {
-        const { projectId, location, filter, pageSize, pageToken } = args;
+        const { projectId, filter, pageSize, pageToken } = args;
+        const location = args.location ?? '-';
         // Create a new NetApp client using the factory
         const netAppClient = NetAppClientFactory.createClient();
-        // Format the parent path for listing storage pools
+        // Format the parent path for listing storage pools (use "-" for all locations)
         const parent = `projects/${projectId}/locations/${location}`;
         // Call the API to list storage pools
         const [storagePools, , paginated_response] = await netAppClient.listStoragePools({

package/build/tools/handlers/volume-handler.js

@@ -430,10 +430,11 @@ export const getVolumeHandler = async (args) => {
 // List Volumes Handler
 export const listVolumesHandler = async (args) => {
     try {
-        const { projectId, location, filter, pageSize, pageToken } = args;
+        const { projectId, filter, pageSize, pageToken } = args;
+        const location = args.location ?? '-';
         // Create a new NetApp client using the factory
         const netAppClient = NetAppClientFactory.createClient();
-        // Format the parent path
+        // Format the parent path (use "-" for all locations)
         const parent = `projects/${projectId}/locations/${location}`;
         // Create the request object
         const request = { parent };

package/build/tools/host-group-tools.js

@@ -25,10 +25,13 @@ export const getHostGroupTool = {
 export const listHostGroupsTool = {
     name: 'gcnv_host_group_list',
     title: 'List Host Groups',
-    description: 'Lists host groups in a specific location',
+    description: 'Lists host groups in a specific location (omit location for all locations)',
     inputSchema: {
         projectId: z.string().describe('The ID of the Google Cloud project'),
-        location: z.string().describe('The location to list host groups from (use "-" for all)'),
+        location: z
+            .string()
+            .optional()
+            .describe('The location to list host groups from; omit or use "-" for all locations'),
         filter: z.string().optional().describe('Filter expression for filtering results'),
         orderBy: z.string().optional().describe('Order by expression'),
         pageSize: z.number().optional().describe('Maximum number of host groups to return per page'),

package/build/tools/kms-config-tools.js

@@ -71,10 +71,13 @@ export const getKmsConfigTool = {
 export const listKmsConfigsTool = {
     name: 'gcnv_kms_config_list',
     title: 'List KMS Configs',
-    description: 'Lists all KMS configurations in the specified location',
+    description: 'Lists all KMS configurations in the specified location (omit location for all locations)',
     inputSchema: {
         projectId: z.string().describe('The ID of the Google Cloud project'),
-        location: z.string().describe('The location to list KMS configs from'),
+        location: z
+            .string()
+            .optional()
+            .describe('The location to list KMS configs from; omit or use "-" for all locations'),
         filter: z.string().optional().describe('Filter expression'),
         pageSize: z.number().optional().describe('Maximum number of items to return'),
         pageToken: z.string().optional().describe('Page token from previous request'),

package/build/tools/operation-tools.js

@@ -39,10 +39,13 @@ export const cancelOperationTool = {
 export const listOperationsTool = {
     name: 'gcnv_operation_list',
     title: 'List Operations',
-    description: 'Lists all active long-running operations in the project',
+    description: 'Lists all active long-running operations in the project (omit location for all locations)',
     inputSchema: {
         projectId: z.string().describe('The ID of the Google Cloud project'),
-        location: z.string().describe('The location to list operations from'),
+        location: z
+            .string()
+            .optional()
+            .describe('The location to list operations from; omit or use "-" for all locations'),
         filter: z.string().optional().describe('Filter expression for operations'),
         pageSize: z.number().optional().describe('The maximum number of operations to return'),
         pageToken: z.string().optional().describe('Page token from a previous list request'),

package/build/tools/quota-rule-tools.js

@@ -90,10 +90,13 @@ export const getQuotaRuleTool = {
 export const listQuotaRulesTool = {
     name: 'gcnv_quota_rule_list',
     title: 'List Quota Rules',
-    description: 'Lists all quota rules for a volume',
+    description: 'Lists all quota rules for a volume (omit location for all locations)',
     inputSchema: {
         projectId: z.string().describe('The ID of the Google Cloud project'),
-        location: z.string().describe('The location of the volume'),
+        location: z
+            .string()
+            .optional()
+            .describe('The location of the volume; omit or use "-" for all locations'),
         volumeId: z.string().describe('The ID of the volume'),
         filter: z.string().optional().describe('Filter expression'),
         pageSize: z.number().optional().describe('Maximum number of items to return'),

package/build/tools/replication-tools.js

@@ -71,10 +71,13 @@ export const getReplicationTool = {
 export const listReplicationsTool = {
     name: 'gcnv_replication_list',
     title: 'List Replications',
-    description: 'Lists all replications in the specified location',
+    description: 'Lists all replications in the specified location (omit location for all locations)',
     inputSchema: {
         projectId: z.string().describe('The ID of the Google Cloud project'),
-        location: z.string().describe('The location to list replications from'),
+        location: z
+            .string()
+            .optional()
+            .describe('The location to list replications from; omit or use "-" for all locations'),
         volumeId: z.string().describe('The ID of the volume for which the replications are listed'),
         filter: z.string().optional().describe('Filter expression for filtering results'),
         pageSize: z.number().optional().describe('The maximum number of replications to return'),

package/build/tools/snapshot-tools.js

@@ -60,10 +60,13 @@ export const getSnapshotTool = {
 export const listSnapshotsTool = {
     name: 'gcnv_snapshot_list',
     title: 'List Snapshots',
-    description: 'Lists all snapshots for a specified volume',
+    description: 'Lists all snapshots for a specified volume (omit location for all locations)',
     inputSchema: {
         projectId: z.string().describe('The ID of the Google Cloud project'),
-        location: z.string().describe('The location of the volume'),
+        location: z
+            .string()
+            .optional()
+            .describe('The location of the volume; omit or use "-" for all locations'),
         volumeId: z.string().describe('The ID of the volume to list snapshots from'),
         filter: z.string().optional().describe('Filter expression for filtering results'),
         pageSize: z.number().optional().describe('The maximum number of snapshots to return'),

package/build/tools/storage-pool-tools.js

@@ -149,10 +149,13 @@ export const getStoragePoolTool = {
 export const listStoragePoolsTool = {
     name: 'gcnv_storage_pool_list',
     title: 'List Storage Pools',
-    description: 'Lists all storage pools in the specified project and location',
+    description: 'Lists all storage pools in the specified project and location (omit location for all locations)',
     inputSchema: {
         projectId: z.string().describe('The ID of the Google Cloud project'),
-        location: z.string().describe('The location to list storage pools from'),
+        location: z
+            .string()
+            .optional()
+            .describe('The location to list storage pools from; omit or use "-" for all locations'),
         filter: z.string().optional().describe('Filter expression for filtering results'),
         pageSize: z.number().optional().describe('The maximum number of storage pools to return'),
         pageToken: z.string().optional().describe('Page token from a previous list request'),

package/build/tools/volume-tools.js

@@ -323,10 +323,13 @@ export const getVolumeTool = {
 export const listVolumesTool = {
     name: 'gcnv_volume_list',
     title: 'List Volumes',
-    description: 'Lists all volumes in the specified storage pool',
+    description: 'Lists all volumes in the specified storage pool (omit location for all locations)',
     inputSchema: {
         projectId: z.string().describe('The ID of the Google Cloud project'),
-        location: z.string().describe('The location to list volumes from'),
+        location: z
+            .string()
+            .optional()
+            .describe('The location to list volumes from; omit or use "-" for all locations'),
         filter: z.string().optional().describe('Filter expression for filtering results'),
         pageSize: z.number().optional().describe('The maximum number of volumes to return'),
         pageToken: z.string().optional().describe('Page token from a previous list request'),

package/gemini-extension.json

@@ -1,5 +1,5 @@
 {
-  "name": "gcnv-mcp",
+  "name": "gcnv-mcp-server",
   "version": "1.0.0",
   "contextFileName": "GEMINI.md",
   "mcpServers": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcnv/gcnv-mcp-server",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "Google Cloud NetApp Volumes MCP Server - A Model Context Protocol server for managing GCNV Backup, StoragePool, Volume and Replication resources",
   "main": "build/index.js",
   "bin": {