From 9f25cbe9388329178dd9a4a637c6e01ebc1a4421 Mon Sep 17 00:00:00 2001 From: Twisha Bansal Date: Thu, 16 Apr 2026 16:07:07 +0530 Subject: [PATCH 1/5] docs: overhaul documentation for skills-based architecture --- .gitignore | 9 ++ DEVELOPER.md | 126 ++++++--------------------- ORACLEDB.md | 32 +++---- README.md | 239 +++++++++++++++++++++++++++++++++++++++++---------- 4 files changed, 244 insertions(+), 162 deletions(-) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..65395be --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +**creds.sh** +toolbox2 +generate-skills-repo.sh +skills-gen/ +.env +node_modules/ +dist/ +build/ +.DS_Store diff --git a/DEVELOPER.md b/DEVELOPER.md index 6761534..194188f 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -1,25 +1,18 @@ # DEVELOPER.md -This document provides instructions for setting up your development environment -and contributing to the OracleDB Gemini CLI Extension project. +This document provides instructions for setting up your development environment and contributing to the Oracle Database Agent skills 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. **OracleDB Cluster & Instance:** For testing data plane tools, you will need access to an active - Oracle DB instance. We recommend using Public IP to eliminate the need to create and use a workspace - within the same VPC network as the 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. You can verify your version by running `gemini --version`. +2. **Oracle Database Instance:** For testing data plane skills, you will need access to an active Oracle Database instance. ## 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. - 1. **Clone the Repository:** ```bash @@ -27,78 +20,36 @@ The core logic for this extension is handled by a pre-built `toolbox` binary. Th cd oracledb ``` -2. **Download the Toolbox Binary:** The required version of the `toolbox` binary - is specified in `toolbox_version.txt`. Download it for your platform. - - ```bash - # Read the required version - VERSION=$(cat toolbox_version.txt) - - # Download the binary for your platform. The binary must be named `toolbox`. - # Adjust the URL for your operating system (`linux/amd64`, `darwin/arm64`, `windows/amd64`). - # Example for macOS/amd64: - curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/geminicli/v$VERSION/darwin/amd64/toolbox - chmod +x toolbox - - # For Windows, you will need to download the .exe file and rename it to `toolbox`. - # The `chmod` command is not required on Windows. - ``` - -3. **Link the Extension Locally:** Use the Gemini CLI to install the - extension from your local directory. +2. **Install the Extension Locally:** Use the Gemini CLI to install the extension from your local directory. ```bash - gemini extensions link . + gemini extensions install . ``` - The CLI will prompt you to confirm the linking. Accept it to proceed. + The CLI will prompt you to confirm the installation and enter your configuration. -4. **Testing Changes:** After linking, start the Gemini CLI (`gemini`). - You can now interact with the `oracledb` tools to manually test your changes - against your connected database. +3. **Testing Changes:** After installation, start the Gemini CLI (`gemini`). You can now interact with the `oracledb` skills to manually test your changes against your connected database. ## 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. +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. -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/mcp-toolbox). +All skills are currently tested in the [MCP Toolbox GitHub](https://github.com/googleapis/mcp-toolbox). -### 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 skills themselves are validated using the `skills-validate.yml` workflow. -The "build" process for this extension involves packaging the extension's -metadata files (`gemini-extension.json`, `ORACLEDB.md`, `LICENSE`) along with the -pre-built `toolbox` binary into platform-specific archives (`.tar.gz` or `.zip`). +### Other GitHub Checks -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. +* **Dependency Updates:** [Renovate](https://github.com/apps/forking-renovate) is configured to automatically create pull requests for dependency updates. ## Maintainer Information ### Team -The primary maintainers for this repository are defined in the -[`.github/CODEOWNERS`](.github/CODEOWNERS) file: - -* `@gemini-cli-extensions/senseai-eco` -* `@gemini-cli-extensions/oracledb-maintainers` +The primary maintainers for this repository are defined in the [`.github/CODEOWNERS`](.github/CODEOWNERS) file. ### Releasing @@ -106,46 +57,19 @@ 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/mcp-toolbox` dependency. This -ensures that the release notes for this extension accurately reflect important -upstream changes. +Before a Release PR is even created, a special workflow automatically mirrors relevant changelogs from the core `googleapis/mcp-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., - `oracledb`), passed as an environment variable in the workflow file. - `oracledb`), 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. +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., `oracle`), 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. \ No newline at end of file +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. diff --git a/ORACLEDB.md b/ORACLEDB.md index 278bb59..2e7202a 100644 --- a/ORACLEDB.md +++ b/ORACLEDB.md @@ -1,27 +1,26 @@ # Setup + ## Required Gemini CLI Version + To install this extension, the Gemini CLI version must be v0.6.0 or above. The version can be found by running: `gemini --version`. -gemini extensions install https://github.com/gemini-cli-extensions/oracledb ## Oracle Database MCP Server (Data Plane: Connecting and Querying) -This section covers connecting to a Oracle Database instance in different deployments and client configurations. -### 1. Authentication -Set the following environment variables before starting the Gemini CLI. +This section covers connecting to an Oracle Database instance. + +1. **Extension Configuration**: This extension requires several settings (e.g., Connection String, Username, Password, and optionally Wallet Path and Use OCI). These values are gathered via prompts when you first install or link the extension: +* `ORACLE_CONNECTION_STRING`: The connection string for your Oracle Database (e.g., `host:port/service_name` or TNS alias). * `ORACLE_USERNAME`: Your Oracle database username. * `ORACLE_PASSWORD`: Your Oracle database password. +* `ORACLE_WALLET`: (Optional) Path to the directory containing your Oracle Wallet files. +* `ORACLE_USE_OCI`: (Optional) Set to `true` to use the OCI (thick client) driver. -### 2. Connection Method -* `ORACLE_CONNECTION_STRING`: The connection string for your Oracle Database (e.g., `host:port/service_name` or TNS alias). +If you need to update any of these values later, use the `gemini extensions config oracledb` command. -### 3. Optional Configuration -* `ORACLE_WALLET`: Path to the directory containing your Oracle Wallet files. -* `ORACLE_USE_OCI`: Set to `true` to use the OCI (thick client) driver. +2. **Handle Missing Variables**: If a command fails with an error related to a missing configuration, it signifies a missing environment variable. Inform the user which variable is missing and instruct them to set it. -### 4. Troubleshooting -* **Missing Variables**: If a command fails with an error related to a missing configuration, it signifies a missing environment variable. Please review the setup instructions and ensure the necessary variables are set. -* **Permission Errors**: If you encounter permission errors, ensure the user has the required database-level permissions. `CREATE SESSION` is required for any user to connect. For monitoring and diagnostic tools, `SELECT` privileges on various `V$` (Dynamic Performance Views) and `DBA_` (Data Dictionary Views) are often necessary. +3. **Handle Permission Errors**: If you encounter permission errors, ensure the user has the required database-level permissions. `CREATE SESSION` is required for any user to connect. For monitoring and diagnostic skills, `SELECT` privileges on various `V$` (Dynamic Performance Views) and `DBA_` (Data Dictionary Views) are often necessary. ## Oracle DB Permisions This section covers administrative operations like managing clusters, instances, and users. @@ -40,14 +39,15 @@ This section covers administrative operations like managing clusters, instances, # Usage Guidelines ## Connecting to New Resources -When you create a new Oracle DB instance, or database using the available tools, the connection is not automatically established. You will need to perform the following steps: +When you create a new Oracle DB instance, or database using the available skills, the connection is not automatically established. 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. `ORACLE_CONNECTION_STRING`, `ORACLE_USERNAME`) to point to the new resource. +3. **Update Extension Configuration:** Use the command `gemini extensions config oracledb` to update your settings (e.g. `ORACLE_CONNECTION_STRING`, `ORACLE_USERNAME`) 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. -Instead of prompting the user for these values for specific tool calls, prompt the user to verify reuse of a specific value. -Make sure to not use the environment variable names like `ORACLE_CONNECTION_STRING`, `${ORACLE_CONNECTION_STRING}`, or `$ORACLE_CONNECTION_STRING`. The value can be found by using command: `echo $ORACLE_USERNAME`. +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 names like `ORACLE_CONNECTION_STRING`, `${ORACLE_CONNECTION_STRING}`, or `$ORACLE_CONNECTION_STRING`. +The value can be verified by the user using the `gemini extensions config oracledb` command or by checking their local settings. diff --git a/README.md b/README.md index 1ce4a1a..d80ff36 100644 --- a/README.md +++ b/README.md @@ -1,96 +1,245 @@ -# Gemini CLI Extension - Oracle Database +# Oracle Database 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). -Developers and Engineers can effortlessly connect, interact, and generate data insights with [OracleDB](https://www.oracle.com/database/) datasets and data using natural language commands. +This repository provides a set of agent skills to interact with [Oracle Database](https://www.oracle.com/database/) instances. 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, execute queries, explore schemas, and troubleshoot issues 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=oracle-extension -## Why Use the Oracle DB Extension? +## Table of Contents -* **Natural Language to enteprise data :** Find required Oracle tables and ask transactional or analytical questions in natural language. -* **Seamless Workflow:** Stay in your CLI. No need to constantly switch contexts to the oracle database admin console for connecting and generating insights. -* **Run advanced sql queries :** Connect to enterprise data, Generate vectors and embedings, run sql specific queries using built-in advanced tools. +- [Why Use Oracle Database Agent Skills?](#why-use-oracle-database-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) -# Prerequisites +## Why Use Oracle Database 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. +- **Full Database Insights:** Monitor active sessions, analyze query plans, and manage tablespace usage using natural language. +- **Code Generation:** Accelerate development by asking your agent to generate data classes and other code snippets based on your table schemas. + +## 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). +- 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 +- Access to an Oracle Database instance. +- Oracle Database permissions: + - `CREATE SESSION` for basic connectivity. + - `SELECT` privileges on `V$` and `DBA_` views for monitoring and diagnostics. ## Getting Started -### Installation +### Configuration + +Please keep these settings handy during the installation process: + +- `ORACLE_CONNECTION_STRING`: The connection string for your Oracle Database (e.g., `host:port/service_name` or TNS alias). +- `ORACLE_USERNAME`: Your Oracle database username. +- `ORACLE_PASSWORD`: Your Oracle database password. +- `ORACLE_WALLET`: (Optional) Path to the directory containing your Oracle Wallet files. +- `ORACLE_USE_OCI`: (Optional) Set to `true` to use the OCI (thick client) driver. + +### Installation & Usage + +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. + +For the latest version, check the [releases page][releases]. -To install the extension, use the command: +[releases]: https://github.com/gemini-cli-extensions/oracledb/releases + + + +
+Gemini CLI + +**1. Install the extension:** ```bash gemini extensions install https://github.com/gemini-cli-extensions/oracledb ``` -### Configuration +During the installation, enter your configuration settings as described in the [configuration section](#configuration). -Set the following environment variables before starting the Gemini CLI. These variables can be loaded from a `.env` file or configured using `gemini extensions config oracledb`. +**2. (Optional) Manage Configuration:** +To view or update your configuration in Gemini CLI: + +- Terminal: `gemini extensions config oracledb [setting name] [--scope ]` +- Gemini CLI: `/extensions list` + +**3. Start the agent:** ```bash -export ORACLE_CONNECTION_STRING="" -export ORACLE_USERNAME="" -export ORACLE_PASSWORD="" +gemini ``` -#### Optional Configuration +_(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 agent and cannot be changed during a session. +> To save and resume conversation history in Gemini CLI use command: `/chat save ` and `/chat resume `. + +
+ +
+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 -export ORACLE_WALLET="/path/to/my/wallet/directory" -export ORACLE_USE_OCI=true +claude ``` -### Start Gemini CLI +**3. Add the marketplace:** + +```bash +/plugin marketplace add https://github.com/gemini-cli-extensions/oracledb.git#0.1.1 +``` -To start the Gemini CLI, use the following command: +**4. Install the plugin:** ```bash -gemini +/plugin install oracledb@oracledb-marketplace ``` -> [!WARNING] -> **Changing Instance & 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 `. +_(Tip: Run `/plugin list` inside Claude Code to verify the plugin is active, or `/reload-plugins` if you just installed it.)_ + +
+ +
+Codex + +**1. Clone the Repo:** + +```bash +git clone --branch 0.1.1 git@github.com:gemini-cli-extensions/oracledb.git +``` + +**2. Install the plugin:** + +```bash +mkdir -p ~/.codex/plugins +cp -R /absolute/path/to/oracledb ~/.codex/plugins/oracledb +``` + +**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-google-data-cloud-marketplace", + "interface": { + "displayName": "Google Data Cloud Skills" + }, + "plugins": [ + { + "name": "oracledb", + "source": { + "source": "local", + "path": "./plugins/oracledb" + }, + "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.1.1 https://github.com/gemini-cli-extensions/oracledb.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 oracledb/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 -Interact with Oracle using natural language: - "List the top N SQL statements from the library cache based on a chosen resource metric (CPU, I/O, or Elapsed Time), following is an example of the sql" +Interact with Oracle Database using natural language: + +- **Query Data:** + - "Show me the first 10 rows from the EMPLOYEES table." + - "What is the total salary by department?" +- **Monitor and Analyze:** + - "List all active sessions." + - "Explain the execution plan for this query: SELECT * FROM orders WHERE order_id = 100" + - "What is the tablespace usage?" +- **Object Health:** + - "List all invalid objects in the schema." + +## Supported Skills -## Supported Tools -This extension provides a comprehensive set of tools: +The following skills are available in this repository: -* `execute_sql`: Use this tool to execute any SQL statement. -* `list_active_sessions`: Lists active database sessions. -* `get_query_plan`: Gets the execution plan for a SQL statement. -* `list_top_sql_by_resource`: Lists top SQL statements by resource usage. -* `list_tablespace_usage`: Lists tablespace usage. -* `list_invalid_objects`: Lists invalid objects. +- [Oracle Database Skills](./skills/SKILL.md) - Use these skills to manage and monitor Oracle databases by executing SQL statements, exploring schema metadata, analyzing query performance, monitoring active sessions and resource consumption, and managing storage and object health. -## 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: -* "✖ 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/oracle/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. \ No newline at end of file +- "✖ Error during discovery for server: MCP error -32000: Connection closed": The database connection has not been established. Ensure your configuration is set correctly. +- "✖ 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. From 178232064068db64279d66ef613b3a408e33b5f6 Mon Sep 17 00:00:00 2001 From: Twisha Bansal <58483338+twishabansal@users.noreply.github.com> Date: Thu, 16 Apr 2026 16:24:00 +0530 Subject: [PATCH 2/5] Delete .gitignore --- .gitignore | 9 --------- 1 file changed, 9 deletions(-) delete mode 100644 .gitignore diff --git a/.gitignore b/.gitignore deleted file mode 100644 index 65395be..0000000 --- a/.gitignore +++ /dev/null @@ -1,9 +0,0 @@ -**creds.sh** -toolbox2 -generate-skills-repo.sh -skills-gen/ -.env -node_modules/ -dist/ -build/ -.DS_Store From b7d9280023ef1a304de3c248725bb8e2dfbad237 Mon Sep 17 00:00:00 2001 From: Twisha Bansal <58483338+twishabansal@users.noreply.github.com> Date: Thu, 16 Apr 2026 16:24:34 +0530 Subject: [PATCH 3/5] Update DEVELOPER.md --- DEVELOPER.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/DEVELOPER.md b/DEVELOPER.md index 194188f..dd3be4c 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -1,13 +1,18 @@ # DEVELOPER.md -This document provides instructions for setting up your development environment and contributing to the Oracle Database Agent skills project. +This document provides instructions for setting up your development environment +and contributing to the OracleDB 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. **Oracle Database Instance:** For testing data plane skills, you will need access to an active Oracle Database instance. +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. **OracleDB Cluster & Instance:** For testing data plane tools, you will need access to an active + Oracle DB instance. We recommend using Public IP to eliminate the need to create and use a workspace + within the same VPC network as the database. ## Developing the Extension From ea69cc6d5018328abc56e5838b3638cbd2e90495 Mon Sep 17 00:00:00 2001 From: Twisha Bansal Date: Thu, 16 Apr 2026 16:26:58 +0530 Subject: [PATCH 4/5] revert --- DEVELOPER.md | 59 ++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 43 insertions(+), 16 deletions(-) diff --git a/DEVELOPER.md b/DEVELOPER.md index dd3be4c..57e8227 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -10,9 +10,9 @@ 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. **OracleDB Cluster & Instance:** For testing data plane tools, you will need access to an active +2. **OracleDB Cluster & Instance:** For testing data plane tools, you will need access to an active Oracle DB instance. We recommend using Public IP to eliminate the need to create and use a workspace - within the same VPC network as the database. + within the same VPC network as the database. ## Developing the Extension @@ -30,6 +30,7 @@ Before you begin, ensure you have the following: ```bash gemini extensions install . ``` + The CLI will prompt you to confirm the installation and enter your configuration. 3. **Testing Changes:** After installation, start the Gemini CLI (`gemini`). You can now interact with the `oracledb` skills to manually test your changes against your connected database. @@ -46,15 +47,19 @@ The skills themselves are validated using the `skills-validate.yml` workflow. ### 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. +- **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. ## 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/oracledb-maintainers` ### Releasing @@ -62,19 +67,41 @@ 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/mcp-toolbox` dependency. This ensures that the release notes for this extension accurately reflect important upstream changes. +Before a Release PR is even created, a special workflow automatically mirrors +relevant changelogs from the core `googleapis/mcp-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., `oracle`), 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. +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., + `oracledb`), 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. +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 92cc5b35d385a42482112c2c7bfdf29b66c9d321 Mon Sep 17 00:00:00 2001 From: Twisha Bansal <58483338+twishabansal@users.noreply.github.com> Date: Thu, 16 Apr 2026 16:29:21 +0530 Subject: [PATCH 5/5] Update ORACLEDB.md --- ORACLEDB.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ORACLEDB.md b/ORACLEDB.md index 2e7202a..c499c26 100644 --- a/ORACLEDB.md +++ b/ORACLEDB.md @@ -4,7 +4,7 @@ To install this extension, the Gemini CLI version must be v0.6.0 or above. The version can be found by running: `gemini --version`. -## Oracle Database MCP Server (Data Plane: Connecting and Querying) +## Oracle Database Agent Skills (Data Plane: Connecting and Querying) This section covers connecting to an Oracle Database instance.