db-mcp: Instructions file for Codex

AGENTS.md

Scope

This file applies to the entire repository. If a more specific AGENTS.md is added under a subdirectory, its instructions supplement and take precedence within that subtree.

Understand the Project First

postgres-mcp is a small text-to-SQL backend that exposes multiple PostgreSQL data sources through one stateless Streamable HTTP MCP endpoint. The MCP host's AI interprets natural language and generates SQL. This server exposes the real database catalog and executes one parameterized PostgreSQL statement against one selected data source inside a constrained transaction.

Before making changes, read the following in order as relevant to the task:

1. README.md: external contracts, configuration, and usage
2. docs/service-boundaries.md: what the service does and does not own
3. docs/architecture-v0.4.0.md: component responsibilities and operational invariants
4. docs/code-story-ko.md: the end-to-end flow of one request
5. For deployment changes only: docs/deployment.md, Dockerfile, and deploy/k8s/postgres-mcp.yaml

Do not treat the local .env, generated dist/ artifacts, .runtime/ logs, or cache directories as work targets.

Fixed Product Boundaries

The following are intentional product invariants. Do not add options or compatibility paths for them unless the requirements explicitly change.

• The public MCP surface consists of exactly two tools: search_objects and execute_sql.
• The server does not provide a separate MCP prompt, a general-purpose REST API, or a web UI.
• The executable is postgres-mcp. The transport is stateless Streamable HTTP, the path is /mcp, and responses are JSON.
• Database configuration comes only from the TOML file referenced by POSTGRES_MCP_CONFIG. The process does not load .env implicitly or fall back to CLI arguments or DSN environment variables.
• TOML contains host, port, database, execution policies, and the names of credential environment variables. Usernames and passwords are read from the environment and must not appear in public results or representations.
• PostgreSQL is the only supported database. Do not introduce a common driver, adapter, or backend layer until a real second database requirement exists.
• One SQL statement runs against exactly one data source. Cross-source joins and transactions are outside this service's responsibility.
• Each source creates its pool lazily on first use. Concurrent first access to the same source is serialized by one lock. A connection that fails to initialize is not stored in the registry.
• MCP requests are stateless, but the process owns and reuses pools until shutdown.
• /healthz reports process liveness. /readyz reports that configuration has loaded and the server can accept requests. Readiness must not preconnect to every database.
• Safe defaults include read-only transactions, prepared statements, $1-style parameters, row limits, and statement and connection timeouts.
• PostgreSQL permissions, TLS, and user authentication belong to PostgreSQL and the gateway or ingress. Application settings do not replace those controls.