abap2UI5

mcp-server

abap2UI5 の MCP サーバー — SAP システムなしで、あらゆる AI コーディングエージェント（Claude Code、 Cursor、VS Code Copilot、または任意の MCP クライアント）に abap2UI5 の開発ループ全体を提供します。

examples -> app_guide -> validate_view + screenshot_view -> deploy_app -> build_backend -> run_app -> pitfalls
(has somebody  (how an app  (SECONDS, no system:        (write ABAP,  (transpile      (boot headless,  (what a green
 built it       is built)    is the view legal,          lint)         to Node)        errors +         run still
 already?)                   and what does it LOOK like)                               SCREENSHOT)      does not prove)

エージェントは ABAP クラスを作成し、ビューを検証してその画像も確認し、数秒でデプロイして、実際のブラウザーで起動したアプリを確認し、その後、反復して改善できます。すべて、CI で abap2UI5 エコシステムをすでに支えているインフラ上でローカルに実行されます。abaplint トランスパイラーと open-abap ランタイム、フレームワークの express シム、 samples-controls のビルドおよび起動ゲート、そして linter の検証コアです。

ドキュメント

→ MCP サーバーの詳細 — ここで MCP が何を意味するのか、3 つのセットアップレベルとそれぞれでできること、クライアントへのサーバー登録方法、各ツールでエージェントが得られるもの、そして想定される使用ループについて説明します。

→ AI を使った開発 — AI のセットアップ全体を、手間の少ない順に紹介します。このサーバーは最上位の選択肢ですが、まずは手軽な選択肢が重要です。

クイックスタート

ワンクリックインストール

どのボタンを使っても、abap2ui5 という名前の同じ stdio サーバーが登録されます。

{"command":"npx","args":["--yes","-p","@abap2ui5/mcp-server","abap2ui5-mcp"]}

GitHub はエディター独自の URL スキームへのリンクを表示しないため、バッジは Web リダイレクトを経由します。ブラウザーに貼り付けるか、 xdg-open／open で開くための直接リンクは次のとおりです。

vscode:mcp/install?%7B%22name%22%3A%22abap2ui5%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22--yes%22%2C%22-p%22%2C%22%40abap2ui5%2Fmcp-server%22%2C%22abap2ui5-mcp%22%5D%7D
cursor://anysphere.cursor-deeplink/mcp/install?name=abap2ui5&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyItLXllcyIsIi1wIiwiQGFiYXAydWk1L21jcC1zZXJ2ZXIiLCJhYmFwMnVpNS1tY3AiXX0%3D

（Insiders の場合は vscode: の代わりに vscode-insiders: を使用します。）Claude Code：

claude mcp add abap2ui5 -- npx --yes -p @abap2ui5/mcp-server abap2ui5-mcp

Claude Code プラグイン。 abap2UI5 プラグインには、フレームワークのエージェントスキル（アプリの構築、ABAP および UI5 の落とし穴に関するカタログ、ビューのチェーンレイアウトなど）と、このサーバーがまとめて含まれています。上記と同じ方法で登録でき、両方を一度にインストールできます。

/plugin marketplace add abap2UI5/abap2UI5
/plugin install abap2ui5@abap2ui5

1.0.0 以降のリリースは、公式の MCP Registry にも io.github.abap2UI5/mcp-server（server.json）として掲載されています。これはレジストリからインストールするクライアント向けです。Smithery（smithery.yaml）および Glama（glama.json）のディレクトリにも同じコマンドが掲載されています。npm パッケージもバージョンも 1 つで、クライアントが参照するカタログを選びません。

以下のレベル 1 に相当します。validate_view と fix_view はすぐに使え、 setup_status はこのマシンでほかに何が動作するのか、何が不足しているのかをエージェントに伝えます。

各インストールで利用できる機能

レベル 1 — validate_view、fix_view、screenshot_view。作業の大半はこれらのツールで行います。これらには linter が必要です。サーバーはこれをピア依存関係（@abap2ui5/linter、>=0.8.0 <0.10.0 — このサーバーが対応する範囲）として宣言しています。npm 7 以降では必須のピア依存関係が自動的にインストールされるため、以下のワンライナーで linter もインストールされ、validate_view／fix_view はすぐに使えます。screenshot_view が使用するレンダリングゲートには、さらに UI5 ライブラリと Playwright が必要です（@abap2ui5/linter-render はオプションのピア依存関係として宣言されています。互換性のある範囲は示されていますが、このパッケージは自動インストールされません — 約 150～200 MB と、初回追加時に数分かかることを見込んでください）。

claude mcp add abap2ui5 -- npx --yes -p @abap2ui5/mcp-server abap2ui5-mcp                            # validate_view, fix_view
claude mcp add abap2ui5 -- npx --yes -p @abap2ui5/mcp-server -p @abap2ui5/linter-render abap2ui5-mcp # + screenshot_view

サーバーは次の順序で linter を探します。AI_VIEW_CHECK_HOME、サーバーの隣にある linter チェックアウト（npx の実行時に npm がピア依存関係を配置する場所でもあります：node_modules/@abap2ui5/{mcp-server,linter}）、サーバーの起動元プロジェクト（node_modules/@abap2ui5/linter — app-template では devDependency として含まれているため、そこで npm install を実行するだけで使えます）、サーバー自身の node_modules、そしてサーバーの場所から Node のモジュール解決で見つかるものです。環境変数が設定されている場合は、それだけが使われます。または、チェックアウトから作業します。

git clone https://github.com/abap2UI5/linter        # AI_VIEW_CHECK_HOME
cd linter && npm ci

サーバー自体は npm に公開されているため、チェックアウトは不要です。上記の登録だけでインストールは完了です。（npm 6 または --legacy-peer-deps を使う場合は、-p @abap2ui5/linter を自分で追加してください。）

（-p … abap2ui5-mcp は bin を明示的に指定しており、公開されているすべてのバージョンで利用できます。短い形式の npx --yes @abap2ui5/mcp-server ではパッケージ名と同じ bin が必要ですが、0.2.0 以前にはありません — npx はそこで "could not determine executable to run" と表示して停止します。）

