- Got it working locally.

Author: general-kroll-4-life

.vscode/launch.json

@@ -445,6 +445,28 @@
         "${input:queryString}"
       ],
     },
+    {
+      "name": "run MCP standalone server",
+      "type": "go",
+      "request": "launch",
+      "envFile": "${workspaceFolder}/.vscode/.env",
+      "mode": "debug",
+      "program": "${workspaceFolder}/stackql",
+      "args": [
+        "mcp",
+        "--pgsrv.port=6555",
+        "--tls.allowInsecure",
+        "--auth=${input:authString}",
+        "--session=${input:sessionString}",
+        "--gc=${input:gcString}",
+        "--registry=${input:registryString}",
+        "--namespaces=${input:namespaceString}",
+        "--sqlBackend=${input:sqlBackendString}",
+        "--dbInternal=${input:dbInternalString}",
+        "--export.alias=${input:exportAliasString}",
+        "--pgsrv.debug.enable=${input:serverDebugPublish}",
+      ],
+    },
     {
       "name": "run server",
       "type": "go",

AGENTS.md

@@ -0,0 +1,85 @@
+# Repository Guidelines
+
+These guidelines help contributors work effectively on the PostgreSQL MCP server in this repo.
+
+## StackQL Resource Key Encoding Quirk
+
+### Hierarchical Keys and URL Encoding
+
+StackQL resource methods (especially for GitHub refs/tags) require exact matches for hierarchical keys, such as `refs/tags/x1.3`. However, due to dependency library behavior (e.g., gorilla/mux in Go), forward slashes in parameters may be interpreted as path delimiters, causing query failures or incorrect resource matching.
+
+**Workaround:** Always URL encode forward slashes in resource keys when constructing queries. For example:
+
+- **Incorrect:**
+  ```sql
+  SELECT ref FROM github.git.refs WHERE owner = 'stackql' AND repo = 'mcp-stackql' AND ref = 'refs/tags/x2.0';
+  ```
+- **Correct:**
+  ```sql
+  SELECT ref FROM github.git.refs WHERE owner = 'stackql' AND repo = 'mcp-stackql' AND ref = 'tags%2Fx2.0';
+  ```
+
+This ensures the backend treats the parameter as a literal string, not a path.
+
+### Guidance for LLMs and Contributors
+
+- Always encode slashes in hierarchical resource keys for StackQL queries.
+- Do not use wildcards or inequalities for `WHERE` clauses that map to parameters (eg: HTTP path parameters); in such cases, only exact matches are supported.
+- Document this quirk in scripts, tests, and code comments to avoid confusion.
+- Example for LLM prompt:
+  > "When querying StackQL resources with keys containing slashes, always URL encode the slash."
+
+### Why This Is Necessary
+
+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`/`query_json` remain for backward compatibility.
+- 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).

internal/stackql/cmd/mcp.go

@@ -0,0 +1,56 @@
+/*
+Copyright © 2019 stackql [email protected]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+	http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+package cmd
+
+import (
+	"context"
+
+	"github.com/spf13/cobra"
+
+	"github.com/stackql/any-sdk/pkg/logging"
+	"github.com/stackql/stackql/internal/stackql/entryutil"
+	"github.com/stackql/stackql/internal/stackql/iqlerror"
+	"github.com/stackql/stackql/pkg/mcp_server"
+)
+
+//nolint:gochecknoglobals // cobra pattern
+var mcpSrvCmd = &cobra.Command{
+	Use:   "mcp",
+	Short: "run mcp server",
+	Long: `
+	Run a MCP protocol server.
+	Supports MCP client connections from all manner or libs.
+  `,
+	//nolint:revive // acceptable for now
+	Run: func(cmd *cobra.Command, args []string) {
+		flagErr := dependentFlagHandler(&runtimeCtx)
+		iqlerror.PrintErrorAndExitOneIfError(flagErr)
+		inputBundle, err := entryutil.BuildInputBundle(runtimeCtx)
+		iqlerror.PrintErrorAndExitOneIfError(err)
+		handlerCtx, err := entryutil.BuildHandlerContext(runtimeCtx, nil, queryCache, inputBundle, false)
+		iqlerror.PrintErrorAndExitOneIfError(err)
+		iqlerror.PrintErrorAndExitOneIfNil(handlerCtx, "handler context is unexpectedly nil")
+		server, serverErr := mcp_server.NewExampleBackendServer(
+			nil,
+			logging.GetLogger(),
+		)
+		// server, serverErr := mcp_server.NewExampleHTTPBackendServer(
+		// 	logging.GetLogger(),
+		// )
+		iqlerror.PrintErrorAndExitOneIfError(serverErr)
+		server.Start(context.Background()) //nolint:errcheck // TODO: investigate
+	},
+}

internal/stackql/cmd/root.go

@@ -197,6 +197,7 @@ func init() {
 	rootCmd.AddCommand(shellCmd)
 	rootCmd.AddCommand(registryCmd)
 	rootCmd.AddCommand(srvCmd)
+	rootCmd.AddCommand(mcpSrvCmd)
 }
 
 func mergeConfigFromFile(runtimeCtx *dto.RuntimeCtx, flagSet pflag.FlagSet) {