MCP SAP GUI Server

MCP SAP GUI

1つの設定済み SAP GUI for Windows セッション向けの MCP ツールです。この修正版では Python MCP SDK 2.1.1 を使用し、公開済みの 2026-07-28 プロトコル（server/discover）と、stdio 経由のレガシーな初期化の両方に対応します。従来の7つのツール名は引き続き利用でき、COM 制御ツールとオプションの GuiXT InputScripts により、画像認識に代わる方法も使えます。

インストールとセッションの選択

ライセンス済みの SAP GUI、設定済みの SAP Logon 接続、管理者によってインストールおよび有効化された SAP GUI Scripting を備えた、対話型の Windows デスクトップで Python 3.11–3.13 を使用してください。実装は、公開されている SAP GUI 8.00/8.10 のスクリプトインターフェースを対象としています。CI では Python と Windows バインディングを確認しますが、実際の SAP 8.00/8.10 システムは CI でテストされていません。お使いの環境については、SAP の最新のプラットフォーム／パッチ対応表を確認してください。SAP GUI for Java や、ヘッドレスの SAP デスクトップには対応していません。

python -m pip install .
Copy-Item .env.example .env
# Edit .env to select the intended session.
python -m sap_gui_server.server

開発を再現可能にするには、uv sync --frozen --python 3.13、uv run pytest、uv build を使用してください。build.bat はローカルソースからビルドし、setup.bat はパスワードを尋ねたり表示したりせずにテンプレートを作成します。Node はオプションで、run.bat debug（MCP Inspector）を実行する場合にのみ必要です。

SSO を含め、既存の認証済みセッションを使う場合、パスワードは不要です。

SAP_SESSION_ID=/app/con[0]/ses[0]
# Optional assertion, checked against the authenticated SAP user:
SAP_USER=YOUR_SAP_USER

自動化用に確保したセッションの正確な ID を指定してください。SAP GUI のスクリプトレコーダーに、接続とセッションのインデックスが表示されます。このサーバーは、任意のアクティブなウィンドウや既存の最初のセッションを選ぶことはありません。代わりに新しい接続を開くには、SAP_SESSION_ID を省略し、SAP_CONNECTION に SAP Logon の正確な説明を設定してください。新しい接続では、既存の Windows／SAP SSO を使用できます。オプションの SAP_CLIENT、SAP_USER、SAP_PASSWORD、SAP_LANGUAGE を設定すると、COM 経由でログイン欄に入力されます。パスワードがプロセス引数やログエントリに含まれることはありません。

SSO では、ローカルの Windows／SAP セッションの ID が使用されます。チャットユーザーの ID を推測したり、ChatGPT トークンを交換したり、リモートの Microsoft 委任認証を実装したりすることはありません。対象となる Windows ユーザーごとに、個別のローカルサーバーを実行してください。ここには共有のリモート認証エンドポイントはありません。この区別は、Issue #8 に残る統合要件の一部です。

カスタムインストールの場合は、SAP_GUI_PATH にインストール済みの saplogon.exe またはそのディレクトリを設定します。例：C:\Program Files\SAP\FrontEnd\SAPGUI。実行中の COM オブジェクトが見つからない場合に SAP Logon を起動するために使用されます。デフォルトでは SAP Logon がすでに起動していることを前提とし、推測に基づく 32 ビットのレジストリパスは使用しません（#3）。

スクリプトによるテキストの読み取りには、Win32 ウィンドウのキャプションではなく SAP コントロールのプロパティを使用し、64 ビット環境でのテキスト読み取りに関する報告（#6）に対応しています。パスワード欄の内容は伏せられます。読み取り専用のスクリプトポリシーでは読み取りが許可されても書き込みが拒否される場合がありますが、その失敗を報告し、SAP のセキュリティ設定を変更することはありません。SAP のスクリプト要件とGUI ドキュメントでは、インストール要件と管理者の前提条件について説明しています。

ツール

ツール	操作
launch_transaction	選択したセッションでトランザクションコードを開始します
end_transaction	他のセッションと SAP Logon を維持したまま、そのセッションのトランザクションを終了します
sap_click, sap_move_mouse	SAP ウィンドウを基準とした物理スクリーンショットのピクセル座標
sap_type	明示的な特殊キーを含む、既存の WScript SendKeys のセマンティクス
sap_scroll	そのウィンドウ内を上下にスクロールします
save_last_screenshot	最後に要求されたスクリーンショットを、設定済みの出力ルート内に保存します
sap_get_screen	最大 300 個の COM コントロール ID／型／テキストを読み取ります。パスワードフィールドはマスキングされます
sap_set_field	セッション相対の SAP テキストフィールドにリテラルテキストを設定します
sap_press	SAP COM ボタンを押します
sap_send_vkey	文書化された SAP 仮想キーを送信します（0 は Enter です）
sap_run_guixt_script	プリインストールされた InputScript を、指定されたセッションウィンドウに送信します

コントロール ID は wnd[N] で始まる必要があります（例：wnd[0]/usr/ctxtFIELD）。セッションをまたぐ絶対 ID は拒否されます。これらは公開されている SAP ActiveX／COM スクリプティング操作（#2）であり、任意の COM メソッドを評価するのではなく、型指定されたメソッドを使用します。SAP のアプリケーション APIとセッション APIを参照してください。

