MCPサーバ実装

[dotani1111]

概要

EC-CUBE の管理データ（商品・在庫／注文／顧客会員／プラグイン）を、AI クライアント（Claude Desktop / Cursor / VS Code など）から自然言語で参照できる読み取り専用の MCP サーバを追加します。/admin/mcp で Streamable HTTP を提供し、4 領域・11 ツール（すべて read-only）を公開します。

MCP サーバ本体は LLM を持たない薄いアダプタで、推論はクライアント側で行います。認証・認可は独自実装せず、API プラグイン api44 の OAuth2 に任せます。

Refs #6796

構成（2 層）

• 本体（このPR）：MCP サーバ本体。ツール、mcp-bundle の配線、scope 強制、監査ログ。
• api44（別PR Controller内で利用するrequestオブジェクトについて #190）：認証・認可。OAuth2、MCP 用 scope、firewall、トークン発行 UI、OAuth 自動ディスカバリ（.well-known / 動的登録）。

認証・認可を api44 の 1 箇所に寄せ、分散によるリスクを避けます。

方針

• 接続とトークン：独自トークン型は作らず、league/oauth2-server の access token をそのまま使います。クライアントは api44 の OAuth 自動ディスカバリで URL を入れるだけで接続できます（ブラウザで管理ログイン＋同意）。管理画面から MCP 用トークンを手動発行することも可能です。
• scope：領域別の read scope（mcp:product:read / mcp:order:read / mcp:customer:read / mcp:plugin:read）。api44 の read/write とは mcp: 接頭辞で分け、GraphQL 用トークンで MCP を叩けないようにします。
• scope 強制：1 箇所に集約。mcp-bundle の ReferenceHandler を ScopeEnforcingReferenceHandler でデコレートし、中央レジストリ McpToolScopeMap を IsGranted で照合します。未登録ツールは fail-closed で全 deny。ツール本体は scope を意識しません。
• 監査ログ：専用チャネル mcp → mcp.log（DB テーブルは増やしません）。MCP 境界のイベント（ツール呼び出し／scope 拒否／rate limit／Origin 違反／認証失敗）を client・IP 単位で記録します。
• 公開フィールド：api44 の allow_list を流用（GraphQL と共用）。値はマスクせず、PII を見せるかは scope の付与で運用統制します。

実装メモ

• firewall：api44 が admin firewall の前に ^/admin/mcp 用 firewall（stateless / oauth2）を prepend します。本体の security.yaml は変更しません（^/api と同じ手法）。
• scope 拒否の応答：HTTP 403 ではなく 200 + JSON-RPC result.isError = true。mcp-bundle がツール実行中の例外を JSON-RPC に変換するため、kernel.exception に届かず HTTP は常に 200 です（詳細 docs/mcp/scope-denied-response.md）。
• 多層ガード：Origin / Content-Type チェック（kernel.request）、2 段 Rate Limiter（認証前は IP 単位／認証後は client_id 単位、cache 障害時は 503 で fail-closed）。
• 監査ログの配線：McpAuditLogger を唯一の書き手とし、compiler pass で mcp チャネルへの注入を 1 点に限定。401 は AuthFailureAuditListener が kernel.response で拾います。
• breaking change ではない：既存挙動は変えません。/admin/mcp と api44 の scope 追加が中心で、MCP 機能は管理画面で有効／無効を切り替えられます。

テスト

• ツール：各領域の DB 結合テスト（検索・取得・在庫・不在時 {"found": false}）。
• 認証認可：MCP firewall が oauth2 経路を通る統合テスト。正常 JWT で 200、トークン失効・Member 無効化で 401。
• scope 強制：デコレータの配線回帰テスト、全ツールが McpToolScopeMap に scope を持つ契約テスト（未登録＝fail-closed）。
• 監査ログ：mcp.log へ分離（site.log に漏れない）契約テスト、401 の記録、AuditResult 全 case の参照確認。
• 基盤：2 段 Rate Limiter、Origin / Content-Type ガード、tools/list と allow_list の契約テスト。

CI は unit-test.yml で実行します：phpunit（16 マトリクス・--exclude-group mcp）と、mcp（--group mcp・api44 を mock-package-api で導入）。

相談したいこと

