Back to Browse

Sprocguard MCP Server

Developer ToolsLow Risk8.0MCP RegistryLocal
Free

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

8.0
Low Risk8.0Low Risk

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.

file_system

Check that this permission is expected for this type of plugin.

What You'll Need

Set these up before or after installing:

Path to sprocguard.toml (defaults to ./sprocguard.toml in the working directory)Optional

Environment variable: SPROCGUARD_CONFIG

ODBC connection string; overrides the connection in sprocguard.tomlRequired

Environment variable: SPROCGUARD_ODBC

SQL login password, only when the config uses user/password_envRequired

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 GitHub

From the project's GitHub README.

sprocguard

PyPI CI Integration GitHub Marketplace License: MIT Python 3.11+

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.

Leer en español

$ 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

WhereHowFor
Terminalpip install sprocguard (CLI)Checking a change on your machine
AI agentsMCP server and Claude Code plugin (MCP)Letting an agent verify its own SQL edits
Pull requestsGitHub Action, also on the GitHub MarketplaceBlocking 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:

ProtectionHow
Nothing is ever committedEach 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 databasesIt refuses to connect to any database not listed in allowed_databases.
No irreversible side effectsProcedures 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 dumpedTables above max_rows_per_table are not snapshotted (reported as skipped).
SQL injectionParameter 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.

ToolWhat it doesRead-only
inspect_procedureParameters, tables read/written, procedures and triggers involved, risksyes
suggest_casesReal parameter values from related tables plus edge valuesyes
capture_baselineRecords the current behavior (refuses to overwrite unless asked)writes a file
verify_procedureRe-runs the cases and lists every differenceyes
generate_tsqlt_testsTurns a baseline into tSQLt testswrites a file
list_baselinesLists captured baselinesyes

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:

  1. 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.
  2. 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.
  3. 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; point config at a separate file such as sprocguard.ci.toml if you prefer. The [safety] rules still apply.

Inputs and outputs

InputDefaultWhat it does
modecommittedcommitted or base-branch (see above)
casesCases files or folders, one per line (base-branch)
base-refthe pull request's base branchBranch, tag or commit to capture from (base-branch)
base-setup-scriptssetup-scriptsScripts that build the database on the base branch (base-branch)
fail-on-changetrueSet to false to only report changes in the job summary
configsprocguard.tomlConfiguration file in your repository
setup-scriptsScripts that build the database, one per line; globs allowed
proceduresevery baselineProcedures to verify, separated by spaces or new lines
databasefirst of allowed_databasesDatabase to create and verify
verifytrueSet to false to only prepare the server for your own sprocguard steps
start-sql-servertrueSet to false to reuse the server started by an earlier step
sql-server-imagemcr.microsoft.com/mssql/server:2022-latestSQL 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 FakeTable for 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!