MCP DB Wizard

MCPDBWizard

選択したオブジェクトから構築する、Oracle 用 MCP サーバーです。 コンソールで PL/SQL パッケージ、 テーブル、シーケンス、テスト済みの独自 SQL ステートメントにチェックを付けると、選択したものだけを 型付きツールとして AI エージェントに公開する Model Context Protocol サーバー を生成します。 各ツールには、プロシージャの実際のシグネチャから導出された JSON Schema が付与されます。

run-sql ツールはありません。 選択しなかったものには、ツールもメソッドもクラスもありません。 実行時に拒否されるのではなく、バイナリに含まれません。また、実行時にクエリを組み立てることもありません。 生成されるコードは、固定の SQL ステートメントと型付きバインドを使う通常の Java であり、MCP サーバーは モデルに実行させる SQL を書くのではなく、それらのラッパーを呼び出します。

このサーバーを生成するには呼び出しレイヤー全体も生成するため、型付き DAO ファクトリー、呼び出し可能な ステートメントのラッパー、テーブルマネージャー、オプションの SOAP レイヤーも利用できます。単独でも便利ですが、 主役は MCP サーバーです。

12c から 26ai までの Oracle に対応し、対象範囲にわたる稼働中の 6 つのインスタンスで リグレッションテスト済みです。

製品全体の構成です。このリポジトリに含まれるのは ジェネレーター、つまり設定ファイル、 生成とコンパイル、生成される MCP サーバーです。Design ページ、Runtime ページ、プロキシは、 Docker イメージのウェブコンソールに含まれています。 このリポジトリでは、代わりに Swing ツールまたは設定ファイルでオブジェクトを選択でき、生成されたサーバーは 単独で実行できます。

---

難しい部分

一般的な方法は、エージェントに run-sql ツールを渡すことです。スキーマが実際のものになるまでは機能しますが、 エンタープライズ規模のスキーマでは、公開されているテキストから SQL を生成する精度は、整然としたベンチマークと 比べて大幅に低下します。誤った UPDATE は誤答ではなく、インシデントです。

もう一つの方法は、厳選したツールを用意することです。しかし、プロシージャごとに手作業でツールを書く方法は、 数個を超えると拡張できません。また、PL/SQL はツールの自動導出がとりわけ困難です。

• プロシージャには、単一の戻り値ではなく、任意の数の OUT および IN OUT パラメーターを指定できます。
• パラメーターには、レコード（レコード内にネストされたレコードを含む）、コレクション、 %ROWTYPE、REF CURSOR、パッケージ型、オーバーロードがあります。
• Oracle のデータディクショナリは、バージョンによってこれらを異なる方法で記述します。

このプロジェクトは、こうした導出を行います。生成される各 MCP ツールには、プロシージャの実際のシグネチャから 構築された JSON Schema が付与されるため、エージェントはパラメーターを文章から推測するのではなく、 その内容を明示的に知ることができます。

oracle:  PROCEDURE order_summary(p_customer IN  NUMBER,
                                 p_totals   OUT summary_rec,
                                 p_lines    OUT SYS_REFCURSOR)

tool:    order_summary { "p_customer": <number> }
      -> { "p_totals": { "orderCount": 12, "value": 4210.55 },
           "p_lines":  [ { "sku": "AB-1", "qty": 3 }, ... ] }

レコードは JSON オブジェクトとして、REF CURSOR は行オブジェクトの配列として、DATE は ISO‑8601 文字列として、 RAW とバイナリベクトルは base64 として、CLOB はテキストとして、BLOB は base64 として受け渡されます。

---

クイックスタート

Java 21 と Maven が必要です。Oracle JDBC ドライバー（com.oracle.database.jdbc:ojdbc11） は Maven Central から取得されるため、手動でインストールする必要はありません。

mvn clean package

これにより、target/ に 2 つの JAR が生成されます。通常の JAR と、ドライバーをバンドルした自己完結型の mcpdbwizard-app-<version>-shaded.jar です。

# Interactive (Swing) -- pick objects and options, save a config
java -jar target/mcpdbwizard-app-*-shaded.jar <log_dir> myconfig.pb2

# Batch -- regenerate from a saved config
java -jar target/mcpdbwizard-app-*-shaded.jar <log_dir> build myconfig.pb2

<log_dir> が存在しない場合は作成されます。

2026-08 に変更： 以前は先頭に <access_code> 引数がありましたが、削除されました。現在もこの引数を渡すコマンドラインは、その値をログディレクトリとして解釈します。 この引数は形式のみ検証されていました（19 文字以上、パスではない、リテラルの build ではない）が、その後は無視されていたため、認証には何も使われていませんでした。これを指定しているスクリプトから削除してください。

設定ファイルには .pb2（フラットなプロパティファイル）または .json を使用できます。どちらも受け付けられ、相互に損失なく変換できます。

java -cp target/mcpdbwizard-app-*-shaded.jar \
     com.mcpdbwizard.schema.ConfigConverter myconfig.pb2 myconfig.json

---

生成されるもの

DAO ファクトリー	設定ごとに 1 つのエントリーポイントを生成し、接続とロギングを設定します
PL/SQL ラッパー	プロシージャ／関数ごとにクラスを生成します — setParamX、executeProc、getParamY
テーブルマネージャー	主キーによる行の CRUD に加え、一意キー、インデックス、外部キーの子行の検索を行います
SQL ステートメントクラス	型付きバインドパラメーターを使用する独自の SQL です
SOAP サービスレイヤー	オプション
JSON / JSON-RPC コネクター	オプション
MCP サーバー	オプション（MCP SDK には Java 17 以降が必要です）

生成されたコードは、このリポジトリ内のランタイムライブラリである com.mcpdbwizard.pub のみに依存します。

MCP サーバー

生成される <Factory>McpServer.java は、デフォルトでは stdio で通信し、http [port] を指定して起動すると Streamable HTTP で通信します。オプションのベアラートークン認証と TLS は、どちらも実行時に環境変数からシークレットを読み込み、設定されていない場合はフェイルクローズします。そのため、生成されたソースにシークレットが埋め込まれることはありません。

PL/SQL ルーチン、テーブル行の CRUD と副次検索、ユーザー SQL ステートメント、シーケンス、さらに 23ai ではドキュメント CRUD と ETag による楽観的ロックを備えた JSON リレーショナルデュアリティビューを公開します。

公開対象は実行時ではなく、生成時に決まります。 選択しなかったオブジェクトのコードは一切生成されません。また、TABLE_MCP_CRUD_<i> を使うと、テーブルの操作を作成／読み取り／更新／削除の任意のサブセットに限定できます。公開対象外の操作についてはツールメソッドが出力されません。バイナリから欠落しており、単に登録解除されているだけではありません。

---

Oracle データ型のサポート

一般的なスカラー型と LOB に加えて、12c の ID 列と拡張 VARCHAR2／RAW、21c のネイティブ JSON、23ai のネイティブ BOOLEAN、VECTOR（密、バイナリ、スパース）、JSON リレーショナルデュアリティビューに対応しています。

既知の制限：TIMESTAMP WITH [LOCAL] TIME ZONE と BFILE はプロシージャパラメーターとして受け渡せますが、テーブル列としてはまだサポートされていません。SDO_GEOMETRY には JSON マッピングがないため、これを使用するルーチンはスキップされます。FLOAT16 ベクトルはサーバー側でブロックされます。

---

ロギング

生成されたファクトリーは、設定から LogInterface の実装を選択します。コンソール、テキストファイル、java.util.logging、Log4j 1.x、SLF4J、または Log4j 2 を使用できます。SLF4J と Log4j 2 のバックエンドは com.mcpdbwizard.pub にあり、ファサード JAR のみに依存します。これはオプションの依存関係です。使用する場合は、API とバインディングを自身で用意してください。

---

テスト

データベース不要のテストスイートは追加設定なしで実行でき、新規クローンでもすべて成功します。

mvn test

Oracle が必要なテストはゲート付きです。接続可能なデータベースがない場合は、失敗せずにスキップします。 独自のインスタンスを指定するには、テンプレートをコピーしてください。実際のファイルは Git で無視され、マシンの外に出ることはありません。

cp src/test/resources/test-boxes.properties.template src/test/resources/test-boxes.properties
cp Scripts/tns/tnsnames.ora.template                 Scripts/tns/tnsnames.ora
cp Scripts/boxes.env.template                        Scripts/boxes.env

設定ごとに、環境変数（MCPDBWIZARD_TEST_HOST など）がファイルの設定より常に優先されます。これにより、実行時に使用するサーバーを選択できます。

第 3 の層はジェネレーターの出力にリンクします。Scripts/testrun_current.sh は一連の設定からコードを再生成してコンパイルし、続いて一連のハーネスが、そのコードを実稼働データベースに対して実行します。