1. 配布形態：本体同梱＋api44 集約の 2 層で良いか。
2. scope の role 名：mcp:product:read がそのまま ROLE_OAUTH2_MCP:PRODUCT:READ になり role 名にコロンが残ります（動作はします）。定数で集中管理し後から一括変更可能ですが、命名の最終形に意見が欲しいです。
3. PII：値をマスクせず scope 付与（運用）でカバーする方針で許容できるか。
4. ツールの初期セット：4 領域 11 ツールは初期セットです。追加要望歓迎。

Summary by CodeRabbit

• 新機能
  • MCPサーバーを追加し、商品・注文・会員・プラグイン情報の取得や検索に対応しました。
  • MCPツールを管理画面経由およびコマンドラインから利用できるようになりました。
• セキュリティ
  • OAuth認証、権限スコープ、Origin・Content-Type検証、レート制限を追加しました。
  • 許可された項目のみを返却し、監査ログを専用ログへ記録します。
• ドキュメント
  • 権限不足時の応答仕様を追加しました。
• 品質改善
  • MCP機能に関する単体・結合・E2Eテストを拡充しました。

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

EC-CUBE に MCP サーバを統合し、OAuth2 認証、scope 強制、レート制限、監査ログ、11 個の Tool、CLI 実行、allow_list 準拠のシリアライズ、ユニット・統合・E2E テストを追加した。

Changes

MCP サーバ統合

Layer / File(s)	Summary
起動設定と DI 配線 app/config/eccube/..., src/Eccube/Kernel.php, composer.json	MCP バンドル、HTTP/stdio トランスポート、ルート、PSR-17 ファクトリ、Rate Limiter、サービス、ログチャネルを設定した。
監査・権限・入口ガード src/Eccube/Service/Mcp/..., src/Eccube/EventListener/Mcp/...	scope マップと検査、監査ログ、Content-Type/Origin 検証、401 監査、IP/client_id レート制限を追加した。
データ整形と Tool src/Eccube/Service/Mcp/Tool/...	allow_list に基づくエンティティ変換と、顧客・注文・商品・配送・プラグインの取得・検索・一覧 Tool を追加した。
CLI とテスト基盤 src/Eccube/Command/..., tests/..., .github/workflows/..., e2e/...	Tool の CLI コマンド登録、各種契約・統合・E2E テスト、専用 CI ジョブを追加した。

Estimated code review effort: 5 (Critical) | ~120 minutes

Possibly related issues

• MCP サーバ機能 — 実装設計 #6796: MCP サーバの設定、OAuth2、scope 強制、レート制限、監査ログ、Tool 実装を扱う Issue であり、本 PR の変更対象と一致する。

Suggested reviewers: nanasess

Poem

🐰 MCP の道をぴょんと掘り、
Scope の門をしっかり守る。
Tool がデータを運びゆけば、
ログの灯りがあとを照らす。
うさぎも安心、にんじん一口！

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 27.38% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	タイトルが「MCPサーバ実装」とだけで、変更内容の要点は伝わるものの具体性が不足しています。	MCPサーバ追加、11ツール実装、OAuth2/レート制限/監査ログ対応など、主変更を具体的に含む短い題名にしてください。

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[dotani1111]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (3)

src/Eccube/Command/EccubeCliToolCommand.php (1)

1-142: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

CLI コマンドの型変換・必須検証ロジックに対する単体テストが見当たりません。