（インストールサイズは約 47 MB です。そのうち 19 MB は run_app だけが使う Playwright ドライバー、2 MB は linter です — 初回起動時にインストールされ、その後はキャッシュされます。代わりにチェックアウトから使う場合： git clone https://github.com/abap2UI5/mcp-server && cd mcp-server && npm ci、 続いて claude mcp add abap2ui5 -- node /path/to/mcp-server/server.mjs を実行します。）

Cursor、VS Code、Claude Desktop では標準的な stdio 形式を使います — JSON と、さらに 2 つのレベル（サンプルカタログとデプロイ、続いてヘッドレスのビルド・起動ループ）についてはドキュメントを参照してください。前提条件が不足しているツールは、必要なものを示すメッセージを返します。サーバーはどちらの場合も起動します。

abap2UI5 VS Code extension はこのサーバーを自動で登録し、実際の SAP システムが必要なツール用に、独自の 2 つ目のサーバーも追加します。

すべてを 1 つのコマンドで — ビルド・起動ループ全体に専用のマシン（またはCodespace）向けに、setup.sh はフレームワーク、コーパス、linter のチェックアウトをこのリポジトリの隣にクローンし、それらの依存関係とヘッドレスブラウザーをインストールします（既存のチェックアウトは再利用されるため、再実行しても安全です）。

git clone https://github.com/abap2UI5/mcp-server && ./mcp-server/setup.sh

setup.sh --no-corpus はフレームワークと linter のみをクローンします。フレームワークのサンドボックスがあるため、自分のアプリで使う場合はこれだけでループ全体を実行できます。コーパスは scope_of、完全なビルド、ローカルで提供する UI5 に必要です。

チェックアウト内で起動した Claude Code は、コミット済みの .mcp.json によりサーバーを自動的に認識します。devcontainer は作成時に同じセットアップを実行します。 レベル 0 — チェックアウトがまったくない場合。 ナレッジツール（app_guide、 api_reference、pitfalls、capabilities、examples、read_example、 docs_search、scaffold_app、generation_rules）はコミット済みのファイルを読み取ります。そのため、 チェックアウトが見つからず、環境変数も設定されていない場合は、代わりに GitHub から読み取ります。 ファイルはユーザーごとのキャッシュ（<tmp>/abap2ui5-mcp-remote。ユーザー自身が所有するディレクトリである場合に限り、一日単位で使用し、0700 で作成します。A2UI5_MCP_REMOTE_DIR で場所を変更できます）に格納され、サーバーはこれを読み取り専用のチェックアウトとして扱います。add_agent_setup もそこからテンプレートを読み取り、指定されたプロジェクトにのみ書き込みます。また、 負荷の大きい処理は npm パッケージ @abap2ui5/node-runtime（以下を参照）上で実行されるため、 新しいプロジェクトで npx --yes -p @abap2ui5/mcp-server abap2ui5-mcp を実行すれば、 何もクローンせずに deploy_app、build_backend、run_app、interact_app、run_unit_tests および verify_app も利用できます。チェックアウトが引き続き必要なのは、コーパスの機能（scope_of、 build_backend の full モード、ローカルで提供する UI5）です。A2UI5_MCP_REMOTE=0 または A2UI5_MCP_OFFLINE=1 を設定すると、ミラーが無効になります。ドキュメントミラーは GitHub の API を使ってページ一覧を取得します。この API は、アドレスごとに認証なしで毎時 60 件のリクエストを許可しています。環境に GITHUB_TOKEN（または GH_TOKEN）を設定すると上限が引き上げられ、そのトークンは api.github.com にのみ送信されます。

フレームワークのチェックアウトなしでバックエンドを利用する方法：@abap2ui5/node-runtime。 フレームワークは、アプリのトランスパイルに使用する同じリリースコミットの ABAP ソースとともに、トランスパイル済みの状態で npm から公開されています。abap2UI5 のチェックアウトがなく（設定もされていない）場合、build_backend はリリースごとに一度、そのパッケージを ~/.abap2ui5-mcp/runtime/<version> にインストールします。パッケージには指定されたトランスパイラー、express、Lint に使う app-template の abaplint が含まれ、正確なバージョンがロックファイルで固定されており、--ignore-scripts が指定されます。次に、リリースのビルドに使用したコミットの open-abap-core を取得し、デプロイされたアプリのみをそれに対してトランスパイルします。処理は数秒で、フレームワーク自体をトランスパイルすることはありません。deploy_app は ~/.abap2ui5-mcp/sandbox に書き込み（パッケージのソースを対象に、app-template 独自の設定で Lint を実行します）、run_app は登録済みのアプリとともにパッケージのサーバーを起動し、run_unit_tests はアプリ独自のテストを実行します。リリースには、A2UI5_MCP_RUNTIME_VERSION で固定しない限り、npm に問い合わせて取得したレジストリの最新バージョン（1 日キャッシュ）を使います。ここで npm のキャッシュを空にして測定したところ、初回インストールは約 10 秒、open-abap-core は約 1 秒、その後のビルドは毎回 7～8 秒、ユニットテストは約 1 秒でした。setup_status にはリリース、ワークスペース、次回のビルドで実行される処理が表示されます。

フレームワークのチェックアウトがある場合（A2UI5_HOME または隣接ディレクトリ）は、これまでどおりすべて動作します。build_backend は初回に、ビルド済みバックエンドのリリース版（backend-<version>.tar.gz）をチェックアウトにダウンロードし、その後は node/zz_dev からデプロイ済みアプリを再トランスパイルします。A2UI5_MCP_BACKEND=npm を設定すると、チェックアウトと並行してパッケージ上で実行します。build_backend の prebuilt モード（または A2UI5_MCP_BACKEND=clone）では、代わりにリリースを ~/.abap2ui5-mcp/abap2UI5 にクローンします。これは、パッケージが利用可能になる前に、チェックアウトがない状態でこのサーバーが使っていたパスです。リリースされていないコミットをチェックアウトしている場合は、完全なコーパスビルドも引き続き mode: "full" で利用できます。

ツール

