# mcp-migration-tools

> A small, **public-safe** [FastMCP](https://github.com/jlowin/fastmcp) server that
> exposes practical **legacy-to-modern migration** helpers as AI-callable tools —
> the same "thin tool wrapper over tested, pure logic" pattern I use on a larger
> production MCP server, distilled into a clean, fully generic example.

<p>
  <a href="../../actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/badge/CI-GitHub_Actions-2088FF?logo=githubactions&logoColor=white"></a>
  <img alt="Python" src="https://img.shields.io/badge/Python-3.11_%7C_3.12-3776AB?logo=python&logoColor=white">
  <img alt="FastMCP" src="https://img.shields.io/badge/FastMCP-server-6c63ff">
  <img alt="Tests" src="https://img.shields.io/badge/tests-17_passing-0ea5a4">
  <img alt="License" src="https://img.shields.io/badge/License-MIT-c9a44c">
</p>

---

## Why this exists

Modernizing 100+ legacy apps means doing the same analysis over and over:
*what stack is this? what endpoints does it expose? how do I port this DDL? how
big is the job?* These are perfect **MCP tools** — small, deterministic, and
callable by an AI agent (or a human) on demand.

## The tools

| Tool | What it does |
| --- | --- |
| **`detect_stack`** | Infers the dominant tech stack from a file listing (weights manifests over single files) |
| **`extract_api_contract`** | Pulls `{method, path}` REST endpoints from Spring controller source |
| **`sql_to_flyway`** | Converts SQL Server DDL into a portable Flyway migration (identity cols, `MONEY`, `NVARCHAR`, `GETDATE()`, brackets, `GO`, `dbo.`) |
| **`estimate_migration_effort`** | Transparent person-day estimate from coarse inventory counts, with a risk band |

## Design: pure logic + thin MCP layer

```
tools/*.py         ← pure, dependency-free functions (100% unit-tested)
   ▲
server.py          ← FastMCP wrappers: @mcp.tool() delegating to the pure logic
```

Keeping the logic free of the MCP runtime means every tool is **fast to test**
and **reusable** outside MCP — the tests don't even import `fastmcp`.

## Quick start

```bash
# install
pip install .[dev]

# run the tests (17 passing)
pytest -q

# run the MCP server (stdio transport)
mcp-migration-tools
```

## Use the tools directly (no MCP needed)

```python
from mcp_migration_tools.tools import detect_stack, sql_to_flyway

detect_stack(["ProductList.asp", "web.config"])
# {'stack': 'aspnet', 'confidence': 0.75, ...}

sql_to_flyway("CREATE TABLE [dbo].[Product]([Id] INT IDENTITY(1,1))", version=1,
              description="create product")
# {'filename': 'V1__create_product.sql', 'body': 'CREATE TABLE Product(Id INT GENERATED BY DEFAULT AS IDENTITY)\n'}
```

## Register with an MCP client

Example client config (e.g. for an MCP-capable IDE/agent):

```json
{
  "mcpServers": {
    "migration-tools": {
      "command": "mcp-migration-tools"
    }
  }
}
```

## Project structure

```
mcp-migration-tools/
├── src/mcp_migration_tools/
│   ├── server.py                 # FastMCP server (tool registration)
│   └── tools/                    # pure, tested logic
│       ├── stack_detector.py
│       ├── api_extractor.py
│       ├── sql_translator.py
│       └── effort_estimator.py
├── tests/                        # pytest suite (one file per tool)
├── .github/workflows/ci.yml      # test on Python 3.11 & 3.12
└── pyproject.toml
```

---

<sub>Part of my modernization portfolio · <a href="https://simeptk.github.io">simeptk.github.io</a> · companion to <a href="https://github.com/simeptk/legacy-to-modern-demo">legacy-to-modern-demo</a></sub>