From 9a2c170053de1e5e34a34294d754ce60746009bf Mon Sep 17 00:00:00 2001 From: Twisha Bansal Date: Tue, 14 Apr 2026 17:25:11 +0530 Subject: [PATCH 1/7] docs: update documentation for skills support --- DEVELOPER.md | 143 ++++++++---------------- FIRESTORE-NATIVE.md | 34 +++--- README.md | 267 +++++++++++++++++++++++++++++++------------- 3 files changed, 257 insertions(+), 187 deletions(-) diff --git a/DEVELOPER.md b/DEVELOPER.md index dff53df..597e5fe 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -1,22 +1,19 @@ # DEVELOPER.md -This document provides instructions for setting up your development environment -and contributing to the Dataplex Gemini CLI Extension project. +This document provides instructions for setting up your development environment and contributing to the Firestore Native Gemini CLI Extension project. ## Prerequisites Before you begin, ensure you have the following: -1. **Gemini CLI:** Install the Gemini CLI version v0.6.0 or above. Installation - instructions can be found on the official Gemini CLI documentation. You can - verify your version by running `gemini --version`. -2. **Firestore database:** For testing data plane tools, you will need access to an active Firestore database. +1. **Gemini CLI:** Install the Gemini CLI version v0.6.0 or above. Installation instructions can be found on the [official Gemini CLI documentation](https://google-gemini.github.io/gemini-cli/). You can verify your version by running `gemini --version`. +2. **Firestore database:** For testing skills, you will need access to an active Firestore database. ## Developing the Extension ### Running from Local Source -The core logic for this extension is handled by a pre-built `toolbox` binary. The development process involves installing the extension locally into the Gemini CLI to test changes. +This extension uses **Agent Skills** to interact with Firestore. The development process involves generating these skills locally and linking the extension to the Gemini CLI. 1. **Clone the Repository:** @@ -25,120 +22,78 @@ The core logic for this extension is handled by a pre-built `toolbox` binary. Th cd firestore-native ``` -2. **Download the Toolbox Binary:** The required version of the `toolbox` binary - is specified in `toolbox_version.txt`. Download it for your platform. +2. **Generate Skills:** Use the `toolbox` binary to generate the skills. ```bash - # Read the required version - VERSION=$(cat toolbox_version.txt) + # Set the required env vars for configuration. + export FIRESTORE_PROJECT="" + export FIRESTORE_DATABASE="(default)" # Optional - # Example for macOS/amd64 - curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/geminicli/v$VERSION/darwin/amd64/toolbox + # Download the toolbox binary + export VERSION=1.1.0 + curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/darwin/arm64/toolbox chmod +x toolbox + + # Generate skills for firestore-data + ./toolbox --prebuilt firestore skills-generate --name "firestore-data" --description "Handles NoSQL document operations and collection hierarchy exploration. Use for CRUD tasks and data retrieval. Provides flexible document manipulation and structured querying." --toolset=data --license-header "// Copyright 2026 Google LLC + // + // Licensed under the Apache License, Version 2.0 (the \"License\"); + // you may not use this file except in compliance with the License. + // You may obtain a copy of the License at + // + // http://www.apache.org/licenses/LICENSE-2.0 + // + // Unless required by applicable law or agreed to in writing, software + // distributed under the License is distributed on an \"AS IS\" BASIS, + // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + // See the License for the specific language governing permissions and + // limitations under the License." + + # Generate skills for firestore-security + ./toolbox --prebuilt firestore skills-generate --name "firestore-security" --description "Manages access control and security compliance. Use when auditing permissions or deploying new security logic. Provides rule retrieval and syntax validation." --toolset=security --license-header "// Copyright 2026 Google LLC + // + // Licensed under the Apache License, Version 2.0 (the \"License\"); + // you may not use this file except in compliance with the License. + // You may obtain a copy of the License at + // + // http://www.apache.org/licenses/LICENSE-2.0 + // + // Unless required by applicable law or agreed to in writing, software + // distributed under the License is distributed on an \"AS IS\" BASIS, + // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + // See the License for the specific language governing permissions and + // limitations under the License." ``` - Adjust the URL for your operating system (`linux/amd64`, `darwin/arm64`, `windows/amd64`). -3. **Link the Extension Locally:** Use the Gemini CLI to install the - extension from your local directory. +3. **Link the Extension Locally:** Use the Gemini CLI to install the extension from your local directory. ```bash gemini extensions link . ``` The CLI will prompt you to confirm the linking. Accept it to proceed. -4. **Testing Changes:** After linking, start the Gemini CLI (`gemini`). - You can now interact with the `firestore-native` tools to manually test your changes - against your connected database. +4. **Testing Changes:** After linking, start the Gemini CLI (`gemini`). You can now interact with the Firestore skills to manually test your changes. ## Testing -### Automated Presubmit Checks - -A GitHub Actions workflow (`.github/workflows/presubmit-tests.yml`) is triggered -for every pull request. This workflow primarily verifies that the extension can -be successfully installed by the Gemini CLI. +### Automated Skills Validation -Currently, there are no automated unit or integration test suites -within this repository. All functional testing must be performed manually. All tools -are currently tested in the [MCP Toolbox GitHub](https://github.com/googleapis/genai-toolbox). +A GitHub Actions workflow (`.github/workflows/skills-validate.yml`) is triggered for every pull request. This workflow validates the structure and content of the generated skills. ### Other GitHub Checks -* **License Header Check:** A workflow ensures all necessary files contain the - proper license header. -* **Conventional Commits:** This repository uses - [Release Please](https://github.com/googleapis/release-please) to manage - releases. Your commit messages must adhere to the - [Conventional Commits](https://www.conventionalcommits.org/) specification. -* **Dependency Updates:** [Renovate](https://github.com/apps/forking-renovate) - is configured to automatically create pull requests for dependency updates. - -## Building the Extension - -The "build" process for this extension involves packaging the extension's -metadata files (`gemini-extension.json`, `firestore-native.md`, `LICENSE`) along with the -pre-built `toolbox` binary into platform-specific archives (`.tar.gz` or `.zip`). - -This process is handled automatically by the -[`package-and-upload-assets.yml`](.github/workflows/package-and-upload-assets.yml) -GitHub Actions workflow when a new release is created. Manual building is not -required. +* **License Header Check:** A workflow ensures all necessary files contain the proper license header. +* **Conventional Commits:** This repository uses [Release Please](https://github.com/googleapis/release-please) to manage releases. Your commit messages must adhere to the [Conventional Commits](https://www.conventionalcommits.org/) specification. ## Maintainer Information ### Team -The primary maintainers for this repository are defined in the -[`.github/CODEOWNERS`](.github/CODEOWNERS) file: +The primary maintainers for this repository are defined in the [`.github/CODEOWNERS`](.github/CODEOWNERS) file: * `@gemini-cli-extensions/senseai-eco` * `@gemini-cli-extensions/firestore-native-maintainers` ### Releasing -The release process is automated using `release-please`. It consists of an automated changelog preparation step followed by the manual merging of a Release PR. - -#### Automated Changelog Enrichment - -Before a Release PR is even created, a special workflow automatically mirrors -relevant changelogs from the core `googleapis/genai-toolbox` dependency. This -ensures that the release notes for this extension accurately reflect important -upstream changes. - -The process is handled by the [`mirror-changelog.yml`](.github/workflows/mirror-changelog.yml) workflow: - -1. **Trigger:** The workflow runs automatically on pull requests created by - Renovate for `toolbox` version updates. -2. **Parsing:** It reads the detailed release notes that Renovate includes in - the PR body. -3. **Filtering:** These release notes are filtered to include only changes - relevant to this extension. The relevance is determined by a keyword (e.g., - `firestore`), passed as an environment variable in the workflow file. -4. **Changelog Injection:** The script formats the filtered entries as - conventional commits and injects them into the PR body within a - `BEGIN_COMMIT_OVERRIDE` block. -5. **Release Please:** When the main Release PR is created, `release-please` - reads this override block instead of the standard `chore(deps): ...` commit - message, effectively mirroring the filtered upstream changelog into this - project's release notes. - -> **Note for Maintainers:** The filtering script is an automation aid, but it -> may occasionally produce "false positives" (e.g., an internal logging change -> that happens to contain the keyword). Before merging a `toolbox` dependency -> PR, maintainers must **review the generated `BEGIN_COMMIT_OVERRIDE` block** -> and manually delete any lines that are not relevant to the end-users of this -> extension. The curated override block is the final source of truth for the -> release changelog. - -#### Release Process - -1. **Release PR:** When commits with conventional commit headers (e.g., `feat:`, - `fix:`) are merged into the `main` branch, `release-please` will - automatically create or update a "Release PR". -2. **Merge Release PR:** A maintainer approves and merges the Release PR. This - action triggers `release-please` to create a new GitHub tag and a - corresponding GitHub Release. -3. **Package and Upload:** The new release triggers the - `package-and-upload-assets.yml` workflow. This workflow builds the - platform-specific extension archives and uploads them as assets to the - GitHub Release. +The release process is automated using `release-please`. It consists of an automated changelog preparation step followed by the manual merging of a Release PR. When the Release PR is merged, `release-please` creates a new GitHub tag and a corresponding GitHub Release. diff --git a/FIRESTORE-NATIVE.md b/FIRESTORE-NATIVE.md index f7a0d9f..7034f0e 100644 --- a/FIRESTORE-NATIVE.md +++ b/FIRESTORE-NATIVE.md @@ -1,6 +1,4 @@ -You are a highly skilled database engineer and database administrator. Your purpose is to -help the developer build and interact with databases and utilize data context throughout the entire -software delivery cycle. +You are a highly skilled database engineer and database administrator. Your purpose is to help the developer build and interact with databases and utilize data context throughout the entire software delivery cycle. --- @@ -14,17 +12,18 @@ To install this extension, the Gemini CLI version must be v0.6.0 or above. The v This section covers connecting to a Firestore instance. -1. **Verify Environment Variables**: Before attempting to connect, confirm with the user that the following environment variables are set in the extension configuration or their shell environment. +1. **Extension Configuration**: This extension requires settings (e.g., Project ID and Database ID). These values are gathered via prompts when you first install or link the extension: - * `FIRESTORE_PROJECT`: The GCP project ID. - * `FIRESTORE_DATABASE`: The Firestore database ID. + * `FIRESTORE_PROJECT`: The GCP project ID. + * `FIRESTORE_DATABASE`: The Firestore database ID. -2. **Handle Missing Variables**: If a command fails with an error message containing a placeholder like `${FIRESTORE_PROJECT}`, it signifies a missing environment variable. Inform the user which variable is missing and instruct them to set it. + If you need to update any of these values later, use the `gemini extensions config firestore-native` command. -3. **Handle Permission Errors**: If you encounter permission errors, ensure the user has the correct Firestore permissions (e.g., `datastore.entities.list`, `datastore.entities.create`). The user likely lacks the roles Cloud Datastore User (`roles/datastore.user`) and Firebase Rules Viewer (`roles/firebaserules.viewer`). You can provide these links for assistance: - * Granting Roles: https://cloud.google.com/iam/docs/grant-role-console - * Firestore Permissions: https://cloud.google.com/iam/docs/roles-permissions/firestore +2. **Handle Missing Variables**: If a command fails with an error message containing a placeholder like `${FIRESTORE_PROJECT}`, it signifies a missing environment variable. Inform the user which variable is missing and instruct them to set it. +3. **Handle Permission Errors**: If you encounter permission errors, ensure the user has the correct Firestore permissions (e.g., `datastore.entities.list`, `datastore.entities.create`). The user likely lacks the roles Cloud Datastore User (`roles/datastore.user`) and Firebase Rules Viewer (`roles/firebaserules.viewer`). You can provide these links for assistance: + * Granting Roles: https://cloud.google.com/iam/docs/grant-role-console + * Firestore Permissions: https://cloud.google.com/iam/docs/roles-permissions/firestore --- @@ -32,14 +31,16 @@ This section covers connecting to a Firestore instance. ## Connecting to New Resources -You will need to perform the following steps to change the current database connection: +When you want to change the current database connection, you will need to perform the following steps: 1. **(Optional) Save your conversation:** To avoid losing your progress, save the current session by running the command: `/chat save ` -2. **Stop the CLI:** Terminate the Gemini CLI. -3. **Update Environment Variables:** Set or update your environment variables (e.g. `FIRESTORE_DATABASE`) to point to the new resource. -4. **Restart:** Relaunch the Gemini CLI +2. **Stop the CLI**: Terminate the Gemini CLI. +3. **Update Extension Configuration**: Use the command `gemini extensions config firestore-native` to update your settings (e.g. `FIRESTORE_DATABASE`) to point to the new resource. +4. **Restart**: Relaunch the Gemini CLI 5. **(Optional) Resume conversation:** Resume your conversation with the command: `/chat resume ` +**Important:** Do not assume a connection to a newly created resource is active. Always follow the steps above to reconfigure your connection. + ## Reusing Project Values Users may have set project environment variables: @@ -47,5 +48,6 @@ Users may have set project environment variables: * `FIRESTORE_PROJECT`: The GCP project ID. * `FIRESTORE_DATABASE`: The Firestore database ID. -Instead of prompting the user for these values for specific tool calls, prompt the user to verify reuse a specific value. -Make sure to not use the environment variable name like `FIRESTORE_PROJECT`, `${FIRESTORE_PROJECT}`, or `$FIRESTORE_PROJECT`. The value can be found by using command: `echo $FIRESTORE_PROJECT`. +Instead of prompting the user for these values for specific skill calls, prompt the user to verify the reuse of a specific setting value. +Make sure to not use the environment variable name like `FIRESTORE_PROJECT`, `${FIRESTORE_PROJECT}`, or `$FIRESTORE_PROJECT`. +The value can be verified by the user using the `gemini extensions config firestore-native` command or by checking their local settings. diff --git a/README.md b/README.md index a5fd15d..ebf7486 100644 --- a/README.md +++ b/README.md @@ -1,136 +1,249 @@ -# Gemini CLI Extension - Firestore Native +# Firestore Native Agent Skills > [!NOTE] -> This extension is currently in beta (pre-v1.0), and may see breaking changes until the first stable release (v1.0). +> Currently in beta (pre-v1.0), and may see breaking changes until the first stable release (v1.0). -This Gemini CLI extension provides a set of tools to interact with [Firestore](https://cloud.google.com/firestore/docs) databases. It allows you to manage your databases, documents, and collections directly from the [Gemini CLI](https://google-gemini.github.io/gemini-cli/), using natural language prompts. +This repository provides a set of agent skills to interact with [Firestore](https://cloud.google.com/firestore/docs) databases. These skills can be used with various AI agents, including [Gemini CLI](https://google-gemini.github.io/gemini-cli/), Claude Code, and Codex, to manage your databases, collections, and documents using natural language prompts. -Learn more about [Gemini CLI Extensions](https://github.com/google-gemini/gemini-cli/blob/main/docs/extensions/index.md). > [!IMPORTANT] > **We Want Your Feedback!** -> Please share your thoughts with us by filling out our feedback [form][form]. +> Please share your thoughts with us by filling out our feedback [form][form]. > Your input is invaluable and helps us improve the project for everyone. [form]: https://docs.google.com/forms/d/e/1FAIpQLSfEGmLR46iipyNTgwTmIDJqzkAwDPXxbocpXpUbHXydiN1RTw/viewform?usp=pp_url&entry.157487=firestore-native -## Why Use the Firestore Native Extension? - -* **Natural Language Management:** Stop wrestling with complex commands. Explore schemas and query data by describing what you want in plain English. -* **Seamless Workflow:** As a Google-developed extension, it integrates seamlessly into the Gemini CLI environment. No need to constantly switch contexts for common database tasks. -* **Code Generation:** Accelerate development by asking Gemini to generate data classes and other code snippets based on your table schemas. - -## 📺 Video Walkthrough -Follow this step-by-step video walkthrough to setup and use the Firestore Native Extension. -

