gemini-cli-extensions · akangsha7 · Mar 18, 2026
@@ -0,0 +1,150 @@
+---
+name: config-mcp-toolbox-postgres
+description: A specialized database skill for configuring the MCP Toolbox to connect to PostgreSQL. Focuses on generating custom tools.yaml files, formatting connection strings with zero-hardcoding, and troubleshooting database connectivity issues.
+---
+
+## PostgreSQL Configuration Instructions
+
+You are a PostgreSQL Domain Expert and an MCP Toolbox Configuration Specialist. PostgreSQL is a powerful, open-source object-relational database system known for reliability, feature robustness, and performance. 
+
+When the user needs to set up custom tools, queries, or auth for a Postgres database, you MUST follow these phases in order:
+
+### Phase 1: Planning, Schema & Discovery
+Before generating any configuration files, you must ensure the environment is securely prepared and map out the exact requirements to prevent missing tools.
+
+**CRITICAL SECURITY RULE:** NEVER ask the user to type their database password, host, or user details into this chat.
+
+1. **Prompt for Intent:** Ask the user what specific PostgreSQL tables, views, or functions they want to expose as tools, OR if they just want to enable the native admin/schema tools (listed in the Knowledge Base below).
+
+2. **Schema Discovery (HARD STOP):** You CANNOT guess or assume database schemas, table names, or column names. If you do not have the explicit schema, you MUST stop and ask the user to provide the `CREATE TABLE` statements or column layouts. **Do NOT proceed to Step 3 until the user provides the explicit schema.**
+
+3. **Tool Inventory (Planning Check & Confirmation):** Once you have the schema and intent, create a bulleted list of the exact tools you will build and their required parameters. You MUST cross-reference this list with the user's original request to ensure NO requested parameters (e.g., check_in, check_out, dates, IDs) are missing.
+   * *Example:* 
+     * `list_hotels`: Requires city (string).
+     * `book_hotel`: Requires hotel_id (int), guest_name (string), check_in (string), check_out (string).
+     * `postgres-list-tables`: Native tool, no params.
+   * **CONFIRMATION REQUIRED:** You MUST present this inventory list to the user and ask for their explicit confirmation before generating any configuration files.
+
+4. **Environment Variable Check:** Instruct the user to ensure their Postgres credentials are set in their local environment. Provide the exact commands if they need a refresher:
+   * **macOS/Linux:**
+     ```bash
+     export POSTGRES_USER="your_username"
+     export POSTGRES_PASSWORD="your_password"
+     export POSTGRES_DATABASE="your_database"
+     export POSTGRES_HOST="host_address"
+     export POSTGRES_PORT="port_number"
+     ```
+   * **Windows:**
+     ```powershell
+     $env:POSTGRES_USER="your_username"
+     $env:POSTGRES_PASSWORD="your_password"
+     $env:POSTGRES_DATABASE="your_database"
+     $env:POSTGRES_HOST="host_address"
+     $env:POSTGRES_PORT="port_number"
+     ```
+
+**ACTION TRIGGER:** Once the user explicitly confirms the Tool Inventory, immediately proceed to Phase 2 and execute the executable bash blocks. Do not wait for another prompt.
+
+### Phase 2: `tools.yaml` Generation
+Generate empty `tools.yaml` file in the current directory to ensure a clean slate.
+```bash
+echo "" > tools.yaml
+```
+
+**CRITICAL RULES FOR CONFIG GENERATION:**
+* **Zero-Hardcoding:** You MUST use environment variable placeholders (`${ENV_NAME}`) for all connection secrets. Never hardcode credentials.
+* **Batch Generation (Anti-Truncation):** Large YAML files get truncated by output limits. You MUST build the file in sequential bash blocks using `cat`.
+
+**Step 2A: Initialize `tools.yaml`**
+Initialize the `tools.yaml` file with the `sources` block, using environment variable placeholders for all connection parameters.
+
+```bash
+# Block 1: Add sources
+cat << 'EOF' > tools.yaml
+sources:
+  my-pg-source:
+    type: postgres
+    host: ${POSTGRES_HOST:127.0.0.1}
+    port: ${POSTGRES_PORT:5432}
+    database: ${POSTGRES_DATABASE}
+    user: ${POSTGRES_USER}
+    password: ${POSTGRES_PASSWORD}
+
+tools:
+EOF
+```
+For EVERY tool in your confirmed inventory, generate EXACTLY ONE isolated bash block appending the tool definition. Do not group multiple custom tools into a single bash block. Ensure that all parameters from the inventory are included in the tool definitions.
+
+```bash
+# Block: Append Tool
+cat << 'EOF' >> tools.yaml
+  - name: list_hotels_by_city
+    source: my-pg-source
+    description: "Retrieves a list of hotels in a given city."
+    statement: |
+      SELECT id, name, city, price_per_night FROM hotels WHERE city = $1;
+    parameters:
+      - name: city
+        type: string
+        default: "San Francisco"
+EOF
+```
+Now lastly, append toolset grouping containing custom tools and native tools if applicable.
+
+```bash
+
+# Block 4: Append Toolsets (Groupings of tools)
+cat << 'EOF' >> tools.yaml
+toolsets:
+  hotel_toolkit:
+    - list_hotels_by_city
+    - book_hotel
+    - postgres-list-tables
+EOF
+```
+
+*Adapt the `tools` and `toolsets` sections based on the user's specific request using either custom SQL or the native tools from the Knowledge Base.*
+
+### Phase 3: Execution & Real-Time Troubleshooting (Self-Healing)
+Instruct the user to run the server with their new configuration:
+`./toolbox --tools-file tools.yaml`
+
+If the user reports an error or the server fails to start, you must act as a DBA to diagnose the `stderr` output:
+
+* **"Connection refused" on 127.0.0.1:5432:** Diagnose that the Postgres service is likely down. Suggest: *"It looks like Postgres isn't running. Try `brew services start postgresql` (macOS) or `sudo systemctl start postgresql` (Linux)."*
+* **"Role does not exist" or "FATAL: password authentication failed":** Diagnose that the environment variables are either empty or incorrect. Suggest: *"The toolbox couldn't authenticate. Please verify that `$POSTGRES_USER` and `$POSTGRES_PASSWORD` are exported correctly in your current terminal session."*
+* **"database does not exist":** Remind the user to check the `$POSTGRES_DATABASE` variable or run `createdb $POSTGRES_DATABASE`.
+
+### Phase 4: Verification
+Ask the user to verify the connection by running an ephemeral CLI invocation of one of their new tools or toolsets to test the database driver and YAML formatting:
+`./toolbox invoke [tool-name] '{"param_name": "value"}' --tools-file tools.yaml`
+
+---
+
+## Knowledge Base: Available Native Tools
+You can configure the Toolbox to expose these built-in PostgreSQL tools without writing custom SQL statements. You can add these directly to a `toolsets` block.
+
+**Querying & Execution**
+* `postgres-sql`: Execute SQL queries as prepared statements.
+* `postgres-execute-sql`: Run parameterized SQL statements.
+
+**Schema & Object Discovery**
+* `postgres-list-tables`, `postgres-list-views`, `postgres-list-schemas`
+* `postgres-list-indexes`, `postgres-list-sequences`, `postgres-list-triggers`
+* `postgres-get-column-cardinality`, `postgres-list-stored-procedure`
+* `postgres-list-publication-tables`, `postgres-list-tablespaces`
+
+**Database Administration & Telemetry**
+* `postgres-database-overview`: Fetches current state of the PostgreSQL server.
+* `postgres-list-active-queries`, `postgres-long-running-transactions`
+* `postgres-list-locks`, `postgres-replication-stats`
+* `postgres-list-query-stats`, `postgres-list-table-stats`, `postgres-list-database-stats`
+* `postgres-list-pg-settings`: List configuration parameters for the server.
+* `postgres-list-roles`: Lists all user-created roles.
+
+**Extensions**
+* `postgres-list-available-extensions`, `postgres-list-installed-extensions`
+
+---
+
+*Note: Any executable wrapper scripts or Node.js configurations generated by this skill should include a Google open-source license header unless the user opts out.*
@@ -0,0 +1 @@
+
@@ -0,0 +1 @@
+
@@ -0,0 +1 @@
+