すべてのツールは隣接するチェックアウトから最新の内容を読み取り、それぞれ特定の隣接チェックアウトを必要とします。「任意」のリポジトリというものはなく、使うツールに必要なリポジトリがあるかどうかだけです。必要なもの列には、欠けているとツールが動作しないチェックアウトが示されています。リンターだけで validate_view、fix_view、screenshot_view の 3 つを提供します（反復の大半が行われる高速なループであり、サーバーとともに npm がインストールする、宣言済みのピア依存関係でもあります）。フレームワークのチェックアウトはガイド、落とし穴、インターフェースを提供します（この 3 つは、チェックアウトがない場合に GitHub からミラーされます）。npm パッケージ @abap2ui5/node-runtime は、フレームワークのチェックアウトがない場合にバックエンドを提供します。コーパスは、それ以外のほぼすべてを提供します。必要なチェックアウトがないツールは、それを解決するクローンコマンドと環境変数を返します。

ツール	機能	必要なもの
setup_status	解決されているもの、ビルド済みのもの、不足しているものとその修正方法を一度に確認できます。最初に呼び出してください	なし
capabilities	検証済みの機能マップに基づいて、abap2UI5 で UI5 の機能を実現できるかどうかを確認できます	samples-controls
app_guide	フレームワークのチェックアウトから最新の情報を取得して、アプリの作成方法を確認できます	abap2UI5
api_reference	ABAP-Doc に基づくクライアント API（z2ui5_if_client）のメソッド、パラメーター、デフォルト値、cs_* 定数を確認できます	abap2UI5
scaffold_app	新しいプロジェクトのひな形となるファイルを app-template から取得できます。{ class: … } は全体で名前が置き換えられ、サイドカーの CLSNAME も対象です	app-template
add_agent_setup	既存のプロジェクトで AI 開発を行うための設定をします。npm create abap2ui5-app -- --agent-setup が行う処理（AGENTS.md、スキル、.mcp.json、許可リスト、両方のゲート、CI ジョブ）を project_dir に書き込みます。既存ファイルは上書きせず、package.json／.gitignore はマージし、STARTING_FOLDER に従います	app-template
examples	3 つのサンプルカタログと検証状況などを検索します。信頼してよいコード片ではなく、確認すべきクラスを回答します	samples／samples-controls／samples-stack のいずれか（または GitHub ミラー）
read_example	examples の検索結果で指定されたサンプルのソースを、チェックアウトまたは GitHub から取得して読み込みます	サンプルのリポジトリ（または GitHub ミラー）
docs_search	ドキュメントサイトのページを全文検索し、ページ、見出し、抜粋、公開 URL を返します	docs
generation_rules	UI5 の demo-kit サンプルを samples-controls に移植する際のルールを確認できます	samples-controls
pitfalls	実行が成功しても検出されない不具合を確認できます。{ area: "abap" } と { area: "view" } を指定します	abap2UI5
scope_of	UI5 コントロールが対象範囲内か対象範囲外かを判定します	samples-controls + OpenUI5 のチェックアウト
validate_view	プロジェクト独自の abap2ui5lint.jsonc に基づき、リンターのゲートを数秒で判定します	linter
fix_view	リンターで機械的に修正できる箇所を適用し、修正後のソースを返します。ファイルには書き込みません	linter
screenshot_view	ビルドもバックエンドも使わず、数秒でビューを確認できます	linter
deploy_app	クラス、abapGit サイドカー（およびテスト用インクルード）を開発用サンドボックスに書き込み、その後 abaplint を実行します	なし（npm バックエンドの ~/.abap2ui5-mcp/sandbox）。利用可能な場合は samples-controls の src/zz_dev または abap2UI5 の node/zz_dev
read_app	デプロイ済みの開発アプリのソースを読み戻し、ビルド済みバックエンドにすでに含まれているかどうかを確認します	サンドボックス（deploy_app と同じ）
build_backend	トランスパイル済みの Node バックエンドを取得します。チェックアウトがない場合は npm の @abap2ui5/node-runtime を使い、開発アプリのみを数秒でトランスパイルします。チェックアウトがある場合、prebuilt はフレームワークのリリース済みバックエンドをダウンロードし、incremental はその上に開発アプリを再トランスパイルします。要求された場合、prebuilt／transpile はフレームワークをクローンします。full はコーパスの e2e-build を実行します	なし（npm）、または abap2UI5（full には samples-controls が必要）
build_log	直近のビルドの完全な出力をページごとに確認します。結果の短い末尾表示で省略されたエラーも確認できます	なし（最後のビルドが残した記録を読み込みます）
run_app	アプリをヘッドレスで起動し、ステータス、実際のページエラー、スクリーンショットを確認できます	ビルド（npm バックエンドまたは abap2UI5 のチェックアウト）。samples-controls がある場合は UI5 をローカルで配信し、それ以外の場合は CDN を使用します
interact_app	アプリを起動し、短いスクリプトでクリック、入力、キー押下、待機を実行します。イベント分岐を撮影します	ビルド（run_app と同じ）
app_list	ビルド済みバックエンドで起動できるアプリクラス（デプロイ済みの開発アプリとフレームワーク自体のアプリ）を一覧表示します	ビルド（npm バックエンドまたは abap2UI5 のチェックアウト）
app_start	アプリを起動し、エージェントスナップショットを取得します。フィールド（パス、ラベル、種類、値）、アクション（イベント＋引数）、テーブル、メッセージを、ブラウザーを介さず abap2UI5 JSON プロトコルで取得できます。MCP Apps ホストでは操作可能な画面も表示され、format: "adaptive-card" を指定すると Adaptive Card も表示されます	ビルド（run_app と同じ）
app_describe	セッションの現在のエージェントスナップショットをメモリーから取得します。再度の通信は不要です	app_start で作成したセッション
app_act	フィールドに入力し、名前を指定してイベントを発火します。スナップショットに基づいて検証され、実際のモデル差分として送信されます。その後、次のスナップショットを取得します	app_start で作成したセッション
run_unit_tests	open-abap ランタイムでデプロイ済みアプリのテストクラスを実行します（チェックアウトがある場合は、トランスパイル済みのツリー全体も実行可能）。画像ではなくアサーションで検証します	ビルド（npm バックエンドまたは abap2UI5 のチェックアウト）
verify_app	検証、デプロイ、ビルド、単体テスト、起動を一度に実行し、最初に失敗した段階で停止します	各段階に必要なもの
migrate_report	従来型の ABAP レポートを abap-cloud-gui のアプリクラスに変換します（report2cloud）。クラスファイル、移行レポート（TODO、後継がある未リリースのテーブル）、拒否内容（file:row:col）を返します。deploy: true の場合はここでビルドし、選択画面のエージェントスナップショットを返します	abap-cloud-gui（npm ci が必要）。deploy にはポップアップとビルドも必要
backend	ローカルの express バックエンドに対して status／start／stop／restart を実行します	ビルド（start／restart の場合。status と stop は常に実行できます）
remove_app	サンドボックスから開発アプリを削除するか、デプロイ済みアプリを一覧表示します	サンドボックス（deploy_app と同じ）
verify_app は 1 回の呼び出しで一連の処理を実行します。検証、デプロイ、ビルド、ユニットテスト、起動を順に行い、失敗した最初の段階で停止して、それまでのすべての段階を報告します。interact_app は操作機能を備えた run_app です。起動後に短いスクリプトでクリック、入力、キー押下を行い、結果を撮影します。これにより、システムなしでアプリのイベント分岐を確認できます。run_unit_tests は、deploy_app がアプリの隣に作成したテストクラス（ローカルの z2ui5_if_client の代替実装。アプリガイドの第 9 章を参照）を open-abap ランタイムで実行し、アサーションの結果を返します。

