# MigrateSafe MCP (Lite Edition)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Protocol: MCP](https://img.shields.io/badge/MCP-2024--11--05-green.svg)](https://modelcontextprotocol.io/)
[![Python: >=3.10](https://img.shields.io/badge/Python->=3.10-yellow.svg)](https://python.org/)

**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.

---

## ✨ 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

```bash
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:

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

### 3. CLI Inspection

```bash
# 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)](https://johanld.gumroad.com/l/zkhrvy)**

---

## 📄 License

MIT © 2026 [Johann Schiffer](https://github.com/johannschiffer)