legacy2mcp 0.2.1

Point it at a WSDL or a database. Get an MCP server whose tools can't drift from the underlying schema, can't send unvalidated arguments, and can't call write operations (or run arbitrary SQL) you didn't opt into.

Contents

• Install
• Quick start
• How it works
• Point it at your own WSDL
• Point it at your own database
• Point it at your own REST API
• Generate a config automatically
• Use it from Claude Desktop
• What's handled
• Safety model
• Use cases
• Real-world usage
• Configuration reference
• Roadmap
• Development · Contributing · License

Install

# Full install (recommended)
pip install "legacy2mcp[ai]"

# Or the identical, scan-only-ready core -- AI-assisted `legacy2mcp init`
# needs no extra package either way, just an API key at runtime; `[ai]`
# above installs nothing extra today, it's just a stable, familiar name
pip install legacy2mcp
# or:  uv tool install legacy2mcp   ·   pipx install legacy2mcp

Also published to the MCP Registry as io.github.bvenkata/legacy2mcp, so registry-aware MCP clients can discover it directly.

Quick start

No API key, no cloning, no local setup — point legacy2mcp init at a real, public REST API (it tries OpenAPI/Swagger discovery against it) and generate a working config in one command:

legacy2mcp init --rest-url "https://petstore3.swagger.io/api/v3" --out config.yaml
legacy2mcp inspect --config config.yaml   # see the generated MCP tools

Or run it with no flags for the interactive menu (WSDL URL / REST API URL / GitHub repo) — see Generate a config automatically for what each option does and when it needs an API key (hint: none of them need one unless you're pointing it at a GitHub repo and want AI-assisted help with ambiguous code):

legacy2mcp init

git clone https://github.com/bvenkata/legacy2mcp.git
cd legacy2mcp
pip install -e ".[dev]"

# 1. start the demo SOAP service (dneonline-style Calculator WSDL)
python examples/soap/run_mock_calculator.py &

# 2. see the MCP tools generated from its WSDL
legacy2mcp inspect --config examples/soap/config.calculator.yaml

docker compose up demo-soap-service -d
docker compose run --rm legacy2mcp legacy2mcp inspect \
  --config examples/soap/config.calculator.docker.yaml

How it works

flowchart LR
  WSDL["WSDL / XSD"] --> GEN["legacy2mcp<br/>schema generation"]
  DB["DB schema<br/>(allowlisted tables)"] --> GEN
  GEN --> TOOLS["Typed MCP tools<br/>one per operation / table / query"]
  AGENT["AI agent /<br/>MCP client"] -->|tool call| VAL{"schema<br/>validation"}
  TOOLS -. defines .-> VAL
  VAL -->|invalid args| REJ["rejected, never<br/>reaches SOAP/DB"]
  VAL -->|valid and allowed| BACKEND["SOAP endpoint<br/>or database"]
  BACKEND --> RESP["plain JSON<br/>back to the agent"]
  VAL --> LOG[("audit log")]

SOAP:

1. Loads the WSDL with zeep, a mature, widely-used Python SOAP client.
2. For every operation on every port/binding, converts the XSD input type into a JSON Schema (schema/xsd_to_jsonschema.py) — simple types, nested complex types, enums and arrays, recursively, depth-limited for pathological WSDLs.
3. Registers one MCP tool per operation, named <adapter_id>_<OperationName>.
4. On a tool call: validates arguments with jsonschema (schemas use additionalProperties: false), calls the operation via zeep, serializes the response to plain JSON, and writes an audit entry.

DB:

1. Connects with the dialect's driver (psycopg / pyodbc / oracledb, imported lazily) and introspects the live column types for each allowlisted table (adapters/db_dialects.py) into JSON Schema (schema/sql_to_jsonschema.py).
2. Registers select_<table> / insert_<table> per allowlisted table-and-operation, plus query_<name> per named query in config.
3. On a tool call: validates arguments, builds SQL from the allowlisted table/columns (or runs the config-supplied named query) using one dialect-neutral :param placeholder convention, executes it, and writes an audit entry. The LLM never sees or writes SQL text.
4. Operations whose names look like writes are excluded unless allow_write_operations: true.

Point it at your own WSDL

# config.yaml
server:
  name: my-legacy-mcp

adapters:
  - id: legacy
    type: soap
    config:
      wsdl_url: "https://service.example.com/LegacyService?wsdl"
      auth:
        type: basic
        username: "svc-account"
        password_env: "SERVICE_PASSWORD"   # value read from the environment, never the file
      allow_write_operations: false        # Create*/Update*/Delete*/… stay hidden
      include_operations: ["GetRecord", "GetRecordDetails", "SearchRecords"]

security:
  audit:
    enabled: true
    path: "./legacy-mcp-audit.log"

export SERVICE_PASSWORD=...
legacy2mcp inspect --config config.yaml   # review the generated tools
legacy2mcp run     --config config.yaml   # start the MCP server (stdio)

A production-shaped template with comments lives at examples/soap/config.template.yaml.

Point it at your own database

pip install "legacy2mcp[db-postgres]"   # or db-mssql / db-oracle

# config.yaml
adapters:
  - id: orders
    type: db
    config:
      dialect: postgres             # postgres | mssql | oracle
      dsn_env: "ORDERS_DB_DSN"      # connection string, read from the environment
      allow_write_operations: false # insert_<table> / write: true queries stay hidden
      tables:
        - name: orders
          operations: [select]
          columns: [id, status, total, created_at]   # column allowlist
          filterable_columns: [status]                # equality filters on select_orders
          max_rows: 200
      queries:
        - name: orders_by_status_since
          sql: "SELECT id, status, total FROM orders WHERE status = :status AND created_at >= :since"
          params:
            - { name: status, type: string, required: true }
            - { name: since, type: string, required: true }

export ORDERS_DB_DSN=...
legacy2mcp inspect --config config.yaml   # review the generated tools

Columns are introspected from the live schema at startup, the same way SOAP operation schemas come from the WSDL -- there's nothing to hand-maintain. There is no path from the LLM to arbitrary SQL, ever: it can only call select_<table> / insert_<table> for tables listed under tables:, or a query_<name> tool whose SQL you wrote under queries: -- the LLM supplies only the placeholder values a query's params declare, never SQL text. A production-shaped template lives at examples/db/config.template.yaml.

Point it at your own REST API

There's no WSDL or live database schema to introspect a plain REST/JSON API from, so the rest adapter's endpoint list is explicit config -- write it by hand, or generate a starting point with legacy2mcp init (next section).

# config.yaml
adapters:
  - id: orders
    type: rest
    config:
      base_url: "https://api.example.com"
      auth:
        type: bearer
        token_env: "ORDERS_API_TOKEN"
      allow_write_operations: false
      endpoints:
        - name: get_order
          method: GET
          path: "/orders/{order_id}"
          params:
            - { name: order_id, location: path, type: integer, required: true }
        - name: create_order
          method: POST
          path: "/orders"
          write: true   # stays hidden unless allow_write_operations: true
          params:
            - { name: total, location: body, type: number, required: true }

A production-shaped template lives at examples/rest/config.template.yaml.

Generate a config automatically

legacy2mcp init asks what to point it at, then writes a starting config.yaml for you:

legacy2mcp init

What do you want to point legacy2mcp at?
  1) WSDL URL (SOAP service)
  2) REST API URL (tries OpenAPI/Swagger discovery)
  3) GitHub repo URL or a local path to its source code
Choice [1-3]:

Each also works non-interactively via a flag -- --wsdl-url, --rest-url, --github-url, or --local-path -- for scripting or CI. Only the GitHub/ source-code path can use an LLM, and only to refine what static analysis already found (ambiguous parameter types, read-vs-write classification) -- never a dump of your repo. It needs no extra dependency, just an OpenAI-compatible API key via --llm-api-key-env, or an interactive hidden prompt if you omit that (never written to disk); pass --scan-only to skip it outright and run static-analysis-only, same as not entering a key.

legacy2mcp init --github-url https://github.com/you/your-api --scan-only --out config.yaml

Whichever path you take, review the generated file before running it -- it's marked up with # TODO comments for anything that couldn't be confidently inferred (an unresolved base_url, an unverified param type, which endpoints got classified write: true), and nothing in it is verified against the real backend until you do:

legacy2mcp inspect --config config.yaml   # review the generated tools
legacy2mcp run     --config config.yaml   # start the MCP server

See docs/security.md for exactly what this heuristic does and doesn't guarantee before pointing it at anything real.

Use it from Claude Desktop (or any MCP client)

{
  "mcpServers": {
    "legacy": {
      "command": "legacy2mcp",
      "args": ["run", "--config", "/absolute/path/to/config.yaml"]
    }
  }
}

What's handled

See docs/security.md for the full, honest security model — what's covered today and what isn't yet.

Safety model

Use cases

Real-world usage

In CI/CD — catch WSDL drift before it reaches production

legacy2mcp inspect loads the config, contacts the WSDL, builds every schema, and exits non-zero if anything fails:

- name: Check the WSDL still generates valid MCP tools
  env:
    SERVICE_PASSWORD: ${{ secrets.SERVICE_PASSWORD }}
  run: |
    pip install legacy2mcp
    legacy2mcp inspect --config config/legacy.yaml > tools.json
    git diff --exit-code --no-index tools/legacy.snapshot.json tools.json  # optional: pin the contract

As a sidecar / long-running MCP server

legacy2mcp run speaks MCP over stdio. Package it with your config using the provided Dockerfile and let your MCP client launch it.

In a data pipeline

Call the same generated, validated tools from your own code via any MCP client library to pull records on a schedule — the audit log records exactly what was fetched.

Configuration reference

SOAP adapter config:

DB adapter config:

REST adapter config:

Security config:

Roadmap

Full detail in docs/roadmap.md. The BaseAdapter interface (discover_tools() + invoke()) is the extension point — the server core handles validation, dispatch and audit for any adapter.

Development

pip install -e ".[dev]"
pytest tests/ -v

Tests run against an in-process mock SOAP service and an in-process SQLite-backed stand-in for the DB adapter — no network, no real Postgres/SQL Server/Oracle required. The DB adapter's Postgres/SQL Server/Oracle dialects (db_dialects.py) have their SQL-translation logic covered by driver-free unit tests; connecting to a real instance of each is not part of the default suite.

CI runs the suite on Python 3.10–3.12 (ci.yml). Releases to PyPI and the MCP Registry are tag-triggered — see docs/releasing.md. The demo GIF is regenerated with vhs demo/demo.tape (demo/).

Contributing

Adapters for new legacy systems are the highest-value contribution — implement BaseAdapter and the core handles the rest. Issues and PRs welcome.

License

Apache 2.0