scaffold_app と add_agent_setup はどちらも、2 種類のプロジェクト向けに app-template 自体の template.json を実行します。scaffold_app はアプリクラスを含む新しいプロジェクト一式を返し、何も書き込みません。add_agent_setup は、すでに存在する abapGit リポジトリ（その大半はテンプレートから始まったものではありません）向けのもので、テンプレートの agentSetup キーを通じて、そこで npm create abap2ui5-app -- --agent-setup を実行した場合と同じ処理を行います。エージェントのセットアップと 2 つのゲートを project_dir（デフォルトは、プロジェクトらしい場合はサーバーの作業ディレクトリ）に書き込みます。プロジェクトにすでに存在するファイルは上書きせず、それぞれスキップしたファイルとして一覧表示します。package.json と .gitignore は不足分だけを追加してマージし、テンプレートと異なる値はそれぞれ警告として示します。設定ファイルはソースフォルダーの .abapgit.xml に記載された名前を参照し、そのファイルには何も書き込みません。2 回目の実行では何も変更されません。dry_run: true を指定すると、書き込みを行わず同じレポートを返します。書き込む各パスはテンプレートのファイル一覧から取得し、事前に検証されます。通常の相対パスであり、テンプレートの共有ファイルであり、ソースフォルダーの外にあるパスの場合、呼び出し全体を拒否し、何も書き込みません。シンボリックリンク、またはシンボリックリンクを経由してプロジェクト外に出るフォルダーには、決して書き込みません。そのファイルはスキップされ、理由が応答に記載されます。

すべての応答はクライアントの上限に収まります。 クライアントは上限を超えるツール結果をエージェントに表示しません（Claude Code：25,000 トークン）。そのため、応答は約 60,000 文字を超えません。上流コンテンツに応じて応答が大きくなるツールは、内容を切り捨てずにページ分割します。matches はすべてのヒット数、returned は現在のページの件数、more は残りを取得するための正確な呼び出し方法を示します（offset — examples、capabilities、api_reference、app_guide、pitfalls、docs_search、files — scaffold_app、from_line — read_app、read_example、build_log は cut 内に次の offset を示します）。ページ分割ではなく短縮されるリストには、短縮されたことを ...Cut フィールド（findingsCut、rulesCut、errorsCut など）で示します。それでも上限を超える場合に備えた最後の処理では、応答を切り詰めて __answerGuardCut を付けます。リソースにも同じ上限が適用されます（以下を参照）。

examples は失敗する代わりに、カタログごとに処理を続行します。見つかったチェックアウトを検索し、見つからなかったものを示すため、内容が少ない応答でも「これを構築した人はいない」と誤解されることはありません。チェックアウトに catalogue.json がある場合は、各リポジトリのコミット済みファイルを読み込みます。このファイルには、コントロールポートの検証ステータス（ランキングの同点を解消するために、確認済み、レビュー済み、生成済みの順で使用）、学習パスの段階、スタックのサンプルがシステムに必要とするものが記載されています。このファイルがまだ存在しなかった頃のチェックアウトでは、SAMPLES.md を解析します。サンプルと samples-controls が catalogue-derived.json をその隣にコミットしている場合、クエリは各サンプルのビューが構築するコントロールの種類にも一致します。そのため、sap.m.Dialog を検索すると、それに分類されたものだけでなく、これを構築するすべてのサンプルが見つかります。screenshot_view と run_app は、桁違いに異なる 2 つの段階で同じ問いに答えます。前者はバックエンドなしで再構成されたビューを撮影し、後者はビルド後の実行中のアプリを撮影します。ほとんどの反復作業は前者で終えるのがよいでしょう。

ブラウザーなしでアプリを操作する

app_start、app_act、app_describe によって、すべての abap2UI5 アプリがエージェントから操作可能になります。UI5 フロントエンドが使用する JSON プロトコル、つまりアプリの開始、引数付きイベント、入力された内容のモデル差分をローカルバックエンドに対して送信し、応答のビュー XML とモデルから導出したエージェントスナップショットを返します。スナップショットには、エージェントが入力できるフィールド（モデルパス、ラベル、種類、現在の値、選択肢の値、編集可能かどうか）、実行可能なアクション（イベント名、固定引数と行に応じた引数）、テーブル（列、先頭の行、選択状態。SelectDialog／TableSelectDialog もテーブルであり、app_act の row で行を選択します）、メッセージ（トースト、メッセージボックス、MessageStrip、フィールドの値ステート、MessagePopover と MessageView の項目）、および一部の静的テキストが含まれます。アクションを送信する前にスナップショットに照らして検証します。未知のイベント、画面に表示されていないフィールド、編集できないフィールド、選択肢にない値は、許可されている項目の一覧とともに拒否されます。abap2UI5/samples の z2ui5_cl_smp_app_009 を使用した短いセッションは次のとおりです。

app_start { app: "z2ui5_cl_smp_app_009" }
  -> fields f1..f5 (f3 "Input with value", /S_SCREEN/COLOR_02, text, ""),
     actions a1 POPUP_TABLE_VALUE (valueHelpRequest of f3), ..., a5 BUTTON_SEND
