From 02048adc20b978a0594596d25b554b8663c0c859 Mon Sep 17 00:00:00 2001 From: Juexin Wang Date: Fri, 14 Aug 2026 17:07:12 -0700 Subject: [PATCH 1/4] feat: adopt Agent Plugin spec and generate harness manifests --- .claude-plugin/plugin.json | 69 ++++++++++++++++++++++++++++++++++++++ .codex-plugin/.mcp.json | 22 ++++++++++++ .codex-plugin/plugin.json | 12 +++++++ mcp.json | 16 +++++++++ mcp_config.json | 14 ++++++++ plugin.json | 52 ++++++++++++++++++++++++++++ 6 files changed, 185 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 .codex-plugin/.mcp.json create mode 100644 .codex-plugin/plugin.json create mode 100644 mcp.json create mode 100644 mcp_config.json create mode 100644 plugin.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..1f87fb5 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,69 @@ +{ + "name": "postgres", + "version": "0.2.2", + "description": "Connect and interact with a PostgreSQL database and data", + "author": { + "name": "Google LLC", + "email": "data-cloud-ai-integrations@google.com" + }, + "repository": "https://github.com/gemini-cli-extensions/postgres", + "license": "Apache-2.0", + "userConfig": { + "postgres_host": { + "title": "Host", + "description": "Host or IP address of the PostgreSQL server", + "type": "string", + "sensitive": false + }, + "postgres_port": { + "title": "Port", + "description": "Port number of the PostgreSQL server", + "type": "string", + "sensitive": false + }, + "postgres_database": { + "title": "Database", + "description": "Name of the database", + "type": "string", + "sensitive": false + }, + "postgres_user": { + "title": "User", + "description": "Username of the database user", + "type": "string", + "sensitive": false + }, + "postgres_password": { + "title": "Password", + "description": "Password of the database user", + "type": "string", + "sensitive": true + }, + "postgres_query_params": { + "title": "Query Params", + "description": "(Optional) Connection String Parameters", + "type": "string", + "sensitive": false + } + }, + "mcpServers": { + "postgresql": { + "command": "npx", + "args": [ + "-y", + "@toolbox-sdk/server@1.8.0", + "--prebuilt", + "postgres", + "--stdio" + ], + "env": { + "POSTGRES_HOST": "${user_config.postgres_host}", + "POSTGRES_PORT": "${user_config.postgres_port}", + "POSTGRES_DATABASE": "${user_config.postgres_database}", + "POSTGRES_USER": "${user_config.postgres_user}", + "POSTGRES_PASSWORD": "${user_config.postgres_password}", + "POSTGRES_QUERY_PARAMS": "${user_config.postgres_query_params}" + } + } + } +} diff --git a/.codex-plugin/.mcp.json b/.codex-plugin/.mcp.json new file mode 100644 index 0000000..d0339b7 --- /dev/null +++ b/.codex-plugin/.mcp.json @@ -0,0 +1,22 @@ +{ + "mcpServers": { + "postgresql": { + "command": "npx", + "args": [ + "-y", + "@toolbox-sdk/server@1.8.0", + "--prebuilt", + "postgres", + "--stdio" + ], + "env_vars": [ + "POSTGRES_HOST", + "POSTGRES_PORT", + "POSTGRES_DATABASE", + "POSTGRES_USER", + "POSTGRES_PASSWORD", + "POSTGRES_QUERY_PARAMS" + ] + } + } +} diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json new file mode 100644 index 0000000..c72dd5d --- /dev/null +++ b/.codex-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "postgres", + "version": "0.2.2", + "description": "Connect and interact with a PostgreSQL database and data", + "author": { + "name": "Google LLC", + "email": "data-cloud-ai-integrations@google.com" + }, + "repository": "https://github.com/gemini-cli-extensions/postgres", + "license": "Apache-2.0", + "mcpServers": "./.codex-plugin/.mcp.json" +} diff --git a/mcp.json b/mcp.json new file mode 100644 index 0000000..ef66465 --- /dev/null +++ b/mcp.json @@ -0,0 +1,16 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", + "mcpServers": { + "postgresql": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@toolbox-sdk/server@1.8.0", + "--prebuilt", + "postgres", + "--stdio" + ] + } + } +} diff --git a/mcp_config.json b/mcp_config.json new file mode 100644 index 0000000..b3478af --- /dev/null +++ b/mcp_config.json @@ -0,0 +1,14 @@ +{ + "mcpServers": { + "postgresql": { + "command": "npx", + "args": [ + "-y", + "@toolbox-sdk/server@1.8.0", + "--prebuilt", + "postgres", + "--stdio" + ] + } + } +} diff --git a/plugin.json b/plugin.json new file mode 100644 index 0000000..8c4159d --- /dev/null +++ b/plugin.json @@ -0,0 +1,52 @@ +{ + "name": "postgres", + "version": "0.2.2", + "description": "Connect and interact with a PostgreSQL database and data", + "author": { + "name": "Google LLC", + "email": "data-cloud-ai-integrations@google.com" + }, + "repository": "https://github.com/gemini-cli-extensions/postgres", + "license": "Apache-2.0", + "extensions": { + "com.google.cloud.data.agent-plugins": { + "config": [ + { + "key": "POSTGRES_HOST", + "title": "Host", + "description": "Host or IP address of the PostgreSQL server" + }, + { + "key": "POSTGRES_PORT", + "title": "Port", + "description": "Port number of the PostgreSQL server" + }, + { + "key": "POSTGRES_DATABASE", + "title": "Database", + "description": "Name of the database" + }, + { + "key": "POSTGRES_USER", + "title": "User", + "description": "Username of the database user" + }, + { + "key": "POSTGRES_PASSWORD", + "title": "Password", + "description": "Password of the database user", + "sensitive": true + }, + { + "key": "POSTGRES_QUERY_PARAMS", + "title": "Query Params", + "description": "(Optional) Connection String Parameters" + } + ], + "gemini": { + "contextFileName": "POSTGRESQL.md", + "mcpServerName": "postgresql" + } + } + } +} From 27c26a8cfa4a454e50e3e03cb2ad9fa8ccaebeb9 Mon Sep 17 00:00:00 2001 From: Juexin Wang Date: Fri, 14 Aug 2026 17:57:49 -0700 Subject: [PATCH 2/4] feat: add marketplace.json for Claude Code and Codex --- .claude-plugin/marketplace.json | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 .claude-plugin/marketplace.json diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..dc84c0f --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,16 @@ +{ + "name": "postgres", + "owner": { + "name": "Google LLC", + "email": "data-cloud-ai-integrations@google.com" + }, + "metadata": { + "description": "Connect and interact with a PostgreSQL database and data." + }, + "plugins": [ + { + "name": "postgres", + "source": "./" + } + ] +} From f7baa108d9ae1b6999f0cb7d6acb14f1f7c6fce0 Mon Sep 17 00:00:00 2001 From: Juexin Wang Date: Fri, 14 Aug 2026 17:57:49 -0700 Subject: [PATCH 3/4] docs: document installation and configuration for all supported harnesses --- README.md | 58 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 40 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 13c6b12..e04260f 100644 --- a/README.md +++ b/README.md @@ -24,8 +24,12 @@ Learn more about [Gemini CLI Extensions](https://github.com/google-gemini/gemini 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 the supported agent harnesses, installed and authenticated: + * [Gemini CLI](https://github.com/google-gemini/gemini-cli) (v0.6.0+) + * [Claude Code](https://code.claude.com) + * [Codex](https://developers.openai.com/codex) + * [Antigravity CLI](https://antigravity.google) +* [Node.js](https://nodejs.org/) (the MCP server runs via `npx`). * A running PostgreSQL instance. * Users are granted database-level permissions to execute queries. @@ -33,42 +37,60 @@ Before you begin, ensure you have the following: ### Installation -To install the extension, use the command: +All harnesses use the same plugin; the MCP server runs via `npx` (no binary to download). Install with your harness of choice: + +**Gemini CLI** ```bash gemini extensions install https://github.com/gemini-cli-extensions/postgres ``` +**Claude Code** + +```bash +claude plugin marketplace add gemini-cli-extensions/postgres +claude plugin install postgres@postgres +``` + +**Codex** + +```bash +codex plugin marketplace add gemini-cli-extensions/postgres +codex plugin add postgres@postgres +``` + +**Antigravity** + +```bash +agy plugin install https://github.com/gemini-cli-extensions/postgres +``` + +See [Configuration](#configuration) for how each harness supplies the connection settings. + ### Configuration -You will be prompted to configure the following settings during installation. These settings are saved in an `.env` file within the extension's directory. +The plugin connects to PostgreSQL using these settings: * `POSTGRES_HOST`: (Optional) The Postgres host. Defaults to `localhost`. * `POSTGRES_PORT`: (Optional) The Postgres port. Defaults to `5432`. * `POSTGRES_DATABASE`: The name of the database to connect to. * `POSTGRES_USER`: The database username. * `POSTGRES_PASSWORD`: The password for the database user. +* `POSTGRES_QUERY_PARAMS`: (Optional) Connection string parameters. -To view or update your configuration: - -**List Settings:** -* Terminal: `gemini extensions list` -* Gemini CLI: `/extensions list` - -**Update Settings:** -* Terminal: `gemini extensions config postgres [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. +How you supply them depends on the harness: -Alternatively, you can manually set these environment variables before starting the Gemini CLI: +* **Gemini CLI**: prompted on install and saved to the extension's `.env`. View or update later with `gemini extensions list` / `gemini extensions config postgres [setting] [--scope user|workspace]` (restart the CLI to apply). +* **Claude Code**: pass `--config KEY=VALUE` on install (repeatable), or run `/plugin` inside Claude Code. +* **Codex** and **Antigravity**: export the variables in your shell before starting: ```bash -export POSTGRES_HOST="" # Optional: defaults to localhost -export POSTGRES_PORT="" # Optional: defaults to 5432 +export POSTGRES_HOST="" # Optional, defaults to localhost +export POSTGRES_PORT="" # Optional, defaults to 5432 export POSTGRES_DATABASE="" export POSTGRES_USER="" export POSTGRES_PASSWORD="" +export POSTGRES_QUERY_PARAMS="" # Optional ``` > [!NOTE] From f7a80b267f6ab1025785f9850e4772c1647ce9a0 Mon Sep 17 00:00:00 2001 From: Juexin Wang Date: Mon, 17 Aug 2026 11:08:52 -0700 Subject: [PATCH 4/4] chore: order config required-first --- .claude-plugin/plugin.json | 28 ++++++++++++++-------------- .codex-plugin/.mcp.json | 4 ++-- README.md | 8 ++++---- gemini-extension.json | 20 ++++++++++---------- plugin.json | 20 ++++++++++---------- 5 files changed, 40 insertions(+), 40 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 1f87fb5..d7b3dfb 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -9,18 +9,6 @@ "repository": "https://github.com/gemini-cli-extensions/postgres", "license": "Apache-2.0", "userConfig": { - "postgres_host": { - "title": "Host", - "description": "Host or IP address of the PostgreSQL server", - "type": "string", - "sensitive": false - }, - "postgres_port": { - "title": "Port", - "description": "Port number of the PostgreSQL server", - "type": "string", - "sensitive": false - }, "postgres_database": { "title": "Database", "description": "Name of the database", @@ -39,6 +27,18 @@ "type": "string", "sensitive": true }, + "postgres_host": { + "title": "Host", + "description": "Host or IP address of the PostgreSQL server", + "type": "string", + "sensitive": false + }, + "postgres_port": { + "title": "Port", + "description": "Port number of the PostgreSQL server", + "type": "string", + "sensitive": false + }, "postgres_query_params": { "title": "Query Params", "description": "(Optional) Connection String Parameters", @@ -57,11 +57,11 @@ "--stdio" ], "env": { - "POSTGRES_HOST": "${user_config.postgres_host}", - "POSTGRES_PORT": "${user_config.postgres_port}", "POSTGRES_DATABASE": "${user_config.postgres_database}", "POSTGRES_USER": "${user_config.postgres_user}", "POSTGRES_PASSWORD": "${user_config.postgres_password}", + "POSTGRES_HOST": "${user_config.postgres_host}", + "POSTGRES_PORT": "${user_config.postgres_port}", "POSTGRES_QUERY_PARAMS": "${user_config.postgres_query_params}" } } diff --git a/.codex-plugin/.mcp.json b/.codex-plugin/.mcp.json index d0339b7..6bfed33 100644 --- a/.codex-plugin/.mcp.json +++ b/.codex-plugin/.mcp.json @@ -10,11 +10,11 @@ "--stdio" ], "env_vars": [ - "POSTGRES_HOST", - "POSTGRES_PORT", "POSTGRES_DATABASE", "POSTGRES_USER", "POSTGRES_PASSWORD", + "POSTGRES_HOST", + "POSTGRES_PORT", "POSTGRES_QUERY_PARAMS" ] } diff --git a/README.md b/README.md index e04260f..3a0dc5f 100644 --- a/README.md +++ b/README.md @@ -71,11 +71,11 @@ See [Configuration](#configuration) for how each harness supplies the connection The plugin connects to PostgreSQL using these settings: -* `POSTGRES_HOST`: (Optional) The Postgres host. Defaults to `localhost`. -* `POSTGRES_PORT`: (Optional) The Postgres port. Defaults to `5432`. * `POSTGRES_DATABASE`: The name of the database to connect to. * `POSTGRES_USER`: The database username. * `POSTGRES_PASSWORD`: The password for the database user. +* `POSTGRES_HOST`: (Optional) The Postgres host. Defaults to `localhost`. +* `POSTGRES_PORT`: (Optional) The Postgres port. Defaults to `5432`. * `POSTGRES_QUERY_PARAMS`: (Optional) Connection string parameters. How you supply them depends on the harness: @@ -85,11 +85,11 @@ How you supply them depends on the harness: * **Codex** and **Antigravity**: export the variables in your shell before starting: ```bash -export POSTGRES_HOST="" # Optional, defaults to localhost -export POSTGRES_PORT="" # Optional, defaults to 5432 export POSTGRES_DATABASE="" export POSTGRES_USER="" export POSTGRES_PASSWORD="" +export POSTGRES_HOST="" # Optional, defaults to localhost +export POSTGRES_PORT="" # Optional, defaults to 5432 export POSTGRES_QUERY_PARAMS="" # Optional ``` diff --git a/gemini-extension.json b/gemini-extension.json index 07c1f44..33ef3ed 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -16,16 +16,6 @@ }, "contextFileName": "POSTGRESQL.md", "settings": [ - { - "name": "Host", - "description": "Host or IP address of the PostgreSQL server", - "envVar": "POSTGRES_HOST" - }, - { - "name": "Port", - "description": "Port number of the PostgreSQL server", - "envVar": "POSTGRES_PORT" - }, { "name": "Database", "description": "Name of the database", @@ -41,6 +31,16 @@ "description": "Password of the database user", "envVar": "POSTGRES_PASSWORD" }, + { + "name": "Host", + "description": "Host or IP address of the PostgreSQL server", + "envVar": "POSTGRES_HOST" + }, + { + "name": "Port", + "description": "Port number of the PostgreSQL server", + "envVar": "POSTGRES_PORT" + }, { "name": "Query Params", "description": "(Optional) Connection String Parameters", diff --git a/plugin.json b/plugin.json index 8c4159d..11d50b4 100644 --- a/plugin.json +++ b/plugin.json @@ -11,16 +11,6 @@ "extensions": { "com.google.cloud.data.agent-plugins": { "config": [ - { - "key": "POSTGRES_HOST", - "title": "Host", - "description": "Host or IP address of the PostgreSQL server" - }, - { - "key": "POSTGRES_PORT", - "title": "Port", - "description": "Port number of the PostgreSQL server" - }, { "key": "POSTGRES_DATABASE", "title": "Database", @@ -37,6 +27,16 @@ "description": "Password of the database user", "sensitive": true }, + { + "key": "POSTGRES_HOST", + "title": "Host", + "description": "Host or IP address of the PostgreSQL server" + }, + { + "key": "POSTGRES_PORT", + "title": "Port", + "description": "Port number of the PostgreSQL server" + }, { "key": "POSTGRES_QUERY_PARAMS", "title": "Query Params",