legacy2mcp

legacy2mcp

---

メモ

legacy2mcp はレガシーシステムを調査します。WSDL 内のすべての操作、またはデータベースのライブスキーマを調査し、調査したスキーマから各ツールの実際の JSON Schema を構築して、MCP ツールとして公開します。SOAP エンドポイントまたはデータベースに到達する前に、すべての呼び出しがスキーマ検証され、書き込みに類する操作や書き込み操作はデフォルトで除外され、すべての呼び出しが監査ログに記録されます。アダプターコードを手書きする必要も、スキーマを手動で保守する必要もなく、LLM から任意の SQL が実行されることもありません。

目次

• インストール
• クイックスタート
• 仕組み
• アダプターを手書きするだけではだめなのですか？
• 独自の WSDL を指定する
• 独自のデータベースを指定する
• 独自の REST API を指定する
• 設定を自動生成する
• Claude Desktop から使用する
• 対応内容
• 安全性モデル
• ユースケース
• 実際の使用例
• 設定リファレンス
• ロードマップ
• 開発 · コントリビューション · ライセンス

インストール

# 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

MCP Registry にも io.github.bvenkata/legacy2mcp として公開されているため、レジストリに対応した MCP クライアントから直接検出できます。

クイックスタート

API キーもクローンも不要です。公開デモ API を使って始められます。

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

次に、AI クライアントに接続します。詳しくは Claude Desktop から使用するをご覧ください。

独自の WSDL、REST API、またはコードベースをお使いですか？ legacy2mcp init（フラグなし）を実行すると、手順に沿って設定できます。詳しくは 設定を自動生成するをご覧ください。その他のデモ（ローカル SOAP サービス、Docker、URL を直接指定して配信される WSDL）は examples/ に掲載されています。

仕組み

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. 成熟した広く使われている Python SOAP クライアントである zeep で WSDL を読み込みます。
2. すべてのポート／バインディングの各操作について、XSD 入力型を JSON Schema（schema/xsd_to_jsonschema.py）に変換します。単純型、ネストされた複合型、列挙型、配列を再帰的に変換し、問題のある WSDL に対しては深さを制限します。
3. 操作ごとに MCP ツールを登録します。ツール名は <adapter_id>_<OperationName> です。
4. ツール呼び出し時には、jsonschema で引数を検証し（スキーマでは additionalProperties: false を使用）、zeep 経由で操作を呼び出し、レスポンスをプレーンな JSON にシリアライズして、監査ログに記録します。

DB：

1. 各テーブルに対して、方言のドライバー（psycopg／pyodbc／oracledb。遅延インポートされます）で接続し、稼働中のカラム型をイントロスペクションして（adapters/db_dialects.py）、JSON Schema（schema/sql_to_jsonschema.py）に変換します。
2. 許可リストにあるテーブルと操作ごとに select_<table>／insert_<table> を登録し、設定内の名前付きクエリごとに query_<name> を登録します。
3. ツール呼び出し時には、許可リストにあるテーブル／カラムから SQL を組み立てるか（または設定で指定された名前付きクエリを実行し）、方言に依存しない :param プレースホルダー規約を使用して引数を検証し、実行して監査ログに記録します。LLM が SQL テキストを見ることも、書き込むこともありません。
4. 書き込み操作に見える名前の操作は、allow_write_operations: true が設定されていない限り除外されます。

アダプターを手作業で書かない理由

手書きのアダプターは、誰も更新を忘れずに行ってくれない、システムのスキーマの二つ目のコピーになるからです。WSDL 操作のシグネチャが変わったり、カラムが変更されたりすると、ツールの JSON Schema は実態からひそかにずれていきます。その結果、LLM が不正な引数を送っても何も検出されなかったり、SOAP／DB クライアントの奥深くで分かりにくい実行時エラーが発生したりします。legacy2mcp は起動するたびに稼働中のシステムからスキーマを構築するため、ずれた呼び出しはバックエンドに到達する前に検証で失敗します。

	手書きのアダプター（FastMCP／raw SDK）	汎用 OpenAPI-to-MCP プロキシ	legacy2mcp
スキーマの情報源	ツールごとに手作業で記述	OpenAPI 仕様が存在する場合はその仕様	稼働中の WSDL／DB スキーマ、または検出された OpenAPI 仕様
実際のシステムとのずれ	あり — 再確認する仕組みはありません	仕様自体が古い場合に限ります	なし — 起動時に稼働中の情報源から再構築します
SOAP／データベースへの対応	クライアントコードを自分で記述します	なし — REST／OpenAPI のみ	あり。REST にも対応します
書き込み操作をデフォルトで非表示	なし — 個別に制御する必要があります	なし — 通常、仕様で定義されたすべてを公開します	あり — allow_write_operations の明示的なオプトインが必要です
すべての呼び出しの監査ログ	自分で実装	通常はありません	組み込み
サーバーを稼働させるまでの時間	システムごとに数時間から数日	仕様がある REST API なら数分	数分 — legacy2mcp init

独自の 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)

本番環境を想定したコメント付きテンプレートは、examples/soap/config.template.yaml にあります。

独自のデータベースを指定する

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

SOAP 操作のスキーマが WSDL から取得されるのと同じ方法で、起動時に稼働中のスキーマからカラムをイントロスペクションするため、手作業で保守する必要はありません。LLM から任意の SQL を実行する経路は一切ありません。呼び出せるのは、tables: に指定されたテーブルに対する select_<table>／insert_<table>、または queries: に記述した SQL を実行する query_<name> ツールだけです。LLM が渡せるのは、クエリの params で宣言されたプレースホルダーの値のみで、SQL テキストは渡せません。本番環境を想定したテンプレートは、examples/db/config.template.yaml にあります。

独自の REST API を指定する

通常の REST/JSON API には、イントロスペクションできる WSDL や稼働中のデータベーススキーマがないため、rest アダプターのエンドポイント一覧は明示的な設定が必要です。手動で記述するか、次のセクションで説明する legacy2mcp init を使ってひな形を生成してください。

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

本番環境に近いテンプレートは examples/rest/config.template.yaml にあります。

メモ

GET 以外のメソッドを使うことも、LLM を使った分類も、ヒューリスティックであり、エンドポイントを監視なしで安全に呼び出せる保証にはなりません。実際のバックエンドに対して実行する前に、write: フラグと allow_write_operations を確認してください。これは、後述する SOAP アダプターの書き込み動詞に基づくヒューリスティックと同じ注意点です。

設定を自動生成する

legacy2mcp init は接続先を尋ね、開始用の config.yaml を生成します。

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]:

オプション	動作	LLM キーが必要か
WSDL URL	soap アダプターを直接指定します。zeep は inspect／run の実行時に稼働中の WSDL をイントロスペクションするため、事前のスキャンは不要です。	いいえ
REST API URL	その URL に対して一般的な OpenAPI／Swagger の仕様の場所（/openapi.json、/swagger.json など）を試し、仕様が見つかれば実際の仕様から rest アダプターのエンドポイント一覧を作成します。見つからない場合は空のひな形を作成します。	いいえ
GitHub リポジトリ／ローカルパス	リポジトリをクローン（または読み込み）し、Python ソースを静的にスキャンします（AST のみを使用し、実行はしません）。zeep.Client(...) 呼び出し、SQLAlchemy／Flask-SQLAlchemy モデル、または Flask／FastAPI ルートを探し、soap／db／rest のいずれかを選びます。	任意

それぞれのオプションは、--wsdl-url、--rest-url、--github-url、--local-path フラグを使って非対話形式でも実行でき、スクリプトや CI に利用できます。LLM を使用できるのは GitHub／ソースコードのパスだけで、静的解析で既に見つかった内容（曖昧なパラメーター型や読み取り／書き込みの分類など）の精査に限られます。リポジトリの内容を丸ごと送信することはありません。追加の依存関係は不要です。--llm-api-key-env で OpenAI 互換の API キーを指定するか、省略した場合は対話形式の非表示プロンプトで入力してください（ディスクには保存されません）。--scan-only を渡すと LLM の使用を完全にスキップして静的解析のみを実行します。キーを入力しない場合と同じです。

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

どの方法を選んでも、実行前に生成されたファイルを確認してください。確信を持って推定できなかった項目（未解決の base_url、未検証のパラメーター型、write: true と分類されたエンドポイントなど）には # TODO コメントが付いています。また、実際のバックエンドに対して確認するまでは、ファイル内の内容は一切検証されていません。

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

実際の対象に接続する前に、このヒューリスティックが保証することと保証しないことの詳細については、docs/security.md を参照してください。

Claude Desktop（または任意の MCP クライアント）から使用する

各クライアントは、stdio 経由で uvx legacy2mcp run --config <absolute path> を起動します。pip または pipx でインストールした場合は、uvx legacy2mcp の代わりに legacy2mcp を使用してください。

このリポジトリには、プロジェクト単位で使うクライアント向けに、動作確認済みの設定ファイルも含まれています。.mcp.json（Claude Code および互換クライアント）、.cursor/mcp.json、.vscode/mcp.json は、いずれも同梱の Petstore REST デモを指定しています。そのため、これらのツールのいずれかでこのリポジトリを開けば、設定なしで動作する legacy2mcp サーバーを利用できます。使用するツールに合った設定を自分のプロジェクトにコピーし、--config に独自の config.yaml を指定してください。

Claude Desktop（claude_desktop_config.json）

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

Claude Code

claude mcp add legacy2mcp -- uvx legacy2mcp run --config /absolute/path/to/config.yaml

Cursor（.cursor/mcp.json）

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

VS Code、シークレットの受け渡し、トラブルシューティングについては、docs/clients.md を参照してください。

対応範囲

領域	対応内容
型のマッピング	string / int / long / decimal / boolean / date / dateTime / base64Binary / … → JSON Schema の型とフォーマット
構造	入れ子の複合型、繰り返し要素 → 配列、xsd:enumeration → enum、再帰の深さを制限
検出	すべてのサービス → ポート → バインディング → オペレーション。重複するツール名は起動時に拒否
呼び出し	引数の検証、zeep の呼び出し、レスポンスをプレーンな JSON にシリアライズ、単一フィールドのレスポンスを名前付きの結果に再ラップ
エラー	SOAP フォルトとトランスポートエラーを捕捉し、クリーンなメッセージとして返します。呼び出し元にスタックトレースは返しません
認証	HTTP ベーシック（ユーザー名 + *_env パスワード）、ベアラートークン（*_env）、匿名
トランスポート	stdio（Claude Desktop やほとんどのエージェントフレームワークが起動するトランスポート）
DB の方言	Postgres、SQL Server、Oracle — ライブスキーマのイントロスペクションを使ったテーブルの許可リスト（select / insert）と、名前付きのパラメーター化クエリ
REST	設定または legacy2mcp init による、明示的なエンドポイント許可リスト（メソッド + パス + 型付きパラメーター）。イントロスペクションできるライブスキーマはないため、実行するまではここに記載された内容は検証されません

完全かつ率直なセキュリティモデルについては、docs/security.md をご覧ください。現在対応している内容と、まだ対応していない内容を説明しています。

安全性モデル

レイヤー	内容
スキーマ検証	生成されたスキーマに対して jsonschema.validate を通過しない引数が、SOAP / DB レイヤーに渡ることはありません。
デフォルトで読み取り専用	SOAP：オペレーション名を、書き込みを表す動詞の接頭辞（Create、Update、Delete、Cancel、Void、Submit、Pay、…）と照合します。DB：テーブルとクエリは明示的にオプトインし、insert と書き込みとしてマークされたクエリにもオプトインが必要です。allow_write_operations: true を設定しない限り、どちらも公開されません。
明示的な許可／拒否	SOAP：include_operations / exclude_operations。DB：テーブル／カラムの許可リスト。「全テーブル」や任意の SQL に相当するものはありません。
監査ログ	呼び出しごとに JSON 形式の1行を記録します。ツール、引数、タイムスタンプ、結果、所要時間が含まれます。
シークレットの管理	認証情報と DB 接続文字列は、名前付き環境変数から取得します。YAML は安全にコミットできます。

警告

SOAP の書き込みオペレーションのフィルターは、名前に基づくヒューリスティックであり、意味解析ではありません。データを削除する ProcessRecord という名前のオペレーションは検出されません。誤った呼び出しが実害につながるシステムでは、include_operations を明示的に設定し、このヒューリスティックに頼らないでください。DB アダプターの許可リストは設計上明示的ですが、カラムレベルのデータマスキングはありません。許可リストに含まれるカラムの値は、常にそのまま返されます。また、MCP サーバー自体にはまだ認証／認可がありません。信頼できない呼び出し元にサーバーを公開しないでください。詳しくは docs/security.md をご覧ください。

ユースケース

分野	概要
基幹システム	エージェントが、レガシーなバックオフィスプラットフォームからステータス／詳細レコードを読み取り専用で取得し、すべての検索をログに記録します。
金融サービス	送金や調整を公開せずに、口座や取引の 読み取り を公開します。
サプライチェーン／ERP	古い SOAP ミドルウェア層から、注文ステータス、在庫、配送状況の追跡情報を提供します。
社内サポートツール	サポート用コパイロットが、スクレイピングした UI ではなく、基幹システムに安全かつ型付けされた形でアクセスします。
移行とモダナイゼーション	今すぐレガシーサービスの前段に MCP レイヤーを配置し、後からエージェントに手を加えずにバックエンドを交換します。

実際の利用例

CI/CD で — WSDL の変更が本番環境に届く前に検出する

legacy2mcp inspect は設定を読み込み、WSDL に接続してすべてのスキーマを構築し、問題が発生するとゼロ以外の終了コードを返します。

- 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

サイドカー／長時間稼働する MCP サーバーとして

legacy2mcp run は stdio 経由で MCP を使用します。用意されている Dockerfile を使って設定と一緒にパッケージ化し、MCP クライアントから起動します。

データパイプラインでの利用

同じ生成済み・検証済みのツールを、任意の MCP クライアントライブラリから独自のコードで呼び出して、スケジュールに沿ってレコードを取得できます。監査ログには、取得した内容が正確に記録されます。

設定リファレンス

キー	デフォルト	意味
server.name	legacy2mcp	クライアントに通知される MCP サーバー名
server.transport	stdio	現時点で実装されているのは stdio のみです
adapters[].id	—	このアダプターのツール名に付けるプレフィックス
adapters[].type	—	soap、db、rest（実装済み）、または queue（ロードマップに掲載）

SOAP アダプターの設定：

キー	デフォルト	意味
adapters[].config.wsdl_url	—	WSDL の場所（http(s)://…?wsdl またはファイルパス）
adapters[].config.auth	{type: none}	none または {type: basic, username, password_env}
adapters[].config.allow_write_operations	false	書き込みに類するオペレーションを公開します
adapters[].config.include_operations	all	オペレーション名の許可リスト
adapters[].config.exclude_operations	[]	オペレーション名の拒否リスト
adapters[].config.timeout_seconds	15	SOAP 呼び出しごとのタイムアウト

DB アダプターの設定：

キー	デフォルト	意味
adapters[].config.dialect	—	postgres、mssql、または oracle
adapters[].config.dsn_env	—	接続文字列／DSN を保持する環境変数
adapters[].config.allow_write_operations	false	insert_<table> と write: true のクエリを公開します
adapters[].config.timeout_seconds	15	接続タイムアウト
adapters[].config.tables[].name / .schema	—	許可リストに登録するテーブル（および任意のスキーマ／所有者）
adapters[].config.tables[].operations	[select]	select および／または insert
adapters[].config.tables[].columns	all introspected	カラムの許可リスト
adapters[].config.tables[].filterable_columns	[]	select_<table> で等価フィルターとして使用できるカラム
adapters[].config.tables[].max_rows	200	行数の上限。クエリ実行後に適用されます
adapters[].config.queries[].name / .sql / .params	—	名前付きクエリ。sql では :param_name プレースホルダーを使用します
adapters[].config.queries[].write	false	このクエリを allow_write_operations で制御します

REST アダプターの設定：

キー	デフォルト	意味
adapters[].config.base_url	—	設定済みエンドポイントの相対 URL の基準となるベース URL
adapters[].config.auth	{type: none}	none、{type: basic, username, password_env}、または {type: bearer, token_env}
adapters[].config.allow_write_operations	false	write: true とマークされたエンドポイントを公開します
adapters[].config.timeout_seconds	15	HTTP 呼び出しごとのタイムアウト
adapters[].config.endpoints[].name / .method / .path / .description	—	許可リストに登録するエンドポイント。path ではパスパラメーターに {param} プレースホルダーを使用します
adapters[].config.endpoints[].params[].name / .location / .type / .required	—	location は path、query、または body です
adapters[].config.endpoints[].write	false	このエンドポイントを allow_write_operations で制御します

セキュリティ設定：

キー	デフォルト	意味
security.audit.enabled	true	監査ログを書き込みます
security.audit.path	./legacy2mcp-audit.log	監査ログの保存場所

ロードマップ

バージョン	対象範囲	ステータス
v0.1	SOAP/WSDL アダプター、スキーマ生成、検証、デフォルトで読み取り専用、監査ログ、run + inspect CLI、基本認証、stdio	✅ リリース済み
v0.2	データベースアダプター（Postgres / SQL Server / Oracle。テーブル／操作の許可リストと名前付きパラメーター化クエリ。任意の SQL は一切実行しません）	✅ リリース済み
v0.2.x	REST アダプター（明示的なエンドポイント許可リスト）。legacy2mcp init -- リポジトリをスキャン（SOAP クライアント／ORM モデル／Flask/FastAPI ルート）して初期設定を生成します。曖昧な部分には、任意で OpenAI 互換の LLM による補助を利用できます	✅ リリース済み
v0.2.x	HTTP/SSE トランスポート、ロール→ツールの認可、SOAP 用 OAuth2	予定
v0.3+	キューアダプター（Kafka/RabbitMQ/SQS）、承認ゲートを備えたワークフローの構成、OpenTelemetry エクスポート	アイデア

詳細は docs/roadmap.md をご覧ください。 BaseAdapter インターフェース（discover_tools() + invoke()）が拡張ポイントです。サーバーコアが、どのアダプターに対しても検証、ディスパッチ、監査を処理します。

開発

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

テストは、プロセス内のモック SOAP サービスと、プロセス内で SQLite を使用した DB アダプターの代替実装に対して実行されます。ネットワーク接続や実際の Postgres / SQL Server / Oracle は不要です。DB アダプターの Postgres / SQL Server / Oracle 向け方言（db_dialects.py）の SQL 変換ロジックは、ドライバーを使わない単体テストでカバーされています。各データベースの実インスタンスへの接続は、デフォルトのテストスイートには含まれません。

CI は Python 3.10–3.12 でテストスイートを実行します（ci.yml）。PyPI と MCP Registry へのリリースはタグをトリガーとして行われます。詳しくは docs/releasing.md をご覧ください。デモ GIF は vhs demo/demo.tape で再生成できます（demo/）。

貢献

新しいレガシーシステム向けのアダプターは、最も価値の高い貢献です。BaseAdapter を実装すれば、残りはコアが処理します。Issue と PR を歓迎します。

ライセンス

Apache 2.0