cast() の整数/真偽値変換やアレイオプションの必須検証など、分岐が多く誤りが混入しやすい箇所です。今回のレビュー対象テスト一覧 (tests/Eccube/Tests/...) に EccubeCliToolCommand や McpCliCommandPass 向けのテストが含まれていないため、McpCliToolInvoker/McpMarkdownFormatter をモックした単体テストの追加を推奨します。

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/Eccube/Command/EccubeCliToolCommand.php` around lines 1 - 142, 追加された
EccubeCliToolCommand の分岐をカバーする単体テストを作成してください。McpCliToolInvoker と
McpMarkdownFormatter をモックし、cast() の整数・浮動小数点・真偽値の成功および不正入力、配列オプションの変換、必須オプション不足時の
Command::INVALID、正常実行時のフォーマット結果出力を検証してください。ツール定義と inputSchema
は各テストで必要な型・必須条件を設定し、McpCliCommandPass 向けテストが未実装なら対象シンボルのコマンド登録も検証してください。

src/Eccube/DependencyInjection/Compiler/McpCliCommandPass.php (1)

34-36: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick win

list/help/引数なし起動時は全ツール分のコマンドがインスタンス化されてしまいます。

doc コメント (34-36行目) は「実際に呼ばれたコマンドだけがインスタンス化される」としていますが、console.command タグに description 属性を渡していないため、bin/console list・bin/console help・引数なし起動時に Symfony が各コマンドの説明を取得するために全コマンドを実体化してしまいます (Symfony Console のドキュメント上、list はレイジーコマンドであっても説明取得のために全コマンドを instantiate すると明記されています)。ツール数分、configure() → $this->invoker->tool($toolName) が毎回呼ばれることになり、コメントの意図と食い違います。

#[McpTool] 属性インスタンスから name と同様に description も compile 時に取得し、タグに渡すことで list を本当にレイジーにできる可能性があります (属性がその情報を持っているか要確認)。

♻️ 提案する修正の方向性

-            foreach ($reflection->getAttributes(McpTool::class, \ReflectionAttribute::IS_INSTANCEOF) as $attribute) {
-                /** `@var` McpTool $instance */
-                $instance = $attribute->newInstance();
-                $names[] = $instance->name ?? $reflection->getShortName();
-            }
+            foreach ($reflection->getAttributes(McpTool::class, \ReflectionAttribute::IS_INSTANCEOF) as $attribute) {
+                /** `@var` McpTool $instance */
+                $instance = $attribute->newInstance();
+                $name = $instance->name ?? $reflection->getShortName();
+                $descriptions[$name] = $instance->description ?? '';
+            }

-            $definition = (new Definition(EccubeCliToolCommand::class))
-                ->setArguments([...])
-                ->addTag('console.command', ['command' => 'eccube:cli:'.$toolName]);
+            $definition = (new Definition(EccubeCliToolCommand::class))
+                ->setArguments([...])
+                ->addTag('console.command', [
+                    'command' => 'eccube:cli:'.$toolName,
+                    'description' => $descriptions[$toolName] ?? '',
+                ]);

Also applies to: 48-58, 82-98

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/Eccube/DependencyInjection/Compiler/McpCliCommandPass.php` around lines
34 - 36, Update McpCliCommandPass so each console.command tag receives the tool
description from the corresponding McpTool attribute, retrieving it at compile
time alongside the tool name. Ensure the tag metadata is sufficient for Symfony
to display list/help descriptions without instantiating every command,
preserving lazy command creation and updating the affected documentation to
match the behavior.

app/config/eccube/packages/lock.yaml (1)

1-6: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

framework.lock の重複設定に注意。

