sql-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sql_mcp-0.1.0/LICENSE +21 -0
- sql_mcp-0.1.0/MANIFEST.in +4 -0
- sql_mcp-0.1.0/PKG-INFO +242 -0
- sql_mcp-0.1.0/README.md +204 -0
- sql_mcp-0.1.0/pyproject.toml +61 -0
- sql_mcp-0.1.0/requirements.txt +3 -0
- sql_mcp-0.1.0/setup.cfg +4 -0
- sql_mcp-0.1.0/sql_mcp/__init__.py +64 -0
- sql_mcp-0.1.0/sql_mcp/__main__.py +4 -0
- sql_mcp-0.1.0/sql_mcp/agent_server.py +71 -0
- sql_mcp-0.1.0/sql_mcp/api/__init__.py +9 -0
- sql_mcp-0.1.0/sql_mcp/api/api_client_sql.py +469 -0
- sql_mcp-0.1.0/sql_mcp/api_client.py +11 -0
- sql_mcp-0.1.0/sql_mcp/auth.py +142 -0
- sql_mcp-0.1.0/sql_mcp/dialects.py +183 -0
- sql_mcp-0.1.0/sql_mcp/main_agent.json +14 -0
- sql_mcp-0.1.0/sql_mcp/mcp/__init__.py +5 -0
- sql_mcp-0.1.0/sql_mcp/mcp/mcp_sql.py +224 -0
- sql_mcp-0.1.0/sql_mcp/mcp_config.json +33 -0
- sql_mcp-0.1.0/sql_mcp/mcp_server.py +59 -0
- sql_mcp-0.1.0/sql_mcp/safety.py +173 -0
- sql_mcp-0.1.0/sql_mcp/sql_input_models.py +63 -0
- sql_mcp-0.1.0/sql_mcp/sql_response_models.py +51 -0
- sql_mcp-0.1.0/sql_mcp.egg-info/PKG-INFO +242 -0
- sql_mcp-0.1.0/sql_mcp.egg-info/SOURCES.txt +36 -0
- sql_mcp-0.1.0/sql_mcp.egg-info/dependency_links.txt +1 -0
- sql_mcp-0.1.0/sql_mcp.egg-info/entry_points.txt +3 -0
- sql_mcp-0.1.0/sql_mcp.egg-info/requires.txt +30 -0
- sql_mcp-0.1.0/sql_mcp.egg-info/top_level.txt +1 -0
- sql_mcp-0.1.0/tests/test_api_wrapper.py +272 -0
- sql_mcp-0.1.0/tests/test_auth.py +160 -0
- sql_mcp-0.1.0/tests/test_concept_parity.py +28 -0
- sql_mcp-0.1.0/tests/test_dialect_paths.py +105 -0
- sql_mcp-0.1.0/tests/test_dialects.py +143 -0
- sql_mcp-0.1.0/tests/test_init_dynamics.py +6 -0
- sql_mcp-0.1.0/tests/test_safety.py +98 -0
- sql_mcp-0.1.0/tests/test_sql_mcp_validation.py +187 -0
- sql_mcp-0.1.0/tests/test_startup.py +30 -0
sql_mcp-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Knuckles-Team
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
sql_mcp-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: sql-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Generic SQL database (Postgres, MySQL/MariaDB, MSSQL, Oracle, SQLite) API + MCP Server + A2A Server for Agentic AI!
|
|
5
|
+
Author-email: Audel Rouhi <knucklessg1@gmail.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Classifier: Development Status :: 4 - Beta
|
|
8
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
9
|
+
Classifier: Environment :: Console
|
|
10
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Requires-Python: <3.15,>=3.11
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
License-File: LICENSE
|
|
15
|
+
Requires-Dist: agent-utilities>=0.47.0
|
|
16
|
+
Requires-Dist: python-dotenv>=1.0.0
|
|
17
|
+
Requires-Dist: sqlalchemy>=2.0.0
|
|
18
|
+
Provides-Extra: mcp
|
|
19
|
+
Requires-Dist: agent-utilities[mcp]>=0.47.0; extra == "mcp"
|
|
20
|
+
Provides-Extra: agent
|
|
21
|
+
Requires-Dist: agent-utilities[agent,logfire]>=0.47.0; extra == "agent"
|
|
22
|
+
Provides-Extra: postgres
|
|
23
|
+
Requires-Dist: psycopg[binary]>=3.1.0; extra == "postgres"
|
|
24
|
+
Provides-Extra: mysql
|
|
25
|
+
Requires-Dist: pymysql>=1.1.0; extra == "mysql"
|
|
26
|
+
Provides-Extra: mssql
|
|
27
|
+
Requires-Dist: pyodbc>=5.0.0; extra == "mssql"
|
|
28
|
+
Provides-Extra: oracle
|
|
29
|
+
Requires-Dist: oracledb>=2.0.0; extra == "oracle"
|
|
30
|
+
Provides-Extra: all
|
|
31
|
+
Requires-Dist: sql-mcp[agent,logfire,mcp,mssql,mysql,oracle,postgres]>=0.1.0; extra == "all"
|
|
32
|
+
Provides-Extra: test
|
|
33
|
+
Requires-Dist: pytest-xdist>=3.6.0; extra == "test"
|
|
34
|
+
Requires-Dist: pytest; extra == "test"
|
|
35
|
+
Requires-Dist: pytest-asyncio; extra == "test"
|
|
36
|
+
Requires-Dist: pytest-cov; extra == "test"
|
|
37
|
+
Dynamic: license-file
|
|
38
|
+
|
|
39
|
+
# Sql Mcp
|
|
40
|
+
## API | MCP Server | A2A Agent
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
Generic SQL database **API + MCP Server + A2A Agent** for the agent-utilities
|
|
61
|
+
ecosystem — one connector for **PostgreSQL, MySQL/MariaDB, Microsoft SQL Server,
|
|
62
|
+
Oracle, and SQLite** over SQLAlchemy 2.x Core.
|
|
63
|
+
|
|
64
|
+
*Version: 0.1.0*
|
|
65
|
+
|
|
66
|
+
> **Documentation** — Installation, deployment, and usage across the API, CLI, and
|
|
67
|
+
> MCP interfaces are maintained in [`docs/`](docs/index.md).
|
|
68
|
+
|
|
69
|
+
## Table of Contents
|
|
70
|
+
|
|
71
|
+
- [Overview](#overview)
|
|
72
|
+
- [What it provides](#what-it-provides)
|
|
73
|
+
- [MCP tools](#mcp-tools)
|
|
74
|
+
- [Dialects & extras](#dialects--extras)
|
|
75
|
+
- [Configuration (environment)](#configuration-environment)
|
|
76
|
+
- [Installation](#installation)
|
|
77
|
+
- [Usage](#usage)
|
|
78
|
+
- [MCP config](#mcp-config)
|
|
79
|
+
- [Docker deployment](#docker-deployment)
|
|
80
|
+
- [Safety model](#safety-model)
|
|
81
|
+
- [Tests](#tests)
|
|
82
|
+
|
|
83
|
+
## Overview
|
|
84
|
+
|
|
85
|
+
`sql-mcp` exposes read-only queries, gated DML/DDL, schema reflection, and
|
|
86
|
+
connection administration as typed, deterministic MCP tools, and ships an optional
|
|
87
|
+
Pydantic-AI agent server. It is **read-only by default**: every query passes a
|
|
88
|
+
statement-type allowlist, every result is bounded by a row cap and a timeout, and
|
|
89
|
+
all values travel as bound parameters — never interpolated into SQL strings.
|
|
90
|
+
|
|
91
|
+
## What it provides
|
|
92
|
+
|
|
93
|
+
- **`SqlApi`** (`sql_mcp.api.api_client_sql`) — a SQLAlchemy 2.x Core facade with
|
|
94
|
+
named multi-connection support, lazy engine creation, the read-only statement
|
|
95
|
+
gate, row-cap/timeout enforcement, and bounded result envelopes
|
|
96
|
+
(`{columns, rows, row_count, truncated}`).
|
|
97
|
+
- **Four MCP tools** (`sql-mcp` console script): `sql_query` (execute/explain),
|
|
98
|
+
`sql_execute` (execute/script — gated by `SQL_ALLOW_WRITES`), `sql_schema`
|
|
99
|
+
(schemas/tables/views/columns/indexes/foreign_keys/ddl/sample), and `sql_admin`
|
|
100
|
+
(ping/version/active_connections/connections/dialects). See
|
|
101
|
+
[`docs/usage.md`](docs/usage.md) for the full action surface.
|
|
102
|
+
- **A dialect registry** (`sql_mcp.dialects`) — per-engine driver, URL scheme, pip
|
|
103
|
+
extra, EXPLAIN prefix, and admin SQL. Core ships SQLite only; the other drivers
|
|
104
|
+
install via extras.
|
|
105
|
+
- **An A2A agent server** (`sql-agent` console script) — a Pydantic-AI graph agent
|
|
106
|
+
wired to the MCP server via `MCP_URL`.
|
|
107
|
+
|
|
108
|
+
## MCP tools
|
|
109
|
+
|
|
110
|
+
| Tool | Actions | Description |
|
|
111
|
+
|---|---|---|
|
|
112
|
+
| `sql_query` | `execute`, `explain` | Run a read-only SELECT/CTE with bound parameters, or return the dialect's query plan |
|
|
113
|
+
| `sql_execute` | `execute`, `script` | One DML/DDL statement (or an all-or-nothing statement list) in a transaction — requires `SQL_ALLOW_WRITES=True` |
|
|
114
|
+
| `sql_schema` | `schemas`, `tables`, `views`, `columns`, `indexes`, `foreign_keys`, `ddl`, `sample` | Reflect schemas, tables, columns, indexes, FKs, CREATE DDL, and preview rows |
|
|
115
|
+
| `sql_admin` | `ping`, `version`, `active_connections`, `connections`, `dialects` | Connection health, server version, server sessions, registry info, driver availability |
|
|
116
|
+
|
|
117
|
+
Every tool takes `action`, `params_json`, and an optional `connection` naming one
|
|
118
|
+
of the configured connections. The whole set is toggled with `SQLTOOL`.
|
|
119
|
+
|
|
120
|
+
## Dialects & extras
|
|
121
|
+
|
|
122
|
+
| Dialect | SQLAlchemy scheme | Driver | Install |
|
|
123
|
+
|---|---|---|---|
|
|
124
|
+
| SQLite | `sqlite+pysqlite` | stdlib | `pip install sql-mcp` (core) |
|
|
125
|
+
| PostgreSQL | `postgresql+psycopg` | psycopg 3 | `pip install sql-mcp[postgres]` |
|
|
126
|
+
| MySQL / MariaDB | `mysql+pymysql` | PyMySQL | `pip install sql-mcp[mysql]` |
|
|
127
|
+
| SQL Server | `mssql+pyodbc` | pyodbc | `pip install sql-mcp[mssql]` |
|
|
128
|
+
| Oracle | `oracle+oracledb` | python-oracledb | `pip install sql-mcp[oracle]` |
|
|
129
|
+
|
|
130
|
+
`pip install sql-mcp[all]` pulls every driver plus the MCP and agent extras.
|
|
131
|
+
|
|
132
|
+
## Configuration (environment)
|
|
133
|
+
|
|
134
|
+
| Var | Default | Meaning |
|
|
135
|
+
|---|---|---|
|
|
136
|
+
| `SQL_CONNECTIONS` | _(empty)_ | JSON map of named connections: DSN strings or `{dialect, host, port, username, password, database, options}` objects |
|
|
137
|
+
| `SQL_URL` | _(empty)_ | Single DSN registered as connection `default` |
|
|
138
|
+
| `SQL_DIALECT` / `SQL_HOST` / `SQL_PORT` / `SQL_USERNAME` / `SQL_PASSWORD` / `SQL_DATABASE` / `SQL_OPTIONS` | _(empty)_ | Discrete fields for a single `default` connection |
|
|
139
|
+
| `SQL_ALLOW_WRITES` | `False` | Enable `sql_execute` (DML/DDL). **Read-only by default** |
|
|
140
|
+
| `SQL_MAX_ROWS` | `500` | Per-call row cap; tool requests are clamped to it |
|
|
141
|
+
| `SQL_TIMEOUT_SECONDS` | `30` | Per-statement timeout |
|
|
142
|
+
| `SQLTOOL` | `True` | Register the SQL tool set |
|
|
143
|
+
|
|
144
|
+
With nothing configured the server registers a zero-infra in-memory SQLite
|
|
145
|
+
connection named `memory`, so it works out of the box. Tools take an optional
|
|
146
|
+
`connection` parameter naming one of the configured connections; it defaults to
|
|
147
|
+
the sole/first one. Passwords are parsed into `sqlalchemy.URL` objects and only
|
|
148
|
+
ever rendered redacted. Copy [`.env.example`](.env.example) to `.env` and
|
|
149
|
+
populate only what you use.
|
|
150
|
+
|
|
151
|
+
## Installation
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
pip install sql-mcp # core (SQLite, MCP server, API)
|
|
155
|
+
pip install sql-mcp[all] # every driver + MCP + agent extras
|
|
156
|
+
pip install -e . # from source
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Or pull the container image:
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
docker pull knucklessg1/sql-mcp:latest
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
## Usage
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
sql-mcp # stdio MCP server (default transport)
|
|
169
|
+
sql-mcp --transport streamable-http --host 0.0.0.0 --port 8000
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Point it at a database:
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
export SQL_URL="postgresql+psycopg://svc:****@db.example.com:5432/app"
|
|
176
|
+
sql-mcp
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Or several:
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
export SQL_CONNECTIONS='{
|
|
183
|
+
"warehouse": "postgresql+psycopg://svc:****@dw.example.com:5432/dw",
|
|
184
|
+
"erp": {"dialect": "mysql", "host": "erp.example.com", "username": "svc",
|
|
185
|
+
"password": "****", "database": "erp"}
|
|
186
|
+
}'
|
|
187
|
+
sql-mcp
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Run the agent server against a live MCP server:
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
sql-agent --mcp-url http://localhost:8000/mcp --host 0.0.0.0 --port 8080
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
## MCP config
|
|
197
|
+
|
|
198
|
+
```json
|
|
199
|
+
{
|
|
200
|
+
"mcpServers": {
|
|
201
|
+
"sql-mcp": {
|
|
202
|
+
"command": "uv",
|
|
203
|
+
"args": ["run", "sql-mcp"],
|
|
204
|
+
"env": {
|
|
205
|
+
"SQL_URL": "postgresql+psycopg://svc:****@db.example.com:5432/app",
|
|
206
|
+
"SQL_ALLOW_WRITES": "False"
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
## Docker deployment
|
|
214
|
+
|
|
215
|
+
```bash
|
|
216
|
+
docker compose -f docker/mcp.compose.yml up -d # MCP server only
|
|
217
|
+
docker compose -f docker/agent.compose.yml up -d # MCP + A2A agent
|
|
218
|
+
curl -s http://localhost:8000/health # {"status":"OK"}
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
Both services read configuration from `../.env` (copy
|
|
222
|
+
[`.env.example`](.env.example)); see [`docs/deployment.md`](docs/deployment.md).
|
|
223
|
+
|
|
224
|
+
## Safety model
|
|
225
|
+
|
|
226
|
+
- **Read-only by default** — `sql_execute` refuses to run unless the *server* was
|
|
227
|
+
started with `SQL_ALLOW_WRITES=True`; agents cannot flip the flag per call.
|
|
228
|
+
- **Statement allowlist** — `sql_query` accepts only `SELECT`/`WITH`/`EXPLAIN`/
|
|
229
|
+
`SHOW`/`DESCRIBE`/`PRAGMA`/`VALUES`; CTEs are inspected at paren depth zero so
|
|
230
|
+
`WITH ... INSERT` cannot smuggle a write, `SELECT INTO` is rejected, and
|
|
231
|
+
multi-statement payloads are refused.
|
|
232
|
+
- **Bounded results** — per-call row caps clamp to `SQL_MAX_ROWS`; statements run
|
|
233
|
+
under `SQL_TIMEOUT_SECONDS` on a worker thread.
|
|
234
|
+
- **Parameterized only** — values bind via `:name` parameters; identifiers are
|
|
235
|
+
quoted by SQLAlchemy reflection, never hand-interpolated.
|
|
236
|
+
|
|
237
|
+
## Tests
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
python -m pytest # full suite against in-memory SQLite (no live DBs)
|
|
241
|
+
pre-commit run --all-files
|
|
242
|
+
```
|
sql_mcp-0.1.0/README.md
ADDED
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
# Sql Mcp
|
|
2
|
+
## API | MCP Server | A2A Agent
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
Generic SQL database **API + MCP Server + A2A Agent** for the agent-utilities
|
|
23
|
+
ecosystem — one connector for **PostgreSQL, MySQL/MariaDB, Microsoft SQL Server,
|
|
24
|
+
Oracle, and SQLite** over SQLAlchemy 2.x Core.
|
|
25
|
+
|
|
26
|
+
*Version: 0.1.0*
|
|
27
|
+
|
|
28
|
+
> **Documentation** — Installation, deployment, and usage across the API, CLI, and
|
|
29
|
+
> MCP interfaces are maintained in [`docs/`](docs/index.md).
|
|
30
|
+
|
|
31
|
+
## Table of Contents
|
|
32
|
+
|
|
33
|
+
- [Overview](#overview)
|
|
34
|
+
- [What it provides](#what-it-provides)
|
|
35
|
+
- [MCP tools](#mcp-tools)
|
|
36
|
+
- [Dialects & extras](#dialects--extras)
|
|
37
|
+
- [Configuration (environment)](#configuration-environment)
|
|
38
|
+
- [Installation](#installation)
|
|
39
|
+
- [Usage](#usage)
|
|
40
|
+
- [MCP config](#mcp-config)
|
|
41
|
+
- [Docker deployment](#docker-deployment)
|
|
42
|
+
- [Safety model](#safety-model)
|
|
43
|
+
- [Tests](#tests)
|
|
44
|
+
|
|
45
|
+
## Overview
|
|
46
|
+
|
|
47
|
+
`sql-mcp` exposes read-only queries, gated DML/DDL, schema reflection, and
|
|
48
|
+
connection administration as typed, deterministic MCP tools, and ships an optional
|
|
49
|
+
Pydantic-AI agent server. It is **read-only by default**: every query passes a
|
|
50
|
+
statement-type allowlist, every result is bounded by a row cap and a timeout, and
|
|
51
|
+
all values travel as bound parameters — never interpolated into SQL strings.
|
|
52
|
+
|
|
53
|
+
## What it provides
|
|
54
|
+
|
|
55
|
+
- **`SqlApi`** (`sql_mcp.api.api_client_sql`) — a SQLAlchemy 2.x Core facade with
|
|
56
|
+
named multi-connection support, lazy engine creation, the read-only statement
|
|
57
|
+
gate, row-cap/timeout enforcement, and bounded result envelopes
|
|
58
|
+
(`{columns, rows, row_count, truncated}`).
|
|
59
|
+
- **Four MCP tools** (`sql-mcp` console script): `sql_query` (execute/explain),
|
|
60
|
+
`sql_execute` (execute/script — gated by `SQL_ALLOW_WRITES`), `sql_schema`
|
|
61
|
+
(schemas/tables/views/columns/indexes/foreign_keys/ddl/sample), and `sql_admin`
|
|
62
|
+
(ping/version/active_connections/connections/dialects). See
|
|
63
|
+
[`docs/usage.md`](docs/usage.md) for the full action surface.
|
|
64
|
+
- **A dialect registry** (`sql_mcp.dialects`) — per-engine driver, URL scheme, pip
|
|
65
|
+
extra, EXPLAIN prefix, and admin SQL. Core ships SQLite only; the other drivers
|
|
66
|
+
install via extras.
|
|
67
|
+
- **An A2A agent server** (`sql-agent` console script) — a Pydantic-AI graph agent
|
|
68
|
+
wired to the MCP server via `MCP_URL`.
|
|
69
|
+
|
|
70
|
+
## MCP tools
|
|
71
|
+
|
|
72
|
+
| Tool | Actions | Description |
|
|
73
|
+
|---|---|---|
|
|
74
|
+
| `sql_query` | `execute`, `explain` | Run a read-only SELECT/CTE with bound parameters, or return the dialect's query plan |
|
|
75
|
+
| `sql_execute` | `execute`, `script` | One DML/DDL statement (or an all-or-nothing statement list) in a transaction — requires `SQL_ALLOW_WRITES=True` |
|
|
76
|
+
| `sql_schema` | `schemas`, `tables`, `views`, `columns`, `indexes`, `foreign_keys`, `ddl`, `sample` | Reflect schemas, tables, columns, indexes, FKs, CREATE DDL, and preview rows |
|
|
77
|
+
| `sql_admin` | `ping`, `version`, `active_connections`, `connections`, `dialects` | Connection health, server version, server sessions, registry info, driver availability |
|
|
78
|
+
|
|
79
|
+
Every tool takes `action`, `params_json`, and an optional `connection` naming one
|
|
80
|
+
of the configured connections. The whole set is toggled with `SQLTOOL`.
|
|
81
|
+
|
|
82
|
+
## Dialects & extras
|
|
83
|
+
|
|
84
|
+
| Dialect | SQLAlchemy scheme | Driver | Install |
|
|
85
|
+
|---|---|---|---|
|
|
86
|
+
| SQLite | `sqlite+pysqlite` | stdlib | `pip install sql-mcp` (core) |
|
|
87
|
+
| PostgreSQL | `postgresql+psycopg` | psycopg 3 | `pip install sql-mcp[postgres]` |
|
|
88
|
+
| MySQL / MariaDB | `mysql+pymysql` | PyMySQL | `pip install sql-mcp[mysql]` |
|
|
89
|
+
| SQL Server | `mssql+pyodbc` | pyodbc | `pip install sql-mcp[mssql]` |
|
|
90
|
+
| Oracle | `oracle+oracledb` | python-oracledb | `pip install sql-mcp[oracle]` |
|
|
91
|
+
|
|
92
|
+
`pip install sql-mcp[all]` pulls every driver plus the MCP and agent extras.
|
|
93
|
+
|
|
94
|
+
## Configuration (environment)
|
|
95
|
+
|
|
96
|
+
| Var | Default | Meaning |
|
|
97
|
+
|---|---|---|
|
|
98
|
+
| `SQL_CONNECTIONS` | _(empty)_ | JSON map of named connections: DSN strings or `{dialect, host, port, username, password, database, options}` objects |
|
|
99
|
+
| `SQL_URL` | _(empty)_ | Single DSN registered as connection `default` |
|
|
100
|
+
| `SQL_DIALECT` / `SQL_HOST` / `SQL_PORT` / `SQL_USERNAME` / `SQL_PASSWORD` / `SQL_DATABASE` / `SQL_OPTIONS` | _(empty)_ | Discrete fields for a single `default` connection |
|
|
101
|
+
| `SQL_ALLOW_WRITES` | `False` | Enable `sql_execute` (DML/DDL). **Read-only by default** |
|
|
102
|
+
| `SQL_MAX_ROWS` | `500` | Per-call row cap; tool requests are clamped to it |
|
|
103
|
+
| `SQL_TIMEOUT_SECONDS` | `30` | Per-statement timeout |
|
|
104
|
+
| `SQLTOOL` | `True` | Register the SQL tool set |
|
|
105
|
+
|
|
106
|
+
With nothing configured the server registers a zero-infra in-memory SQLite
|
|
107
|
+
connection named `memory`, so it works out of the box. Tools take an optional
|
|
108
|
+
`connection` parameter naming one of the configured connections; it defaults to
|
|
109
|
+
the sole/first one. Passwords are parsed into `sqlalchemy.URL` objects and only
|
|
110
|
+
ever rendered redacted. Copy [`.env.example`](.env.example) to `.env` and
|
|
111
|
+
populate only what you use.
|
|
112
|
+
|
|
113
|
+
## Installation
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
pip install sql-mcp # core (SQLite, MCP server, API)
|
|
117
|
+
pip install sql-mcp[all] # every driver + MCP + agent extras
|
|
118
|
+
pip install -e . # from source
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Or pull the container image:
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
docker pull knucklessg1/sql-mcp:latest
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## Usage
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
sql-mcp # stdio MCP server (default transport)
|
|
131
|
+
sql-mcp --transport streamable-http --host 0.0.0.0 --port 8000
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Point it at a database:
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
export SQL_URL="postgresql+psycopg://svc:****@db.example.com:5432/app"
|
|
138
|
+
sql-mcp
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Or several:
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
export SQL_CONNECTIONS='{
|
|
145
|
+
"warehouse": "postgresql+psycopg://svc:****@dw.example.com:5432/dw",
|
|
146
|
+
"erp": {"dialect": "mysql", "host": "erp.example.com", "username": "svc",
|
|
147
|
+
"password": "****", "database": "erp"}
|
|
148
|
+
}'
|
|
149
|
+
sql-mcp
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Run the agent server against a live MCP server:
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
sql-agent --mcp-url http://localhost:8000/mcp --host 0.0.0.0 --port 8080
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
## MCP config
|
|
159
|
+
|
|
160
|
+
```json
|
|
161
|
+
{
|
|
162
|
+
"mcpServers": {
|
|
163
|
+
"sql-mcp": {
|
|
164
|
+
"command": "uv",
|
|
165
|
+
"args": ["run", "sql-mcp"],
|
|
166
|
+
"env": {
|
|
167
|
+
"SQL_URL": "postgresql+psycopg://svc:****@db.example.com:5432/app",
|
|
168
|
+
"SQL_ALLOW_WRITES": "False"
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
## Docker deployment
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
docker compose -f docker/mcp.compose.yml up -d # MCP server only
|
|
179
|
+
docker compose -f docker/agent.compose.yml up -d # MCP + A2A agent
|
|
180
|
+
curl -s http://localhost:8000/health # {"status":"OK"}
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Both services read configuration from `../.env` (copy
|
|
184
|
+
[`.env.example`](.env.example)); see [`docs/deployment.md`](docs/deployment.md).
|
|
185
|
+
|
|
186
|
+
## Safety model
|
|
187
|
+
|
|
188
|
+
- **Read-only by default** — `sql_execute` refuses to run unless the *server* was
|
|
189
|
+
started with `SQL_ALLOW_WRITES=True`; agents cannot flip the flag per call.
|
|
190
|
+
- **Statement allowlist** — `sql_query` accepts only `SELECT`/`WITH`/`EXPLAIN`/
|
|
191
|
+
`SHOW`/`DESCRIBE`/`PRAGMA`/`VALUES`; CTEs are inspected at paren depth zero so
|
|
192
|
+
`WITH ... INSERT` cannot smuggle a write, `SELECT INTO` is rejected, and
|
|
193
|
+
multi-statement payloads are refused.
|
|
194
|
+
- **Bounded results** — per-call row caps clamp to `SQL_MAX_ROWS`; statements run
|
|
195
|
+
under `SQL_TIMEOUT_SECONDS` on a worker thread.
|
|
196
|
+
- **Parameterized only** — values bind via `:name` parameters; identifiers are
|
|
197
|
+
quoted by SQLAlchemy reflection, never hand-interpolated.
|
|
198
|
+
|
|
199
|
+
## Tests
|
|
200
|
+
|
|
201
|
+
```bash
|
|
202
|
+
python -m pytest # full suite against in-memory SQLite (no live DBs)
|
|
203
|
+
pre-commit run --all-files
|
|
204
|
+
```
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = [ "setuptools>=80.9.0", "wheel",]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "sql-mcp"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Generic SQL database (Postgres, MySQL/MariaDB, MSSQL, Oracle, SQLite) API + MCP Server + A2A Server for Agentic AI!"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
classifiers = [ "Development Status :: 4 - Beta", "License :: OSI Approved :: MIT License", "Environment :: Console", "Operating System :: POSIX :: Linux", "Programming Language :: Python :: 3",]
|
|
11
|
+
requires-python = ">=3.11, <3.15"
|
|
12
|
+
dependencies = [ "agent-utilities>=0.47.0", "python-dotenv>=1.0.0", "sqlalchemy>=2.0.0",]
|
|
13
|
+
[[project.authors]]
|
|
14
|
+
name = "Audel Rouhi"
|
|
15
|
+
email = "knucklessg1@gmail.com"
|
|
16
|
+
|
|
17
|
+
[project.license]
|
|
18
|
+
text = "MIT"
|
|
19
|
+
|
|
20
|
+
[project.optional-dependencies]
|
|
21
|
+
mcp = [ "agent-utilities[mcp]>=0.47.0",]
|
|
22
|
+
agent = [ "agent-utilities[agent,logfire]>=0.47.0",]
|
|
23
|
+
postgres = [ "psycopg[binary]>=3.1.0",]
|
|
24
|
+
mysql = [ "pymysql>=1.1.0",]
|
|
25
|
+
mssql = [ "pyodbc>=5.0.0",]
|
|
26
|
+
oracle = [ "oracledb>=2.0.0",]
|
|
27
|
+
all = [ "sql-mcp[mcp,agent,postgres,mysql,mssql,oracle,logfire]>=0.1.0",]
|
|
28
|
+
test = [ "pytest-xdist>=3.6.0", "pytest", "pytest-asyncio", "pytest-cov",]
|
|
29
|
+
|
|
30
|
+
[project.scripts]
|
|
31
|
+
sql-mcp = "sql_mcp.mcp_server:mcp_server"
|
|
32
|
+
sql-agent = "sql_mcp.agent_server:agent_server"
|
|
33
|
+
|
|
34
|
+
[tool.setuptools]
|
|
35
|
+
include-package-data = true
|
|
36
|
+
|
|
37
|
+
[tool.ruff]
|
|
38
|
+
line-length = 88
|
|
39
|
+
target-version = "py310"
|
|
40
|
+
|
|
41
|
+
[tool.mypy]
|
|
42
|
+
python_version = "3.10"
|
|
43
|
+
ignore_missing_imports = true
|
|
44
|
+
check_untyped_defs = true
|
|
45
|
+
|
|
46
|
+
[dependency-groups]
|
|
47
|
+
dev = [ "pytest-timeout>=2.4.0",]
|
|
48
|
+
|
|
49
|
+
[tool.setuptools.package-data]
|
|
50
|
+
sql_mcp = [ "mcp_config.json", "agent_data/**",]
|
|
51
|
+
|
|
52
|
+
[tool.ruff.lint]
|
|
53
|
+
select = [ "E", "F", "I", "UP", "B",]
|
|
54
|
+
ignore = [ "E402", "E501", "B008",]
|
|
55
|
+
|
|
56
|
+
[tool.vulture]
|
|
57
|
+
ignore_names = ["request", "config"]
|
|
58
|
+
|
|
59
|
+
[tool.setuptools.packages.find]
|
|
60
|
+
where = [ ".",]
|
|
61
|
+
include = [ "sql_mcp*",]
|
sql_mcp-0.1.0/setup.cfg
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
"""sql-mcp: Generic SQL database API + MCP Server + A2A Server (SQLAlchemy 2.x Core)."""
|
|
2
|
+
|
|
3
|
+
import importlib
|
|
4
|
+
import inspect
|
|
5
|
+
from typing import Any
|
|
6
|
+
|
|
7
|
+
__version__ = "0.1.0"
|
|
8
|
+
__all__: list[str] = []
|
|
9
|
+
|
|
10
|
+
CORE_MODULES = ["sql_mcp.api_client"]
|
|
11
|
+
OPTIONAL_MODULES = {
|
|
12
|
+
"sql_mcp.agent_server": "agent",
|
|
13
|
+
"sql_mcp.mcp_server": "mcp",
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def _expose_members(module):
|
|
18
|
+
for name, obj in inspect.getmembers(module):
|
|
19
|
+
if (inspect.isclass(obj) or inspect.isfunction(obj)) and not name.startswith(
|
|
20
|
+
"_"
|
|
21
|
+
):
|
|
22
|
+
globals()[name] = obj
|
|
23
|
+
if name not in __all__:
|
|
24
|
+
__all__.append(name)
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
for module_name in CORE_MODULES:
|
|
28
|
+
module = importlib.import_module(module_name)
|
|
29
|
+
_expose_members(module)
|
|
30
|
+
|
|
31
|
+
_loaded_optional_modules: dict = {}
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def _import_module_safely(module_name: str):
|
|
35
|
+
try:
|
|
36
|
+
return importlib.import_module(module_name)
|
|
37
|
+
except ImportError:
|
|
38
|
+
return None
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def __getattr__(name: str) -> Any:
|
|
42
|
+
if name == "_MCP_AVAILABLE":
|
|
43
|
+
mcp_key = next((k for k in OPTIONAL_MODULES if "mcp_server" in k), None)
|
|
44
|
+
return _import_module_safely(mcp_key) is not None if mcp_key else False
|
|
45
|
+
if name == "_AGENT_AVAILABLE":
|
|
46
|
+
agent_key = next((k for k in OPTIONAL_MODULES if "agent_server" in k), None)
|
|
47
|
+
return _import_module_safely(agent_key) is not None if agent_key else False
|
|
48
|
+
|
|
49
|
+
for module_name in OPTIONAL_MODULES:
|
|
50
|
+
if module_name not in _loaded_optional_modules:
|
|
51
|
+
module = _import_module_safely(module_name)
|
|
52
|
+
if module is not None:
|
|
53
|
+
_loaded_optional_modules[module_name] = module
|
|
54
|
+
_expose_members(module)
|
|
55
|
+
|
|
56
|
+
module = _loaded_optional_modules.get(module_name)
|
|
57
|
+
if module is not None and hasattr(module, name):
|
|
58
|
+
return getattr(module, name)
|
|
59
|
+
|
|
60
|
+
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def __dir__() -> list[str]:
|
|
64
|
+
return sorted(list(globals().keys()) + __all__)
|