app_act { session, values: { f4: "Smith" }, event: "POPUP_TABLE_VALUE" }
  -> layer "popup", table t1 /T_SUGGESTION_SEL (6 rows, Single, editableCells [SELKZ]),
     action a1 POPUP_TABLE_VALUE_CONTINUE
app_act { session, values: { "/T_SUGGESTION_SEL/2/SELKZ": true }, event: "POPUP_TABLE_VALUE_CONTINUE" }
  -> layer "main", f3 = "BLACK", f4 = "Smith", message { toast, "value selected" }

スナップショットの形式は、VS Code 拡張機能および ABAP エージェントアドオンと共通です。docs/agent-snapshot.md がそのリファレンスです。導出ルール、操作、元の契約からの相違点、そしてスナップショットではまだ確認できない内容について説明しています。ブラウザーにしか表示されない内容（レンダリングされたページやクライアント側の動作）には、引き続き interact_app を使用します。

チャット画面：MCP Apps と Adaptive Cards

スナップショットはエージェント向けのテキストです。オプションの 2 つの表示形式では、チャット内で同じ画面をユーザーに表示し、ユーザーの操作を app_act 経由で送り返します。エージェント自身のアクションと同じ検証が適用されるため、スナップショットで許可されていない操作は実行できず、エージェントはその操作を確認できます。

• MCP Apps（SEP-1865、2026-01-26 安定版、拡張機能 io.modelcontextprotocol/ui）。クライアントが initialize で拡張機能を通知すると、app_start、app_describe、app_act は UI リソース ui://abap2ui5/app-screen（_meta.ui.resourceUri、MIME タイプ text/html;profile=mcp-app）を指定します。MCP Apps をレンダリングするホスト（拡張機能の README には Claude、ChatGPT、VS Code、Goose が記載されています）は、結果の横にサンドボックス化された iframe として画面を表示します。そこには、入力フィールド、ボタン、行アクション、テーブルセル、メッセージが表示されます。クリックすると、画面上のスナップショットから組み立てられた app_act の tools/call がホスト経由で実行されます。その後、ページは何が起きたかをモデルに通知し（ui/update-model-context）、新しいスナップショットを表示します。このページは自己完結型の単一 HTML ドキュメントで、外部 URL、ネットワーク、eval を使用しないため、仕様の制限的なデフォルト CSP の下で動作し、ほかに何も必要ありません。A2UI5_MCP_UI=on は、拡張機能を通知せずに MCP Apps をレンダリングするホストに画面を提供し、off は常に無効にします。どちらの場合も、ツールのテキスト応答は変わりません。
• Adaptive Cards（Copilot／Teams 形式のホスト向け）：app_start、app_describe、app_act に format: "adaptive-card" を指定するか（すべての呼び出しに適用する場合は A2UI5_MCP_APP_FORMAT=adaptive-card）、スナップショットの後に、Adaptive Card 1.5 として画面を埋め込みリソース application/vnd.microsoft.card.adaptive で追加します。レンダリングには abap2UI5/protocol のレンダラーを使用します（lib/vendor/adaptive-cards にベンダー提供されています）。デフォルトでは無効です。各 Action.Submit には session（行のアクションの場合は row も）が含まれます。送信されたペイロードは 1 回の app_act 呼び出しに対応付けられます。event と row はそのまま使用され、値が変化したすべての入力は values["<binding path>"] として渡されます。メッセージボックスのボタンは、そのボタンを $action 引数とするボックスの閉じるアクションに対応付けられ、ポップアップ／ポップオーバーの閉じるワイヤーは @CLOSE_POPUP／@CLOSE_POPOVER に対応付けられます（lib/adaptive-card.mjs の cardSubmitToAct。完全な一覧は docs/agent-snapshot.md を参照してください）。

クラシックレポートの移行

migrate_report は、クラシックレポートのソース（REPORT、 PARAMETERS、SELECT-OPTIONS、イベントブロック、WRITE リスト、ALV）と その .prog.xml テキストプールを受け取り、 abap-cloud-gui アドオンのクラスを返します。このクラスは、移行レポート（TODO、ABAP Cloud でリリースされていないテーブルや API とその後継、リストで引き継がれない内容）と、 変換を拒否したステートメント（file:row:col 形式）とともに、 プログラミングモデルである selection_screen( )、 start_of_selection( )、write( )、alv( )、message( ) を維持します。open-abap の @KERNEL エスケープ（WRITE '@KERNEL ...'.、トランスパイル後は JavaScript）を含むレポートは、変換を始める前に拒否されます。また、動的な WHERE (cond) は変換されますが、warnings に警告が記録されます。実行時には eval() で評価されます（SECURITY.md）。このコンバーターはアドオン独自の report2cloud で、アドオンのチェックアウトから実行します。npm にはありません：

git clone https://github.com/abap2UI5-addons/abap-cloud-gui   # ABAP_CLOUD_GUI_HOME
cd abap-cloud-gui && npm ci

deploy: true を指定すると、クラスはアドオンのランタイム（src/01。データベーステーブルも含み、バックエンドは起動時にデプロイ済みテーブルを作成します）と、呼び出すポップアップ（POPUPS_HOME にある popups のチェックアウト。なければ、順にアドオンの .deps/popups、その隣の ../popups、アドオンの build/popups）とともに開発用サンドボックスへ書き込まれ、バックエンドがビルドされます。また、返答には選択画面の app_start のスナップショットが含まれます。app_act と CGUI_EXECUTE を使用するとレポートが実行されます。レポートが読み取るデータベーステーブルはローカルバックエンドには含まれません。画面は実行されますが、それらのテーブルを読み取る実行はできません。

システムモード：実 SAP システム上でアプリを操作

上記はすべてシステムなしで実行されます。A2UI5_MCP_SYSTEM_URL を設定すると、同じサーバーが別の役割を果たします。設定されたユーザーとしてログインした実 SAP システム上でアプリを操作するツールになります。対象となる MCP クライアントは VS Code 拡張機能以外のもので、拡張機能は自身のシステムサーバーを使ってウィンドウのクライアントを処理します。たとえば Claude Desktop、Claude Code、Cursor、任意の stdio クライアントが該当します。このモードではサンドボックスのツールは提供されません。両方を使うには、変数を設定した状態と設定しない状態でサーバーをそれぞれ登録します。