**この層はこのリポジトリには含まれておらず、必要となるスキーマも含まれていません。**設定は、構造を公開できない Oracle スキーマをイントロスペクトします。その一部は何年も前の顧客向け作業に由来するものであり、設定は参照先のスキーマを列挙するため、設定も同梱できません。ハーネスも同様です。これらのスキーマのテーブルやルーチンを指定しており、ここには存在し得ない再生成済みツリーに対してのみコンパイルできます。

そのために必要となるものはありません。ジェネレーターの実行にも、テストスイートの実行にも、追加のものは必要ありません。データベース不要のテストはすべて揃っており、新規クローンでもすべて成功します。ゲート付きの実稼働テストはスキップされます。用意された、再生成に使えるコーパスはありません。Scripts/check_provisioning.sh は残されており、設定が必要とするオブジェクトを正確に示します。独自の環境を構築する場合は、ここから始めてください。

examples/generated-output/ には、データベースを一切使わずにジェネレーターが出力する内容が示されています。

---

リポジトリの構成

パス	内容
src/main/java/com/mcpdbwizard/pub	生成コードがリンクするランタイムライブラリ
src/main/java/com/mcpdbwizard/app	ジェネレーター — エンジン、Swing UI、共通ヘルパー
src/main/java/com/mcpdbwizard/schema	設定の型付きモデル。.pb2 ↔ .json
src/main/java/com/mcpdbwizard/mcpdbwizardconnector	JSON / JSON‑RPC コネクターのジェネレーター
examples/generated-output	ジェネレーター出力のチェックイン済みサンプル。2026‑08‑07 に再生成
Scripts/	再生成、プロビジョニングのチェック、エクスポートのゲート
API ドキュメント	リンク先となるライブラリ com.mcpdbwizard.pub の生成済み Javadoc

アーキテクチャ、規約、蓄積された注意点などのコントリビューター向けメモは、 CLAUDE.md にあります。

---

API ドキュメント

com.mcpdbwizard.pub の API ドキュメント

これは生成コードがリンクするランタイムライブラリであり、ドキュメント化されている唯一のパッケージです。ジェネレーター自体の内部は実装の詳細であり、公開すると、呼び出す側に必要な部分が埋もれてしまうためです。パッケージの概要では、何を使えばよいかが説明されており、互換性の契約も示されています。ここに記載されたシグネチャは、このジェネレーターが生成したすべてのプログラムにとって不可欠なため、メソッドの追加は行われますが、シグネチャは変更されません。

同じページはプロジェクトサイトの mcpdbwizard.com/javadoc にもあります。どちらも一方からコピーするのではなく、公開時にソースから再生成されます。

ローカルでは、mvn javadoc:javadoc を実行すると target/reports/apidocs/ に出力されます。failOnWarnings を有効にして実行されるため、壊れた @link がある場合は、リンク切れの相互参照を公開するのではなく、ビルドが失敗します。

---

既知の問題

既知の問題 — 何が問題なのか、問題が発生したときに呼び出し元に実際に何が見えるのか、それぞれの回避策をまとめています。ほとんどの問題は、自ら知らせてくれません。JSON のキーが列名ではなく生成されたフィールド名になっているレコード、密配列しか受け付けない VECTOR ルーチンパラメーター、ツールの数が Oracle の open_cursors の上限を超える設定などがあります。

ここに掲載されている未解決の項目はすべて、このリポジトリ内の issue でもあり、ページからリンクされています。 新しい issue を登録する前にお読みください。該当する問題が発生している場合は、新しい issue を作成するのではなく、その issue にコメントしてください。項目のうち 3 つは、要望がなかったため修正されず、ドキュメントに記載されています。コメントひとつで、「これを必要とした人は一度もいない」から「必要としている人がいる」に変わります。

---

コントリビューション

CONTRIBUTING.md をご覧ください。プルリクエストを作成する前に実行するコマンドは次のとおりです。

Scripts/export/check-export-clean.sh

プライベートなホスト名、認証情報、または jar がツリーに紛れ込んでいると、失敗します。

ライセンス

Apache License 2.0 — LICENSE と NOTICE をご覧ください。

このジェネレーターが 出力する コードはお客様自身の著作物であり、このプロジェクトによるライセンス上の義務はありません。実行時には、このリポジトリに含まれ、同じく Apache‑2.0 でライセンスされている com.mcpdbwizard.pub にリンクするため、生成したアプリケーションはお好きな条件で配布できます。