From 6c9ca511b513c37eb8be3ad3ccb4ecec0746dcee Mon Sep 17 00:00:00 2001 From: Akangsha goel Date: Wed, 18 Mar 2026 10:23:41 -0700 Subject: [PATCH] Add config-mcp-toolbox-postgres skill and directory structure --- skills/config-mcp-toolbox-postgres/SKILL.md | 150 ++++++++++++++++++ .../assets/.gitkeep | 1 + .../references/.gitkeep | 1 + .../scripts/.gitkeep | 1 + 4 files changed, 153 insertions(+) create mode 100644 skills/config-mcp-toolbox-postgres/SKILL.md create mode 100644 skills/config-mcp-toolbox-postgres/assets/.gitkeep create mode 100644 skills/config-mcp-toolbox-postgres/references/.gitkeep create mode 100644 skills/config-mcp-toolbox-postgres/scripts/.gitkeep diff --git a/skills/config-mcp-toolbox-postgres/SKILL.md b/skills/config-mcp-toolbox-postgres/SKILL.md new file mode 100644 index 0000000..a8dc97e --- /dev/null +++ b/skills/config-mcp-toolbox-postgres/SKILL.md @@ -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.* diff --git a/skills/config-mcp-toolbox-postgres/assets/.gitkeep b/skills/config-mcp-toolbox-postgres/assets/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/skills/config-mcp-toolbox-postgres/assets/.gitkeep @@ -0,0 +1 @@ + diff --git a/skills/config-mcp-toolbox-postgres/references/.gitkeep b/skills/config-mcp-toolbox-postgres/references/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/skills/config-mcp-toolbox-postgres/references/.gitkeep @@ -0,0 +1 @@ + diff --git a/skills/config-mcp-toolbox-postgres/scripts/.gitkeep b/skills/config-mcp-toolbox-postgres/scripts/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/skills/config-mcp-toolbox-postgres/scripts/.gitkeep @@ -0,0 +1 @@ +