ツール	機能
system_status	エンドポイントとユーザー（パスワードは表示しません）、およびホストの応答、証明書の受け入れ、ログインの成功を確認する1回のリクエストです。ok になるのは、応答が200でもフォームログインページではなく、abap2UI5 のスタートページが応答した場合のみです。最初に呼び出してください
app_list	ADT クイック検索によるシステム上のクラス名です（filter：名前の先頭部分。ワイルドカードとして * を使用。最大50件）
app_start	システム上でアプリを起動し、エージェントのスナップショットを取得します。サンドボックスの app_start と同じスナップショット、引数、拒否動作です
app_describe	メモリ上にあるセッションの現在のスナップショットです。何も送信されません
app_act	スナップショットに照らして検証したうえでフィールドに入力し、イベントを発生させ、実際のモデルデルタとして送信します。実際に実行されます

Claude Desktop（claude_desktop_config.json：Settings → Developer → Edit Config）で、システム用サーバーの隣にサンドボックスサーバーを登録します。

{
  "mcpServers": {
    "abap2ui5": {
      "command": "npx",
      "args": ["--yes", "-p", "@abap2ui5/mcp-server", "abap2ui5-mcp"]
    },
    "abap2ui5-dev-system": {
      "command": "npx",
      "args": ["--yes", "-p", "@abap2ui5/mcp-server", "abap2ui5-mcp"],
      "env": {
        "A2UI5_MCP_SYSTEM_URL": "https://host:44300/sap/bc/z2ui5?app_start={class}&sap-client=100",
        "A2UI5_MCP_SYSTEM_USER": "DEVELOPER",
        "A2UI5_MCP_SYSTEM_PASSWORD_CMD": "security find-generic-password -s abap2ui5-dev -w"
      }
    }
  }
}

Claude Code の場合は、同じ設定を1つのコマンドで行います。

claude mcp add abap2ui5-dev-system \
  -e A2UI5_MCP_SYSTEM_URL='https://host:44300/sap/bc/z2ui5?app_start={class}&sap-client=100' \
  -e A2UI5_MCP_SYSTEM_USER=DEVELOPER \
  -e A2UI5_MCP_SYSTEM_PASSWORD_CMD='security find-generic-password -s abap2ui5-dev -w' \
  -- npx --yes -p @abap2ui5/mcp-server abap2ui5-mcp

変数
A2UI5_MCP_SYSTEM_URL	VS Code 拡張機能の F9 が認識する起動 URL。{class} はクエリパラメーターとして指定します。または、クラスを含まないエンドポイントです。システムモードを有効にします
A2UI5_MCP_SYSTEM_USER	SAP ユーザー（Basic 認証）
A2UI5_MCP_SYSTEM_PASSWORD	そのパスワード。クライアントの設定ファイルに平文で記載します
A2UI5_MCP_SYSTEM_PASSWORD_CMD	代わりに、パスワードを出力するシェルコマンドを指定します。1回実行され、メモリに保持されます。macOS キーチェーンの場合は security add-generic-password -s abap2ui5-dev -a DEVELOPER -w で保存し、上記と同様に読み取ります。Linux の場合は secret-tool lookup service abap2ui5-dev を使います
A2UI5_MCP_SYSTEM_INSECURE_TLS	1 を指定すると、検証できない証明書（開発システムの自己署名証明書など）を受け入れます。推奨される方法は、システムの CA 証明書（PEM）を指定する NODE_EXTRA_CA_CERTS です

有効にする前に、次の点を確認してください。

• 実際の操作を行います。 app_act のイベントは、設定されたユーザーとしてシステム上で実行され、データの保存、転記、削除を行う可能性があります。開発システムを使用し、エージェントが実行する可能性のある操作に適した権限を持つユーザーを設定してください。エージェントに見えるのは、そのユーザーが参照できる範囲のみです。
• ログインの失敗は1回だけ送信されます。 SAP はログインに数回失敗するとユーザーをロックしますが、エージェントは再試行します。401 の後は、そのパスワードを使ったリクエストはそれ以上送信されません。すべてのツールでその旨が示されます。正しいパスワードでサーバーを再起動するまで（Claude Desktop の場合は終了して再度開きます）、またはパスワードコマンドが別のパスワードを返すまで、この状態が続きます。
• Basic 認証のみ対応しています。 このモードでは SAML、X.509、SSO によるログインはサポートされていません。これらを使う場合は、VS Code 拡張機能のシステムサーバー（認証プロキシ）を使用してください。
• 登録1つにつきシステムは1つです。 2つのシステムには、名前を付けたエントリが2つ必要です。
• プロキシはサポートされていません。 リクエストはホストに直接送信されます。HTTPS_PROXY は読み取られません。
• プロトコルクライアントにはサンドボックスのもの（lib/appclient.mjs）を使用します。CSRF トークンのハンドシェイクを行い、ステートフルセッションの sap-contextid を自身で保持します。このモードでは、ログイン、システムの Cookie、起動場所の処理が追加されます（lib/system.mjs）。app_list には ADT サービスと、それらを利用するユーザー権限が必要です。クラス名が分かっていれば、そのどちらもなくても app_start を使用できます。

システムなしで CI で単体テストを実行

同じランタイムで、GitHub Actions（またはターミナル）上でアプリリポジトリの ABAP Unit テストを実行できます。プロジェクトの abaplint.jsonc で固定されたリリースの @abap2ui5/node-runtime を一度だけインストールしてキャッシュし、そのランタイムに対してクラスをトランスパイルし、生成されたランナーでテストを実行します。フレームワークのクローンも、フレームワークの devDependencies も不要で、このパッケージの npm ci も不要です（ランナーはその依存関係を一切インポートしません）。app-template のスターターアプリで 1 台のマシンにて計測したところ、キャッシュなしでは 16 秒、キャッシュありでは 8 秒でした。一方、0.2.0 のクローンでは 30 秒と 23 秒かかり、ワークスペースのサイズも 67 MB ではなく 231 MB になりました。

- uses: abap2UI5/mcp-server@v1
  with:
    paths: src

framework: X.Y.Z でプロジェクトとは異なるリリースを固定した場合や、backend: clone を指定した場合は、以前の方法（リリースをクローンし、そのバックエンドをダウンロードまたはビルドする方法）が使われます。パッケージより古いバージョン（1.145.0）を固定した場合も、同様に以前の方法が使われます。