スクリーンショットに対応したツールは return_screenshot を受け付けます。指定できる値は none（既定値）、as_file、as_base64、as_imagecontent、as_imageurl です。最後の表記は互換性のため引き続き使用できますが、現在は偽の取得可能なリモート URL ではなく、有効な埋め込み PNG ブロブリソースを返します。スクリーンショットは二重の DPI スケーリングを行わない物理ピクセルで、上限は 3,000 万ピクセル／7 MB です。ファイルに書き込む前に、SAP_OUTPUT_ROOT が既存のディレクトリである必要があります。as_file_target_folder はそのディレクトリ内を指す必要があります。保存時に既存ファイルが上書きされることはありません。既定ではスクリーンショットはキャプチャされないため、save_last_screenshot を使用するには、事前に明示的なスクリーンショット要求が必要です。

GuiXT (#1)

ライセンスを取得している環境に応じて、GuiXT／InputAssistant をインストールしてください。GUIXT_PATH には guixt.exe の絶対パスを、GUIXT_SCRIPT_ROOT には read_order.txt のようなシンプルな名前の、レビュー済み InputScript を格納した既存のディレクトリを設定してください。GuiXT のプロファイルで AllowExternalInput Yes を明示的に有効にしてください。サーバーがこの設定を変更することはありません。このツールはスクリプト名を受け取り、ルートディレクトリの境界を検証したうえで、選択された SAP ウィンドウに対して findsession=hwnd:'…' を指定して GuiXT を呼び出します。シェルや呼び出し元が指定するコマンド断片は使用されません。

GuiXT への送信は非同期です。成功結果は、外部呼び出しが受け付けられたことを意味します。業務プロセスの完了が確認されたことを意味するものではありません。追加の入力を送信する前に、同じセッションとスクリプト固有の出力を確認してください。GuiXT が受け付けたスクリプトの自動再試行や汎用的なキャンセル機能はありません。2026 Q1 1 に導入されたオプトイン要件を含め、ベンダーの外部 InputScript 契約を参照してください。

ライフサイクルと移行

すべての COM 作業は、1 つの直列化された STA ワーカープロセス内で実行されます。SAP_OPERATION_TIMEOUT のデフォルトは 30 秒です（1～120）。キャンセルまたは期限切れが発生すると、このサーバーのワーカープロセスのみを終了し、MCP サーバーが再起動されるまで以降の作業を拒否します。すでに実行された SAP 操作はロールバックできないため、再開前にセッションを確認してください。taskkill、プロセス名による照合、SAP の一括終了、自動的な複数ログオンのポップアップ操作は、いずれも行われなくなりました。MCP を終了するとハンドルは解放されますが、SAP セッションは開いたままになります。明示的な end_transaction を実行すると、選択したトランザクション内の未保存の作業が破棄される場合があります。

実行時の失敗には isError=true が設定され、無効な入力や不明なツールには SDK のエラーセマンティクスが適用され、標準出力には MCP JSON-RPC のみが出力されます。ツール引数、フォームのテキスト、認証情報、COM の例外詳細はログに記録されません。ローカルの stdio プロセスは、Windows ユーザーのデスクトップ権限で動作します。専用の自動化セッションを使用し、出力先およびスクリプト用ディレクトリはそのユーザーの管理下に置いてください。

バージョン 0.2 では、壊れていた SDK1 のコンストラクター／デコレーターと、プロセス全体に作用する制御動作が置き換えられています。SAP_SYSTEM は、ログオン記述を指定する SAP_CONNECTION、または SAP_SESSION_ID に置き換えられました。パスワードは任意です。ファイル出力にはルートの指定が必要になりました。内部コントローラーメソッドをインポートする旧コードは、名前付き MCP ツールに移行してください。統合ヘルパーは、それを呼び出した Python インタープリターを使用します。パッケージを含む環境から実行してください。

検証と Docker

uv run ruff check .、uv run ruff format --check .、uv run pytest、uv build により、ソース、制御された COM モック、タイムアウト／キャンセル、実際の子プロセスを用いたモダン／レガシープロトコルのセッション、インストール済みパッケージの検出、エラー動作を検証します。Windows CI ではネイティブバインディングをインポートし、破棄可能なテストウィンドウをキャプチャします。SAP へのログイン、実システムでのトランザクション実行、またはお使いの環境における SSO／GuiXT の動作を証明するものではありません。

Dockerfile はこのチェックアウトからビルドされ、非 root のプロトコル／検出用イメージを実行するようになりました。Linux コンテナーから、対話型でライセンス認証された Windows SAP GUI にアクセスすることはできません。このイメージで SAP ツールを呼び出すと、プラットフォームエラーが明示的に返されます。自動化にはネイティブの Windows パッケージを使用してください。これにより #4 の無効な Dockerfile の問題は修正されますが、コンテナーで SAP が動作することや、Glama へのデプロイが検証済みであることを主張するものではありません。サードパーティのディレクトリー掲載情報の更新や、その掲載に関する主張は、別途行う外部作業です。

本番環境で使用する前に、破棄可能な SAP クライアントで次の事項を確認してください。選択した SSO ID と任意の不一致アサーション、使用中の GUI パッチでのテキスト読み取り、無害なトランザクションの開始と別のオープンセッションに影響がないこと、コントロール、スクリーンショット、GuiXT スクリプトの動作、長時間のリクエストをキャンセルしても無関係なプロセスが終了しないことを検証してください。GUI のバージョン、パッチ、Windows ビルド、スクリプトポリシー、検証結果を記録してください。これらのネイティブ SAP の受け入れ確認は、テストが完了するまで明示的な確認事項として残ります。