- Doc improvements.

Author: general-kroll-4-life

AGENTS.md

@@ -1,6 +1,51 @@
 # Repository Guidelines
 
-These guidelines help contributors work effectively on the PostgreSQL MCP server in this repo.
+These guidelines help contributors work effectively on this repository.  We gratefully acknowledge [mcp-postgres](https://github.com/gldc/mcp-postgres) as the chief inspiration for the MCP server function and this document.
+
+We also encourage reading [`docs/developer_guide.md`](/docs/developer_guide.md) for further useful information.
+
+
+## Project Structure & Module Organization
+
+- Entrypoint: [`stackql/main.go`](/stackql/main.go).
+- Ideally, foregin system semantics are dealt with in the `any-sdk` repository.
+- Loose adherence to popular idioms:
+    - App internals in [`internal`](/internal).
+    - Re-usable modules in [`pkg`](/pkg).
+— The MCP server function is built upon the golang MCP SDK.
+- CICD: please see [the github actions workflows](/.github/workflows).
+- Docs: `README.md`, this `AGENTS.md`.
+
+## Build, Test, and Development Commands
+
+- Create env: `python -m venv .venv && source .venv/bin/activate`
+- Install deps: `pip install -r requirements.txt`
+- Run server (no DB): `python postgres_server.py`
+- Run with DB: `POSTGRES_CONNECTION_STRING="postgresql://user:pass@host:5432/db" python postgres_server.py`
+- Docker build/run: `docker build -t mcp-postgres .` then `docker run -e POSTGRES_CONNECTION_STRING=... -p 8000:8000 mcp-postgres`
+
+## Coding Style & Naming Conventions
+
+- Publish and program to abstractions.
+
+## Testing Guidelines
+
+- Black box regression tests are effectively mandatory.  The canaonical ones reside in [`test/robot/functional`](/test/robot/functional).
+
+## Tools & Resources
+
+- Please inspect using the API.
+
+
+## Commit & Pull Request Guidelines
+
+- Fork and pull model for general public; we **strongly** welcome public contributions, comment and issues.
+
+## Security & Configuration Tips
+
+- WIP.
+
+---
 
 ## StackQL Resource Key Encoding Quirk
 
@@ -34,53 +79,3 @@ This ensures the backend treats the parameter as a literal string, not a path.
 Many RESTful routing libraries (like gorilla/mux) treat slashes as path separators. Encoding slashes prevents misinterpretation and ensures correct resource access.
 
 Refer to this section whenever you encounter issues with resource keys containing slashes or hierarchical identifiers.
-
-
-## Project Structure & Module Organization
-- Root module: `postgres_server.py` — FastMCP server exposing PostgreSQL tools.
-- Config: `.env` (optional), `smithery.yaml` (publishing metadata).
-- Packaging/infra: `requirements.txt`, `Dockerfile`.
-- Docs: `README.md`, this `AGENTS.md`.
-- No dedicated `src/` or `tests/` directories yet; keep server logic cohesive and small, or start a `src/` layout if adding modules.
-
-## Build, Test, and Development Commands
-- Create env: `python -m venv .venv && source .venv/bin/activate`
-- Install deps: `pip install -r requirements.txt`
-- Run server (no DB): `python postgres_server.py`
-- Run with DB: `POSTGRES_CONNECTION_STRING="postgresql://user:pass@host:5432/db" python postgres_server.py`
-- Docker build/run: `docker build -t mcp-postgres .` then `docker run -e POSTGRES_CONNECTION_STRING=... -p 8000:8000 mcp-postgres`
-
-## Coding Style & Naming Conventions
-- Python 3.10+, 4-space indentation, PEP 8.
-- Use type hints (as in current code) and concise docstrings.
-- Functions/variables: `snake_case`; classes: `PascalCase`; MCP tool names: short `snake_case`.
-- Logging: use the existing `logger` instance; prefer informative, non-PII messages.
-- Optional formatting/linting: `black` and `ruff` (not enforced in repo). Example: `pip install black ruff && ruff check . && black .`.
-
-## Testing Guidelines
-- There is no test suite yet. Prefer adding `pytest` with tests under `tests/` named `test_*.py`.
-- For DB behaviors, use a disposable PostgreSQL instance or mock `psycopg2` connections.
-- Minimum smoke test: start server without DSN, verify each tool returns the friendly “connection string is not set” message.
-
-## Typed Tools & Resources
-- Preferred tools: `run_query(QueryInput)` and `run_query_json(QueryJSONInput)` with validated inputs (via Pydantic) and `row_limit` safeguards.
-- Legacy tools `query_v2`/`query_json` remain for backward compatibility.  These return a json object with a property for rows.
-    - Note the `query_v2` requires input of the form `{ "tool": "query", "input": {   "sql": "SELECT 1;",   "row_limit": 1 } }`
-- Table resources: `table://{schema}/{table}` (best-effort registration), with fallback tools `list_table_resources` and `read_table_resource`.
-- Prompts available as MCP prompts and tools: `write_safe_select`, `explain_plan_tips`.
-
-## Tests
-- Test deps: `dev-requirements.txt` (`pytest`, `pytest-cov`).
-- Layout: `tests/test_server_tools.py` includes no-DSN smoke tests and prompt checks.
-- Run: `pytest -q`. Ensure runtime deps installed from `requirements.txt`.
-
-## Commit & Pull Request Guidelines
-- Commit style: conventional commits preferred (`feat:`, `fix:`, `chore:`, `docs:`). Keep subjects imperative and concise.
-- PRs should include: purpose & scope, before/after behavior, example commands/queries, and any config changes (`POSTGRES_CONNECTION_STRING`, Docker, `mcp.json`).
-- When adding tools, document them in `README.md` (name, args, example) and ensure safe output formatting.
-- Never commit secrets. `.env`, `.venv`, and credentials are ignored by `.gitignore`.
-
-## Security & Configuration Tips
-- Pass DB credentials via `POSTGRES_CONNECTION_STRING` env var; avoid hardcoding.
-- Prefer least-privilege DB users and SSL options (e.g., add `?sslmode=require`).
-- The server runs without a DSN for inspection; database-backed tools should fail gracefully (maintain this behavior).

README.md

@@ -250,6 +250,9 @@ Forks of the following support our work:
 * [gorilla/mux](https://github.com/gorilla/mux)
 * [readline](https://github.com/chzyer/readline)
 * [psql-wire](https://github.com/jeroenrinzema/psql-wire)
+* [mcp-postgres](https://github.com/gldc/mcp-postgres)
+* [the `golang` MCP SDK](https://github.com/modelcontextprotocol/go-sdk)
+* ...and more.  Please excuse us for any omissions.
 
 We gratefully acknowledge these pieces of work.
 

docs/licenses/gldc_mcp_postgres_license

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 gldc
+
+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.