-Video Tutorial -

+## Table of Contents + +- [Why Use Firestore Native Agent Skills?](#why-use-firestore-native-agent-skills) +- [Prerequisites](#prerequisites) +- [Getting Started](#getting-started) + - [Configuration](#configuration) + - [Installation & Usage](#installation--usage) + - [Gemini CLI](#gemini-cli) + - [Claude Code](#claude-code) + - [Codex](#codex) + - [Antigravity](#antigravity) +- [Usage Examples](#usage-examples) +- [Supported Skills](#supported-skills) +- [Additional Agent Skills](#additional-agent-skills) +- [Troubleshooting](#troubleshooting) + +## Why Use Firestore Native Agent Skills? + +- **Seamless Workflow:** Integrates seamlessly into your AI agent's environment. No need to constantly switch contexts for common database tasks. +- **Natural Language Queries:** Stop wrestling with complex commands. Explore schemas and query data by describing what you want in plain English. +- **Data & Security Management:** Manage your Firestore data and security rules directly from your agent. +- **Code Generation:** Accelerate development by asking your agent to generate data classes and other code snippets based on your document structures. ## Prerequisites Before you begin, ensure you have the following: -* [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed with version **+v0.6.0**. -* Setup Gemini CLI [Authentication](https://github.com/google-gemini/gemini-cli/tree/main?tab=readme-ov-file#-authentication-options). -* A Google Cloud project with the **Firestore API** enabled. -* Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. -* IAM Permissions +- One of these AI agents installed + - [Gemini CLI](https://github.com/google-gemini/gemini-cli) version **v0.6.0** or higher + - [Claude Code](https://claude.com/product/claude-code) version **v2.1.94** or higher + - [Codex](https://developers.openai.com/codex) **v0.117.0** or higher + - [Antigravity](https://antigravity.google) **v1.14.2** or higher +- A Google Cloud project with the **Firestore API** enabled. +- Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. +- IAM Permissions: * Cloud Datastore User (`roles/datastore.user`) * Firebase Rules Viewer (`roles/firebaserules.viewer`) ## Getting Started -### Installation +### Configuration -To install the extension, use the `gemini extensions install` command: +Please keep these env vars handy during the installation process: -```bash -gemini extensions install https://github.com/gemini-cli-extensions/firestore-native -``` +- `FIRESTORE_PROJECT`: The GCP project ID. +- `FIRESTORE_DATABASE`: (Optional) The Firestore database ID. Defaults to `(default)`. -### Configuration +> [!NOTE] +> +> - Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. -You will be prompted to configure the following settings during installation. These settings are saved in an `.env` file within the extension's directory. +### Installation & Usage -* `FIRESTORE_PROJECT`: The GCP project ID. -* `FIRESTORE_DATABASE`: (Optional) The Firestore database ID. Defaults to `(default)`. +To start interacting with your database, install the skills for your preferred AI agent, then launch the agent and use natural language to ask questions or perform tasks. -To view or update your configuration: +For the latest version, check the [releases page][releases]. -**List Settings:** -* Terminal: `gemini extensions list` -* Gemini CLI: `/extensions list` +[releases]: https://github.com/gemini-cli-extensions/firestore-native/releases -**Update Settings:** -* Terminal: `gemini extensions config firestore-native [setting name] [--scope ]` - * `setting name`: (Optional) The single setting to configure. - * `scope`: (Optional) The scope of the setting in (`user` or `workspace`). Defaults to `user`. -* Currently, you must restart the Gemini CLI for changes to take effect. We recommend using `gemini --resume` to resume your session. + -Alternatively, you can manually set these environment variables before starting the Gemini CLI: +
+Gemini CLI + +**1. Install the extension:** ```bash -export FIRESTORE_PROJECT="" -export FIRESTORE_DATABASE="(default)" # Optional +gemini extensions install https://github.com/gemini-cli-extensions/firestore-native ``` -> [!NOTE] -> * Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. -> * See [Troubleshooting](#troubleshooting) for debugging your configuration. +During the installation, enter your environment vars as described in the [configuration section](#configuration). + +**2. (Optional) Manage Configuration:** +To view or update your configuration in Gemini CLI: -### Start Gemini CLI +- Terminal: `gemini extensions config firestore-native [setting name] [--scope ]` +- Gemini CLI: `/extensions list` -To start the Gemini CLI, use the following command: +**3. Start the agent:** ```bash gemini ``` +_(Tip: Run `/extensions list` to verify your configuration and active extensions.)_ + > [!WARNING] > **Changing Database Connections** -> Currently, the database connection must be configured before starting the Gemini CLI and can not be changed during a session. -> To save and resume conversation history use command: `/chat save ` and `/chat resume `. +> Currently, the database connection must be configured before starting the agent and can not be changed during a session. +> To save and resume conversation history in Gemini CLI use command: `/chat save ` and `/chat resume `. -## Usage Examples +
+ +
+Claude Code + +**1. Set env vars:** +In your terminal, set your environment vars as described in the [configuration section](#configuration). + +**2. Start the agent:** + +```bash +claude +``` + +**3. Add the marketplace:** + +```bash +/plugin marketplace add https://github.com/gemini-cli-extensions/firestore-native.git#0.2.1 +``` + +**4. Install the plugin:** + +```bash +/plugin install firestore-native@firestore-native-marketplace +``` + +_(Tip: Run `/plugin list` inside Claude Code to verify the plugin is active, or `/reload-plugins` if you just installed it.)_ -Interact with Firestore using natural language right from your IDE: +
-* **Document and Data Retrieval**: +
+Codex - * "Show me the Firestore data for the test users qa_user_123 and qa_user_456 from the users-staging collection." - * "Find all users in the users-staging collection whose wishlist contains product-glasses." +**1. Clone the Repo:** + +```bash +git clone --branch 0.2.1 git@github.com:gemini-cli-extensions/firestore-native.git +``` + +**2. Install the plugin:** + +```bash +mkdir -p ~/.codex/plugins +cp -R /absolute/path/to/firestore-native ~/.codex/plugins/firestore-native +``` + +**3. Set env vars:** +Enter your environment vars as described in the [configuration section](#configuration). + +**4. Create or update marketplace.json:** +`~/.agents/plugins/marketplace.json` + +```json +{ + "name": "my-data-cloud-google-marketplace", + "interface": { + "displayName": "Google Data Cloud Skills" + }, + "plugins": [ + { + "name": "firestore-native", + "source": { + "source": "local", + "path": "./plugins/firestore-native" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Database" + } + ] +} +``` + +_(Tip: Run `codex plugin list` or use the `/plugins` interactive menu to verify your installed plugins.)_ + +
+ +
+Antigravity + +**1. Clone the Repo:** + +```bash +git clone --branch 0.2.1 https://github.com/gemini-cli-extensions/firestore-native.git +``` + +**2. Install the skills:** + +Choose a location for the skills: +- **Global (all workspaces):** `~/.gemini/antigravity/skills/` +- **Workspace-specific:** `/.agents/skills/` + +Copy the skill folders from the cloned repository's `skills/` directory to your chosen location: + +```bash +cp -R firestore-native/skills/* ~/.gemini/antigravity/skills/ +``` + +**3. Set env vars:** +Set your environment vars as described in the [configuration section](#configuration). + +_(Tip: Antigravity automatically discovers skills in these directories at the start of a session.)_ + +
+ + + +## Usage Examples -* **Document Updates and Cleanup**: - * "For all 20 test users you just found, please remove product-glasses(inactive) from their wishlist." - * "Update the document with ID order-987 in the orders collection to set the status to 'Shipped'." +Interact with Firestore using natural language: -* **Security Rules Management**: - * "new_rules.txt is a new Firestore Security Rule I'm working on for staging. Can you validate it for me?" - * "Show me the active Firestore security rules for this project." +- **Document and Data Retrieval**: + - "Show me the Firestore data for the test users qa_user_123 and qa_user_456 from the users-staging collection." + - "Find all users in the users-staging collection whose wishlist contains product-glasses." +- **Document Updates and Cleanup**: + - "For all 20 test users you just found, please remove product-glasses(inactive) from their wishlist." + - "Update the document with ID order-987 in the orders collection to set the status to 'Shipped'." +- **Security Rules Management**: + - "new_rules.txt is a new Firestore Security Rule I'm working on for staging. Can you validate it for me?" + - "Show me the active Firestore security rules for this project." -## Supported Tools +## Supported Skills -This extension provides a comprehensive set of tools: +The following skills are available in this repository: -* `add_documents`: Use this tool to add documents to a Firestore collection path. -* `get_documents`: Use this tool to get multiple documents from Firestore by their paths. -* `list_collections`: Use this tool to list Firestore collections for a given parent path. -* `delete_documents`: Use this tool to delete multiple documents from Firestore. -* `query_collection`: Use this tool to query documents from a collection with filtering, ordering, and limit options. -* `get_rules`: Use this tool to retrieve the active Firestore security rules for the current project. -* `update_document`: Use this tool to update an existing document in Firestore by its path. -* `validate_rules`: Use this tool to validate Firestore security rules syntax and errors. +- [Firestore Data](./skills/firestore-data/SKILL.md) - Handles NoSQL document operations and collection hierarchy exploration. Use for CRUD tasks and data retrieval. Provides flexible document manipulation and structured querying. +- [Firestore Security](./skills/firestore-security/SKILL.md) - Manages access control and security compliance. Use when auditing permissions or deploying new security logic. Provides rule retrieval and syntax validation. -## Additional Extensions +## Additional Agent Skills -Find additional extensions to support your entire software development lifecycle at [github.com/gemini-cli-extensions](https://github.com/gemini-cli-extensions). +Find additional skills to support your entire software development lifecycle at [github.com/gemini-cli-extensions](https://github.com/gemini-cli-extensions). ## Troubleshooting -Use `gemini --debug` to enable debugging. +Use the debug mode of your agent (e.g., `gemini --debug`) to enable debugging. Common issues: -* "failed to find default credentials: google: could not find default credentials.": Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. See [Set up Application Default Credentials](https://cloud.google.com/docs/authentication/external/set-up-adc) for more information. -* "✖ Error during discovery for server: MCP error -32000: Connection closed": The database connection has not been established. Ensure your configuration is set via environment variables. -* "✖ MCP ERROR: Error: spawn /Users/USER/.gemini/extensions/firestore-native/toolbox ENOENT": The Toolbox binary did not download correctly. Ensure you are using Gemini CLI v0.6.0+. -* "cannot execute binary file": The Toolbox binary did not download correctly. Ensure the correct binary for your OS/Architecture has been downloaded. See [Installing the server](https://mcp-toolbox.dev/documentation/introduction/#install-toolbox) for more information. +- "failed to find default credentials: google: could not find default credentials.": Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. See [Set up Application Default Credentials](https://cloud.google.com/docs/authentication/external/set-up-adc) for more information. +- "✖ Error during discovery for server: MCP error -32000: Connection closed": The database connection has not been established. Ensure your configuration is set via environment variables. +- "✖ MCP ERROR: Error: spawn .../toolbox ENOENT": The Toolbox binary did not download correctly. Ensure you are using the latest version of your agent. +- "cannot execute binary file": The Toolbox binary did not download correctly. Ensure the correct binary for your OS/Architecture has been downloaded. See [Installing the server](https://mcp-toolbox.dev/documentation/introduction/#install-toolbox) for more information. From f6273265a10486ef09ea4c47df4e02abd6a46f90 Mon Sep 17 00:00:00 2001 From: Yuan Teoh <45984206+Yuan325@users.noreply.github.com> Date: Tue, 14 Apr 2026 04:56:39 -0700 Subject: [PATCH 2/7] docs: fix links to mcp toolbox (#104) --- DEVELOPER.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/DEVELOPER.md b/DEVELOPER.md index dff53df..efb14ca 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -60,7 +60,7 @@ be successfully installed by the Gemini CLI. Currently, there are no automated unit or integration test suites within this repository. All functional testing must be performed manually. All tools -are currently tested in the [MCP Toolbox GitHub](https://github.com/googleapis/genai-toolbox). +are currently tested in the [MCP Toolbox GitHub](https://github.com/googleapis/mcp-toolbox). ### Other GitHub Checks @@ -101,7 +101,7 @@ The release process is automated using `release-please`. It consists of an autom #### Automated Changelog Enrichment Before a Release PR is even created, a special workflow automatically mirrors -relevant changelogs from the core `googleapis/genai-toolbox` dependency. This +relevant changelogs from the core `googleapis/mcp-toolbox` dependency. This ensures that the release notes for this extension accurately reflect important upstream changes. From ac552d0702430782ab452dbd8f29f9f8532b645e Mon Sep 17 00:00:00 2001 From: Mend Renovate Date: Tue, 14 Apr 2026 12:58:25 +0100 Subject: [PATCH 3/7] feat(deps): update dependency googleapis/mcp-toolbox to v1 (#102) Co-authored-by: Twisha Bansal <58483338+twishabansal@users.noreply.github.com> --- toolbox_version.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/toolbox_version.txt b/toolbox_version.txt index 022a033..1cc5f65 100644 --- a/toolbox_version.txt +++ b/toolbox_version.txt @@ -1 +1 @@ -0.28.0 \ No newline at end of file +1.1.0 \ No newline at end of file From 098f1d359f2bfa0e20da6ccf9588924c663db9d9 Mon Sep 17 00:00:00 2001 From: Mend Renovate Date: Tue, 14 Apr 2026 13:01:14 +0100 Subject: [PATCH 4/7] chore(deps): update actions/upload-artifact digest to 043fb46 (#103) Co-authored-by: Twisha Bansal <58483338+twishabansal@users.noreply.github.com> --- .github/workflows/package-and-upload-assets.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/package-and-upload-assets.yml b/.github/workflows/package-and-upload-assets.yml index a54df6b..710cdba 100644 --- a/.github/workflows/package-and-upload-assets.yml +++ b/.github/workflows/package-and-upload-assets.yml @@ -103,7 +103,7 @@ jobs: echo "ARCHIVE_PATH=${ARCHIVE_NAME}" >> $GITHUB_OUTPUT - name: Upload archive as workflow artifact - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7 + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 with: name: ${{ steps.vars.outputs.archive_name }} path: ${{ steps.create_archive.outputs.ARCHIVE_PATH }} From 5918056e9e8ebf13b0f33635d0d49df09c26616b Mon Sep 17 00:00:00 2001 From: Twisha Bansal <58483338+twishabansal@users.noreply.github.com> Date: Tue, 14 Apr 2026 17:33:45 +0530 Subject: [PATCH 5/7] Update DEVELOPER.md --- DEVELOPER.md | 63 ++++++++++++---------------------------------------- 1 file changed, 14 insertions(+), 49 deletions(-) diff --git a/DEVELOPER.md b/DEVELOPER.md index 597e5fe..c29d521 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -20,65 +20,30 @@ This extension uses **Agent Skills** to interact with Firestore. The development ```bash git clone https://github.com/gemini-cli-extensions/firestore-native.git cd firestore-native - ``` -2. **Generate Skills:** Use the `toolbox` binary to generate the skills. +2. **Install the Extension Locally:** Use the Gemini CLI to install the + extension from your local directory. ```bash - # Set the required env vars for configuration. - export FIRESTORE_PROJECT="" - export FIRESTORE_DATABASE="(default)" # Optional - - # Download the toolbox binary - export VERSION=1.1.0 - curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/darwin/arm64/toolbox - chmod +x toolbox - - # Generate skills for firestore-data - ./toolbox --prebuilt firestore skills-generate --name "firestore-data" --description "Handles NoSQL document operations and collection hierarchy exploration. Use for CRUD tasks and data retrieval. Provides flexible document manipulation and structured querying." --toolset=data --license-header "// Copyright 2026 Google LLC - // - // Licensed under the Apache License, Version 2.0 (the \"License\"); - // you may not use this file except in compliance with the License. - // You may obtain a copy of the License at - // - // http://www.apache.org/licenses/LICENSE-2.0 - // - // Unless required by applicable law or agreed to in writing, software - // distributed under the License is distributed on an \"AS IS\" BASIS, - // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - // See the License for the specific language governing permissions and - // limitations under the License." - - # Generate skills for firestore-security - ./toolbox --prebuilt firestore skills-generate --name "firestore-security" --description "Manages access control and security compliance. Use when auditing permissions or deploying new security logic. Provides rule retrieval and syntax validation." --toolset=security --license-header "// Copyright 2026 Google LLC - // - // Licensed under the Apache License, Version 2.0 (the \"License\"); - // you may not use this file except in compliance with the License. - // You may obtain a copy of the License at - // - // http://www.apache.org/licenses/LICENSE-2.0 - // - // Unless required by applicable law or agreed to in writing, software - // distributed under the License is distributed on an \"AS IS\" BASIS, - // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - // See the License for the specific language governing permissions and - // limitations under the License." + gemini extensions install . ``` + The CLI will prompt you to confirm the installation. Accept it to proceed. -3. **Link the Extension Locally:** Use the Gemini CLI to install the extension from your local directory. - - ```bash - gemini extensions link . - ``` - The CLI will prompt you to confirm the linking. Accept it to proceed. - -4. **Testing Changes:** After linking, start the Gemini CLI (`gemini`). You can now interact with the Firestore skills to manually test your changes. +3. **Testing Changes:** After installation, start the Gemini CLI (`gemini`). + You can now interact with the `firestore-native` skills to manually test your changes + against your connected database. ## Testing ### Automated Skills Validation -A GitHub Actions workflow (`.github/workflows/skills-validate.yml`) is triggered for every pull request. This workflow validates the structure and content of the generated skills. +A GitHub Actions workflow (`.github/workflows/presubmit-tests.yml`) is triggered +for every pull request. This workflow primarily verifies that the extension can +be successfully installed by the Gemini CLI. + +All tools are currently tested in the [MCP Toolbox GitHub](https://github.com/googleapis/mcp-toolbox). + +The skills themselves are validated using the `skills-validate.yml` workflow. ### Other GitHub Checks From 3b2e1a63b56cb1b6f070ba187d5c41c7b9031c8b Mon Sep 17 00:00:00 2001 From: Twisha Bansal <58483338+twishabansal@users.noreply.github.com> Date: Tue, 14 Apr 2026 17:34:46 +0530 Subject: [PATCH 6/7] Update DEVELOPER.md --- DEVELOPER.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/DEVELOPER.md b/DEVELOPER.md index c29d521..b648f42 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -62,3 +62,44 @@ The primary maintainers for this repository are defined in the [`.github/CODEOWN ### Releasing The release process is automated using `release-please`. It consists of an automated changelog preparation step followed by the manual merging of a Release PR. When the Release PR is merged, `release-please` creates a new GitHub tag and a corresponding GitHub Release. + +#### Automated Changelog Enrichment + +Before a Release PR is even created, a special workflow automatically mirrors +relevant changelogs from the core `googleapis/genai-toolbox` dependency. This +ensures that the release notes for this extension accurately reflect important +upstream changes. + +The process is handled by the [`mirror-changelog.yml`](.github/workflows/mirror-changelog.yml) workflow: + +1. **Trigger:** The workflow runs automatically on pull requests created by + Renovate for `toolbox` version updates. +2. **Parsing:** It reads the detailed release notes that Renovate includes in + the PR body. +3. **Filtering:** These release notes are filtered to include only changes + relevant to this extension. The relevance is determined by a keyword (e.g., + `firestore`), passed as an environment variable in the workflow file. +4. **Changelog Injection:** The script formats the filtered entries as + conventional commits and injects them into the PR body within a + `BEGIN_COMMIT_OVERRIDE` block. +5. **Release Please:** When the main Release PR is created, `release-please` + reads this override block instead of the standard `chore(deps): ...` commit + message, effectively mirroring the filtered upstream changelog into this + project's release notes. + +> **Note for Maintainers:** The filtering script is an automation aid, but it +> may occasionally produce "false positives" (e.g., an internal logging change +> that happens to contain the keyword). Before merging a `toolbox` dependency +> PR, maintainers must **review the generated `BEGIN_COMMIT_OVERRIDE` block** +> and manually delete any lines that are not relevant to the end-users of this +> extension. The curated override block is the final source of truth for the +> release changelog. + +#### Release Process + +1. **Release PR:** When commits with conventional commit headers (e.g., `feat:`, + `fix:`) are merged into the `main` branch, `release-please` will + automatically create or update a "Release PR". +2. **Merge Release PR:** A maintainer approves and merges the Release PR. This + action triggers `release-please` to create a new GitHub tag and a + corresponding GitHub Release. From 527d78f35358cb097c7ac773aa8fbbbff9ade074 Mon Sep 17 00:00:00 2001 From: Twisha Bansal <58483338+twishabansal@users.noreply.github.com> Date: Tue, 14 Apr 2026 17:35:55 +0530 Subject: [PATCH 7/7] Update README.md --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index ebf7486..c908b9b 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,12 @@ This repository provides a set of agent skills to interact with [Firestore](http - **Data & Security Management:** Manage your Firestore data and security rules directly from your agent. - **Code Generation:** Accelerate development by asking your agent to generate data classes and other code snippets based on your document structures. +## 📺 Video Walkthrough +Follow this step-by-step video walkthrough to setup and use the Firestore Native Extension. +

+Video Tutorial +

+ ## Prerequisites Before you begin, ensure you have the following: