Skip to main content
Glama
johannschiffer

MigrateSafe MCP

by johannschiffer
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

MigrateSafe MCP (Lite Edition)

License: MIT Protocol: MCP Python: >=3.10

MigrateSafe MCP is a zero-downtime database migration inspection and verification Model Context Protocol server for AI coding assistants (Claude Desktop, Cursor, LangGraph, CrewAI).

It analyzes DDL migration scripts before execution, flagging table-locking statements, destructive drops, and backward-incompatible schema changes that would otherwise cause production downtime or data loss.

🎯 The Problem

When autonomous AI agents write database migrations:

  1. Production Table Lockups: A naive ALTER TABLE ... ADD COLUMN ... NOT NULL or unindexed column change acquires an AccessExclusiveLock, blocking all reads and writes and taking down user-facing services.

  2. Silent Breaking Changes: Dropping or renaming columns without an Expand/Contract migration pattern breaks active application pods during rolling deployments.

  3. Write-Blocking Index Builds: Running CREATE INDEX instead of CREATE INDEX CONCURRENTLY blocks INSERT and UPDATE traffic on critical transactional tables.

MigrateSafe catches these issues automatically inside your AI workflow before migration scripts ever reach production.

Related MCP server: MCP Migration Advisor

✨ Features (Lite Edition)

  • 🔒 Lock Contention Detection: Identifies statements that acquire AccessExclusiveLock or ShareLock.

  • ⚠️ Destructive Statement Detection: Flags DROP TABLE, DROP COLUMN, RENAME COLUMN, and incompatible column type rewrites.

  • ⏱️ Lock Duration & Risk Estimator: Estimates exclusive lock durations based on table row volume.

  • 🛠️ Full MCP Stdio Protocol: Native integration with Claude Desktop, Cursor, and agent frameworks.

🚀 Quickstart

1. Installation

git clone https://github.com/johannschiffer/migratesafe-mcp.git
cd migratesafe-mcp
pip install -e .

2. Configure in Claude Desktop or Cursor

Add to your claude_desktop_config.json or Cursor MCP configuration:

{
  "mcpServers": {
    "migratesafe": {
      "command": "migratesafe",
      "args": ["run"]
    }
  }
}

3. CLI Inspection

# Analyze migration safety via CLI
migratesafe analyze path/to/migration.sql --dialect postgres

🛠️ MCP Tools Reference

Tool

Parameters

Description

analyze_migration_safety

sql, dialect

Inspects migration for table locks and destructive patterns

detect_table_locks

sql, dialect

Maps lock levels (AccessExclusiveLock, etc.) per SQL statement

generate_dry_run_plan

sql, sample_row_count

Estimates exclusive lock time and production outage risk

inspect_schema_diff

before_sql, after_sql

Identifies breaking changes between DDL schemas

🚀 Upgrade to MigrateSafe Pro

Need production-grade rolling upgrade validation and automated safe refactoring?

The MigrateSafe Pro Edition adds:

  • 🔄 Zero-Downtime Pattern Generator: Automatically transforms dangerous DDL into safe 3-phase Expand/Contract migrations.

  • ⚡ Live Shadow Traffic Simulation Harness: Runs concurrent read/write transactions against a clone database while executing the migration to benchmark lock contention and latency spikes.

  • ⏪ Automated Rollback Verifier: Proves that down.sql completely restores original schema with 0 data loss.

  • 🐳 Production Docker & Compose: Ready-to-deploy CI/CD sidecar.

  • 🧪 100% Passing Pytest Suite.

👉 Get MigrateSafe Pro on Gumroad ($14.99 USD)

📄 License

MIT © 2026 Johann Schiffer

Available Tools

4 tools
analyze_migration_safetyB

Analyze a SQL migration script for table locks, destructive drops, and breaking changes.

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYesRaw SQL migration text to inspect.
dialectNoSQL dialect ('postgres', 'mysql', 'sqlite'). Default: 'postgres'.

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It discloses the risk categories checked, but does not clarify whether the tool only statically inspects SQL or executes anything, what permissions are required, or what the analysis result contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is a single front-loaded sentence with no wasted words. The action and the three risk categories are immediately clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The schema fully covers the two parameters, but there is no output schema and no annotations. The description is adequate on purpose but does not describe the analysis result or behavioral constraints, leaving some gaps for an agent invoking the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the 'sql' and 'dialect' parameters including the default dialect. The description adds no additional meaning beyond what the schema provides, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Analyze a SQL migration script') and names three concrete risk categories it inspects. It is clear on what the tool does, but it does not differentiate itself from siblings such as detect_table_locks, which overlaps with one of its stated checks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit guidance on when to use this tool versus alternatives like detect_table_locks or inspect_schema_diff. Usage is only implied by the purpose statement, with no exclusions or decision criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

detect_table_locksC

Map out lock levels (AccessExclusiveLock, ShareLock) acquired per statement in migration.

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYesRaw SQL migration text to inspect.
dialectNoTarget SQL dialect (default: 'postgres').

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It says nothing about whether the SQL is executed or only parsed, whether the operation is read-only, or what happens with unsupported dialects. For an analysis tool operating on raw SQL, the execution/safety profile is a meaningful omission.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with the core concept (lock levels per statement) front-loaded and zero filler. It is efficient, though it errs toward terseness given the absence of annotations and output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotations, the description should explain the return shape and execution semantics. It does convey the essential idea (lock levels mapped per statement), which is the minimum viable for this analysis tool, but leaves the response format and read-only behavior unspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for both parameters (sql, dialect), so the schema already documents them fully. The description adds no syntax, format, or dialect-handling detail beyond what the schema provides, which matches the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Map out') and resource ('lock levels ... acquired per statement in migration'), naming concrete examples (AccessExclusiveLock, ShareLock) that make the scope unambiguous. It is clearly distinguishable from siblings like inspect_schema_diff or generate_dry_run_plan, though it never names them explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use statement, no prerequisite, and no mention of the three sibling tools. The 'in migration' phrasing implies a migration-analysis context, but the agent gets no guidance on when to pick this over analyze_migration_safety.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_dry_run_planC

Estimate lock duration and production outage risk based on table row count.

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYesRaw SQL migration script.
sample_row_countNoEstimated target table row count (default: 100,000).

TDQS

C2.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. 'Estimate' and the tool's dry-run framing imply a non-destructive read, and it usefully signals that output concerns outage risk, but it never explicitly states that no migration is applied, nor does it describe limits, cost, or return format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with no filler and a front-loaded statement of what is computed. It is, however, arguably too terse for a tool whose name implies a richer 'plan' output.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool with full schema coverage the input side is complete, but there is no output schema and the description never explains what the 'plan' or risk estimate looks like. An agent knows what it computes but not what it receives back.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both 'sql' and 'sample_row_count' are already documented. The description reinforces that row count drives the estimate, which usefully connects sample_row_count to the result, but adds no format or default detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific computation – estimating lock duration and production outage risk – but diverges from the tool name, which promises a 'dry run plan.' An agent sees no mention of what the plan actually contains, leaving the link between the name and the described output unclear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance and no comparison to the siblings analyze_migration_safety, detect_table_locks, or inspect_schema_diff. The agent must infer that this is a pre-execution estimation step rather than an analysis of an already-running migration.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

inspect_schema_diffB

Compare before and after SQL DDL schemas to identify breaking changes.

ParametersJSON Schema
NameRequiredDescriptionDefault
after_sqlYesProposed schema definition.
before_sqlYesPrevious schema definition.

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and it does imply the operation is a read-only comparison that reports breaking changes. However, it says nothing about the shape of the result, whether the change set is classified by severity, or any prerequisites, so it is only partially transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no wasted words; the purpose and output are both delivered immediately. It is efficient, though arguably terse given the absence of annotations and output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-string-parameter tool this covers the core action, but with no annotations and no output schema an agent still lacks any sense of what the diff returns and how it differs from the migration-safety sibling. Adequate but with clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters are documented in the schema, so the baseline is 3. The description confirms the before/after ordering concept but adds no format or syntax detail beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description pairs a specific verb (compare) with a specific resource (before/after SQL DDL schemas) and states the outcome (identify breaking changes). It is clear on its own, but it never acknowledges the adjacent siblings such as analyze_migration_safety or generate_dry_run_plan, so an agent must infer the boundary itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use or when-not-to-use statement and no alternative tool is named. The phrase 'to identify breaking changes' hints at intent but gives no condition that would route an agent here rather than to analyze_migration_safety.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.0
    • First observedanalyze_migration_safety
    • First observeddetect_table_locks
    • First observedgenerate_dry_run_plan
    • First observedinspect_schema_diff
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

B3.4/5.0

Scored across 4 tools

Disambiguation4/5

Each tool has a distinct focus: safety analysis, lock detection, dry-run risk estimation, and schema diffing. analyze_migration_safety is somewhat umbrella-like and overlaps conceptually with the other three, but the descriptions still make tool boundaries understandable.

Naming Consistency5/5

All four tools follow a consistent snake_case verb_noun pattern: analyze_migration_safety, detect_table_locks, generate_dry_run_plan, inspect_schema_diff. No mixed conventions or vague names.

Tool Count5/5

Four tools is well-scoped for a focused SQL migration safety server. Each tool maps to a clear, non-redundant capability within that domain.

Completeness4/5

The surface covers core migration-safety workflows: broad analysis, lock mapping, outage-risk estimation, and schema diffing. Minor gaps exist around rollback planning or safe-rewrite suggestions, but agents can work around them.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Alma Atlas

    velum-labs
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to query live schema, lineage, and query-context across data warehouses, dbt projects, orchestration systems, and BI tools via MCP tools.
    Apache 2.0

  • pg-context

    mewsyy
    A
    license
    A
    quality
    B
    maintenance
    MCP server providing deep PostgreSQL context to AI assistants, including schema DDL, index health, foreign key associations, query execution plans, and performance statistics via read-only tools.
    12
    1
    MIT

  • pg-mcp

    rakesh-ridecell
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI assistants to safely explore PostgreSQL schemas, inspect sample rows, draft queries, and read EXPLAIN plans through a read-only enforced interface for MCP clients.
    MIT