MCP tool contract

This is the early v0 surface. The tools are intentionally narrow: agents can request tracked database lifecycle operations without receiving a general-purpose database admin shell.

Workflow tools return compact envelopes with ok, summary, structured errors, warnings, optional change counts, detail handles, and bounded result data.

`list_profiles`

Lists configured profiles and discoverable local Postgres versions so agents can choose a target profile or postgresVersion.

`ensure_postgres`

Installs missing local Postgres server binaries with a supported package manager when available, then starts a managed local profile.

`doctor`

Returns MCP-safe diagnostics and profile health without exposing secrets.

`list_extensions`

Lists available extensions for a profile and installed extension versions for an existing sandbox. Use this before create or clone when an app depends on Postgres extensions.

`create_database`

Creates an isolated database and login role, optionally installing requested extensions available on the target profile. Returns the database id, database name, role name, expiry, installed extensions, and redacted connection string.

`clone_database`

Creates a sandbox, optionally installs requested extensions, and restores an existing Postgres source into it with pg_dump and pg_restore. The restore runs as the sandbox role and cleans up the destination if cloning fails.

`delete_database`

Deletes a database and role created by this MCP. Destructive operations are scoped to tracked sandbox resources.

`get_connection_string`

Returns the connection string for a created sandbox database plus expiry metadata.

`run_sql`

Runs SQL against an experiment database with optional readonly mode and capped row limits.

`describe_schema`

Returns tables, columns, indexes, and extensions for an experiment database.

`schema_digest`

Returns a compact fingerprinted schema digest with object counts and bounded object summaries.

`schema_diff`

Compares two sandbox schemas and returns bounded added, removed, and changed object lists.

`create_schema_snapshot`

Stores an explicit named schema checkpoint for a PGSandbox-owned database.

`list_schema_snapshots`

Lists saved schema checkpoints for a selected sandbox.

`diff_schema_snapshot`

Compares a saved schema checkpoint with the current sandbox schema.

`delete_schema_snapshot`

Deletes a saved schema checkpoint artifact.

`prepare_for_repo`

Writes generic secret-free .pgsandbox/project.json workflow metadata with optional explicit command argv arrays.

`run_repo_command`

Runs an explicit or configured repo command against a selected sandbox with bounded output.

`validate_schema_change`

Captures before and after schema digests around a repo schema-change command and returns a compact diff.

`seed_database`

Runs only an explicit seed command against a selected sandbox.

`create_template_from_sandbox`

Exports a PGSandbox-owned sandbox to a local pg_dump template artifact.

`create_sandbox_from_template`

Restores a local template into a fresh tracked sandbox with its own TTL and role.

`list_templates`

Lists local template artifacts for a profile.

`delete_template`

Deletes a local template artifact.

`list_databases`

Lists active experiment databases, optionally filtered by owner, with a truncation flag and no full secrets.

`cleanup_expired`

Deletes expired resources, with dry-run support for audit-friendly cleanup.