sql-mini-mcp 0.9.1__tar.gz → 1.0.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_mini_mcp-0.9.1 → sql_mini_mcp-1.0.0}/CHANGELOG.md +9 -0
- sql_mini_mcp-1.0.0/PKG-INFO +215 -0
- sql_mini_mcp-1.0.0/README.md +178 -0
- {sql_mini_mcp-0.9.1 → sql_mini_mcp-1.0.0}/pyproject.toml +5 -1
- {sql_mini_mcp-0.9.1 → sql_mini_mcp-1.0.0}/server.json +2 -2
- {sql_mini_mcp-0.9.1 → sql_mini_mcp-1.0.0}/src/sql_mini_mcp/__init__.py +1 -1
- {sql_mini_mcp-0.9.1 → sql_mini_mcp-1.0.0}/src/sql_mini_mcp/mcp_server.py +14 -1
- {sql_mini_mcp-0.9.1 → sql_mini_mcp-1.0.0}/src/sql_mini_mcp/models.py +23 -0
- sql_mini_mcp-1.0.0/src/sql_mini_mcp/security/__init__.py +1 -0
- sql_mini_mcp-1.0.0/src/sql_mini_mcp/security/executor.py +125 -0
- sql_mini_mcp-1.0.0/src/sql_mini_mcp/security/lineage.py +218 -0
- sql_mini_mcp-1.0.0/src/sql_mini_mcp/security/parser.py +173 -0
- sql_mini_mcp-1.0.0/src/sql_mini_mcp/security/pipeline.py +40 -0
- sql_mini_mcp-1.0.0/src/sql_mini_mcp/security/policy.py +100 -0
- sql_mini_mcp-1.0.0/src/sql_mini_mcp/security/schema.py +132 -0
- sql_mini_mcp-1.0.0/src/sql_mini_mcp/security/tokens.py +207 -0
- sql_mini_mcp-1.0.0/src/sql_mini_mcp/security/validated_query.py +203 -0
- {sql_mini_mcp-0.9.1 → sql_mini_mcp-1.0.0}/src/sql_mini_mcp/service.py +74 -2
- sql_mini_mcp-0.9.1/PKG-INFO +0 -130
- sql_mini_mcp-0.9.1/README.md +0 -95
- {sql_mini_mcp-0.9.1 → sql_mini_mcp-1.0.0}/.gitignore +0 -0
- {sql_mini_mcp-0.9.1 → sql_mini_mcp-1.0.0}/LICENSE +0 -0
- {sql_mini_mcp-0.9.1 → sql_mini_mcp-1.0.0}/sql-mini-mcp.example.yaml +0 -0
- {sql_mini_mcp-0.9.1 → sql_mini_mcp-1.0.0}/src/sql_mini_mcp/__main__.py +0 -0
- {sql_mini_mcp-0.9.1 → sql_mini_mcp-1.0.0}/src/sql_mini_mcp/config.py +0 -0
- {sql_mini_mcp-0.9.1 → sql_mini_mcp-1.0.0}/src/sql_mini_mcp/db/__init__.py +0 -0
- {sql_mini_mcp-0.9.1 → sql_mini_mcp-1.0.0}/src/sql_mini_mcp/db/extras.py +0 -0
- {sql_mini_mcp-0.9.1 → sql_mini_mcp-1.0.0}/src/sql_mini_mcp/db/reflection.py +0 -0
- {sql_mini_mcp-0.9.1 → sql_mini_mcp-1.0.0}/src/sql_mini_mcp/db/registry.py +0 -0
- {sql_mini_mcp-0.9.1 → sql_mini_mcp-1.0.0}/src/sql_mini_mcp/db/sqlserver.py +0 -0
- {sql_mini_mcp-0.9.1 → sql_mini_mcp-1.0.0}/src/sql_mini_mcp/errors.py +0 -0
|
@@ -7,6 +7,15 @@ categories `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, and `Security`.
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [1.0.0] - 2026-09-20
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- `execute_sql` tool for `pii_safe` SQL Server aliases. It runs one restricted `SELECT`, returns
|
|
15
|
+
configured PII columns as alias-bound tokens, accepts those tokens only in `=` and `IN`
|
|
16
|
+
predicates, and returns at most `max_rows` rows with a `truncated` flag. Servers with
|
|
17
|
+
`access_level: metadata` return `ACCESS_LEVEL_DENIED`.
|
|
18
|
+
|
|
10
19
|
## [0.9.1] - 2026-09-20
|
|
11
20
|
|
|
12
21
|
### Added
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: sql-mini-mcp
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Minimal, read-only, PII-safe MCP server for SQL databases.
|
|
5
|
+
License: MIT License
|
|
6
|
+
|
|
7
|
+
Copyright (c) 2026 Anton Padapryhara
|
|
8
|
+
|
|
9
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
10
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
11
|
+
in the Software without restriction, including without limitation the rights
|
|
12
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
13
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
14
|
+
furnished to do so, subject to the following conditions:
|
|
15
|
+
|
|
16
|
+
The above copyright notice and this permission notice shall be included in all
|
|
17
|
+
copies or substantial portions of the Software.
|
|
18
|
+
|
|
19
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
20
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
21
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
22
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
23
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
24
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
25
|
+
SOFTWARE.
|
|
26
|
+
License-File: LICENSE
|
|
27
|
+
Requires-Python: <3.15,>=3.12
|
|
28
|
+
Requires-Dist: anyio<5,>=4.8
|
|
29
|
+
Requires-Dist: cryptography<47,>=46.0.7
|
|
30
|
+
Requires-Dist: mcp<3,>=2
|
|
31
|
+
Requires-Dist: pydantic<3,>=2.10
|
|
32
|
+
Requires-Dist: pyodbc<6,>=5.2
|
|
33
|
+
Requires-Dist: pyyaml<7,>=6
|
|
34
|
+
Requires-Dist: sqlalchemy<3,>=2.0
|
|
35
|
+
Requires-Dist: sqlglot<31,>=30.18
|
|
36
|
+
Description-Content-Type: text/markdown
|
|
37
|
+
|
|
38
|
+
<div align="center">
|
|
39
|
+
|
|
40
|
+
# sql-mini-mcp
|
|
41
|
+
|
|
42
|
+
A read-only SQL Server MCP server for coding agents: 6 metadata tools, no unrestricted SQL.
|
|
43
|
+
|
|
44
|
+
[](https://github.com/proprock/sql-mini-mcp/actions/workflows/ci.yml)
|
|
45
|
+
[](https://github.com/proprock/sql-mini-mcp/releases)
|
|
46
|
+
[](https://pypi.org/project/sql-mini-mcp/)
|
|
47
|
+
[](https://www.python.org/downloads/)
|
|
48
|
+
[](LICENSE)
|
|
49
|
+
|
|
50
|
+
[](https://modelcontextprotocol.io)
|
|
51
|
+
[](server.json)
|
|
52
|
+
|
|
53
|
+
<img src="https://raw.githubusercontent.com/proprock/sql-mini-mcp/master/images/luna-guard.jpg" alt="Read the data. Protect the identity." width="760">
|
|
54
|
+
|
|
55
|
+
<i>Read the data. Protect the identity.</i>
|
|
56
|
+
|
|
57
|
+
</div>
|
|
58
|
+
|
|
59
|
+
<!-- mcp-name: io.github.proprock/sql-mini-mcp -->
|
|
60
|
+
|
|
61
|
+
General-purpose database MCP servers hand the agent a raw SQL prompt and dozens of tools. This
|
|
62
|
+
server gives a coding agent the schema knowledge it needs to write correct code - servers,
|
|
63
|
+
databases, tables, columns, keys, indexes, stored procedures - and nothing that can change or leak
|
|
64
|
+
data.
|
|
65
|
+
|
|
66
|
+
- **6 tools, all read-only** - every one is annotated read-only and earns its place in context; see
|
|
67
|
+
[tools](docs/tools.md).
|
|
68
|
+
<!-- - **Read-only by design. PII-safe by default.** [placeholder] -->
|
|
69
|
+
- **No caller-provided SQL** - the server never executes SQL an agent wrote. Metadata comes from
|
|
70
|
+
SQLAlchemy Inspector and fixed catalog queries.
|
|
71
|
+
- **Your aliases, not your network** - the agent sees only the server aliases you configure. There
|
|
72
|
+
is no network discovery, and the catalog is not published as MCP resources.
|
|
73
|
+
- **Secrets stay out of sight** - connection URLs live in YAML with `${NAME}` placeholders resolved
|
|
74
|
+
from the environment. They never appear in logs or model-visible errors.
|
|
75
|
+
- **Compact, predictable output** - object-rooted results with stable sorting, literal
|
|
76
|
+
case-insensitive name filters, and stored procedure lists that do not expand definitions.
|
|
77
|
+
- **Errors an agent can act on** - an ambiguous name lists the candidate schemas. Errors never
|
|
78
|
+
contain connection details, credentials, or rows.
|
|
79
|
+
- **Fails closed** - security decisions are allowlists; anything unrecognized is refused.
|
|
80
|
+
- **On PyPI** - `uvx sql-mini-mcp`, no repo clone required.
|
|
81
|
+
|
|
82
|
+
| Tool | Access | Purpose |
|
|
83
|
+
|---|---|---|
|
|
84
|
+
| `list_servers` | 🟢 read | Configured server aliases |
|
|
85
|
+
| `list_databases` | 🟢 read | Databases visible to the credentials |
|
|
86
|
+
| `list_tables` | 🟢 read | Base tables, filtered by schema or name |
|
|
87
|
+
| `get_table_definition` | 🟢 read | Columns, keys, constraints, and indexes of one table |
|
|
88
|
+
| `list_stored_procedures` | 🟢 read | Stored procedures, without definitions |
|
|
89
|
+
| `get_stored_procedure` | 🟢 read | The definition of one stored procedure |
|
|
90
|
+
| `execute_sql` | 🟢 read | One restricted `SELECT` on a `pii_safe` server; protected columns return tokens |
|
|
91
|
+
|
|
92
|
+
> [!NOTE]
|
|
93
|
+
> **Status:** SQL Server only. MySQL/MariaDB is planned; see [ARCHITECTURE.md](ARCHITECTURE.md).
|
|
94
|
+
> Configuration for MySQL/MariaDB is rejected until it ships.
|
|
95
|
+
|
|
96
|
+
- [Install](#install)
|
|
97
|
+
- [Configure](#configure)
|
|
98
|
+
- [Security](#security)
|
|
99
|
+
- [Contributing and security](#contributing-and-security)
|
|
100
|
+
|
|
101
|
+
More detail lives in [`docs/`](docs): the [configuration reference](docs/configuration.md) and
|
|
102
|
+
[what the tools return](docs/tools.md).
|
|
103
|
+
|
|
104
|
+
## Install
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
uvx sql-mini-mcp
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
or
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
pip install sql-mini-mcp
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Pin a version when you want a fixed surface: `uvx sql-mini-mcp==1.0.0`.
|
|
117
|
+
|
|
118
|
+
Requires Python 3.12+, [uv](https://docs.astral.sh/uv/) (or `pip`), and
|
|
119
|
+
[Microsoft ODBC Driver 18 for SQL Server](https://learn.microsoft.com/sql/connect/odbc/download-odbc-driver-for-sql-server).
|
|
120
|
+
|
|
121
|
+
## Configure
|
|
122
|
+
|
|
123
|
+
Copy [sql-mini-mcp.example.yaml](sql-mini-mcp.example.yaml) to `sql-mini-mcp.yaml`, list your
|
|
124
|
+
servers, and keep credentials in environment variables:
|
|
125
|
+
|
|
126
|
+
```yaml
|
|
127
|
+
version: 1
|
|
128
|
+
servers:
|
|
129
|
+
reporting:
|
|
130
|
+
engine: sqlserver
|
|
131
|
+
access_level: metadata
|
|
132
|
+
connection_url: "${REPORTING_SQL_URL}"
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Point the server at the file with `SQL_MINI_MCP_CONFIG` (or `--config`), and check it without
|
|
136
|
+
connecting to any database:
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
SQL_MINI_MCP_CONFIG=sql-mini-mcp.yaml uvx sql-mini-mcp --check-config
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Configuration is validated at startup, and an error names the problem without printing a URL or
|
|
143
|
+
secret. Keep credentials in the host's own configuration and never commit them. The server acts
|
|
144
|
+
with the database account's permissions, so use a dedicated login with the least access the job
|
|
145
|
+
needs. Every setting, including the runtime limits, is in
|
|
146
|
+
[configuration.md](docs/configuration.md).
|
|
147
|
+
|
|
148
|
+
<details>
|
|
149
|
+
<summary><b>Claude Code</b></summary>
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
claude mcp add --env SQL_MINI_MCP_CONFIG=/path/to/sql-mini-mcp.yaml --env REPORTING_SQL_URL=mssql+pyodbc://... --transport stdio sql-mini -- uvx sql-mini-mcp
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Put at least one other option between the last `--env` and the server name, as above - the CLI
|
|
156
|
+
otherwise reads the name as another `KEY=value` pair.
|
|
157
|
+
|
|
158
|
+
</details>
|
|
159
|
+
|
|
160
|
+
<details>
|
|
161
|
+
<summary><b>Claude Desktop</b></summary>
|
|
162
|
+
|
|
163
|
+
In `claude_desktop_config.json`:
|
|
164
|
+
|
|
165
|
+
```json
|
|
166
|
+
{
|
|
167
|
+
"mcpServers": {
|
|
168
|
+
"sql-mini": {
|
|
169
|
+
"command": "uvx",
|
|
170
|
+
"args": ["sql-mini-mcp"],
|
|
171
|
+
"env": {
|
|
172
|
+
"SQL_MINI_MCP_CONFIG": "/path/to/sql-mini-mcp.yaml",
|
|
173
|
+
"REPORTING_SQL_URL": "mssql+pyodbc://..."
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
</details>
|
|
181
|
+
|
|
182
|
+
<details>
|
|
183
|
+
<summary><b>Codex CLI</b></summary>
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
codex mcp add sql-mini --env SQL_MINI_MCP_CONFIG=/path/to/sql-mini-mcp.yaml --env REPORTING_SQL_URL=mssql+pyodbc://... -- uvx sql-mini-mcp
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
</details>
|
|
190
|
+
|
|
191
|
+
<details>
|
|
192
|
+
<summary><b>Any other stdio host</b></summary>
|
|
193
|
+
|
|
194
|
+
Command `uvx`, argument `sql-mini-mcp`, and the environment variables your configuration
|
|
195
|
+
references, plus `SQL_MINI_MCP_CONFIG`. The server speaks MCP over stdio and logs only to stderr.
|
|
196
|
+
|
|
197
|
+
</details>
|
|
198
|
+
|
|
199
|
+
## Security
|
|
200
|
+
|
|
201
|
+
The MCP caller, SQL input, database metadata, rows, and tokens are untrusted; the operator, the
|
|
202
|
+
process environment, and the database credentials are the trusted boundary. Database permissions
|
|
203
|
+
remain the primary authorization control - this server never widens them. The full model, and how
|
|
204
|
+
to report a vulnerability, are in [SECURITY.md](SECURITY.md).
|
|
205
|
+
|
|
206
|
+
## Contributing and security
|
|
207
|
+
|
|
208
|
+
Setup, checks, the test commands, the branch and commit conventions, and the release model are in
|
|
209
|
+
[CONTRIBUTING.md](CONTRIBUTING.md). Report vulnerabilities privately as described in
|
|
210
|
+
[SECURITY.md](SECURITY.md). Changes that affect someone running the server are recorded in
|
|
211
|
+
[CHANGELOG.md](CHANGELOG.md).
|
|
212
|
+
|
|
213
|
+
## License
|
|
214
|
+
|
|
215
|
+
[MIT](LICENSE).
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# sql-mini-mcp
|
|
4
|
+
|
|
5
|
+
A read-only SQL Server MCP server for coding agents: 6 metadata tools, no unrestricted SQL.
|
|
6
|
+
|
|
7
|
+
[](https://github.com/proprock/sql-mini-mcp/actions/workflows/ci.yml)
|
|
8
|
+
[](https://github.com/proprock/sql-mini-mcp/releases)
|
|
9
|
+
[](https://pypi.org/project/sql-mini-mcp/)
|
|
10
|
+
[](https://www.python.org/downloads/)
|
|
11
|
+
[](LICENSE)
|
|
12
|
+
|
|
13
|
+
[](https://modelcontextprotocol.io)
|
|
14
|
+
[](server.json)
|
|
15
|
+
|
|
16
|
+
<img src="https://raw.githubusercontent.com/proprock/sql-mini-mcp/master/images/luna-guard.jpg" alt="Read the data. Protect the identity." width="760">
|
|
17
|
+
|
|
18
|
+
<i>Read the data. Protect the identity.</i>
|
|
19
|
+
|
|
20
|
+
</div>
|
|
21
|
+
|
|
22
|
+
<!-- mcp-name: io.github.proprock/sql-mini-mcp -->
|
|
23
|
+
|
|
24
|
+
General-purpose database MCP servers hand the agent a raw SQL prompt and dozens of tools. This
|
|
25
|
+
server gives a coding agent the schema knowledge it needs to write correct code - servers,
|
|
26
|
+
databases, tables, columns, keys, indexes, stored procedures - and nothing that can change or leak
|
|
27
|
+
data.
|
|
28
|
+
|
|
29
|
+
- **6 tools, all read-only** - every one is annotated read-only and earns its place in context; see
|
|
30
|
+
[tools](docs/tools.md).
|
|
31
|
+
<!-- - **Read-only by design. PII-safe by default.** [placeholder] -->
|
|
32
|
+
- **No caller-provided SQL** - the server never executes SQL an agent wrote. Metadata comes from
|
|
33
|
+
SQLAlchemy Inspector and fixed catalog queries.
|
|
34
|
+
- **Your aliases, not your network** - the agent sees only the server aliases you configure. There
|
|
35
|
+
is no network discovery, and the catalog is not published as MCP resources.
|
|
36
|
+
- **Secrets stay out of sight** - connection URLs live in YAML with `${NAME}` placeholders resolved
|
|
37
|
+
from the environment. They never appear in logs or model-visible errors.
|
|
38
|
+
- **Compact, predictable output** - object-rooted results with stable sorting, literal
|
|
39
|
+
case-insensitive name filters, and stored procedure lists that do not expand definitions.
|
|
40
|
+
- **Errors an agent can act on** - an ambiguous name lists the candidate schemas. Errors never
|
|
41
|
+
contain connection details, credentials, or rows.
|
|
42
|
+
- **Fails closed** - security decisions are allowlists; anything unrecognized is refused.
|
|
43
|
+
- **On PyPI** - `uvx sql-mini-mcp`, no repo clone required.
|
|
44
|
+
|
|
45
|
+
| Tool | Access | Purpose |
|
|
46
|
+
|---|---|---|
|
|
47
|
+
| `list_servers` | 🟢 read | Configured server aliases |
|
|
48
|
+
| `list_databases` | 🟢 read | Databases visible to the credentials |
|
|
49
|
+
| `list_tables` | 🟢 read | Base tables, filtered by schema or name |
|
|
50
|
+
| `get_table_definition` | 🟢 read | Columns, keys, constraints, and indexes of one table |
|
|
51
|
+
| `list_stored_procedures` | 🟢 read | Stored procedures, without definitions |
|
|
52
|
+
| `get_stored_procedure` | 🟢 read | The definition of one stored procedure |
|
|
53
|
+
| `execute_sql` | 🟢 read | One restricted `SELECT` on a `pii_safe` server; protected columns return tokens |
|
|
54
|
+
|
|
55
|
+
> [!NOTE]
|
|
56
|
+
> **Status:** SQL Server only. MySQL/MariaDB is planned; see [ARCHITECTURE.md](ARCHITECTURE.md).
|
|
57
|
+
> Configuration for MySQL/MariaDB is rejected until it ships.
|
|
58
|
+
|
|
59
|
+
- [Install](#install)
|
|
60
|
+
- [Configure](#configure)
|
|
61
|
+
- [Security](#security)
|
|
62
|
+
- [Contributing and security](#contributing-and-security)
|
|
63
|
+
|
|
64
|
+
More detail lives in [`docs/`](docs): the [configuration reference](docs/configuration.md) and
|
|
65
|
+
[what the tools return](docs/tools.md).
|
|
66
|
+
|
|
67
|
+
## Install
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
uvx sql-mini-mcp
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
or
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
pip install sql-mini-mcp
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Pin a version when you want a fixed surface: `uvx sql-mini-mcp==1.0.0`.
|
|
80
|
+
|
|
81
|
+
Requires Python 3.12+, [uv](https://docs.astral.sh/uv/) (or `pip`), and
|
|
82
|
+
[Microsoft ODBC Driver 18 for SQL Server](https://learn.microsoft.com/sql/connect/odbc/download-odbc-driver-for-sql-server).
|
|
83
|
+
|
|
84
|
+
## Configure
|
|
85
|
+
|
|
86
|
+
Copy [sql-mini-mcp.example.yaml](sql-mini-mcp.example.yaml) to `sql-mini-mcp.yaml`, list your
|
|
87
|
+
servers, and keep credentials in environment variables:
|
|
88
|
+
|
|
89
|
+
```yaml
|
|
90
|
+
version: 1
|
|
91
|
+
servers:
|
|
92
|
+
reporting:
|
|
93
|
+
engine: sqlserver
|
|
94
|
+
access_level: metadata
|
|
95
|
+
connection_url: "${REPORTING_SQL_URL}"
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Point the server at the file with `SQL_MINI_MCP_CONFIG` (or `--config`), and check it without
|
|
99
|
+
connecting to any database:
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
SQL_MINI_MCP_CONFIG=sql-mini-mcp.yaml uvx sql-mini-mcp --check-config
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Configuration is validated at startup, and an error names the problem without printing a URL or
|
|
106
|
+
secret. Keep credentials in the host's own configuration and never commit them. The server acts
|
|
107
|
+
with the database account's permissions, so use a dedicated login with the least access the job
|
|
108
|
+
needs. Every setting, including the runtime limits, is in
|
|
109
|
+
[configuration.md](docs/configuration.md).
|
|
110
|
+
|
|
111
|
+
<details>
|
|
112
|
+
<summary><b>Claude Code</b></summary>
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
claude mcp add --env SQL_MINI_MCP_CONFIG=/path/to/sql-mini-mcp.yaml --env REPORTING_SQL_URL=mssql+pyodbc://... --transport stdio sql-mini -- uvx sql-mini-mcp
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Put at least one other option between the last `--env` and the server name, as above - the CLI
|
|
119
|
+
otherwise reads the name as another `KEY=value` pair.
|
|
120
|
+
|
|
121
|
+
</details>
|
|
122
|
+
|
|
123
|
+
<details>
|
|
124
|
+
<summary><b>Claude Desktop</b></summary>
|
|
125
|
+
|
|
126
|
+
In `claude_desktop_config.json`:
|
|
127
|
+
|
|
128
|
+
```json
|
|
129
|
+
{
|
|
130
|
+
"mcpServers": {
|
|
131
|
+
"sql-mini": {
|
|
132
|
+
"command": "uvx",
|
|
133
|
+
"args": ["sql-mini-mcp"],
|
|
134
|
+
"env": {
|
|
135
|
+
"SQL_MINI_MCP_CONFIG": "/path/to/sql-mini-mcp.yaml",
|
|
136
|
+
"REPORTING_SQL_URL": "mssql+pyodbc://..."
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
</details>
|
|
144
|
+
|
|
145
|
+
<details>
|
|
146
|
+
<summary><b>Codex CLI</b></summary>
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
codex mcp add sql-mini --env SQL_MINI_MCP_CONFIG=/path/to/sql-mini-mcp.yaml --env REPORTING_SQL_URL=mssql+pyodbc://... -- uvx sql-mini-mcp
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
</details>
|
|
153
|
+
|
|
154
|
+
<details>
|
|
155
|
+
<summary><b>Any other stdio host</b></summary>
|
|
156
|
+
|
|
157
|
+
Command `uvx`, argument `sql-mini-mcp`, and the environment variables your configuration
|
|
158
|
+
references, plus `SQL_MINI_MCP_CONFIG`. The server speaks MCP over stdio and logs only to stderr.
|
|
159
|
+
|
|
160
|
+
</details>
|
|
161
|
+
|
|
162
|
+
## Security
|
|
163
|
+
|
|
164
|
+
The MCP caller, SQL input, database metadata, rows, and tokens are untrusted; the operator, the
|
|
165
|
+
process environment, and the database credentials are the trusted boundary. Database permissions
|
|
166
|
+
remain the primary authorization control - this server never widens them. The full model, and how
|
|
167
|
+
to report a vulnerability, are in [SECURITY.md](SECURITY.md).
|
|
168
|
+
|
|
169
|
+
## Contributing and security
|
|
170
|
+
|
|
171
|
+
Setup, checks, the test commands, the branch and commit conventions, and the release model are in
|
|
172
|
+
[CONTRIBUTING.md](CONTRIBUTING.md). Report vulnerabilities privately as described in
|
|
173
|
+
[SECURITY.md](SECURITY.md). Changes that affect someone running the server are recorded in
|
|
174
|
+
[CHANGELOG.md](CHANGELOG.md).
|
|
175
|
+
|
|
176
|
+
## License
|
|
177
|
+
|
|
178
|
+
[MIT](LICENSE).
|
|
@@ -1,17 +1,19 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "sql-mini-mcp"
|
|
3
|
-
version = "0.
|
|
3
|
+
version = "1.0.0"
|
|
4
4
|
description = "Minimal, read-only, PII-safe MCP server for SQL databases."
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
requires-python = ">=3.12,<3.15"
|
|
7
7
|
license = { file = "LICENSE" }
|
|
8
8
|
dependencies = [
|
|
9
9
|
"anyio>=4.8,<5",
|
|
10
|
+
"cryptography>=46.0.7,<47",
|
|
10
11
|
"mcp>=2,<3",
|
|
11
12
|
"pydantic>=2.10,<3",
|
|
12
13
|
"pyodbc>=5.2,<6",
|
|
13
14
|
"pyyaml>=6,<7",
|
|
14
15
|
"sqlalchemy>=2.0,<3",
|
|
16
|
+
"sqlglot>=30.18,<31",
|
|
15
17
|
]
|
|
16
18
|
|
|
17
19
|
[project.scripts]
|
|
@@ -19,6 +21,8 @@ sql-mini-mcp = "sql_mini_mcp.__main__:main"
|
|
|
19
21
|
|
|
20
22
|
[dependency-groups]
|
|
21
23
|
dev = [
|
|
24
|
+
"hypothesis>=6.168,<7",
|
|
25
|
+
"mutmut>=3.8,<4 ; sys_platform != 'win32'",
|
|
22
26
|
"prek>=0.2",
|
|
23
27
|
"pytest>=8.3,<10",
|
|
24
28
|
"pytest-cov>=6,<8",
|
|
@@ -7,12 +7,12 @@
|
|
|
7
7
|
"url": "https://github.com/proprock/sql-mini-mcp",
|
|
8
8
|
"source": "github"
|
|
9
9
|
},
|
|
10
|
-
"version": "0.
|
|
10
|
+
"version": "1.0.0",
|
|
11
11
|
"packages": [
|
|
12
12
|
{
|
|
13
13
|
"registryType": "pypi",
|
|
14
14
|
"identifier": "sql-mini-mcp",
|
|
15
|
-
"version": "0.
|
|
15
|
+
"version": "1.0.0",
|
|
16
16
|
"transport": {
|
|
17
17
|
"type": "stdio"
|
|
18
18
|
}
|
|
@@ -14,6 +14,7 @@ from sql_mini_mcp.errors import DomainError
|
|
|
14
14
|
from sql_mini_mcp.models import (
|
|
15
15
|
DatabaseList,
|
|
16
16
|
ServerList,
|
|
17
|
+
SqlResult,
|
|
17
18
|
StoredProcedureDefinition,
|
|
18
19
|
StoredProcedureList,
|
|
19
20
|
TableDefinition,
|
|
@@ -49,7 +50,7 @@ def create_server(config: AppConfig) -> MCPServer[AppContext]:
|
|
|
49
50
|
server: MCPServer[AppContext] = MCPServer(
|
|
50
51
|
"sql-mini-mcp",
|
|
51
52
|
description="Minimal, read-only, PII-safe SQL database navigation.",
|
|
52
|
-
version="0.
|
|
53
|
+
version="1.0.0",
|
|
53
54
|
lifespan=lifespan,
|
|
54
55
|
)
|
|
55
56
|
|
|
@@ -124,4 +125,16 @@ def create_server(config: AppConfig) -> MCPServer[AppContext]:
|
|
|
124
125
|
lambda: service.get_stored_procedure(server, database, name, schema)
|
|
125
126
|
)
|
|
126
127
|
|
|
128
|
+
@server.tool(annotations=READ_ONLY)
|
|
129
|
+
async def execute_sql(
|
|
130
|
+
server: str,
|
|
131
|
+
database: str,
|
|
132
|
+
sql: str,
|
|
133
|
+
ctx: Context[AppContext],
|
|
134
|
+
max_rows: int | None = None,
|
|
135
|
+
) -> SqlResult:
|
|
136
|
+
"""Run one restricted SELECT on a pii_safe server; protected columns return tokens."""
|
|
137
|
+
service = ctx.request_context.lifespan_context.service
|
|
138
|
+
return await _domain_call(lambda: service.execute_sql(server, database, sql, max_rows))
|
|
139
|
+
|
|
127
140
|
return server
|
|
@@ -99,3 +99,26 @@ class StoredProcedureDefinition(OutputModel):
|
|
|
99
99
|
name: str
|
|
100
100
|
definition: str | None
|
|
101
101
|
definition_available: bool
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
ResultEncoding = Literal["json", "token", "decimal", "date", "time", "datetime", "uuid", "base64"]
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
class ColumnSource(OutputModel):
|
|
108
|
+
schema_: str | None = Field(alias="schema")
|
|
109
|
+
table: str
|
|
110
|
+
column: str
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
class SqlColumn(OutputModel):
|
|
114
|
+
name: str
|
|
115
|
+
source: ColumnSource | None
|
|
116
|
+
protected: bool
|
|
117
|
+
encoding: ResultEncoding
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
class SqlResult(OutputModel):
|
|
121
|
+
columns: list[SqlColumn]
|
|
122
|
+
rows: list[list[Any]]
|
|
123
|
+
row_count: int
|
|
124
|
+
truncated: bool
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""SQL validation and PII protection pipeline for execute_sql."""
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import base64
|
|
4
|
+
import math
|
|
5
|
+
from collections.abc import Sequence
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
from datetime import date, datetime, time
|
|
8
|
+
from decimal import Decimal
|
|
9
|
+
from typing import Any, Protocol
|
|
10
|
+
from uuid import UUID
|
|
11
|
+
|
|
12
|
+
from sql_mini_mcp.errors import DomainError, ErrorCode
|
|
13
|
+
from sql_mini_mcp.models import ResultEncoding
|
|
14
|
+
from sql_mini_mcp.security.lineage import SourceColumn
|
|
15
|
+
from sql_mini_mcp.security.tokens import TokenCodec
|
|
16
|
+
from sql_mini_mcp.security.validated_query import ValidatedQuery
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class _Result(Protocol):
|
|
20
|
+
def keys(self) -> Any: ...
|
|
21
|
+
|
|
22
|
+
def fetchmany(self, size: int) -> Sequence[Any]: ...
|
|
23
|
+
|
|
24
|
+
def close(self) -> None: ...
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class SqlConnection(Protocol):
|
|
28
|
+
"""The part of a SQLAlchemy Core connection the executor uses."""
|
|
29
|
+
|
|
30
|
+
def exec_driver_sql(self, statement: str, parameters: tuple[Any, ...]) -> _Result: ...
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
@dataclass(frozen=True, slots=True)
|
|
34
|
+
class ResultColumn:
|
|
35
|
+
name: str
|
|
36
|
+
source: SourceColumn | None
|
|
37
|
+
protected: bool
|
|
38
|
+
encoding: ResultEncoding
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
@dataclass(frozen=True, slots=True)
|
|
42
|
+
class ExecutionResult:
|
|
43
|
+
columns: tuple[ResultColumn, ...]
|
|
44
|
+
rows: tuple[tuple[Any, ...], ...]
|
|
45
|
+
truncated: bool
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def _unsupported_result() -> DomainError:
|
|
49
|
+
return DomainError(
|
|
50
|
+
ErrorCode.DATABASE_ERROR,
|
|
51
|
+
"The result contains a value type that is not supported.",
|
|
52
|
+
"Select different columns.",
|
|
53
|
+
)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def _encode(value: Any) -> tuple[Any, ResultEncoding]:
|
|
57
|
+
"""Return the JSON-safe form and encoding name of one non-null, unprotected value."""
|
|
58
|
+
kind = type(value)
|
|
59
|
+
if kind in (str, bool, int):
|
|
60
|
+
return value, "json"
|
|
61
|
+
if kind is float:
|
|
62
|
+
if not math.isfinite(value):
|
|
63
|
+
raise _unsupported_result()
|
|
64
|
+
return value, "json"
|
|
65
|
+
if kind is Decimal:
|
|
66
|
+
if not value.is_finite():
|
|
67
|
+
raise _unsupported_result()
|
|
68
|
+
return str(value), "decimal"
|
|
69
|
+
if kind is datetime:
|
|
70
|
+
return value.isoformat(), "datetime"
|
|
71
|
+
if kind is date:
|
|
72
|
+
return value.isoformat(), "date"
|
|
73
|
+
if kind is time:
|
|
74
|
+
return value.isoformat(), "time"
|
|
75
|
+
if kind is UUID:
|
|
76
|
+
return str(value), "uuid"
|
|
77
|
+
if kind in (bytes, bytearray, memoryview):
|
|
78
|
+
return base64.b64encode(bytes(value)).decode("ascii"), "base64"
|
|
79
|
+
raise _unsupported_result()
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def execute_validated(
|
|
83
|
+
connection: SqlConnection, query: ValidatedQuery, codec: TokenCodec
|
|
84
|
+
) -> ExecutionResult:
|
|
85
|
+
"""Run a ValidatedQuery: generated SQL and binds only, at most max_rows + 1 rows buffered."""
|
|
86
|
+
if not isinstance(query, ValidatedQuery):
|
|
87
|
+
raise TypeError("the executor accepts only ValidatedQuery")
|
|
88
|
+
if codec.alias != query.alias:
|
|
89
|
+
raise TypeError("the token codec belongs to a different server alias")
|
|
90
|
+
|
|
91
|
+
result = connection.exec_driver_sql(query.sql, query.parameters)
|
|
92
|
+
try:
|
|
93
|
+
if len(result.keys()) != len(query.outputs):
|
|
94
|
+
raise _unsupported_result()
|
|
95
|
+
fetched = result.fetchmany(query.max_rows + 1)
|
|
96
|
+
truncated = len(fetched) > query.max_rows
|
|
97
|
+
encodings: list[ResultEncoding | None] = [None] * len(query.outputs)
|
|
98
|
+
rows: list[tuple[Any, ...]] = []
|
|
99
|
+
for raw in fetched[: query.max_rows]:
|
|
100
|
+
cells: list[Any] = []
|
|
101
|
+
for index, (plan, value) in enumerate(zip(query.outputs, tuple(raw), strict=True)):
|
|
102
|
+
if value is None:
|
|
103
|
+
cells.append(None)
|
|
104
|
+
elif plan.protected:
|
|
105
|
+
cells.append(codec.encrypt(value))
|
|
106
|
+
else:
|
|
107
|
+
encoded, encoding = _encode(value)
|
|
108
|
+
if encodings[index] not in (None, encoding):
|
|
109
|
+
raise _unsupported_result()
|
|
110
|
+
encodings[index] = encoding
|
|
111
|
+
cells.append(encoded)
|
|
112
|
+
rows.append(tuple(cells))
|
|
113
|
+
finally:
|
|
114
|
+
result.close()
|
|
115
|
+
|
|
116
|
+
columns = tuple(
|
|
117
|
+
ResultColumn(
|
|
118
|
+
plan.label,
|
|
119
|
+
plan.source,
|
|
120
|
+
plan.protected,
|
|
121
|
+
"token" if plan.protected else (encodings[index] or "json"),
|
|
122
|
+
)
|
|
123
|
+
for index, plan in enumerate(query.outputs)
|
|
124
|
+
)
|
|
125
|
+
return ExecutionResult(columns, tuple(rows), truncated)
|