@v1 は変動するメジャータグです。リリースワークフローによって、公開されるすべての 1.x リリースに合わせて更新されるため、このタグを指定したワークフローでは、破壊的変更を取り込まずに修正を取得できます。このタグは 1.0.0 のリリース時に作成されます。そのリリースが公開されるまでは、@v0（0.3.0 のままです）または @v0.3.0 のようなリリースタグを固定してください。

npx -p @abap2ui5/mcp-server abap2ui5-unit src     # the same, locally

paths の下にあるすべてのクラスとインターフェースは、すべてのファイルとともにデプロイされます（アプリかどうかを問わず、テスト用およびローカルクラスのインクルードも含みます）。また、すべてのテスト用インクルードが実行されます。このパッケージでは、実行時に独自のサンドボックスとビルドが使われるため、同じマシン上の MCP セッションのアプリは実行に含まれず、影響も受けません。結果として、ジョブの判定と、すべてのテストメソッドおよび最初の失敗を記載したステップサマリーが出力されます。デプロイできないオブジェクト（名前空間付きの名前）がある場合、そのテストを除外して続行するのではなく、実行が失敗します。app-template には、check.yml のジョブと npm run test:unit コマンドが含まれています。ランナーが確認できないのは、open-abap ランタイムでモデル化できない要素です（pitfalls の abap 領域を参照してください）。ここでテストに合格すれば、その要素を除いてシステム上でも合格します。また、PARTIALLY IMPLEMENTED のテストダブルでは、テスト対象コードが呼び出すすべてのメソッドを実装する必要があります。ランタイムは空のスタブを生成しないためです。

リソース

これらのツールを支えるナレッジベースのドキュメントも、MCP リソースとして提供されます。これらのドキュメントを表示するクライアント（コンテキストピッカーやドキュメント添付 UI など）や、分割された内容ではなくドキュメント全体を必要とするエージェントが利用できます。読み取り先は、同じ兄弟チェックアウトから取得する最新の内容です。リスト表示は無料（チェックアウト不要）です。チェックアウトがない状態でリソースを読み取ろうとすると、対応するツールと同じ、対処方法を示すエラーが返されます。クライアントが1回の読み取りで表示できる長さ（約60,000文字。現時点では abap-check のカタログと capability map）を超えるドキュメントは、セクション見出しで分割されます。最後の行には、読み飛ばされた最初のセクションから続きを読み取るツール呼び出し（pitfalls { area, offset }、app_guide { offset }、capabilities { status }）が記載されます。 ドキュメントではない唯一のリソースは ui://abap2ui5/app-screen です。これはアプリツールの MCP Apps 画面です（上記の「チャット内の画面」を参照）。このサーバーの一部であり、チェックアウトは不要です。

リソース	内容	必要なもの
abap2ui5://guide	アプリ構築ガイド全体（app_guide で分割）	abap2UI5
abap2ui5://guide/{chapter}	番号または見出しキーワードで指定するガイドの1章（リソーステンプレート）	abap2UI5
abap2ui5://api	クライアント API の概要 — z2ui5_if_client の各メソッド、定数グループ、型をそれぞれ1行で記載	abap2UI5
abap2ui5://pitfalls/abap	abap-check — CI が成功しても検出されない ABAP の不具合	abap2UI5
abap2ui5://pitfalls/view	ui5-check — CI が成功しても検出されないビューの不具合	abap2UI5
abap2ui5://capabilities	CAPABILITIES.md — 検証済みの機能マップ	samples-controls
abap2ui5://generation-rules	UI5 demo-kit のサンプルを移植するためのルールブック	samples-controls
ui://abap2ui5/app-screen	アプリツールの MCP Apps 画面（text/html;profile=mcp-app）— ユーザーがチャット内で操作するページとしてのスナップショット	-

プロンプト

このサーバーが担う2つの作業それぞれに対応するプロンプトがあり、ツールの説明だけから実行順序を組み立て直す必要なく、エージェントをすぐに作業へ導きます。それぞれ、上記のツールを使ったオーケストレーション用スクリプトを生成し、ツールの内容を重複させません。

• build-an-abap2ui5-app（引数：task、アプリに実行させる処理）— examples／capabilities で概要を把握し、app_guide で構成を学び、クラスを作成して、数秒で validate_view／screenshot_view による反復を行います。deploy_app → build_backend → run_app で動作を証明し、最後に pitfalls で確認します。
• port-a-ui5-sample（引数：sample、demo-kit のサンプル）— コーパスの作業です。作業概要として generation_rules を使い、作成前に scope_of と capabilities を確認します。examples から近接する移植例を参照し、その後、同じ validate／screenshot／deploy／run の手順を実行します。

メモ