framework.yaml にも既に lock: flock（Agent Commerce/UCP Catalog のキャッシュスタンピード対策用）が設定されており、本ファイルは同じキーを MCP 向けの別理由で再度設定しています。現在は同値のため実害はありませんが、将来どちらか一方だけを変更すると設定ドリフトが起きやすくなります。理由コメントを1ファイルに集約するか、既存の framework.yaml にMCP向けの理由コメントを追記する形に統合することを推奨します。

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@app/config/eccube/packages/lock.yaml` around lines 1 - 6, Remove the
duplicate framework.lock setting from lock.yaml and consolidate the flock
rationale in the existing framework.yaml configuration. Extend that file’s
comments to cover the MCP Rate Limiter and login_throttling requirements while
preserving the single shared lock: flock setting.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/e2e-test.yml:
- Around line 230-240: Update both actions/checkout steps in the mcp job—the
self-repository Checkout and Checkout Api44 plugin—to set persist-credentials to
false, including the external EC-CUBE/eccube-api4 checkout.

---

Nitpick comments:
In `@app/config/eccube/packages/lock.yaml`:
- Around line 1-6: Remove the duplicate framework.lock setting from lock.yaml
and consolidate the flock rationale in the existing framework.yaml
configuration. Extend that file’s comments to cover the MCP Rate Limiter and
login_throttling requirements while preserving the single shared lock: flock
setting.

In `@src/Eccube/Command/EccubeCliToolCommand.php`:
- Around line 1-142: 追加された EccubeCliToolCommand
の分岐をカバーする単体テストを作成してください。McpCliToolInvoker と McpMarkdownFormatter をモックし、cast()
の整数・浮動小数点・真偽値の成功および不正入力、配列オプションの変換、必須オプション不足時の
Command::INVALID、正常実行時のフォーマット結果出力を検証してください。ツール定義と inputSchema
は各テストで必要な型・必須条件を設定し、McpCliCommandPass 向けテストが未実装なら対象シンボルのコマンド登録も検証してください。

In `@src/Eccube/DependencyInjection/Compiler/McpCliCommandPass.php`:
- Around line 34-36: Update McpCliCommandPass so each console.command tag
receives the tool description from the corresponding McpTool attribute,
retrieving it at compile time alongside the tool name. Ensure the tag metadata
is sufficient for Symfony to display list/help descriptions without
instantiating every command, preserving lazy command creation and updating the
affected documentation to match the behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9895f4a9-f053-497d-80aa-5c68955c1d14

📥 Commits

Reviewing files that changed from the base of the PR and between 1db2254 and 1d611c3.

⛔ Files ignored due to path filters (1)

• composer.lock is excluded by !**/*.lock

📒 Files selected for processing (16)

• .github/workflows/e2e-test.yml
• .github/workflows/unit-test.yml
• app/config/eccube/packages/dev/monolog.yml
• app/config/eccube/packages/e2e/monolog.yml
• app/config/eccube/packages/lock.yaml
• app/config/eccube/packages/monolog.yml
• app/config/eccube/packages/prod/monolog.yml
• app/config/eccube/services.yaml
• composer.json
• e2e/playwright.config.ts
• e2e/tests/mcp.spec.ts
• rector.php
• src/Eccube/Command/EccubeCliToolCommand.php
• src/Eccube/DependencyInjection/Compiler/McpCliCommandPass.php
• src/Eccube/DependencyInjection/Compiler/McpScopeEnforcementPass.php
• src/Eccube/Kernel.php

🚧 Files skipped from review as they are similar to previous changes (6)

• app/config/eccube/packages/dev/monolog.yml
• app/config/eccube/packages/prod/monolog.yml
• app/config/eccube/packages/monolog.yml
• .github/workflows/unit-test.yml
• src/Eccube/DependencyInjection/Compiler/McpScopeEnforcementPass.php
• app/config/eccube/services.yaml

[dotani1111]

CodeRabbit のレビュー指摘に対応しました（feature/poc-mcp 反映済み）。

• McpCliCommandPass: 対応済み。console.command タグにツールの description を compile 時に渡し、bin/console list/help で全 eccube:cli:* を実体化しないようにしました（146b2ae60c）
• lock.yaml: 対応済み。framework.yaml の lock: flock と重複のため削除しました（d17d2d6307）
• EccubeCliToolCommand cast(): 対応済み。型変換分岐（integer/number/boolean の成功・不正入力・falsy 成功・素通し）の単体テストを追加しました（c15af8d6a4）
• persist-credentials（e2e-test.yml の mcp ジョブ checkout）: 不要と判断し見送ります（理由は該当行への返信に記載）

[ttokoro20240902]

MCPサーバ本体のレビュー（実機検証ベース）

feature/poc-mcp を Docker（PostgreSQL 18）に checkout し、eccube-api4#190 を併用して実機で確認しました。土台（scope 判定・allow_list 射影・書き込み無し）は堅牢です。修正すると良くなる点を以下にまとめます（実コードと実機挙動に基づく）。

#	対応	指摘	該当	内容・提案
1	要修正	会員・注文検索で解決不能な statusIds が無視され全件返る	Service/Mcp/Tool/SearchCustomersTool.php / SearchOrdersTool.php の buildSearchData()	...StatusRepository->findBy(['id' => $statusIds]) が空配列だと customer_status（注文は status）キーをセットせず、フィルタ無しで全件返る。statusIds:[999] で会員検索 → 全件返却（PII 込み）を実機確認。SearchProductsTool には「解決不能なら 0 件」ガードがあり不揃い。会員・注文にも同じ 0 件ガードを入れるのが安価で確実。
2	要修正	在庫で絞り込むと価格・在庫の範囲表示が実態とズレる	Service/Mcp/Tool/SearchProductsTool.php（stockMin/Max の andWhere）＋ Service/Mcp/ProductPriceStockSummarizer.php	ProductRepository::getQueryBuilderBySearchDataForAdmin は addSelect('pc') で ProductClass を fetch-join する。そこへ pc.stock >= :min を足すと、Paginator(fetchJoinCollection) の本体クエリで ProductClasses が絞り込み後の規格だけ部分ハイドレートされ、getProductClasses() を辿る集計が条件外の規格を落とす。価格レンジが縮む（実機: 在庫800以上で「2341〜3395円」→「3395円」）。集計を別クエリ化 or 絞り込み後に再取得。PoC として許容するなら説明文に明記。
3	要検討	注文番号検索が説明と異なる（完全一致・前後空白に弱い）	SearchOrdersTool.php（$orderNo を trim せず代入）／ OrderRepository::getQueryBuilderBySearchDataForAdmin（o.order_no = :order_no の完全一致）	docblock は「部分一致」だが実際は完全一致。前後空白も除去しないため空白付きは 0 件。trim を入れ、説明を「完全一致」に訂正（部分一致が要るなら keyword を案内）。
4	要検討	Origin チェックが初期設定（許可リスト空）で素通り	EventListener/Mcp/OriginContentTypeListener.php（[] === allowedOrigins で skip）	既定で ECCUBE_MCP_ALLOWED_ORIGINS 未設定 → Origin 検証がまるごと無効。JSON 必須・トークン必須が緩和材料だが、必須設定化 or 初期値の見直しを検討。
5	要検討	tools/list が scope でフィルタされない	MCP ツール一覧	保有 scope に関わらず全ツール名を返す（呼び出し時の scope 検査はあり）。GitHub MCP 等は list を token の scope でフィルタしており「list フィルタ＋ハンドラ検査」の二重防御が定石。実害は軽微だが露出を減らせる（優先度低）。
6	要検討	「閲覧専用」の担保がツール層の scope 検査だけに依存	Service/Mcp/ScopeChecker.php ／ /admin/mcp firewall	MCP トークンは Member として認証されるため /admin/mcp 通過時は ROLE_ADMIN しか確認しない。領域・read 限定は ScopeChecker（ツール呼び出し）でのみ効く。将来 /admin/mcp 配下に scope 検査を経ない通常の管理コントローラ URL（#[IsGranted('ROLE_ADMIN')] 相当）を足すと、read 専用トークンでも到達できてしまう。「/admin/mcp 配下は必ず領域 scope も検査する」を規約化し、クロス scope 拒否テストを顧客・プラグインにも拡充（今は商品↔注文の1組のみ）。

[ttokoro20240902]

再確認レビューです。07-21 に出した 6 件はいずれも指摘した範囲を超えて丁寧に対応いただいており（Origin は環境別 fail-closed、tools/list はページング順序の落とし穴まで踏まえた実装、認可境界は規約文書化＋実カーネルでのテスト固定）、対応漏れはありませんでした。CI も現 HEAD fad62d943e で 115 チェック全緑です。

残る指摘は 3 点で、すべて 在庫絞り込みを EXISTS 化した 9b0b4bc94 が持ち込んだ意味変更とそのテストです。base 4.4 に当該ファイルは無いので 4.4 に対する regression ではなく、PR 内での意味変更という位置づけです。

#	重大度	指摘	該当	内容	提案
A	🟠 仕様確認	stockMin / stockMax が別々の EXISTS なので、min と max を別の規格が満たしてもヒットする	src/Eccube/Service/Mcp/Tool/SearchProductsTool.php の在庫絞り込み	独立した 2 本の EXISTS は式として max(stock) >= stockMin AND min(stock) <= stockMax、つまり**「商品の在庫レンジが [stockMin, stockMax] と交差する」と等価です。EXISTS 化前の andWhere('pc.stock >= :min') / andWhere('pc.stock <= :max') は「[stockMin, stockMax] に入る規格が 1 つ以上ある」**でした。どちらも成立する解釈ですが、現状の挙動は docblock（＝AI に渡すツール契約）に書かれていません。 実データでの確認: 商品 id 6041 の規格在庫は 372, 822, 832, 931。stockMin=400 stockMax=800 で現状はヒットしますが [400,800] に入る規格は 1 つもありません。同条件の件数は 分離 26 件 / 同一規格 25 件（差は 6041 の 1 件）で、eccube:cli:search_products --stockMin=400 --stockMax=800 の total も 26 でした。	レンジ交差が意図なら docblock に明記。「範囲内の規格を持つ商品」が意図なら min/max を 1 本の EXISTS にまとめる（pc を制約しない＝レンジ縮み対策は維持されます）。C と同じ 1 箇所で両方直ります
C	🟠 要修正	EXISTS に visible 条件が無く、非表示規格だけが在庫条件を満たす商品がヒットする（出力レンジに現れない在庫で絞り込まれる）	同上	置き換え前の pc は ProductRepository::getQueryBuilderBySearchDataForAdmin が andWhere('pc.visible = :visible')（true）を掛けていたため、在庫絞り込みも表示規格だけが対象でした。新しい EXISTS は別エイリアスなのでこの制約が外れています。一方 ProductPriceStockSummarizer は isVisible() で非表示規格を除外して集計するので、絞り込みの母集団と出力レンジの母集団が食い違います。 非表示規格は特殊データではなく、規格なし商品に規格を登録すると ProductClassController の「デフォルト規格を非表示にする」処理が stock / stock_unlimited をそのまま残して visible=false にするだけなので、通常運用で発生します。 実データでの確認: stockMin=900 の件数は 現状 11 件 / visible=true 条件付き 8 件（CLI の total も 11）。差分 3 件（id 6026・6029・6041）は非表示規格だけが 900 以上で、表示規格の最大在庫は 705 / 426 / 832。「在庫 900 以上」で検索して stock.max が 832 の商品が返ります。	EXISTS に pcStock.visible = true を追加
B	🔵 テスト	在庫絞り込みのテストが、②の元の不具合も A・C も縛れていない	tests/Eccube/Tests/Command/McpCliCommandTest.php の testSearchProductsStockFilterExecutes	--stockMin=1 --stockMax=1000 で Command::SUCCESS のみ assert しており、コミットメッセージどおり「DQL エラーにならない」ことしか保証していません。②の価格/在庫レンジが縮まないことは未検証で、SearchProductsToolTest にも在庫絞り込みのケースがありません。	置き場所は SearchProductsToolTest（Tool を直接呼べて items[].stock.min/max を見られる）が適切。①絞り込みあり／なしでレンジが一致（②の回帰ガード）②[400,800] に入る規格が無い商品がヒットしない（A）③非表示規格だけが満たす場合にヒットしない（C）の 3 本。Generator::createProduct は全規格を visible=true / 在庫 100〜999 で作るので、テスト内で stock を上書きし、C 用に visible=false の規格を 1 つ足す形になります

A・C をまとめて直す差分案

// 在庫絞り込みは 1 本の EXISTS にまとめる (同一規格が両条件を満たすことを要求)。
// visible = true は元の pc (getQueryBuilderBySearchDataForAdmin) と揃え、
// 出力レンジ (ProductPriceStockSummarizer は非表示規格を除外) と母集団を一致させる。
if (null !== $stockMin || null !== $stockMax) {
    $dql = 'SELECT pcStock.id FROM '.ProductClass::class.' pcStock'
        .' WHERE pcStock.Product = p AND pcStock.visible = true AND pcStock.stock_unlimited = false';
    if (null !== $stockMin) {
        $dql .= ' AND pcStock.stock >= :mcpStockMin';
    }
    if (null !== $stockMax) {
        $dql .= ' AND pcStock.stock <= :mcpStockMax';
    }
    $qb->andWhere($qb->expr()->exists($dql));
    if (null !== $stockMin) {
        $qb->setParameter('mcpStockMin', $stockMin);
    }
    if (null !== $stockMax) {
        $qb->setParameter('mcpStockMax', $stockMax);
    }
}

A をレンジ交差のまま維持する判断であれば、visible の追加（＝C の修正）だけ入れて docblock に交差セマンティクスを明記する形でも構いません。A はどちらの解釈を採るかの仕様判断なので、実装前に方針だけ合わせさせてください。

---

検証方法: コード読解 ＋ 実 DB への直 SQL ＋ eccube:cli:search_products の実機実行（件数は SQL と実機で一致）。ブラウザ経路は手元環境がメンテナンスモードのままで未確認です。

[dotani1111]

再確認レビューありがとうございます。
残りの A / C / B に対応しました（現 HEAD 0b8eff6dea）。

A（仕様判断）は単一 EXISTS を採用しました。
「[stockMin, stockMax] に入る規格を 1 つ以上持つ商品」という、EXISTS 化前と同じ契約です。
docblock（ツール契約）にこの意味を明記しました。

C は EXISTS に visible = true を足しました。
出力レンジ（ProductPriceStockSummarizer）は非表示規格を除外して集計するため、絞り込みの母集団もそこに揃え、非表示規格だけが在庫条件を満たす商品は返しません。
A と同じ 1 本の EXISTS にまとめたので、修正は 1 箇所です。

B は SearchProductsToolTest に回帰テストを足しました。

• 絞り込みの有無で在庫レンジが縮まないこと（②の回帰ガード）
• 範囲内の規格を持たない商品がヒットしないこと（A）
• 非表示規格だけが条件を満たす商品がヒットしないこと（C）