sql-query-mcp 0.1.1__py3-none-any.whl

sql_query_mcp-0.1.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,21 @@
+sql_query_mcp/__init__.py,sha256=Eb_QoNJG5EBxNk4vA8H6ndIDD7qPpQ4iNi3yTsILaEo,79
+sql_query_mcp/__main__.py,sha256=9SRp-Yw7ShGxc6DhSIXcDLKgGEdAVm3oBZ59rBOPjT0,62
+sql_query_mcp/app.py,sha256=rivQ4No6KzpTQ8ewHDGye2pnbLv-sytPujQ5wzO-wo4,3180
+sql_query_mcp/audit.py,sha256=VwTas2hugs8TsWgse3K56BVhPPCleWGNE8vYh-naxBk,1238
+sql_query_mcp/config.py,sha256=EowPhas29uK0bzZu6Op65lnxCPPwdymr0d7XYHqPkYw,9002
+sql_query_mcp/errors.py,sha256=cfZRUWl4iljfFahJGv1QjqxisUg-LL2d0pbM0nX9jHQ,825
+sql_query_mcp/executor.py,sha256=yraGtfIfcbGjofvwnBZWy_djfnYuPe8hxyuS3eeE3jg,9211
+sql_query_mcp/introspection.py,sha256=PZdZN1JwKny8jXIW9FFilFkH2nnGfzJiI5XhN0sp0ds,8360
+sql_query_mcp/namespace.py,sha256=n1Lj6XgpQmMUpYeMywvINVa6UYHVcLa3hMRzsusdQSM,1639
+sql_query_mcp/registry.py,sha256=lup8rkuP_kkU-M_T0omBifYVFrHUUwu5-LLNsj_2G6Y,2327
+sql_query_mcp/release_metadata.py,sha256=b9q0SJr_zUfJunXTrZHx70FNKNY43yGQ2xz8bchuicI,2659
+sql_query_mcp/validator.py,sha256=Sq0c9MaVnEezdU1AbrTfFoXmqVo9ug1-U0_KxyzKFyE,3859
+sql_query_mcp/adapters/__init__.py,sha256=lEwMmaBnTDuLj3eXicd6rRCifkO4scYvCo8XQdlMm1g,361
+sql_query_mcp/adapters/mysql.py,sha256=YiWmK8WG9kzsiaJmsaZ7f4l0cBcPqq98S6GmoPjM2i4,6101
+sql_query_mcp/adapters/postgres.py,sha256=jBTkyPFu5oBmDQpNCXv1h8bwa2YKfSGA78ePv_8nl8U,6679
+sql_query_mcp-0.1.1.dist-info/licenses/LICENSE,sha256=5CusFN4dwxPOZK9Zxz37uwXDSWDwCC4A8gHmnLqpOZ4,1066
+sql_query_mcp-0.1.1.dist-info/METADATA,sha256=VxF4vVgY8_EY9NILzI38bTmD-PVWniQqyXG9bCXMeEM,8109
+sql_query_mcp-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sql_query_mcp-0.1.1.dist-info/entry_points.txt,sha256=mBOXnUfsGGV9bkZ-8xJq8UrKe_7V2kJRhAel0x2kxSs,57
+sql_query_mcp-0.1.1.dist-info/top_level.txt,sha256=kiFI-HI7u7-YjgvF2PbHY4QTkcHlW8XS0jXOpWjL-H8,14
+sql_query_mcp-0.1.1.dist-info/RECORD,,

sql_query_mcp-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sql_query_mcp-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sql-query-mcp = sql_query_mcp.app:main

sql_query_mcp-0.1.1.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+sql_query_mcp