From 9afa37f923159ca6f42f8edc15d8895feb8bee64 Mon Sep 17 00:00:00 2001 From: Juexin Wang Date: Wed, 19 Aug 2026 15:22:52 -0700 Subject: [PATCH 1/8] feat: add the cloud-storage MCP server and generate harness manifests --- .claude-plugin/plugin.json | 26 ++++++++++++++++++++++++-- .codex-plugin/.mcp.json | 17 +++++++++++++++++ .codex-plugin/plugin.json | 10 +++++++--- gemini-extension.json | 24 ++++++++++++++++++++++++ mcp.json | 16 ++++++++++++++++ mcp_config.json | 14 ++++++++++++++ plugin.json | 31 +++++++++++++++++++++++++++++-- 7 files changed, 131 insertions(+), 7 deletions(-) create mode 100644 .codex-plugin/.mcp.json create mode 100644 gemini-extension.json create mode 100644 mcp.json create mode 100644 mcp_config.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 7de5e0a..6dc2b7d 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -7,8 +7,30 @@ "email": "gcs-agentic-ai-customer-support@google.com" }, "homepage": "https://cloud.google.com/storage", - "license": "Apache-2.0", "repository": "https://github.com/gemini-cli-extensions/google-cloud-storage", + "license": "Apache-2.0", "skills": "./skills/", - "userConfig": {} + "userConfig": { + "cloud_storage_project": { + "title": "Project ID", + "description": "ID of the Google Cloud project", + "type": "string", + "sensitive": false + } + }, + "mcpServers": { + "cloud-storage": { + "command": "npx", + "args": [ + "-y", + "@toolbox-sdk/server@1.9.0", + "--prebuilt", + "cloud-storage", + "--stdio" + ], + "env": { + "CLOUD_STORAGE_PROJECT": "${user_config.cloud_storage_project}" + } + } + } } diff --git a/.codex-plugin/.mcp.json b/.codex-plugin/.mcp.json new file mode 100644 index 0000000..5a0cc15 --- /dev/null +++ b/.codex-plugin/.mcp.json @@ -0,0 +1,17 @@ +{ + "mcpServers": { + "cloud-storage": { + "command": "npx", + "args": [ + "-y", + "@toolbox-sdk/server@1.9.0", + "--prebuilt", + "cloud-storage", + "--stdio" + ], + "env_vars": [ + "CLOUD_STORAGE_PROJECT" + ] + } + } +} diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 497012e..9ff2c07 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -13,9 +13,12 @@ "gcs", "google-cloud-storage", "storage", - "google-cloud" + "google-cloud", + "cloud storage", + "object storage", + "blob storage" ], - "skills": "./skills/", + "skills": "./skills", "interface": { "displayName": "Google Cloud Storage", "shortDescription": "Google Cloud Storage skills for your coding agent.", @@ -27,5 +30,6 @@ "defaultPrompt": [ "You are a Google Cloud Storage expert assistant. Help the user work with their Google Cloud Storage resources from their coding agent." ] - } + }, + "mcpServers": "./.codex-plugin/.mcp.json" } diff --git a/gemini-extension.json b/gemini-extension.json new file mode 100644 index 0000000..a9fb259 --- /dev/null +++ b/gemini-extension.json @@ -0,0 +1,24 @@ +{ + "name": "google-cloud-storage", + "version": "1.0.0", + "description": "Official Google Cloud Storage (GCS) plugin. Manage buckets and objects, transfer data, and configure MCP, FUSE, IAM, security, lifecycle rules, signed URLs, Terraform, and the CLI.", + "mcpServers": { + "cloud-storage": { + "command": "npx", + "args": [ + "-y", + "@toolbox-sdk/server@1.9.0", + "--prebuilt", + "cloud-storage", + "--stdio" + ] + } + }, + "settings": [ + { + "name": "Project ID", + "description": "ID of the Google Cloud project", + "envVar": "CLOUD_STORAGE_PROJECT" + } + ] +} diff --git a/mcp.json b/mcp.json new file mode 100644 index 0000000..b051242 --- /dev/null +++ b/mcp.json @@ -0,0 +1,16 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", + "mcpServers": { + "cloud-storage": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@toolbox-sdk/server@1.9.0", + "--prebuilt", + "cloud-storage", + "--stdio" + ] + } + } +} diff --git a/mcp_config.json b/mcp_config.json new file mode 100644 index 0000000..704f6ea --- /dev/null +++ b/mcp_config.json @@ -0,0 +1,14 @@ +{ + "mcpServers": { + "cloud-storage": { + "command": "npx", + "args": [ + "-y", + "@toolbox-sdk/server@1.9.0", + "--prebuilt", + "cloud-storage", + "--stdio" + ] + } + } +} diff --git a/plugin.json b/plugin.json index fed84f4..b8d150e 100644 --- a/plugin.json +++ b/plugin.json @@ -1,5 +1,4 @@ { - "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "google-cloud-storage", "version": "1.0.0", "description": "Official Google Cloud Storage (GCS) plugin. Manage buckets and objects, transfer data, and configure MCP, FUSE, IAM, security, lifecycle rules, signed URLs, Terraform, and the CLI.", @@ -18,5 +17,33 @@ "cloud storage", "object storage", "blob storage" - ] + ], + "extensions": { + "com.google.cloud.data.agent-plugins": { + "config": [ + { + "key": "CLOUD_STORAGE_PROJECT", + "title": "Project ID", + "description": "ID of the Google Cloud project" + } + ], + "gemini": { + "mcpServerName": "cloud-storage" + }, + "codex": { + "interface": { + "displayName": "Google Cloud Storage", + "shortDescription": "Google Cloud Storage skills for your coding agent.", + "developerName": "Google LLC", + "category": "Storage", + "capabilities": [ + "Read" + ], + "defaultPrompt": [ + "You are a Google Cloud Storage expert assistant. Help the user work with their Google Cloud Storage resources from their coding agent." + ] + } + } + } + } } From 0d063ae663a4ab1a43a4c253eb7d0b8e7db0541d Mon Sep 17 00:00:00 2001 From: Juexin Wang Date: Wed, 19 Aug 2026 16:07:50 -0700 Subject: [PATCH 2/8] docs: reposition the repo as a plugin and document the MCP server --- .claude-plugin/plugin.json | 4 +- .codex-plugin/plugin.json | 9 +- CONTRIBUTING.md | 4 +- README.md | 127 ++++++++++++++---- gemini-extension.json | 4 +- plugin.json | 9 +- .../references/mcp-usage.md | 25 +++- 7 files changed, 136 insertions(+), 46 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 6dc2b7d..cd7ea53 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "google-cloud-storage", - "version": "1.0.0", - "description": "Official Google Cloud Storage (GCS) plugin. Manage buckets and objects, transfer data, and configure MCP, FUSE, IAM, security, lifecycle rules, signed URLs, Terraform, and the CLI.", + "version": "1.1.0", + "description": "Official Google Cloud Storage (GCS) plugin. Storage tools plus vetted skills to manage buckets and objects, transfer data, and configure MCP, FUSE, IAM, security, lifecycle rules, signed URLs, Terraform, and the CLI.", "author": { "name": "Google LLC", "email": "gcs-agentic-ai-customer-support@google.com" diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 9ff2c07..4a89fda 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "google-cloud-storage", - "version": "1.0.0", - "description": "Official Google Cloud Storage (GCS) plugin. Manage buckets and objects, transfer data, and configure MCP, FUSE, IAM, security, lifecycle rules, signed URLs, Terraform, and the CLI.", + "version": "1.1.0", + "description": "Official Google Cloud Storage (GCS) plugin. Storage tools plus vetted skills to manage buckets and objects, transfer data, and configure MCP, FUSE, IAM, security, lifecycle rules, signed URLs, Terraform, and the CLI.", "author": { "name": "Google LLC", "email": "gcs-agentic-ai-customer-support@google.com" @@ -21,11 +21,12 @@ "skills": "./skills", "interface": { "displayName": "Google Cloud Storage", - "shortDescription": "Google Cloud Storage skills for your coding agent.", + "shortDescription": "Google Cloud Storage tools and skills for your coding agent.", "developerName": "Google LLC", "category": "Storage", "capabilities": [ - "Read" + "Read", + "Write" ], "defaultPrompt": [ "You are a Google Cloud Storage expert assistant. Help the user work with their Google Cloud Storage resources from their coding agent." diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c43a525..c6af45e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ -# Contributing to Google Cloud Storage Skills +# Contributing to the Google Cloud Storage Plugin -Thank you for your interest in the Google Cloud Storage Skills repository! +Thank you for your interest in the Google Cloud Storage plugin! ## Our Contribution Policy diff --git a/README.md b/README.md index ae2891e..f749519 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,18 @@ -# Google Cloud Storage Skills +# Google Cloud Storage Plugin -[![Install via skills.sh](https://img.shields.io/badge/skills.sh-install-green)](https://skills.sh/gemini-cli-extensions/google-cloud-storage) +The official plugin for +[Google Cloud Storage](https://cloud.google.com/storage). It bundles a growing +collection of [Agent Skills](https://agentskills.io/home) with a +[Cloud Storage MCP server](#cloud-storage-mcp-server), so your coding agent gets +both vetted GCS expertise and structured tools for buckets and objects. -This repository contains a growing collection of -[Agent Skills](https://agentskills.io/home) for -[Google Cloud Storage](https://cloud.google.com/storage). These skills deliver -vetted GCS expertise directly into your coding agent, letting you use natural -language prompts in your preferred CLI or IDE to work with your storage -resources — from everyday bucket and object management to file-system mounts -with Cloud Storage FUSE, access-error diagnostics, security assessments, and -infrastructure code generation. +The skills let you work with your storage resources through natural language in +your preferred CLI or IDE: everyday bucket and object management, file-system +mounts with Cloud Storage FUSE, access-error diagnostics, security assessments, +and infrastructure code generation. > [!NOTE] -> This repository is under active development. More skills will be added +> This plugin is under active development. More skills will be added > over time. > [!IMPORTANT] @@ -25,6 +25,7 @@ infrastructure code generation. - [Installation](#installation) - [Available Skills](#available-skills) +- [Cloud Storage MCP Server](#cloud-storage-mcp-server) - [Prerequisites](#prerequisites) - [Authentication](#authentication) - [Additional Setup: GCS Security Assessment](#additional-setup-gcs-security-assessment) @@ -36,27 +37,35 @@ infrastructure code generation. ## Installation -### Installing using [open agent skills tool](https://github.com/vercel-labs/skills) +### Installing in Gemini CLI ```bash -npx skills add gemini-cli-extensions/google-cloud-storage +gemini extensions install https://github.com/gemini-cli-extensions/google-cloud-storage ``` -From the `npx` install command, you can select the specific skills from this -repo to install. The skills work with any compatible coding agent, including -Gemini CLI, Claude Code, Codex, and Antigravity CLI. +### Installing in Claude Code -### Installing via a compatible Agent Plugins client +This plugin is listed in Claude Code's official marketplace, which is built in, +so no marketplace needs to be added first: -This repository is also a valid -[Agent Plugins](https://github.com/agentplugins/agent-plugins-spec) (v1) plugin. -Any -[Agent Plugins–compatible client](https://agent-plugins.org/compatible-clients) -(VS Code, Cursor, GitHub Copilot, Codex, Kiro, …) can install it directly using -its own built-in plugin command, by pointing at this repository: +```bash +claude plugin install google-cloud-storage@claude-plugins-official +``` + +### Installing in Codex +Add the [Google plugins](https://github.com/google/skills) marketplace, which +lists this plugin, then install from it: + +```bash +codex plugin marketplace add google/skills +codex plugin add google-cloud-storage@google-plugins ``` -https://github.com/gemini-cli-extensions/google-cloud-storage + +### Installing in Antigravity CLI + +```bash +agy plugin install https://github.com/gemini-cli-extensions/google-cloud-storage ``` ## Available Skills @@ -93,6 +102,71 @@ https://github.com/gemini-cli-extensions/google-cloud-storage Needs [additional setup](#additional-setup-gcs-security-assessment) for a complete assessment. +## Cloud Storage MCP Server + +Installing the plugin also configures a local Cloud Storage MCP server, so your +agent can call structured storage tools instead of only shelling out to the CLI. +The server is +[MCP Toolbox](https://github.com/googleapis/mcp-toolbox) running its prebuilt +`cloud-storage` tools over stdio. It starts on demand through `npx`, so there is +no binary to download, but Node.js must be installed. + +It authenticates with the same Application Default Credentials as the skills +(see [Authentication](#authentication)), and needs the `roles/storage.*` roles +for the operations you call: `roles/storage.objectViewer` to read, +`roles/storage.objectAdmin` to copy, move, and delete objects, and +`roles/storage.admin` to create or delete buckets. + +### Configuration + +The server needs one setting: + +* `CLOUD_STORAGE_PROJECT`: the Google Cloud project it operates on. + +How you supply it depends on the harness: + +* **Gemini CLI**: prompted on install. View or update later with + `gemini extensions config google-cloud-storage` (restart the CLI to apply). +* **Claude Code**: pass `--config CLOUD_STORAGE_PROJECT=` on + install, or run `/plugin` inside Claude Code. +* **Codex** and **Antigravity**: export it before starting your agent: + +```bash +export CLOUD_STORAGE_PROJECT="" +``` + +### Available Tools + +| Tool | Description | +| :---------------------- | :------------------------------------------------ | +| `list_buckets` | List buckets in the project. | +| `get_bucket_metadata` | Get a bucket's metadata. | +| `get_bucket_iam_policy` | Get a bucket's IAM policy. | +| `create_bucket` | Create a bucket. | +| `delete_bucket` | Delete an empty bucket. | +| `list_objects` | List objects in a bucket. | +| `get_object_metadata` | Get an object's metadata. | +| `read_object` | Read UTF-8 text content (up to 8 MiB). | +| `download_object` | Download an object (binary included) to a file. | +| `write_object` | Write text content to an object (overwrites). | +| `upload_object` | Upload a local file (binary included). | +| `copy_object` | Copy an object. | +| `move_object` | Rename an object; deletes the source. | +| `delete_object` | Delete an object. | + +> [!CAUTION] +> Five of these tools destroy or overwrite data: `delete_bucket`, +> `delete_object`, `move_object` (deletes the source), `write_object`, and +> `upload_object`. Your agent must ask for explicit permission before calling +> them. + +For a comparison with the Google-hosted remote Cloud Storage MCP server, which +supports Model Armor screening and IAM deny policies, see the +[MCP usage reference](./skills/google-cloud-storage-basics/references/mcp-usage.md). + +If your agent reports `spawn npx ENOENT`, Node.js is not installed or `npx` is +not on your `PATH`. + ## Prerequisites Ensure you have the following: @@ -105,6 +179,9 @@ Ensure you have the following: are configured. * **A compatible coding agent**, such as Gemini CLI, Claude Code, Codex, or Antigravity CLI. +* **[Node.js](https://nodejs.org/)**, if you install the plugin: the + [Cloud Storage MCP server](#cloud-storage-mcp-server) runs via `npx`. Not + needed for a skills-only install. ## Authentication @@ -306,7 +383,7 @@ We welcome contributions to improve these skills. You can help by: * [Reporting bugs or inaccuracies](https://github.com/gemini-cli-extensions/google-cloud-storage/issues) in the skill files. -* Suggesting new skills to add to this repository by filing a feature request. +* Suggesting new skills to add to this plugin by filing a feature request. ## License diff --git a/gemini-extension.json b/gemini-extension.json index a9fb259..a17417b 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -1,7 +1,7 @@ { "name": "google-cloud-storage", - "version": "1.0.0", - "description": "Official Google Cloud Storage (GCS) plugin. Manage buckets and objects, transfer data, and configure MCP, FUSE, IAM, security, lifecycle rules, signed URLs, Terraform, and the CLI.", + "version": "1.1.0", + "description": "Official Google Cloud Storage (GCS) plugin. Storage tools plus vetted skills to manage buckets and objects, transfer data, and configure MCP, FUSE, IAM, security, lifecycle rules, signed URLs, Terraform, and the CLI.", "mcpServers": { "cloud-storage": { "command": "npx", diff --git a/plugin.json b/plugin.json index b8d150e..7f22328 100644 --- a/plugin.json +++ b/plugin.json @@ -1,7 +1,7 @@ { "name": "google-cloud-storage", - "version": "1.0.0", - "description": "Official Google Cloud Storage (GCS) plugin. Manage buckets and objects, transfer data, and configure MCP, FUSE, IAM, security, lifecycle rules, signed URLs, Terraform, and the CLI.", + "version": "1.1.0", + "description": "Official Google Cloud Storage (GCS) plugin. Storage tools plus vetted skills to manage buckets and objects, transfer data, and configure MCP, FUSE, IAM, security, lifecycle rules, signed URLs, Terraform, and the CLI.", "author": { "name": "Google LLC", "email": "gcs-agentic-ai-customer-support@google.com" @@ -33,11 +33,12 @@ "codex": { "interface": { "displayName": "Google Cloud Storage", - "shortDescription": "Google Cloud Storage skills for your coding agent.", + "shortDescription": "Google Cloud Storage tools and skills for your coding agent.", "developerName": "Google LLC", "category": "Storage", "capabilities": [ - "Read" + "Read", + "Write" ], "defaultPrompt": [ "You are a Google Cloud Storage expert assistant. Help the user work with their Google Cloud Storage resources from their coding agent." diff --git a/skills/google-cloud-storage-basics/references/mcp-usage.md b/skills/google-cloud-storage-basics/references/mcp-usage.md index c48e6f2..01878d1 100644 --- a/skills/google-cloud-storage-basics/references/mcp-usage.md +++ b/skills/google-cloud-storage-basics/references/mcp-usage.md @@ -14,6 +14,13 @@ CLI or building HTTP requests. It comes in two forms: need local filesystem integration (upload, download), copy/move operations, or larger payloads. +> [!IMPORTANT] +> **Check what is already connected before setting anything up.** Installing +> this repository as a plugin (rather than as skills alone) already configures +> the local MCP Toolbox server, named `cloud-storage`. If those tools are +> available to you, skip the setup below and just call them. The only setting is +> `CLOUD_STORAGE_PROJECT`. + ## Choosing a Server | Your need | Use | @@ -132,11 +139,12 @@ MCP Toolbox is Google's open-source MCP server (formerly Gen AI Toolbox for Databases). It ships a prebuilt `cloud-storage` tool source that exposes the full set of bucket and object operations. -1. **Download the binary.** The Toolbox ships as a standalone binary (or - container image) — it is not published as an npm or pip package, so never - configure it via `npx` or `pip`. Replace `VERSION` with the - [latest release](https://github.com/googleapis/mcp-toolbox/releases) and - pick your OS/architecture path: +1. **Pick how to run it.** The Toolbox is published on npm as + `@toolbox-sdk/server`, so `npx` fetches and runs it on demand (this is what + the plugin does, and it needs Node.js). A standalone binary and a container + image are also available if you prefer no Node dependency: replace `VERSION` + with the [latest release](https://github.com/googleapis/mcp-toolbox/releases) + and pick your OS/architecture path. ```bash curl -L -o toolbox \ @@ -162,14 +170,17 @@ full set of bucket and object operations. { "mcpServers": { "cloud-storage": { - "command": "./PATH/TO/toolbox", - "args": ["--prebuilt", "cloud-storage", "--stdio"], + "command": "npx", + "args": ["-y", "@toolbox-sdk/server@1.9.0", "--prebuilt", "cloud-storage", "--stdio"], "env": {"CLOUD_STORAGE_PROJECT": "PROJECT_ID"} } } } ``` + With the standalone binary instead, use `"command": "./PATH/TO/toolbox"` and + drop the first two `args`. + The identity behind ADC needs the `roles/storage.*` roles for the operations you intend to call (for example, `roles/storage.objectAdmin` for copy, move, and delete; `roles/storage.admin` to create or delete buckets). From 0aabccfc0b00e369e08004ecdf0371c1c619ae18 Mon Sep 17 00:00:00 2001 From: Juexin Wang Date: Wed, 19 Aug 2026 16:17:18 -0700 Subject: [PATCH 3/8] feat: add marketplace.json so Codex installs from this repo --- .claude-plugin/marketplace.json | 16 ++++++++++++++++ README.md | 7 +++---- 2 files changed, 19 insertions(+), 4 deletions(-) create mode 100644 .claude-plugin/marketplace.json diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..0f0833f --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,16 @@ +{ + "name": "google-cloud-storage", + "owner": { + "name": "Google LLC", + "email": "gcs-agentic-ai-customer-support@google.com" + }, + "metadata": { + "description": "Official Google Cloud Storage (GCS) plugin. Storage tools plus vetted skills to manage buckets and objects, transfer data, and configure MCP, FUSE, IAM, security, lifecycle rules, signed URLs, Terraform, and the CLI." + }, + "plugins": [ + { + "name": "google-cloud-storage", + "source": "./" + } + ] +} diff --git a/README.md b/README.md index f749519..2c482dc 100644 --- a/README.md +++ b/README.md @@ -54,12 +54,11 @@ claude plugin install google-cloud-storage@claude-plugins-official ### Installing in Codex -Add the [Google plugins](https://github.com/google/skills) marketplace, which -lists this plugin, then install from it: +Add this repository as a marketplace, then install from it: ```bash -codex plugin marketplace add google/skills -codex plugin add google-cloud-storage@google-plugins +codex plugin marketplace add gemini-cli-extensions/google-cloud-storage +codex plugin add google-cloud-storage@google-cloud-storage ``` ### Installing in Antigravity CLI From b805ceb998c236c993821069ce5747da15357226 Mon Sep 17 00:00:00 2001 From: Juexin Wang Date: Wed, 19 Aug 2026 16:23:46 -0700 Subject: [PATCH 4/8] docs: correct read-only claim and Node prerequisite for the MCP server --- PERMISSIONS.md | 14 +++++++++++--- README.md | 11 +++++------ 2 files changed, 16 insertions(+), 9 deletions(-) diff --git a/PERMISSIONS.md b/PERMISSIONS.md index b57a43f..842a8dd 100644 --- a/PERMISSIONS.md +++ b/PERMISSIONS.md @@ -1,8 +1,16 @@ -# GCS Skills Permissions Guide +# GCS Plugin Permissions Guide This guide documents the Google Cloud IAM permissions used by the skills in this -repository. All access is **read-only**—the skills never mutate your resources. -More skills (and their permission requirements) will be added here over time. +plugin. All skill access is **read-only**: the skills never mutate your +resources. More skills (and their permission requirements) will be added here +over time. + +> [!IMPORTANT] +> The plugin's [Cloud Storage MCP server](./README.md#cloud-storage-mcp-server) +> is **not** read-only. Its tools can create, overwrite, and delete buckets and +> objects, so it needs `roles/storage.objectAdmin` (copy, move, delete objects) +> or `roles/storage.admin` (create, delete buckets) for those operations. Grant +> only `roles/storage.objectViewer` to keep it read-only. ## GCS Security Assessment Skill diff --git a/README.md b/README.md index 2c482dc..06c0309 100644 --- a/README.md +++ b/README.md @@ -178,9 +178,8 @@ Ensure you have the following: are configured. * **A compatible coding agent**, such as Gemini CLI, Claude Code, Codex, or Antigravity CLI. -* **[Node.js](https://nodejs.org/)**, if you install the plugin: the - [Cloud Storage MCP server](#cloud-storage-mcp-server) runs via `npx`. Not - needed for a skills-only install. +* **[Node.js](https://nodejs.org/)**: the + [Cloud Storage MCP server](#cloud-storage-mcp-server) runs via `npx`. ## Authentication @@ -372,13 +371,13 @@ on how to mitigate prompt injection attacks with Google Cloud MCP. ## Support -If you need help or encounter issues with these skills, search for existing +If you need help or encounter issues with this plugin, search for existing issues or open a new one in the [GitHub Issue Tracker](https://github.com/gemini-cli-extensions/google-cloud-storage/issues). ## Contributing -We welcome contributions to improve these skills. You can help by: +We welcome contributions to improve this plugin. You can help by: * [Reporting bugs or inaccuracies](https://github.com/gemini-cli-extensions/google-cloud-storage/issues) in the skill files. @@ -386,5 +385,5 @@ We welcome contributions to improve these skills. You can help by: ## License -You are free to copy, modify, and distribute these skills under the terms of the +You are free to copy, modify, and distribute this plugin under the terms of the Apache 2.0 license. See the `LICENSE` file for details. From a8ba4af1227357cb192a59bb172819812e71470c Mon Sep 17 00:00:00 2001 From: Juexin Wang Date: Tue, 25 Aug 2026 16:52:54 -0700 Subject: [PATCH 5/8] docs: keep mcp-usage.md as upstream, only note the bundled server --- .../references/mcp-usage.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/skills/google-cloud-storage-basics/references/mcp-usage.md b/skills/google-cloud-storage-basics/references/mcp-usage.md index 01878d1..4de1c01 100644 --- a/skills/google-cloud-storage-basics/references/mcp-usage.md +++ b/skills/google-cloud-storage-basics/references/mcp-usage.md @@ -139,12 +139,11 @@ MCP Toolbox is Google's open-source MCP server (formerly Gen AI Toolbox for Databases). It ships a prebuilt `cloud-storage` tool source that exposes the full set of bucket and object operations. -1. **Pick how to run it.** The Toolbox is published on npm as - `@toolbox-sdk/server`, so `npx` fetches and runs it on demand (this is what - the plugin does, and it needs Node.js). A standalone binary and a container - image are also available if you prefer no Node dependency: replace `VERSION` - with the [latest release](https://github.com/googleapis/mcp-toolbox/releases) - and pick your OS/architecture path. +1. **Download the binary.** The Toolbox ships as a standalone binary (or + container image) — it is not published as an npm or pip package, so never + configure it via `npx` or `pip`. Replace `VERSION` with the + [latest release](https://github.com/googleapis/mcp-toolbox/releases) and + pick your OS/architecture path: ```bash curl -L -o toolbox \ @@ -170,17 +169,14 @@ full set of bucket and object operations. { "mcpServers": { "cloud-storage": { - "command": "npx", - "args": ["-y", "@toolbox-sdk/server@1.9.0", "--prebuilt", "cloud-storage", "--stdio"], + "command": "./PATH/TO/toolbox", + "args": ["--prebuilt", "cloud-storage", "--stdio"], "env": {"CLOUD_STORAGE_PROJECT": "PROJECT_ID"} } } } ``` - With the standalone binary instead, use `"command": "./PATH/TO/toolbox"` and - drop the first two `args`. - The identity behind ADC needs the `roles/storage.*` roles for the operations you intend to call (for example, `roles/storage.objectAdmin` for copy, move, and delete; `roles/storage.admin` to create or delete buckets). From 6114398aaf8c895d34fb46bd2a88a30f33bfadde Mon Sep 17 00:00:00 2001 From: Juexin Wang Date: Fri, 28 Aug 2026 16:30:20 -0700 Subject: [PATCH 6/8] docs: authentication covers the plugin, not just the skills --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 06c0309..3cabc4d 100644 --- a/README.md +++ b/README.md @@ -183,9 +183,10 @@ Ensure you have the following: ## Authentication -Before using the skills, authenticate with Google Cloud so your agent can read -your storage resources and run any changes you approve. It is recommended to run -**both** of the following commands: +Before using the plugin, authenticate with Google Cloud so your agent can read +your storage resources and run any changes you approve. Both the skills and the +[MCP server](#cloud-storage-mcp-server) use these credentials. It is recommended +to run **both** of the following commands: ```bash gcloud auth login From 9acab77d6e74ad1edf0063a11c5d49d186af23a1 Mon Sep 17 00:00:00 2001 From: Juexin Wang Date: Fri, 28 Aug 2026 16:31:03 -0700 Subject: [PATCH 7/8] feat: restore $schema in plugin.json for spec clients --- README.md | 4 ++-- plugin.json | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3cabc4d..8213bbc 100644 --- a/README.md +++ b/README.md @@ -176,8 +176,8 @@ Ensure you have the following: gcloud CLI and ensure [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/provide-credentials-adc) are configured. -* **A compatible coding agent**, such as Gemini CLI, Claude Code, Codex, or - Antigravity CLI. +* **A compatible coding agent**, such as Gemini CLI, Claude Code, Codex + (v0.150.0+), or Antigravity CLI. * **[Node.js](https://nodejs.org/)**: the [Cloud Storage MCP server](#cloud-storage-mcp-server) runs via `npx`. diff --git a/plugin.json b/plugin.json index 7f22328..5ec0b14 100644 --- a/plugin.json +++ b/plugin.json @@ -1,4 +1,5 @@ { + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "google-cloud-storage", "version": "1.1.0", "description": "Official Google Cloud Storage (GCS) plugin. Storage tools plus vetted skills to manage buckets and objects, transfer data, and configure MCP, FUSE, IAM, security, lifecycle rules, signed URLs, Terraform, and the CLI.", From cce93fa749d47c47ea620665e8761588a4f3a2a9 Mon Sep 17 00:00:00 2001 From: Juexin Wang Date: Fri, 28 Aug 2026 16:47:35 -0700 Subject: [PATCH 8/8] docs: address review on config key, npx guidance, and read-only scope --- PERMISSIONS.md | 7 ++++--- README.md | 5 +++-- skills/google-cloud-storage-basics/references/mcp-usage.md | 6 +++--- 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/PERMISSIONS.md b/PERMISSIONS.md index 842a8dd..186d2a7 100644 --- a/PERMISSIONS.md +++ b/PERMISSIONS.md @@ -1,9 +1,10 @@ # GCS Plugin Permissions Guide This guide documents the Google Cloud IAM permissions used by the skills in this -plugin. All skill access is **read-only**: the skills never mutate your -resources. More skills (and their permission requirements) will be added here -over time. +plugin. The scripts bundled with the skills are **read-only**: they never mutate +your resources. A skill may still propose a change, such as creating a bucket +with gcloud or Terraform, which runs only once you approve it. More skills (and +their permission requirements) will be added here over time. > [!IMPORTANT] > The plugin's [Cloud Storage MCP server](./README.md#cloud-storage-mcp-server) diff --git a/README.md b/README.md index 8213bbc..7a2205a 100644 --- a/README.md +++ b/README.md @@ -126,8 +126,9 @@ How you supply it depends on the harness: * **Gemini CLI**: prompted on install. View or update later with `gemini extensions config google-cloud-storage` (restart the CLI to apply). -* **Claude Code**: pass `--config CLOUD_STORAGE_PROJECT=` on - install, or run `/plugin` inside Claude Code. +* **Claude Code**: pass `--config cloud_storage_project=` on + install, or run `/plugin` inside Claude Code. The key is the lowercased + setting name, as declared in the plugin's `userConfig`. * **Codex** and **Antigravity**: export it before starting your agent: ```bash diff --git a/skills/google-cloud-storage-basics/references/mcp-usage.md b/skills/google-cloud-storage-basics/references/mcp-usage.md index 4de1c01..8036ca9 100644 --- a/skills/google-cloud-storage-basics/references/mcp-usage.md +++ b/skills/google-cloud-storage-basics/references/mcp-usage.md @@ -139,9 +139,9 @@ MCP Toolbox is Google's open-source MCP server (formerly Gen AI Toolbox for Databases). It ships a prebuilt `cloud-storage` tool source that exposes the full set of bucket and object operations. -1. **Download the binary.** The Toolbox ships as a standalone binary (or - container image) — it is not published as an npm or pip package, so never - configure it via `npx` or `pip`. Replace `VERSION` with the +1. **Download the binary.** The Toolbox also ships as a standalone binary (or + container image), which avoids the Node dependency of the `npx` command this + plugin uses. Replace `VERSION` with the [latest release](https://github.com/googleapis/mcp-toolbox/releases) and pick your OS/architecture path: