sql-query-mcp 0.1.1__tar.gz

sql_query_mcp-0.1.1/LICENSE

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

sql_query_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: sql-query-mcp
+Version: 0.1.1
+Summary: Read-only SQL MCP server for PostgreSQL and MySQL.
+Author: Andy Wang
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/andyWang1688/sql-query-mcp
+Project-URL: Repository, https://github.com/andyWang1688/sql-query-mcp
+Project-URL: Documentation, https://github.com/andyWang1688/sql-query-mcp/blob/main/README.md
+Project-URL: Issues, https://github.com/andyWang1688/sql-query-mcp/issues
+Keywords: mcp,mcp-server,sql,database,postgresql,mysql,cli,codex,chatgpt
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Environment :: Console
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.12.4
+Requires-Dist: PyMySQL>=1.1
+Requires-Dist: psycopg[binary]>=3.2
+Requires-Dist: psycopg-pool>=3.2
+Requires-Dist: sqlglot>=25.20.2
+Requires-Dist: tomli>=2; python_version < "3.11"
+Dynamic: license-file
+
+# sql-query-mcp
+
+[中文版](README-zh.md)
+
+A general-purpose MCP server that lets AI work with multiple databases within
+clear boundaries.
+
+## Current database support
+
+| Database | Status | Current availability |
+| --- | --- | --- |
+| PostgreSQL | Supported | Available today |
+| MySQL | Supported | Available today |
+| SQLite | Candidate | Not supported yet |
+| SQL Server | Candidate | Not supported yet |
+| ClickHouse | Candidate | Not supported yet |
+
+## Product value
+
+`sql-query-mcp` helps AI clients discover schema, sample data, and analyze
+read-only queries through one controlled MCP interface.
+
+It keeps connection handling, namespace rules, SQL validation, and audit
+logging on the server side, so you can expose useful database context to AI
+without exposing raw connection strings or flattening engine-specific concepts.
+
+## What AI can do with it
+
+The current tool set focuses on database discovery and controlled query
+workflows. You can use it to help an AI assistant understand structure before
+it generates or refines SQL.
+
+MySQL supports `explain_query`, but not `explain_query(..., analyze=True)` in
+the current implementation.
+
+| Tool | PostgreSQL | MySQL | Purpose |
+| --- | --- | --- | --- |
+| `list_connections()` | Yes | Yes | List configured connections |
+| `list_schemas(connection_id)` | Yes | No | List visible PostgreSQL schemas |
+| `list_databases(connection_id)` | No | Yes | List visible MySQL databases |
+| `list_tables(connection_id, schema?, database?)` | Yes | Yes | List tables and views |
+| `describe_table(connection_id, table_name, schema?, database?)` | Yes | Yes | Inspect columns, keys, and indexes |
+| `run_select(connection_id, sql, limit?)` | Yes | Yes | Run read-only queries |
+| `explain_query(connection_id, sql, analyze?)` | Yes | Yes | Inspect query plans |
+| `get_table_sample(connection_id, table_name, schema?, database?, limit?)` | Yes | Yes | Fetch small table samples |
+
+These tools are useful for tasks such as listing namespaces, inspecting table
+definitions, reviewing indexes, sampling records, and analyzing read-only
+queries with `EXPLAIN`. For full request and response details, see
+`docs/api-reference.md` (Chinese).
+
+## How boundaries are constrained
+
+The product boundary is intentionally narrow today. Only PostgreSQL and MySQL
+are available today, and the current tool set is fully read-only.
+
+The service keeps those boundaries explicit in a few ways.
+
+- Connections declare `engine` explicitly, so the server never guesses from
+  `connection_id`.
+- PostgreSQL uses `schema`, and MySQL uses `database`, without collapsing both
+  into one vague namespace field.
+- Real DSNs stay in environment variables, while config files store only the
+  environment variable names.
+- Query execution passes through `sqlglot` validation before reaching the
+  database.
+- The server accepts only `SELECT` and `WITH ... SELECT`, rejects comments and
+  multi-statement input, and records audit logs for each call.
+
+For MySQL, `explain_query(..., analyze=True)` is not available in the current
+implementation.
+
+## Quick start
+
+If you want to get the server running first and explore the rest later, follow
+these steps.
+
+1. Create a virtual environment and install the project.
+
+```bash
+python3.10 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install sql-query-mcp
+```
+
+Install a specific release with `pip install sql-query-mcp==X.Y.Z` if you want
+to pin a version. Published release artifacts are also attached to each GitHub
+Release.
+
+2. Copy the example connection config.
+
+```bash
+cp config/connections.example.json config/connections.json
+```
+
+3. Export your database DSNs as environment variables.
+
+These example names match the copied `config/connections.example.json` file.
+
+```bash
+export PG_CONN_CRM_PROD_MUQIAO_RO='postgresql://user:password@host:5432/dbname'
+export MYSQL_CONN_CRM_PROD_MUQIAO_RO='mysql://user:password@host:3306/crm'
+export SQL_QUERY_MCP_CONFIG='/absolute/path/to/sql-query-mcp/config/connections.json'
+```
+
+4. Register the server in your MCP client.
+
+- Codex: `docs/codex-setup.md` (Chinese)
+- OpenCode: `docs/opencode-setup.md` (Chinese)
+
+The console entry point is `sql-query-mcp`, which maps to
+`sql_query_mcp.app:main`.
+
+The PyPI install name is `sql-query-mcp`, and the Python package import path is
+`sql_query_mcp`.
+
+The default config path is `config/connections.json`. If you need a different
+location, set `SQL_QUERY_MCP_CONFIG`.
+
+The example config looks like this.
+
+```json
+{
+  "settings": {
+    "default_limit": 200,
+    "max_limit": 1000,
+    "audit_log_path": "logs/audit.jsonl"
+  },
+  "connections": [
+    {
+      "connection_id": "crm_prod_muqiao_ro",
+      "engine": "postgres",
+      "label": "CRM PostgreSQL production / Muqiao / read-only",
+      "env": "prod",
+      "tenant": "muqiao",
+      "role": "ro",
+      "dsn_env": "PG_CONN_CRM_PROD_MUQIAO_RO",
+      "enabled": true,
+      "default_schema": "public"
+    },
+    {
+      "connection_id": "crm_mysql_prod_muqiao_ro",
+      "engine": "mysql",
+      "label": "CRM MySQL production / Muqiao / read-only",
+      "env": "prod",
+      "tenant": "muqiao",
+      "role": "ro",
+      "dsn_env": "MYSQL_CONN_CRM_PROD_MUQIAO_RO",
+      "enabled": true,
+      "default_database": "crm"
+    }
+  ]
+}
+```
+
+## Documentation
+
+If you want implementation details, setup guidance, or internal structure, use
+these docs as your starting points.
+
+- `docs/project-overview.md`: project goals, concepts, and code structure (Chinese)
+- `docs/api-reference.md`: MCP tool reference (Chinese)
+- `docs/codex-setup.md`: Codex setup steps (Chinese)
+- `docs/opencode-setup.md`: OpenCode setup steps (Chinese)
+- `docs/release-process.md`: PyPI and GitHub Release workflow (Chinese)
+- `docs/git-workflow.md`: repository collaboration workflow (Chinese)
+
+## Development
+
+If you want to modify or verify the project locally, use this shortest path.
+Editable install remains the development path, and the local environment still
+requires Python 3.10+.
+
+```bash
+python3.10 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -e .
+PYTHONPATH=. python3 -m unittest discover -s tests
+```
+
+The main entry point is `sql_query_mcp/app.py`. Core modules include:
+
+- `sql_query_mcp/config.py`: config loading and validation
+- `sql_query_mcp/validator.py`: read-only SQL validation
+- `sql_query_mcp/introspection.py`: metadata inspection
+- `sql_query_mcp/executor.py`: query execution and limits
+- `sql_query_mcp/adapters/`: PostgreSQL and MySQL adapters
+
+## Contributing
+
+If you want to contribute or review the repository workflow, start with these
+pages.
+
+- `CONTRIBUTING.md`
+- `docs/roadmap.md`
+- `docs/git-workflow.md` (Chinese)
+
+Run `PYTHONPATH=. python3 -m unittest discover -s tests` before you submit
+changes.
+
+## License
+
+This project is released under the MIT License. See `LICENSE`.

sql_query_mcp-0.1.1/README.md

@@ -0,0 +1,205 @@
+# sql-query-mcp
+
+[中文版](README-zh.md)
+
+A general-purpose MCP server that lets AI work with multiple databases within
+clear boundaries.
+
+## Current database support
+
+| Database | Status | Current availability |
+| --- | --- | --- |
+| PostgreSQL | Supported | Available today |
+| MySQL | Supported | Available today |
+| SQLite | Candidate | Not supported yet |
+| SQL Server | Candidate | Not supported yet |
+| ClickHouse | Candidate | Not supported yet |
+
+## Product value
+
+`sql-query-mcp` helps AI clients discover schema, sample data, and analyze
+read-only queries through one controlled MCP interface.
+
+It keeps connection handling, namespace rules, SQL validation, and audit
+logging on the server side, so you can expose useful database context to AI
+without exposing raw connection strings or flattening engine-specific concepts.
+
+## What AI can do with it
+
+The current tool set focuses on database discovery and controlled query
+workflows. You can use it to help an AI assistant understand structure before
+it generates or refines SQL.
+
+MySQL supports `explain_query`, but not `explain_query(..., analyze=True)` in
+the current implementation.
+
+| Tool | PostgreSQL | MySQL | Purpose |
+| --- | --- | --- | --- |
+| `list_connections()` | Yes | Yes | List configured connections |
+| `list_schemas(connection_id)` | Yes | No | List visible PostgreSQL schemas |
+| `list_databases(connection_id)` | No | Yes | List visible MySQL databases |
+| `list_tables(connection_id, schema?, database?)` | Yes | Yes | List tables and views |
+| `describe_table(connection_id, table_name, schema?, database?)` | Yes | Yes | Inspect columns, keys, and indexes |
+| `run_select(connection_id, sql, limit?)` | Yes | Yes | Run read-only queries |
+| `explain_query(connection_id, sql, analyze?)` | Yes | Yes | Inspect query plans |
+| `get_table_sample(connection_id, table_name, schema?, database?, limit?)` | Yes | Yes | Fetch small table samples |
+
+These tools are useful for tasks such as listing namespaces, inspecting table
+definitions, reviewing indexes, sampling records, and analyzing read-only
+queries with `EXPLAIN`. For full request and response details, see
+`docs/api-reference.md` (Chinese).
+
+## How boundaries are constrained
+
+The product boundary is intentionally narrow today. Only PostgreSQL and MySQL
+are available today, and the current tool set is fully read-only.
+
+The service keeps those boundaries explicit in a few ways.
+
+- Connections declare `engine` explicitly, so the server never guesses from
+  `connection_id`.
+- PostgreSQL uses `schema`, and MySQL uses `database`, without collapsing both
+  into one vague namespace field.
+- Real DSNs stay in environment variables, while config files store only the
+  environment variable names.
+- Query execution passes through `sqlglot` validation before reaching the
+  database.
+- The server accepts only `SELECT` and `WITH ... SELECT`, rejects comments and
+  multi-statement input, and records audit logs for each call.
+
+For MySQL, `explain_query(..., analyze=True)` is not available in the current
+implementation.
+
+## Quick start
+
+If you want to get the server running first and explore the rest later, follow
+these steps.
+
+1. Create a virtual environment and install the project.
+
+```bash
+python3.10 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install sql-query-mcp
+```
+
+Install a specific release with `pip install sql-query-mcp==X.Y.Z` if you want
+to pin a version. Published release artifacts are also attached to each GitHub
+Release.
+
+2. Copy the example connection config.
+
+```bash
+cp config/connections.example.json config/connections.json
+```
+
+3. Export your database DSNs as environment variables.
+
+These example names match the copied `config/connections.example.json` file.
+
+```bash
+export PG_CONN_CRM_PROD_MUQIAO_RO='postgresql://user:password@host:5432/dbname'
+export MYSQL_CONN_CRM_PROD_MUQIAO_RO='mysql://user:password@host:3306/crm'
+export SQL_QUERY_MCP_CONFIG='/absolute/path/to/sql-query-mcp/config/connections.json'
+```
+
+4. Register the server in your MCP client.
+
+- Codex: `docs/codex-setup.md` (Chinese)
+- OpenCode: `docs/opencode-setup.md` (Chinese)
+
+The console entry point is `sql-query-mcp`, which maps to
+`sql_query_mcp.app:main`.
+
+The PyPI install name is `sql-query-mcp`, and the Python package import path is
+`sql_query_mcp`.
+
+The default config path is `config/connections.json`. If you need a different
+location, set `SQL_QUERY_MCP_CONFIG`.
+
+The example config looks like this.
+
+```json
+{
+  "settings": {
+    "default_limit": 200,
+    "max_limit": 1000,
+    "audit_log_path": "logs/audit.jsonl"
+  },
+  "connections": [
+    {
+      "connection_id": "crm_prod_muqiao_ro",
+      "engine": "postgres",
+      "label": "CRM PostgreSQL production / Muqiao / read-only",
+      "env": "prod",
+      "tenant": "muqiao",
+      "role": "ro",
+      "dsn_env": "PG_CONN_CRM_PROD_MUQIAO_RO",
+      "enabled": true,
+      "default_schema": "public"
+    },
+    {
+      "connection_id": "crm_mysql_prod_muqiao_ro",
+      "engine": "mysql",
+      "label": "CRM MySQL production / Muqiao / read-only",
+      "env": "prod",
+      "tenant": "muqiao",
+      "role": "ro",
+      "dsn_env": "MYSQL_CONN_CRM_PROD_MUQIAO_RO",
+      "enabled": true,
+      "default_database": "crm"
+    }
+  ]
+}
+```
+
+## Documentation
+
+If you want implementation details, setup guidance, or internal structure, use
+these docs as your starting points.
+
+- `docs/project-overview.md`: project goals, concepts, and code structure (Chinese)
+- `docs/api-reference.md`: MCP tool reference (Chinese)
+- `docs/codex-setup.md`: Codex setup steps (Chinese)
+- `docs/opencode-setup.md`: OpenCode setup steps (Chinese)
+- `docs/release-process.md`: PyPI and GitHub Release workflow (Chinese)
+- `docs/git-workflow.md`: repository collaboration workflow (Chinese)
+
+## Development
+
+If you want to modify or verify the project locally, use this shortest path.
+Editable install remains the development path, and the local environment still
+requires Python 3.10+.
+
+```bash
+python3.10 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -e .
+PYTHONPATH=. python3 -m unittest discover -s tests
+```
+
+The main entry point is `sql_query_mcp/app.py`. Core modules include:
+
+- `sql_query_mcp/config.py`: config loading and validation
+- `sql_query_mcp/validator.py`: read-only SQL validation
+- `sql_query_mcp/introspection.py`: metadata inspection
+- `sql_query_mcp/executor.py`: query execution and limits
+- `sql_query_mcp/adapters/`: PostgreSQL and MySQL adapters
+
+## Contributing
+
+If you want to contribute or review the repository workflow, start with these
+pages.
+
+- `CONTRIBUTING.md`
+- `docs/roadmap.md`
+- `docs/git-workflow.md` (Chinese)
+
+Run `PYTHONPATH=. python3 -m unittest discover -s tests` before you submit
+changes.
+
+## License
+
+This project is released under the MIT License. See `LICENSE`.

sql_query_mcp-0.1.1/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sql-query-mcp"
+version = "0.1.1"
+description = "Read-only SQL MCP server for PostgreSQL and MySQL."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Andy Wang" }]
+keywords = ["mcp", "mcp-server", "sql", "database", "postgresql", "mysql", "cli", "codex", "chatgpt"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Database",
+  "Environment :: Console",
+]
+dependencies = [
+  "mcp>=1.12.4",
+  "PyMySQL>=1.1",
+  "psycopg[binary]>=3.2",
+  "psycopg-pool>=3.2",
+  "sqlglot>=25.20.2",
+  "tomli>=2; python_version < '3.11'",
+]
+
+[project.urls]
+Homepage = "https://github.com/andyWang1688/sql-query-mcp"
+Repository = "https://github.com/andyWang1688/sql-query-mcp"
+Documentation = "https://github.com/andyWang1688/sql-query-mcp/blob/main/README.md"
+Issues = "https://github.com/andyWang1688/sql-query-mcp/issues"
+
+[project.scripts]
+sql-query-mcp = "sql_query_mcp.app:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["sql_query_mcp*"]

sql_query_mcp-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sql_query_mcp-0.1.1/sql_query_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""sql-query-mcp package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

sql_query_mcp-0.1.1/sql_query_mcp/__main__.py

@@ -0,0 +1,5 @@
+from .app import main
+
+
+if __name__ == "__main__":
+    main()

sql_query_mcp-0.1.1/sql_query_mcp/adapters/__init__.py

@@ -0,0 +1,15 @@
+"""Engine adapters for sql-query-mcp."""
+
+__all__ = ["MySQLAdapter", "PostgresAdapter"]
+
+
+def __getattr__(name: str):
+    if name == "MySQLAdapter":
+        from .mysql import MySQLAdapter
+
+        return MySQLAdapter
+    if name == "PostgresAdapter":
+        from .postgres import PostgresAdapter
+
+        return PostgresAdapter
+    raise AttributeError(name)