Seedfast

Probes a PostgreSQL database for reachability by opening a connection pool and issuing a ping with a 10-second timeout. Returns a short text line stating success or failure for the supplied DSN (credentials are masked in the output). Use this before seedfast_plan or seedfast_run to catch bad DSNs, firewall issues, or wrong credentials without incurring a planning or seeding round-trip. Does not require SEEDFAST_API_KEY. Next: on success, call seedfast_plan to preview a seeding plan or seedfast_run to execute one.

Diagnoses whether the Seedfast CLI environment is healthy and ready to run seedings. Returns a multi-line text summary: CLI status and version, binary path, whether SEEDFAST_API_KEY is configured, platform (GOOS/GOARCH), Go runtime version, and MCP server version. Call this FIRST before any other seedfast_* tool — it surfaces misconfigurations (missing CLI, missing API key) early and in plain language. Next: if status is OK, call seedfast_connections_test to verify database reachability before seedfast_plan or seedfast_run.

Generates a seeding plan for the given database and scope WITHOUT writing any data, then stores the plan in the current MCP session for later reuse. Returns a text block containing the generated plan ID, the scope echoed back, a table list with count, and an optional human-readable preview. Use this when the user wants to review what would be seeded before committing — e.g., to inspect which tables the scope covers. Requires SEEDFAST_API_KEY configured in MCP env. For scope-writing guidance, request the `scope-examples` prompt. Next: call seedfast_plan_get or read the seedfast://plans/{planId} resource to inspect the plan, then seedfast_run with planId to execute it.

Stores a manually-crafted seeding plan in the current MCP session without calling the backend planner. Returns a text block with the new plan ID, scope, and table list. Use this when the caller already knows exactly which tables to seed (e.g., derived from a user prompt or a previous run) and wants to skip the planner round-trip, or to construct a plan for seedfast_run with planId. At least one entry in `tables` is required. Does not require SEEDFAST_API_KEY. Next: call seedfast_run with planId to execute, or seedfast_plan_update to refine the plan.

Permanently removes a stored plan from the current MCP session. Returns a short text line confirming deletion; returns an error when the ID is unknown or the delete fails. This is a destructive action — the plan cannot be recovered through this tool. It does NOT cancel or affect any seeding run that was previously started from the plan. Use only when the user explicitly wants to discard a plan. Does not require SEEDFAST_API_KEY. Next: call seedfast_plans_list to confirm the plan is gone.

Retrieves a single stored seeding plan by ID. Returns a text block with the plan ID, scope, full table list, optional human-readable preview, and created/updated timestamps; returns an error when the ID is unknown. Use this to inspect a plan's table set before executing it, or to show the user what a plan contains. Does not require SEEDFAST_API_KEY (reads local session state). Next: call seedfast_run with planId to execute, seedfast_plan_update to modify, or seedfast_plan_delete to remove it.

Modifies an existing stored plan in place. Returns a text block confirming the update with the plan ID, scope, table list, and new updated-at timestamp; returns an error when the ID is unknown. Only non-empty/non-zero fields in the request overwrite the stored plan — omitted fields are preserved (there is no way to clear preview or scope to empty via this tool). Use this to adjust a plan's tables or scope before executing with seedfast_run. Does not require SEEDFAST_API_KEY. Next: call seedfast_plan_get to verify, or seedfast_run with planId to execute.

Lists seeding plans stored in the current MCP session (in-memory; plans do not persist across MCP server restarts). Returns a text block with up to `limit` plans, each showing ID, scope, table count with names, and created/updated timestamps; returns 'No plans found' when the session has none. Use this to discover plan IDs before calling seedfast_plan_get, seedfast_plan_update, seedfast_plan_delete, or seedfast_run with planId. Does not require SEEDFAST_API_KEY. Next: pick an ID and call seedfast_plan_get for full details, or seedfast_run to execute.

Kicks off an asynchronous seeding run against the target database. Returns immediately with a text block containing the new runId, initial status (pending), the plan ID if supplied, and the effective scope; the seeding itself runs in the background — poll seedfast_run_status or subscribe to the seedfast://runs/{runId}/summary and seedfast://runs/{runId}/log resources for progress. If planId is provided, the scope is auto-generated from that plan's tables and the scope argument is ignored; otherwise scope is required. If idempotencyKey matches a prior run, that existing run is returned instead of starting a new one. Use this once the user has approved a plan (or wants direct execution). Requires SEEDFAST_API_KEY configured in MCP env. For production-safe workflows, request the `seed-production-db` prompt first. Next: seedfast_run_status to poll, or seedfast_run_cancel to abort.

Answers a pending question for a run that is in state 'awaiting_input'. The CLI forwards backend questions (scope validation issues, replans) to this MCP server via subprocess stdio and blocks for up to 5 minutes on a reply. Call this tool with the runId, the questionId from seedfast_run_status (or the seedfast://runs/{runId}/pending_question resource), and an answer object. Set answer.human_answer=true to approve the current plan/scope as-is; set human_answer=false and supply answer.raw with a textual refinement (e.g., 'seed only the org schema') when the plan should be adjusted. Returns a short text confirmation. On success the run transitions back to 'running'; poll seedfast_run_status to observe progress. Does not require SEEDFAST_API_KEY.

Requests cancellation of a pending or running seeding operation. Returns a text line confirming cancellation, or — if the run is already completed/failed/cancelled — a message that it is not cancellable (no error). This is a destructive action against the run: partial inserts already written to the database are NOT rolled back. Use only when the user explicitly asks to stop a run or when a runaway operation must be aborted. Does not require SEEDFAST_API_KEY. Next: call seedfast_run_status to confirm the final state.

Reports the current state and progress of a seeding run by ID. Returns a text block containing: run ID, state (pending/running/completed/failed/cancelled), scope, started/completed timestamps, progress (completed vs total tables with percent, total rows, failed count, currently-seeding table), any error message, and — once finished — a summary block with success flag, totals, and elapsed milliseconds. Use this to poll an async seedfast_run; it is safe to call repeatedly. Does not require SEEDFAST_API_KEY (reads local in-memory state). Next: if state is still running, poll again; if failed, inspect the error and failed-tables map; if completed, the run is done.

Introspects a PostgreSQL database schema — lists tables, columns, primary keys, foreign keys, and approximate row counts. Returns a JSON object with a tables array; each entry has name (schema-qualified), columns (name, data_type, nullable, default), primary_key, foreign_keys (columns, references_table, references_columns), and approximate_row_count. Row counts come from pg_class.reltuples and are APPROXIMATE — they may be stale between ANALYZEs and may be -1 on never-analyzed tables. Implementation invokes `seedfast schema --json` as a subprocess with a 30s timeout. Call this before writing a scope description — it helps you understand table relationships and size so you can craft a precise scope; especially useful for large databases where you want to target specific tables. Does not require SEEDFAST_API_KEY. The `dsn` argument is optional — when omitted, the server falls back to SEEDFAST_DSN or DATABASE_URL from its environment. Next: use the schema info to write a scope string, then call seedfast_plan with that scope. For scope-writing guidance, also request the `scope-examples` prompt.