databridge-kit

databridge-kit

databridge-kit is a small bridge between an agent (or a terminal) and one configured PostgreSQL database. It can run a single SQL statement and answer the seven inspection questions that come up constantly while exploring an unfamiliar database: which tables, views, schemas, triggers, indexes, sequences and stored procedures exist.

The toolset mirrors the documented prebuilt Postgres toolset of a config-defined database toolbox: the tools are fixed, the database is whatever the connection string points at. There is no bundled database driver — statements run through the psql command-line client, so a machine that wants live answers needs psql on its PATH. Without it — or without a connection string — the server still starts and lists its tools; only the calls themselves report the problem.

Install

npx @reneturcios/databridge-kit list-tables postgres://user@localhost:5432/mydb

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/databridge-kit

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

CLI

# Run one SQL statement; rows print as JSON
databridge-kit execute-sql postgres://alice@localhost/shop "SELECT id, name FROM products ORDER BY id"

# Inspection commands; each prints its rows as JSON
databridge-kit list-tables postgres://alice@localhost/shop
databridge-kit list-views postgres://alice@localhost/shop
databridge-kit list-schemas postgres://alice@localhost/shop
databridge-kit list-triggers postgres://alice@localhost/shop
databridge-kit list-indexes postgres://alice@localhost/shop
databridge-kit list-sequences postgres://alice@localhost/shop
databridge-kit list-stored-procedures postgres://alice@localhost/shop

# Start the MCP server (connection string optional, see below)
databridge-kit mcp postgres://alice@localhost/shop

databridge-kit --version

Exit codes: 0 on success, 1 when the statement, the connection string, or psql itself fails (the error says which), 2 for usage errors.

The connection string is a normal PostgreSQL URL: postgres:// or postgresql://, with host, optional port (default 5432), database name from the path, and optional user and password in the userinfo. For the mcp command the string can be left off the command line and supplied through the DATABRIDGE_DATABASE_URL environment variable instead (plain DATABASE_URL works too).

How statements and inspections work

execute_sql accepts exactly one statement per call. Semicolons inside string literals and comments do not count as statement boundaries, but a second real statement is rejected before anything reaches the database. The statement type is not restricted — this is a general bridge, so a caller who can reach it can write as well as read; point it only at databases where that is intended.

Each inspection tool runs one fixed catalogue query:

Tool	Catalogue read
list_tables	information_schema.tables (base tables)
list_views	information_schema.views
list_schemas	information_schema.schemata
list_triggers	information_schema.triggers
list_indexes	pg_indexes
list_sequences	information_schema.sequences
list_stored_procedure	information_schema.routines

Statements run as psql -v ON_ERROR_STOP=1 --csv -c <sql> and the CSV output is parsed into row objects. Values come back as the strings psql rendered.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/databridge-kit mcp postgres://alice@localhost/shop

MCP client configuration:

{
  "mcpServers": {
    "databridge-kit": {
      "command": "npx",
      "args": ["-y", "@reneturcios/databridge-kit", "mcp"],
      "env": { "DATABRIDGE_DATABASE_URL": "postgres://alice@localhost/shop" }
    }
  }
}

Tools

Tool	Input	What it returns
execute_sql	sql (string, required) — one SQL statement	The result rows as a JSON array of objects keyed by column name.
list_tables	—	Rows describing the base tables in the configured source.
list_views	—	Rows describing the views in the configured source.
list_schemas	—	Rows describing the schemas in the configured source.
list_triggers	—	Rows describing the triggers in the configured source.
list_indexes	—	Rows describing the indexes in the configured source.
list_sequences	—	Rows describing the sequences in the configured source.
list_stored_procedure	—	Rows describing the stored procedures (routines) in the configured source.

A missing connection, a missing psql, a multi-statement execute_sql, and database errors all come back as tool errors — never as made-up rows.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network, no live database
npm run dev     # run the CLI from source via tsx

The core logic sits behind an injectable executor interface, which is what the test suite drives: connection-string parsing, the single-statement check, pass-through execution, error propagation, and the exact catalogue SQL behind every inspection tool are all covered with a fake executor.

License

MIT — see LICENSE.