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/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 7de5e0a..cd7ea53 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,14 +1,36 @@ { "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" }, "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..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" @@ -13,19 +13,24 @@ "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.", + "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." ] - } + }, + "mcpServers": "./.codex-plugin/.mcp.json" } 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/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 ae2891e..06c0309 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,34 @@ 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 this repository as a marketplace, then install from it: + +```bash +codex plugin marketplace add gemini-cli-extensions/google-cloud-storage +codex plugin add google-cloud-storage@google-cloud-storage ``` -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 +101,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 +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/)**: the + [Cloud Storage MCP server](#cloud-storage-mcp-server) runs via `npx`. ## Authentication @@ -296,19 +371,19 @@ 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. -* 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 -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. diff --git a/gemini-extension.json b/gemini-extension.json new file mode 100644 index 0000000..a17417b --- /dev/null +++ b/gemini-extension.json @@ -0,0 +1,24 @@ +{ + "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.", + "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..7f22328 100644 --- a/plugin.json +++ b/plugin.json @@ -1,8 +1,7 @@ { - "$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.", + "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" @@ -18,5 +17,34 @@ "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 tools and skills for your coding agent.", + "developerName": "Google LLC", + "category": "Storage", + "capabilities": [ + "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).