@futuretea/postgres-mcp-server 0.0.1 → 0.1.0

package/README.md

@@ -1,5 +1,7 @@
 # PostgreSQL Read-only MCP Server
 
+[中文](README.zh.md)
+
 An MCP (Model Context Protocol) server for discovering one PostgreSQL 17+ instance and running a deliberately narrow SELECT subset. It exposes MCP over stdio or HTTP and includes a CLI.
 
 ## Quick start
@@ -15,6 +17,97 @@ make build
 
 `tools list` and `tools describe` do not read database connection settings. Starting MCP/HTTP or calling a tool validates the connection and verifies the server and role before it reports ready.
 
+## Use a release
+
+Release `v0.0.1` is available as an npm package and a multi-architecture Docker image. Both release entry points start MCP over stdio by default.
+
+### npm
+
+Run the published package with `npx`:
+
+```sh
+export DATABASE_URL='postgres://reader@127.0.0.1:5432/app?sslmode=disable'
+npx -y @futuretea/postgres-mcp-server@0.0.1
+```
+
+For an MCP client configuration, use:
+
+```json
+{
+  "mcpServers": {
+    "postgres-readonly": {
+      "command": "npx",
+      "args": ["-y", "@futuretea/postgres-mcp-server@0.0.1"],
+      "env": {
+        "DATABASE_URL": "postgres://reader@127.0.0.1:5432/app?sslmode=disable"
+      }
+    }
+  }
+}
+```
+
+The npm command is an MCP entry point, not a wrapper for the server's other CLI subcommands. Pin the package version you intend to run.
+
+### Docker
+
+Run the published image directly:
+
+```sh
+export DATABASE_URL='postgres://reader@db.example.internal:5432/app?sslmode=require'
+docker run --rm -i \
+  --env DATABASE_URL \
+  ghcr.io/futuretea/postgres-mcp-server:v0.0.1
+```
+
+For an MCP client that launches Docker, pass the connection setting through the Docker process:
+
+```json
+{
+  "mcpServers": {
+    "postgres-readonly": {
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "-i",
+        "--env",
+        "DATABASE_URL",
+        "ghcr.io/futuretea/postgres-mcp-server:v0.0.1"
+      ],
+      "env": {
+        "DATABASE_URL": "postgres://reader@db.example.internal:5432/app?sslmode=require"
+      }
+    }
+  }
+}
+```
+
+The database hostname must be reachable from the container. `localhost` inside the container is not the host machine; use a database hostname on the Docker network, or the platform-specific host gateway when appropriate.
+
+The Docker examples use `sslmode=require` for a remote database. Set the PostgreSQL TLS mode and certificates required by your deployment.
+
+### HTTP mode
+
+Pass MCP flags after the release command to start HTTP instead of stdio. On the host, the default listener is loopback:
+
+```sh
+export DATABASE_URL='postgres://reader@127.0.0.1:5432/app?sslmode=disable'
+npx -y @futuretea/postgres-mcp-server@0.0.1 --port 8080
+```
+
+For Docker, the server must listen on all container interfaces, while the published port can remain loopback-only on the host:
+
+```sh
+export DATABASE_URL='postgres://reader@db.example.internal:5432/app?sslmode=require'
+docker run --rm \
+  --env DATABASE_URL \
+  --publish 127.0.0.1:8080:8080 \
+  ghcr.io/futuretea/postgres-mcp-server:v0.0.1 \
+  --port 8080 --listen 0.0.0.0
+```
+
+Use `http://127.0.0.1:8080/mcp` for Streamable HTTP MCP clients. The server also provides SSE at `/sse` with messages at `/message`, and `GET /healthz` for health checks. HTTP has no authentication or TLS; keep it on a trusted network or place it behind infrastructure that provides both.
+
 ## Tools
 
 | Tool | Parameters | Purpose |
@@ -35,6 +128,56 @@ Use a bare `DATABASE_URL`, or standard PostgreSQL environment variables such as
 
 At startup the server requires PostgreSQL 17 or newer and rejects service roles that are superusers, bypass row-level security, have replication, or belong to server-file, server-program, or backend-signalling roles. Use a dedicated, least-privilege database role.
 