• **開発用サンドボックス：**デプロイされたアプリは、samples-controls のチェックアウトがある場合はその Git で無視される src/zz_dev/ に、なければ abap2UI5 のチェックアウトがある場合はその Git で無視される node/zz_dev/ に、それ以外の場合は ~/.abap2ui5-mcp/sandbox に配置されます（A2UI5_MCP_WORKSPACE で変更できます）。エージェントがデプロイしたものがコミットに混入することはありません。
• **バックエンド：**フレームワークのチェックアウトがない場合は、npm パッケージ @abap2ui5/node-runtime が使用されます。A2UI5_MCP_RUNTIME_VERSION でそのリリースを固定できます（デフォルト：レジストリの最新バージョン。1 日に 1 回確認します）。チェックアウトがある場合も A2UI5_MCP_BACKEND=npm でその隣にこのパッケージを使用でき、A2UI5_MCP_BACKEND=clone でフレームワークのクローンをデフォルトに戻せます。インストールされるものはすべて ~/.abap2ui5-mcp に置かれるため、安全に削除できます。
• **ポート：**バックエンドは 3000 で待ち受けます（A2UI5_MCP_PORT で変更できます）。
• Lint：deploy_app は app-template の abaplint 設定で Lint を実行します。npm バックエンドでは、長時間稼働するワーカーが、フレームワークを解析した状態で @abaplint/core（@abaplint/cli と同じバージョンを隣にインストール）を保持するため、デプロイ時の Lint は数ミリ秒で完了します。新しい abaplint プロセスを起動すると（2～3 秒、その大半はフレームワークの解析にかかります）、それより時間がかかります。チェックアウトにその core がない場合や、ワーカーが同等に処理できない設定の場合など、ワーカーで CLI を代替できないときは、従来どおり CLI が実行されます。A2UI5_MCP_LINT_WORKER=0 でワーカーを無効にできます。A2UI5_MCP_LINT_IDLE_MS（デフォルトは 10 分、0 = 無期限）では、リクエストがない状態でワーカーを保持する時間を指定します。フレームワークを解析した状態では約 300 MB を使用し、指定時間が過ぎると終了します。次の Lint では新しいワーカーが起動します。
• **タイムアウト：**起動された子プロセスは、制限時間を超えると（プロセスツリー全体を）終了します。Lint／スコープは 5 分、ユニットテストは 10 分、ビルド（ビルド済みファイルのダウンロードと npm のインストールを含む）はデフォルトで 30 分です。A2UI5_MCP_LINT_TIMEOUT_MS、A2UI5_MCP_SCOPE_TIMEOUT_MS、A2UI5_MCP_UNIT_TIMEOUT_MS、A2UI5_MCP_BUILD_TIMEOUT_MS で変更できます（値はミリ秒）。
• **ダウンロード制限：**GitHub から読み込むデータには、時間だけでなくサイズの上限もあります。読み取り専用ミラーのファイル、ドキュメントツリーの一覧、リリース一覧は 8 MB（現在最大のものは 0.34 MB）、ビルド済みバックエンドのアーカイブは 200 MB（1.146.0 では 2.7 MB）です。上限を超える応答は、サイズが宣言されていれば拒否され、そうでなければ上限で切り詰められます。ツールはその旨を URL とともに通知します。キャッシュ済みのミラーや前回のビルドはそのまま保持されます。
• **ビルド済みバックエンドは展開前に検証されます：**フレームワークは、アーカイブの隣に backend-<version>.tar.gz.sha256 サイドカーを添付します（1.148.0 より後のリリース）。build_backend はダウンロードしたファイルの sha256 をサイドカーと照合します。一致しない場合はダウンロードを破棄し、前回のビルドを保持します。サイドカーのないリリースは従来どおり展開され、ビルドログに未検証であることが記録されます。このアーカイブは run_app が起動するコードであるため、A2UI5_MCP_PREBUILT_URL は https: である必要があります。ループバック以外の通常の http: ミラーは、ネットワークが信頼できることを A2UI5_MCP_PREBUILT_INSECURE=1 で示さない限り拒否されます。この場合もサイドカーは <url>.sha256 で検索されます。
• UI5 ソースは、samples-controls のチェックアウトがある場合、その @openui5 パッケージから配信されるため、起動時にネットワークは不要です。チェックアウトがない場合、run_app と interact_app は CDN から UI5 を読み込みます。CDN に接続できない場合は、起動タイムアウトまで待たずにすぐ通知します。ビルド済みのテーマ CSS はこれらのパッケージに含まれません。ネットワークに接続できれば CDN から読み込まれ（スタイル付きのスクリーンショットになります）、接続できない場合、アプリはスタイルなしで表示されますが、構造は完全な状態です。CDN の応答は呼び出し間でメモリに保持されるため（A2UI5_MCP_UI5_CACHE_MB、デフォルトは 64。0 で無効化）、2 回目の起動では UI5 を再ダウンロードしません。A2UI5_MCP_OFFLINE=1 でネットワークを使わない動作を強制できます。
• Chromium：A2UI5_MCP_CHROMIUM（または、リンターも読み取る CHROMIUM_BIN）で実行ファイルを指定します。指定がない場合は Playwright が管理するブラウザー（npx playwright install chromium）、それもない場合はシステムの chromium が使われます。setup_status には、見つかったブラウザーとその入手元が表示されます。validate_view のウォームレンダーゲートは、そのブラウザーのページを 2 つ保持し、同時呼び出しはそのページの空きを待ちます。A2UI5_MCP_RENDER_PAGES（1～8）でページ数を指定できます。
• スクリーンショット：run_app と interact_app は PNG を <tmp>/abap2ui5-mcp-screenshots/<class>-<stamp>.png に書き込み（新しいものから 50 件を保持し、それより古い同じ形式のファイルを削除）、画像とともにパスを返します。npm からインストールするとインストールディレクトリは node_modules 内にあるため、意図的にそこには保存しません。再起動後に build_log が読み取る前回のビルドログも同じ場所に保存されます。このディレクトリはアクセス権を 0700 に設定して作成され、自分だけが所有している場合に限り使用されます（Linux では /tmp は共有されています）。そうでない場合、画像は返されますが保存されず、理由が screenshotNotSaved に記録されます。A2UI5_MCP_SCREENSHOT_DIR で保存先を指定できます。
• **scope_of にはコーパスに加えて OpenUI5 のチェックアウトも必要です。**JSDoc は OPENUI5_SRC から読み込まれます。この変数が設定されていない場合は、samples-controls のチェックアウトと同じ階層にある ../fork-openui5 から読み込みます。
• **以前にセットアップしたことがある場合：**コーパスのリポジトリ名は、以前は ai-demokit、その後は abap2UI5-api で、現在は samples-controls です。変更は不要です。既存のチェックアウトは、3 つのディレクトリ名のいずれでも引き続き検出されます。また、AI_DEMOKIT_HOME も引き続き SAMPLES_CONTROLS_HOME とあわせて読み込まれます。
• 実システムへのデプロイは従来どおり abapGit を使用します。このサーバーは開発時の内側のループを担い、実システム側はVS Code 拡張機能が担います。この拡張機能独自の MCP サーバーでは、run_app_on_system として公開されています。両方のサーバーが同じエディターウィンドウに登録されるため、このツールは run_app という名前ではありません。

このリポジトリでの作業

npm ci
npm test

規約は AGENTS.md に、ワークフローの残りは CONTRIBUTING.md と RELEASING.md に記載されています。

bench/ は abap2UI5-bench です。AI エージェントの abap2UI5 アプリが、このサーバーを使う場合と使わない場合に、テンプレートのゲートをどの程度の頻度で通過するかを示します。独立したパッケージであり、公開されるサーバーには含まれません。