@futuretea/postgres-mcp-server 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 futuretea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# PostgreSQL Read-only MCP Server
+
+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
+
+Set a connection target for a minimally privileged PostgreSQL role, then build and inspect the catalog:
+
+```sh
+export DATABASE_URL='postgres://reader@127.0.0.1:5432/app?sslmode=disable'
+make build
+./bin/postgres-mcp-server tools list
+./bin/postgres-mcp-server mcp
+```
+
+`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.
+
+## Tools
+
+| Tool | Parameters | Purpose |
+|---|---|---|
+| `postgres_get_server_info` | none | Return server and current connection identity. |
+| `postgres_list_databases` | none | List visible databases. |
+| `postgres_list_schemas` | none | List visible schemas. |
+| `postgres_list_tables` | `schema` | List tables and views in a schema. |
+| `postgres_describe_table` | `schema`, `table` | Describe table columns. |
+| `postgres_list_indexes` | `schema`, `table` | List indexes for a table. |
+| `postgres_query` | `sql` | Run one strict read-only SELECT query. |
+
+Every successful tool response is one JSON text envelope with `schema_version`, `tool`, and `data`. Parameters must be a JSON object with no unknown keys. Empty-parameter tools require `{}`; missing, `null`, array, or scalar arguments are rejected.
+
+## Database connection
+
+Use a bare `DATABASE_URL`, or standard PostgreSQL environment variables such as `PGHOST`, `PGPORT`, `PGDATABASE`, `PGUSER`, `PGPASSWORD`, and `PGSSLMODE`. When `DATABASE_URL` is set it takes precedence. Configuration must resolve to one `host:port`; distinct URL or comma-separated `PGHOST` targets are rejected before a connection is created.
+
+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.
+
+## 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.
+
+This is not a complete proof that every user-defined function, extension, FDW, or future PostgreSQL built-in is harmless. Grant only the database access you intend the server to have.
+
+HTTP transports have no authentication or TLS layer. The default listener is loopback. If you set `--listen` to a remote address, place the service only on a trusted network or behind infrastructure that provides the required protection. This server intentionally has no query timeout, row limit, response-size limit, or concurrency budget.
+
+## Running MCP and HTTP
+
+```sh
+# stdio MCP
+./bin/postgres-mcp-server mcp
+
+# HTTP MCP on loopback
+./bin/postgres-mcp-server mcp --port 8080
+
+# Explicit remote listener; see the trusted-network requirement above
+./bin/postgres-mcp-server mcp --port 8080 --listen 0.0.0.0
+```
+
+The HTTP health endpoint is `GET /healthz`. See `config.example.yaml` for transport and tool-filter settings; database connection settings remain in the environment.
+
+## CLI
+
+```sh
+./bin/postgres-mcp-server tools list --json
+./bin/postgres-mcp-server tools describe postgres_query --json
+./bin/postgres-mcp-server tools call postgres_list_schemas --params '{}'
+./bin/postgres-mcp-server tools call postgres_query --params '{"sql":"SELECT 1"}'
+./bin/postgres-mcp-server version
+```
+
+## Container
+
+`make docker` first builds the Alpine CGO parser-check target and then builds the runnable image:
+
+```sh
+make docker
+docker run --rm -i --env DATABASE_URL postgres-mcp-server:dev
+```
+
+The image entrypoint is `postgres-mcp-server mcp`.
+
+## Development checks
+
+```sh
+make format
+make lint
+make test
+make test-integration  # requires a running Docker daemon; creates a PostgreSQL 17 fixture
+make build
+make docker
+```

package/bin/index.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+const childProcess = require('child_process');
+
+const BINARY_MAP = {
+  darwin_x64: {name: 'postgres-mcp-server-darwin-amd64', suffix: ''},
+  darwin_arm64: {name: 'postgres-mcp-server-darwin-arm64', suffix: ''},
+  linux_x64: {name: 'postgres-mcp-server-linux-amd64', suffix: ''},
+  linux_arm64: {name: 'postgres-mcp-server-linux-arm64', suffix: ''},
+  win32_x64: {name: 'postgres-mcp-server-windows-amd64', suffix: '.exe'},
+};
+
+const resolveBinaryPath = () => {
+  const binary = BINARY_MAP[`${process.platform}_${process.arch}`];
+  if (!binary) {
+    throw new Error(`Unsupported platform/architecture: ${process.platform}/${process.arch}`);
+  }
+
+  try {
+    return require.resolve(`@futuretea/${binary.name}/bin/postgres-mcp-server${binary.suffix}`);
+  } catch {
+    throw new Error(`Could not resolve binary path for platform/architecture: ${process.platform}/${process.arch}`);
+  }
+};
+
+const child = childProcess.spawn(resolveBinaryPath(), ['mcp', ...process.argv.slice(2)], {
+  stdio: 'inherit',
+});
+
+const handleSignal = (signal) => {
+  if (!child.killed) {
+    child.kill(signal);
+  }
+};
+
+['SIGTERM', 'SIGINT', 'SIGHUP'].forEach((signal) => {
+  process.on(signal, () => handleSignal(signal));
+});
+
+child.on('close', (code, signal) => {
+  if (signal) {
+    process.exit(128 + (signal === 'SIGTERM' ? 15 : signal === 'SIGINT' ? 2 : 1));
+  }
+
+  process.exit(code || 0);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@futuretea/postgres-mcp-server",
+  "version": "0.0.1",
+  "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"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/futuretea/postgres-mcp-server.git"
+  },
+  "keywords": [
+    "mcp",
+    "postgresql",
+    "postgres",
+    "database",
+    "model-context-protocol"
+  ],
+  "author": {
+    "name": "futuretea",
+    "url": "https://github.com/futuretea"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/futuretea/postgres-mcp-server/issues"
+  },
+  "homepage": "https://github.com/futuretea/postgres-mcp-server#readme"
+}