+If you cannot provision such a role, set `allow_unsafe_database_role: true` (`MCP_ALLOW_UNSAFE_DATABASE_ROLE=true` for the environment) to skip only this role check. The server still wraps every statement in a read-only transaction, but the role-level guarantee is gone: a superuser role can read tables you did not intend to expose, read server files, and run server-side programs that a read-only transaction does not constrain, and a `BYPASSRLS` role sees through row-level security policies. Enable it only against a database you control.
+
+### Create a read-only service role
+
+Run the following in `psql` as a database administrator. Replace `app` and `public` with your database and schema. This creates a fresh login role with no inherited privileges; do not reuse an administrator or application-owner role.
+
+```sql
+CREATE ROLE mcp_reader
+  LOGIN
+  NOSUPERUSER NOCREATEDB NOCREATEROLE
+  NOINHERIT NOREPLICATION NOBYPASSRLS;
+\password mcp_reader
+
+GRANT CONNECT ON DATABASE app TO mcp_reader;
+\connect app
+GRANT USAGE ON SCHEMA public TO mcp_reader;
+GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_reader;
+```
+
+### Verify effective schema privileges
+
+Before configuring `DATABASE_URL`, verify that `mcp_reader` cannot create objects in the target schema:
+
+```sql
+SELECT has_schema_privilege('mcp_reader', 'public', 'CREATE') AS can_create_objects;
+```
+
+The result must be `false`. A result of `true` means the role is not restricted to read access in that schema. This can occur when an installation upgraded from PostgreSQL 14 or earlier retains a shared `PUBLIC` `CREATE` grant on `public`. Do not revoke a shared `PUBLIC` privilege solely for this server; have the database administrator decide the database-wide schema policy first.
+
+The `\password` command prompts without placing the password in shell history. Store the resulting connection secret only in the runtime secret or environment manager, not in the repository. If the role must read tables created in the future and `postgres` creates those tables, run this optional command as `postgres`. Replace `postgres` with the actual object-creator role in other environments:
+
+```sql
+ALTER DEFAULT PRIVILEGES FOR ROLE postgres IN SCHEMA public
+  GRANT SELECT ON TABLES TO mcp_reader;
+```
+
+Before configuring `DATABASE_URL`, connect as `mcp_reader` and verify that every boolean below is `false`:
+
+```sql
+SELECT current_user, rolsuper, rolbypassrls, rolreplication,
+  pg_has_role(current_user, 'pg_read_server_files', 'member') AS read_server_files,
+  pg_has_role(current_user, 'pg_write_server_files', 'member') AS write_server_files,
+  pg_has_role(current_user, 'pg_execute_server_program', 'member') AS execute_server_program,
+  pg_has_role(current_user, 'pg_signal_backend', 'member') AS signal_backend
+FROM pg_roles
+WHERE rolname = current_user;
+```
+
+If any value is `true`, use a new dedicated role rather than removing privileges from a shared administrator or application role.
+
 ## Read-only boundary and deployment risk
 
 Each database operation uses a PostgreSQL read-only transaction and pgx's extended execution protocol. `postgres_query` is parsed as exactly one SELECT, rejecting DML, DDL, row locks, SELECT INTO, modifying CTEs, and selected PostgreSQL built-ins with known side effects.

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@futuretea/postgres-mcp-server",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Read-only PostgreSQL Model Context Protocol server",
   "main": "./bin/index.js",
   "bin": {
     "postgres-mcp-server": "bin/index.js"
   },
   "optionalDependencies": {
-    "@futuretea/postgres-mcp-server-darwin-amd64": "0.0.1",
-    "@futuretea/postgres-mcp-server-darwin-arm64": "0.0.1",
-    "@futuretea/postgres-mcp-server-linux-amd64": "0.0.1",
-    "@futuretea/postgres-mcp-server-linux-arm64": "0.0.1",
-    "@futuretea/postgres-mcp-server-windows-amd64": "0.0.1"
+    "@futuretea/postgres-mcp-server-darwin-amd64": "0.1.0",
+    "@futuretea/postgres-mcp-server-darwin-arm64": "0.1.0",
+    "@futuretea/postgres-mcp-server-linux-amd64": "0.1.0",
+    "@futuretea/postgres-mcp-server-linux-arm64": "0.1.0",
+    "@futuretea/postgres-mcp-server-windows-amd64": "0.1.0"
   },
   "repository": {
     "type": "git",