SqlAugur

1<!-- mcp-name: io.github.mbentham/sqlaugur -->
2# SqlAugur
3 
4[![NuGet](https://img.shields.io/nuget/v/SqlAugur.svg)](https://www.nuget.org/packages/SqlAugur)
5[![NuGet Downloads](https://img.shields.io/nuget/dt/SqlAugur.svg)](https://www.nuget.org/packages/SqlAugur)
6[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
7![.NET 10.0](https://img.shields.io/badge/.NET-10.0-purple.svg)
8 
9<a href="https://glama.ai/mcp/servers/@mbentham/sql-augur">
10  <img width="380" height="200" src="https://glama.ai/mcp/servers/@mbentham/sql-augur/badge" />
11</a>
12 
13**An MCP server that gives AI assistants safe, read-only access to SQL Server databases. Every query is parsed into a full AST using Microsoft's official T-SQL parser — not regex — so comment injection, string literal tricks, and encoding bypasses are blocked at the syntax level.**
14 
15```
16┌──────────────┐          ┌───────────────────────────────────────────┐        ┌──────────────┐
17│              │  stdio   │  SqlAugur                                 │        │              │
18│  AI Client   │◄────────►│                                           │───────►│  SQL Server  │
19│              │          │  ┌────────────┐  ┌──────────────────────┐ │        │              │
20└──────────────┘          │  │  Query     │  │  Schema / Diagram /  │ │        └──────────────┘
21                          │  │  Validator │  │  DBA Services        │ │
22                          │  └────────────┘  └──────────────────────┘ │
23                          │  ┌────────────────────────────────────┐   │
24                          │  │  Rate Limiter                      │   │
25                          │  └────────────────────────────────────┘   │
26                          └───────────────────────────────────────────┘
27```
28 
29## Quick Start
30 
31Prerequisite: [.NET 10.0 runtime](https://dotnet.microsoft.com/download)
32 
33**1. Install**
34 
35```bash
36dotnet tool install -g SqlAugur
37```
38 
39**2. Configure** — create `~/.config/sqlaugur/appsettings.json` (Linux/macOS) or `%APPDATA%\sqlaugur\appsettings.json` (Windows), setting the connection string for your environment:
40 
41```json
42{
43  "SqlAugur": {
44    "Servers": {
45      "production": {
46        "ConnectionString": "Server=myserver;Database=master;Integrated Security=True;TrustServerCertificate=False;Encrypt=True;"
47      }
48    }
49  }
50}
51```
52 
53**3. Connect** — add to your MCP client:
54 
55<details open>
56<summary><strong>Claude Desktop</strong></summary>
57 
58Add to your [Claude Desktop config](https://modelcontextprotocol.io/quickstart/user) (`claude_desktop_config.json`):
59 
60```json
61{
62  "mcpServers": {
63    "sqlaugur": {
64      "command": "sqlaugur"
65    }
66  }
67}
68```
69 
70</details>
71 
72<details>
73<summary><strong>Claude Code</strong></summary>
74 
75```bash
76claude mcp add --transport stdio sqlaugur -- sqlaugur
77```
78 
79Or add to `.mcp.json` in your project root:
80 
81```json
82{
83  "mcpServers": {
84    "sqlaugur": {
85      "type": "stdio",
86      "command": "sqlaugur"
87    }
88  }
89}
90```
91 
92</details>
93 
94<details>
95<summary><strong>VS Code / Copilot</strong></summary>
96 
97Add to `.vscode/mcp.json` in your workspace:
98 
99```json
100{
101  "servers": {
102    "sqlaugur": {
103      "command": "sqlaugur"
104    }
105  }
106}
107```
108 
109</details>
110 
111**4. Verify** — ask your AI assistant to `list_servers` and you should see your configured connection.
112 
113For Docker, Podman, and other install methods, see [Installation](#installation).
114 
115## Why This Approach
116 
117- **AST-level query validation** — Most MCP database servers use keyword blocking or no validation at all. This project parses every query into a full syntax tree using Microsoft's official `TSql170Parser`. Comment injection, string literal tricks, and encoding bypasses are blocked at the syntax level, not with fragile regex patterns.
118 
119- **Rate limiting** — Token bucket throughput limiting and concurrency control prevent runaway AI query loops from overwhelming production SQL Servers. No other MCP database server offers this.
120 
121- **DBA diagnostic tooling** — Integrated support for First Responder Kit, DarlingData, and sp_WhoIsActive with parameter blocking that prevents write operations. This is an entirely new MCP capability category.
122 
123- **Progressive discovery** — Up to 29 tools organized into toolsets that load on demand. Only 6 core tools are exposed initially, keeping the AI's context window small and reducing token usage. Additional toolsets are discovered and enabled as needed.
124 
125## Features
126 
127**Security**
128- Read-only by design — only SELECT and CTE queries are permitted
129- AST-based query validation using [ScriptDom](https://www.nuget.org/packages/Microsoft.SqlServer.TransactSql.ScriptDom) (not regex)
130- Parameter blocking on all diagnostic stored procedures to prevent writes
131- Concurrency and throughput rate limiting
132 
133**Database Tooling**
134- Multi-server support — named connections to multiple SQL Server instances
135- Schema overview — concise Markdown schema maps with PKs, FKs, constraints, and defaults
136- Table documentation — Markdown descriptions of columns, indexes, foreign keys, and constraints
137- ER diagram generation — PlantUML and Mermaid diagrams with smart cardinality detection
138- Schema exploration — list programmable objects, view definitions, extended properties, dependency graphs
139- Query plan analysis — estimated or actual XML execution plans
140- DBA diagnostics — optional integration with [First Responder Kit](https://github.com/BrentOzarULTD/SQL-Server-First-Responder-Kit), [DarlingData](https://github.com/erikdarlingdata/DarlingData), and [sp_WhoIsActive](https://github.com/amachanic/sp_whoisactive/)
141- Progressive discovery — dynamic toolset mode reduces initial context window usage by exposing tools on demand
142 
143## Installation
144 
145All methods produce the same MCP server.
146 
147### NuGet Global Tool (recommended)
148 
149Prerequisite: [.NET 10.0 runtime](https://dotnet.microsoft.com/download)
150 
151```bash
152dotnet tool install -g SqlAugur
153```
154 
155Create your configuration file:
156 
157```bash
158# Linux/macOS
159mkdir -p ~/.config/sqlaugur
160# Edit ~/.config/sqlaugur/appsettings.json with your server connections
161 
162# Windows (PowerShell)
163mkdir "$env:APPDATA\sqlaugur" -Force
164# Edit %APPDATA%\sqlaugur\appsettings.json with your server connections
165```
166 
167MCP client configuration:
168 
169```json
170{
171  "mcpServers": {
172    "sqlserver": {
173      "command": "sqlaugur"
174    }
175  }
176}
177```
178 
179To update: `dotnet tool update -g SqlAugur`
180 
181### Docker / Podman
182 
183```bash
184# Volume-mount a config file
185docker run -i --rm \
186  -v /path/to/appsettings.json:/app/appsettings.json:ro,Z \
187  ghcr.io/mbentham/sqlaugur:latest
188 
189# Or use environment variables (no config file needed)
190docker run -i --rm \
191  -e SqlAugur__Servers__production__ConnectionString="Server=host.docker.internal;Database=master;..." \
192  ghcr.io/mbentham/sqlaugur:latest
193```
194 
195> **Note:** To reach a SQL Server on the host machine, use `host.docker.internal` (Docker Desktop) or `--network=host` (Linux). Replace `docker` with `podman` — all commands are identical. The `:Z` flag on volume mounts is required for SELinux-enabled systems (Fedora, RHEL); Docker Desktop users on macOS/Windows can omit it.
196 
197MCP client configuration:
198 
199```json
200{
201  "mcpServers": {
202    "sqlserver": {
203      "command": "docker",
204      "args": ["run", "-i", "--rm",
205        "-v", "/path/to/appsettings.json:/app/appsettings.json:ro,Z",
206        "ghcr.io/mbentham/sqlaugur:latest"]
207    }
208  }
209}
210```
211 
212<details>
213<summary>Docker Compose</summary>
214 
215```yaml
216services:
217  sqlaugur:
218    image: ghcr.io/mbentham/sqlaugur:latest
219    stdin_open: true
220    volumes:
221      - ./appsettings.json:/app/appsettings.json:ro,Z
222```
223 
224MCP client configuration:
225 
226```json
227{
228  "mcpServers": {
229    "sqlserver": {
230      "command": "docker",
231      "args": ["compose", "run", "-i", "--rm", "sqlaugur"]
232    }
233  }
234}
235```
236 
237</details>
238 
239 
240### Build from Source
241 
242Prerequisite: [.NET 10.0 SDK](https://dotnet.microsoft.com/download)
243 
244```bash
245git clone git@github.com:mbentham/SqlAugur.git
246cd SqlAugur
247dotnet publish SqlAugur -c Release -o SqlAugur/publish
248cp SqlAugur/appsettings.example.json SqlAugur/publish/appsettings.json
249# Edit SqlAugur/publish/appsettings.json with your server connections
250```
251 
252MCP client configuration:
253 
254```json
255{
256  "mcpServers": {
257    "sqlserver": {
258      "command": "dotnet",
259      "args": ["/absolute/path/to/SqlAugur/publish/SqlAugur.dll"]
260    }
261  }
262}
263```
264 
265## Configuration
266 
267The server loads configuration from multiple sources. Higher-priority sources override lower ones:
268 
2691. **Command-line arguments**
2702. **Environment variables** — using `__` as section delimiter (e.g., `SqlAugur__Servers__production__ConnectionString=...`)
2713. **Current working directory** — `appsettings.json` in the directory you run the command from
2724. **User config directory** — `~/.config/sqlaugur/appsettings.json` on Linux, `%APPDATA%\sqlaugur\appsettings.json` on Windows
2735. **Azure Key Vault** — when `AzureKeyVaultUri` is set (see below)
2746. **App directory** — `appsettings.json` next to the DLL
275 
276**Example configuration (Windows Authentication — recommended):**
277 
278```json
279{
280  "SqlAugur": {
281    "Servers": {
282      "production": {
283        "ConnectionString": "Server=myserver;Database=master;Integrated Security=True;TrustServerCertificate=False;Encrypt=True;"
284      }
285    },
286    "MaxRows": 1000,
287    "CommandTimeoutSeconds": 30,
288    "MaxConcurrentQueries": 5,
289    "MaxQueriesPerMinute": 60,
290    "EnableFirstResponderKit": false,
291    "EnableDarlingData": false,
292    "EnableWhoIsActive": false,
293    "EnableDynamicToolsets": false
294  }
295}
296```
297 
298| Option | Default | Description |
299|--------|---------|-------------|
300| `Servers` | — | Named SQL Server connections (name → connection string) |
301| `MaxRows` | 1000 | Maximum rows returned per query |
302| `CommandTimeoutSeconds` | 30 | SQL command timeout for all queries and procedures |
303| `MaxConcurrentQueries` | 5 | Maximum number of SQL queries that can execute concurrently |
304| `MaxQueriesPerMinute` | 60 | Maximum queries allowed per minute (token bucket rate limit) |
305| `EnableFirstResponderKit` | false | Enable First Responder Kit diagnostic tools (sp_Blitz, sp_BlitzFirst, sp_BlitzCache, sp_BlitzIndex, sp_BlitzWho, sp_BlitzLock) |
306| `EnableDarlingData` | false | Enable DarlingData diagnostic tools (sp_PressureDetector, sp_QuickieStore, sp_HealthParser, sp_LogHunter, sp_HumanEventsBlockViewer, sp_IndexCleanup, sp_QueryReproBuilder) |
307| `EnableWhoIsActive` | false | Enable sp_WhoIsActive session monitoring |
308| `EnableDynamicToolsets` | false | Enable progressive tool discovery — DBA tools load on demand via 3 meta-tools instead of at startup. Reduces initial context window usage. The `Enable*` flags still control which toolsets are allowed. |
309| `AzureKeyVaultUri` | — | Azure Key Vault URI (e.g., `https://myvault.vault.azure.net/`). When set, secrets from the vault are added as a configuration source using [`DefaultAzureCredential`](https://learn.microsoft.com/en-us/dotnet/api/azure.identity.defaultazurecredential). Key Vault secret names use `--` as a section separator (e.g., a secret named `SqlAugur--Servers--prod--ConnectionString` maps to `SqlAugur:Servers:prod:ConnectionString`). |
310 
311> **Security Note:** `appsettings.json` is gitignored to prevent accidental credential commits. See [SECURITY.md](SECURITY.md) for recommended authentication methods including Windows Authentication, Azure Managed Identity, and secure credential storage options.
312 
313## Tools
314 
315The server provides 29 tools organized into toolsets. Six core tools are always available. Additional toolsets are loaded at startup (static mode) or on demand (dynamic mode).
316 
317### Core Tools
318 
319| Tool | Description |
320|------|-------------|
321| `list_servers` | Lists available SQL Server instances configured in `appsettings.json`. |
322| `list_databases` | Lists all databases on a named server with names, IDs, states, and creation dates. |
323| `read_data` | Executes a read-only SQL SELECT query. Only `SELECT` and `WITH` (CTE) queries are allowed. Results returned as JSON with a configurable row limit. |
324| `get_query_plan` | Returns the estimated or actual XML execution plan for a SELECT query. |
325| `get_schema_overview` | Concise Markdown schema overview: tables, columns, PKs, FKs, unique/check constraints, defaults. Supports `compact` mode, schema and table filtering. |
326| `describe_table` | Comprehensive table metadata in Markdown: columns, data types, nullability, defaults, identity, computed expressions, indexes, FKs, constraints. |
327 
328<details open>
329<summary><strong>Schema Exploration</strong> (4 tools)</summary>
330 
331| Tool | Description |
332|------|-------------|
333| `list_programmable_objects` | Lists views, stored procedures, functions, and triggers. Filterable by type and schema. |
334| `get_object_definition` | Returns the source definition (CREATE statement) of a programmable object. |
335| `get_extended_properties` | Reads extended properties (descriptions, metadata) on tables, columns, and other objects. |
336| `get_object_dependencies` | Shows what an object references and what references it — upstream and downstream dependency graphs. |
337 
338</details>
339 
340<details open>
341<summary><strong>Diagrams</strong> (2 tools)</summary>
342 
343| Tool | Description |
344|------|-------------|
345| `get_plantuml_diagram` | Generates a PlantUML ER diagram with tables, columns, PKs, and FK relationships. Saves to a `.puml` file. Supports `compact` mode, schema/table filtering, and a configurable table limit (max 200). |
346| `get_mermaid_diagram` | Generates a Mermaid ER diagram with tables, columns, PKs, and FK relationships. Saves to a `.mmd` file. Supports `compact` mode, schema/table filtering, and a configurable table limit (max 200). |
347 
348</details>
349 
350### DBA Diagnostic Tools
351 
352Each toolkit is enabled independently via config flags and requires the corresponding stored procedures installed on the target SQL Server.
353 
354<details>
355<summary><strong>First Responder Kit</strong> (6 tools) — requires <code>EnableFirstResponderKit: true</code></summary>
356 
357Install from: [github.com/BrentOzarULTD/SQL-Server-First-Responder-Kit](https://github.com/BrentOzarULTD/SQL-Server-First-Responder-Kit)
358 
359| Tool | Description |
360|------|-------------|
361| `sp_blitz` | Overall SQL Server health check — prioritized findings for performance, configuration, and security. |
362| `sp_blitz_first` | Real-time performance diagnostics — samples DMVs over an interval for waits, file latency, and perfmon counters. |
363| `sp_blitz_cache` | Plan cache analysis — top queries by CPU, reads, duration, executions, or memory grants. |
364| `sp_blitz_index` | Index analysis — missing, unused, and duplicate indexes with usage patterns. |
365| `sp_blitz_who` | Active query monitor — what's running, blocking info, tempdb usage, query plans. |
366| `sp_blitz_lock` | Deadlock analysis from the `system_health` extended event session. |
367 
368</details>
369 
370<details>
371<summary><strong>DarlingData</strong> (7 tools) — requires <code>EnableDarlingData: true</code></summary>
372 
373Install from: [github.com/erikdarling/DarlingData](https://github.com/erikdarling/DarlingData)
374 
375| Tool | Description |
376|------|-------------|
377| `sp_pressure_detector` | Diagnoses CPU and memory pressure — resource bottlenecks, high-CPU queries, memory grants, disk latency. |
378| `sp_quickie_store` | Query Store analysis — top resource-consuming queries, plan regressions, wait statistics. |
379| `sp_health_parser` | Parses the `system_health` extended event session for historical waits, disk latency, CPU, memory, and locking. |
380| `sp_log_hunter` | Searches SQL Server error logs for errors, warnings, and custom messages. |
381| `sp_human_events_block_viewer` | Analyzes blocking events from `sp_HumanEvents` sessions — blocking chains, lock details, waits. |
382| `sp_index_cleanup` | Finds unused and duplicate indexes that are candidates for removal. |
383| `sp_query_repro_builder` | Generates reproduction scripts for Query Store queries with parameter values. |
384 
385</details>
386 
387<details>
388<summary><strong>sp_WhoIsActive</strong> (1 tool) — requires <code>EnableWhoIsActive: true</code></summary>
389 
390Install from: [whoisactive.com](http://whoisactive.com/)
391 
392| Tool | Description |
393|------|-------------|
394| `sp_whoisactive` | Monitors active sessions and queries — wait info, blocking details, tempdb usage, resource consumption. |
395 
396</details>
397 
398### Progressive Discovery
399 
400When `EnableDynamicToolsets` is true, only core tools load at startup. Three meta-tools let the AI discover and enable additional toolsets on demand, reducing initial context window usage:
401 
402| Tool | Description |
403|------|-------------|
404| `list_toolsets` | Lists available toolsets with status (available, enabled, not configured) and tool counts. |
405| `get_toolset_tools` | Returns detailed tool and parameter info for a specific toolset before enabling it. |
406| `enable_toolset` | Enables a toolset, making its tools available. Only works if the admin has enabled the toolset via the corresponding `Enable*` config flag. |
407 
408**Example flow:**
4091. AI calls `list_toolsets` — sees `first_responder_kit` is "available" (configured but not yet enabled)
4102. AI calls `get_toolset_tools("first_responder_kit")` — reviews the 6 tools and their parameters
4113. AI calls `enable_toolset("first_responder_kit")` — the 6 tools are now registered and usable
4124. AI calls `sp_blitz` — runs the health check as normal
413 
414In static mode (`EnableDynamicToolsets: false`), all enabled toolsets load at startup and the discovery tools are not registered. Schema Exploration and Diagrams toolsets are always loaded regardless of mode.
415 
416> **Known limitation:** Progressive discovery relies on the MCP `notifications/tools/list_changed` notification to inform clients that new tools have been registered. Claude Code does not currently handle this notification ([anthropics/claude-code#4118](https://github.com/anthropics/claude-code/issues/4118)), so dynamically enabled toolsets will not appear. Use static mode (`EnableDynamicToolsets: false`) when using Claude Code.
417 
418## Security
419 
420### Query Validation
421 
422Every query is parsed into an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) (AST) using Microsoft's official `TSql170Parser` and must pass these rules:
423 
424- **Single statement only** — multiple statements are rejected
425- **SELECT only** — INSERT, UPDATE, DELETE, DROP, EXEC, CREATE, ALTER, and all other statement types are blocked
426- **No SELECT INTO** — prevents table creation via SELECT
427- **No external data access** — OPENROWSET, OPENQUERY, OPENDATASOURCE, OPENXML blocked
428- **No linked servers** — four-part name references are rejected
429- **No MAXRECURSION hint** — prevents overriding the default recursion limit
430- **Cross-database queries are allowed** — three-part names work by design; the security boundary is the server, not the database. To restrict to a single database, limit the login's permissions.
431 
432Because validation operates on the parsed AST, it correctly handles edge cases that defeat string-based approaches: keywords inside comments, string literals, nested block comments, and encoding tricks.
433 
434### Parameter Blocking
435 
436Diagnostic stored procedures execute via whitelisted procedure names with blocked parameters that prevent writes:
437 
438- **First Responder Kit** — all `@Output*` parameters blocked (prevents writing results to server tables)
439- **DarlingData** — logging and output parameters blocked (prevents table creation and data retention)
440- **sp_WhoIsActive** — `@destination_table`, `@return_schema`, `@schema`, `@help` blocked
441 
442### Rate Limiting
443 
444All tool executions are subject to concurrency limiting (`MaxConcurrentQueries`, default 5) and throughput limiting (`MaxQueriesPerMinute`, default 60). Excess requests are rejected with a retry message.
445 
446### Connection Security
447 
448Use Windows Authentication or Azure Managed Identity where possible to avoid storing credentials in config files. When SQL Authentication is required, use environment variable overrides to inject credentials at runtime. See [SECURITY.md](SECURITY.md) for detailed guidance including credential stores and connection string encryption.
449 
450### Known Risks
451 
452- This project depends on the official Microsoft [MCP C# SDK](https://github.com/modelcontextprotocol/csharp-sdk) (`ModelContextProtocol` NuGet package) which is currently a prerelease version. Prerelease packages may contain undiscovered security vulnerabilities and receive breaking changes. As the MCP framework handles all protocol I/O, any vulnerability in it directly affects this application's security boundary. Monitor the package for stable releases and upgrade when available.
453- The data returned from a SQL Server query could include malicious prompt injection targeting AIs. This is a risk of all AI use and cannot be mitigated by this project. Ensure you're following best practices for AI security and only connecting to trusted data sources.
454 
455## Contributing
456 
457Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for architecture details, development setup, testing instructions, and guidelines for adding new tools.
458 
459## License
460 
461[MIT](LICENSE)
462