Server data from the Official MCP Registry
Safety net for SQL Server stored procedures: capture their behavior and verify changes.
About
Safety net for SQL Server stored procedures: capture their behavior and verify changes.
Security Report
Valid MCP server (1 strong, 1 medium validity signals). 4 known CVEs in dependencies Package registry verified. Imported from the Official MCP Registry.
5 files analyzed · 5 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
What You'll Need
Set these up before or after installing:
Environment variable: SPROCGUARD_CONFIG
Environment variable: SPROCGUARD_ODBC
Environment variable: SPROCGUARD_PASSWORD
How to Install
Add this to your MCP configuration file:
{
"mcpServers": {
"sprocguard": {
"command": "uvx",
"args": [
"sprocguard==0.3.0"
],
"env": {
"SPROCGUARD_ODBC": "your-sprocguard-odbc-here",
"SPROCGUARD_CONFIG": "your-sprocguard-config-here",
"SPROCGUARD_PASSWORD": "your-sprocguard-password-here"
}
}
}
}Some servers take additional arguments. See the repository for details.
Documentation
View on GitHubFrom the project's GitHub README.
sprocguard
A safety net for SQL Server stored procedures. Capture what a procedure does today, let a human or an AI agent change it, and get a clear report of every behavior that changed — before it reaches production.
$ sprocguard verify dbo.usp_PlaceOrder
FAIL dbo.usp_PlaceOrder: 3/5 case(s) behave exactly as in the baseline.
(the procedure definition changed since the baseline was captured)
ok regular customer buys 2 coffees
XX VIP customer gets 10% off
- Result set #1, row 1: Total "33.75" -> "33.80"
- dbo.Orders: no longer inserts {"CustomerId": 1, "Total": "33.75"}
- dbo.Orders: now inserts {"CustomerId": 1, "Total": "33.80"}
XX VIP discount with odd cents
- Result set #1, row 1: Total "78.75" -> "78.80"
- dbo.Orders: no longer inserts {"CustomerId": 1, "Total": "78.75"}
- dbo.Orders: now inserts {"CustomerId": 1, "Total": "78.80"}
ok buys exactly the last units
ok insufficient stock raises error
Three ways to use it
| Where | How | For |
|---|---|---|
| Terminal | pip install sprocguard (CLI) | Checking a change on your machine |
| AI agents | MCP server and Claude Code plugin (MCP) | Letting an agent verify its own SQL edits |
| Pull requests | GitHub Action, also on the GitHub Marketplace | Blocking a merge that changes behavior |
Why
Many companies keep their business rules inside stored procedures, usually without tests. AI coding agents are now asked to "clean up" or "optimize" them, and a refactor that looks equivalent can quietly change a rounding rule, an error path or a table it updates.
sprocguard gives you characterization tests (also called golden master tests) in minutes: it records what the procedure returns and what it changes in the database, then compares any new version against that record.
What it captures
For every case (a set of parameter values):
- every result set, in order when the order is stable;
- the return value and OUTPUT parameters;
- the error raised, if any (errors are behavior too);
- the rows inserted, updated and deleted in each table the procedure writes, including tables written by procedures it calls and by triggers.
Each case runs twice. Values that change by themselves (new IDENTITY values, NEWID(), and any
date or time taken while the procedure was running, even at second or day precision) are detected
automatically and ignored when verifying.
Safety model
sprocguard executes your procedures, so safety comes first:
| Protection | How |
|---|---|
| Nothing is ever committed | Each execution runs inside a transaction that is always rolled back, with IMPLICIT_TRANSACTIONS ON and two nesting levels, so an inner ROLLBACK or a stray COMMIT in the procedure cannot leak changes. |
| Only development databases | It refuses to connect to any database not listed in allowed_databases. |
| No irreversible side effects | Procedures that send e-mail, run xp_cmdshell, start jobs, use OPENROWSET/OPENQUERY or linked servers are refused by default: a rollback cannot undo them. |
| Big tables are not dumped | Tables above max_rows_per_table are not snapshotted (reported as skipped). |
| SQL injection | Parameter values are always sent as query parameters, never concatenated. |
Captures hold locks on the tables involved for a moment: use a development database.
Install
Requires Python 3.11+ and the Microsoft ODBC Driver 17 or 18 for SQL Server
(usually already installed with SQL Server or SSMS). Check which one you have with
Get-OdbcDriver | Where-Object Name -like "*SQL Server*" in PowerShell.
pip install sprocguard
# SQL authentication without ODBC: pip install "sprocguard[pymssql]"
Quick start (5 minutes, with the demo database)
The demo scripts live in the examples folder of the repository:
git clone https://github.com/JheysonJhordyHuarauyaRiquelme/sprocguard.git
cd sprocguard
sqlcmd -S localhost -E -i examples/demo.sql # creates DemoShop with two procedures
sprocguard init # writes sprocguard.toml; edit the connection
sprocguard inspect dbo.usp_PlaceOrder # parameters, tables, risks
sprocguard capture dbo.usp_PlaceOrder --cases examples/cases/usp_PlaceOrder.json
sqlcmd -S localhost -E -i examples/regression.sql # a "harmless" refactor
sprocguard verify dbo.usp_PlaceOrder # catches the rounding change (exit code 2)
sprocguard.toml (use ODBC Driver 17 for SQL Server if that is the one you have):
[connection]
odbc = "Driver={ODBC Driver 18 for SQL Server};Server=localhost;Database=DemoShop;Trusted_Connection=yes;TrustServerCertificate=yes"
[safety]
allowed_databases = ["DemoShop"]
max_rows_per_table = 5000
allow_external_side_effects = false
[storage]
baseline_dir = ".sprocguard/baselines" # commit this folder
tsqlt_dir = ".sprocguard/tsqlt"
Use it with AI agents (MCP)
sprocguard ships an MCP server and an Agent Skill that teaches agents the workflow: inspect → design cases → capture → change → verify.
Claude Code (plugin with the MCP server and the skill):
/plugin marketplace add JheysonJhordyHuarauyaRiquelme/sprocguard
/plugin install sprocguard@sprocguard
Any MCP client (VS Code, Cursor, Claude Desktop...):
{ "mcpServers": { "sprocguard": { "command": "sprocguard", "args": ["serve"] } } }
With uv you can skip the install step: use "command": "uvx", "args": ["sprocguard", "serve"].
sprocguard is also listed in the MCP Registry as
io.github.JheysonJhordyHuarauyaRiquelme/sprocguard.
| Tool | What it does | Read-only |
|---|---|---|
inspect_procedure | Parameters, tables read/written, procedures and triggers involved, risks | yes |
suggest_cases | Real parameter values from related tables plus edge values | yes |
capture_baseline | Records the current behavior (refuses to overwrite unless asked) | writes a file |
verify_procedure | Re-runs the cases and lists every difference | yes |
generate_tsqlt_tests | Turns a baseline into tSQLt tests | writes a file |
list_baselines | Lists captured baselines | yes |
CLI
sprocguard init create sprocguard.toml
sprocguard inspect <proc> [--definition] describe a procedure and its risks
sprocguard suggest <proc> suggest parameter values
sprocguard capture <proc> --cases cases.json capture a baseline [--watch schema.table ...] [--overwrite]
sprocguard capture-cases <folder or files> capture every cases file (usp_X.json -> dbo.usp_X)
[--overwrite] [--skip-missing]
sprocguard verify [<proc> ...] verify one, several or all baselines (exit 2 if behavior changed)
[--markdown-report report.md]
[--only-failures]
sprocguard tsqlt <proc> generate tSQLt tests (read-only procedures)
sprocguard list list baselines
sprocguard serve run the MCP server (stdio)
Add --json for machine-readable output.
Use sprocguard verify --only-failures to keep passing procedures to one PASS line
and show only failing cases with their differences for changed procedures. JSON output
and Markdown reports are unaffected.
Verify on every pull request (GitHub Action)
This repository is also a GitHub Action, listed on the
GitHub Marketplace. It starts a throwaway SQL Server in Docker, builds
your database from the scripts in your repository and runs sprocguard verify. The pull
request fails when a procedure changed behavior, and the job summary lists every difference.
It compares against one of two references:
- The base branch (
mode: base-branch, from v0.3.0): nothing to prepare on your machine. - Baselines committed in the repository (the default,
mode: committed).
Compare with the base branch
The action builds the database with the scripts of the base branch, captures baselines with your cases files, rebuilds the database with the scripts of the pull request and verifies.
name: Stored procedures
on: pull_request
permissions:
contents: read
jobs:
sprocguard:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: JheysonJhordyHuarauyaRiquelme/sprocguard@v0.3.0
with:
mode: base-branch
cases: db/cases
setup-scripts: |
db/schema.sql
db/seed.sql
db/procedures/*.sql
db/cases holds one file per procedure, named after it (usp_PlaceOrder.json is
dbo.usp_PlaceOrder, sales.usp_Refund.json is sales.usp_Refund), in the same format as
sprocguard capture --cases. Procedures that do not exist on the base branch yet are skipped.
If the pull request moves or renames the scripts, set base-setup-scripts to the paths on the
base branch. Your scripts must create the same test data every time, because both sides are
compared on the data they build.
Compare with committed baselines
- uses: actions/checkout@v7
- uses: JheysonJhordyHuarauyaRiquelme/sprocguard@v0.3.0
with:
setup-scripts: |
db/schema.sql
db/seed.sql
db/procedures/*.sql
To set it up:
- Keep scripts that build a development copy of your database (tables, test data and
procedures) in the repository. The action runs them in order with
sqlcmd. - Build that database on your machine from the same scripts and capture the baselines there, so they describe the same data the action will build.
- Commit the baselines (
.sprocguard/baselines) and a sprocguard configuration file. The action replaces its[connection]with the throwaway server, so it does not need your real connection string; pointconfigat a separate file such assprocguard.ci.tomlif you prefer. The[safety]rules still apply.
Inputs and outputs
| Input | Default | What it does |
|---|---|---|
mode | committed | committed or base-branch (see above) |
cases | Cases files or folders, one per line (base-branch) | |
base-ref | the pull request's base branch | Branch, tag or commit to capture from (base-branch) |
base-setup-scripts | setup-scripts | Scripts that build the database on the base branch (base-branch) |
fail-on-change | true | Set to false to only report changes in the job summary |
config | sprocguard.toml | Configuration file in your repository |
setup-scripts | Scripts that build the database, one per line; globs allowed | |
procedures | every baseline | Procedures to verify, separated by spaces or new lines |
database | first of allowed_databases | Database to create and verify |
verify | true | Set to false to only prepare the server for your own sprocguard steps |
start-sql-server | true | Set to false to reuse the server started by an earlier step |
sql-server-image | mcr.microsoft.com/mssql/server:2022-latest | SQL Server image |
Outputs: passed (true or false) and report (path to the Markdown report). The action
needs a Linux runner with Docker, such as ubuntu-latest. It connects with pymssql; if a
baseline captured with ODBC differs only in how a value is formatted, please open an issue.
The integration workflow
of this repository uses the action on the demo database and is a complete example.
To run sprocguard against another server in CI, set environment variables instead of
editing the configuration: SPROCGUARD_ODBC (an ODBC connection string), or
SPROCGUARD_SERVER, SPROCGUARD_PORT, SPROCGUARD_USER, SPROCGUARD_DATABASE and
SPROCGUARD_PASSWORD (a pymssql connection). SPROCGUARD_BASELINE_DIR stores baselines in
another folder without changing [storage].
tSQLt export
For read-only procedures, sprocguard tsqlt <proc> writes a .sql file with one
tSQLt test per case, using tSQLt.AssertEqualsTable and
tSQLt.ExpectException. Volatile columns are left out of the comparison.
Troubleshooting
Common connection problems and how to fix them.
ODBC driver not found
Check which drivers are installed:
Get-OdbcDriver | Where-Object Name -like "*SQL Server*"
If ODBC Driver 17 for SQL Server is the one installed, use it in
sprocguard.toml in place of 18:
odbc = "Driver={ODBC Driver 17 for SQL Server};Server=localhost;Database=DemoShop;Trusted_Connection=yes;TrustServerCertificate=yes"
Login failed (SQL authentication)
Install the pymssql extra and set the password in the environment variable
named by password_env (default SPROCGUARD_PASSWORD):
pip install "sprocguard[pymssql]"
$env:SPROCGUARD_PASSWORD = "..." # PowerShell
# export SPROCGUARD_PASSWORD=... # bash / zsh
In sprocguard.toml, set server, user, and password_env.
"Connected to database '...', which is not in [safety].allowed_databases"
sprocguard refuses to run against any database not listed in
[safety].allowed_databases, on purpose. If it is a development database, add it:
[safety]
allowed_databases = ["DemoShop", "MyOtherDb"]
Certificate errors with ODBC Driver 18
For local development servers, add TrustServerCertificate=yes to the ODBC
connection string:
odbc = "Driver={ODBC Driver 18 for SQL Server};Server=localhost;Database=DemoShop;Trusted_Connection=yes;TrustServerCertificate=yes"
Limitations
- Table-valued parameters are not supported yet.
- Tables changed only through dynamic SQL are not detected automatically; add them with
--watch. - If the procedure fails, result sets returned before the error are not recorded (the error is).
- tSQLt export covers read-only procedures; procedures that modify data use
verify. - Comparisons ignore the order of rows when the order was not stable between the two capture runs.
Roadmap
- tSQLt export with
FakeTablefor procedures that modify data - Table-valued parameters
-
sprocguard impact <table>: verify every procedure that uses a table you are changing - PostgreSQL support
- Publish to PyPI and the MCP Registry
- GitHub Action that verifies procedures on every pull request
- List the GitHub Action on the GitHub Marketplace
- Verify a pull request without committed baselines (
mode: base-branch)
Contributing
Contributions are welcome, in English or Spanish. See CONTRIBUTING.md to set up the project, run the checks and open a pull request, and the changelog for what changed in each version. Security problems: please report them privately as described in SECURITY.md.
The unit tests use an in-memory imitation of SQL Server (tests/fakedb.py), so they run
anywhere. The integration workflow runs the demo in examples/ against a real SQL Server
on every change.
License
MIT
Reviews
No reviews yet
Be the first to review this server!
More Developer Tools MCP Servers
Rea
Freeby Morluto · Developer Tools
Reverse engineer anything from your terminal or agent with one CLI and MCP server.
Paperclip
Freeby Paperclipai · Developer Tools
Trending hip-hop artist momentum scores across four cultural dimensions.
Scrapling
Freeby D4Vinci · Developer Tools
Web scraping with stealth HTTP, real browsers, and Cloudflare bypass. CSS selectors supported.
Git
Freeby Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
MCP Marketplace
Freeby mcp-marketplace · Developer Tools
Search and install MCP servers from inside your AI client.
