feat(market-intel): add mcp activation runbook

docs/adr/ADR-035-cross-platform-market-campaign-intelligence.md

@@ -155,6 +155,7 @@ EwoooC 目前已有 MOMO EDM / 節慶活動資料、`promo_products`、PChome
 - 2026-05-18 追加 MCP readiness preview：`/api/market_intel/mcp_readiness` 預設 `execute=false` 只回 planned，盤點 ADR-031 外部 MCP server、`services.mcp_router` feature flag、tool registry、`mcp_calls` telemetry 與 market_intel tool contract 缺口。人工 smoke 才能以 `execute=true` 做只讀 health / telemetry probe；此探針不得寫 DB、不得建立 ORM session、不得替市場情報自動啟用 MCP 或外部爬取。
 - 2026-05-18 追加 internal MCP tool contract preview：`services.market_intel.mcp_contract` 與 `/api/market_intel/mcp_tool_contract` 定義 `market_campaign_search`、`market_campaign_scrape`、`market_product_match_lookup` 三個 read-only contract，並在 `services.mcp_router.TOOL_REGISTRY` 註冊 `market_intel` caller 白名單。此階段只建立可審核合約與 readiness 檢查，不啟用 `MCP_ROUTER_ENABLED`、不呼叫 MCP server、不寫 DB、不掛 scheduler。
 - 2026-05-18 追加 external MCP deploy preflight preview：`services.market_intel.mcp_deploy_preflight` 與 `/api/market_intel/mcp_deploy_preflight` 只讀檢查 `docker-compose.mcp.yml`、必要 env、localhost-only ports、read-only volume、Firecrawl resource guard 與 fallback plan。`docker-compose.mcp.yml` 需以 read-only bind mount 進 app 容器供 preflight 審核。此 preflight 不執行 docker/SSH、不建立 `mcp_readonly` role、不啟用 `MCP_ROUTER_ENABLED`、不寫 DB、不掛 scheduler；外部 MCP stack 須等 env 與 operator smoke 全過後另行批准。
+- 2026-05-18 追加 MCP activation runbook preview：`services.market_intel.mcp_activation_runbook` 與 `/api/market_intel/mcp_activation_runbook` 只輸出人工啟用順序與 gate：補必要 env、人工建立/驗證 `mcp_readonly`、啟動外部 MCP stack、四個 health 全過、最後才允許 `MCP_ROUTER_ENABLED=true`。此 runbook 不執行 docker/SSH、不寫 env、不建立 DB role、不跑 health、不啟用 router、不寫 DB、不掛 scheduler。
 
 ### Phase 4：Coupang / Shopee Adapter
 

routes/README.md

@@ -19,7 +19,7 @@
 | `edm_routes.py` | EDM 與節慶儀表板 | `/edm`, `/festival` |
 | `monthly_routes.py` | 月結分析 | `/monthly_summary_analysis`, `/api/monthly_summary_data` |
 | `daily_sales_routes.py` | 當日業績 | `/daily_sales`, `/daily_sales/export*` |
-| `market_intel_routes.py` | 市場情報 Phase 30 external MCP preflight preview | `/market_intel`, `/market_intel/*`, `/api/market_intel/status`, `/api/market_intel/schema`, `/api/market_intel/schema_smoke`, `/api/market_intel/schema_db_probe`, `/api/market_intel/platform_seed_db_diff`, `/api/market_intel/legacy_source_bridge`, `/api/market_intel/mcp_readiness`, `/api/market_intel/mcp_tool_contract`, `/api/market_intel/mcp_deploy_preflight`, `/api/market_intel/adapters`, `/api/market_intel/dry_run_plan`, `/api/market_intel/discovery_plan`, `/api/market_intel/manual_discovery`, `/api/market_intel/candidate_preview`, `/api/market_intel/platform_seed_plan`, `/api/market_intel/platform_seed_write_guard`, `/api/market_intel/platform_seed_writer_plan`, `/api/market_intel/migration_blueprint`, `/api/market_intel/seed_writer_cli_status`, `/api/market_intel/write_approval_runbook`, `/api/market_intel/deployment_readiness` |
+| `market_intel_routes.py` | 市場情報 Phase 31 MCP activation runbook preview | `/market_intel`, `/market_intel/*`, `/api/market_intel/status`, `/api/market_intel/schema`, `/api/market_intel/schema_smoke`, `/api/market_intel/schema_db_probe`, `/api/market_intel/platform_seed_db_diff`, `/api/market_intel/legacy_source_bridge`, `/api/market_intel/mcp_readiness`, `/api/market_intel/mcp_tool_contract`, `/api/market_intel/mcp_deploy_preflight`, `/api/market_intel/mcp_activation_runbook`, `/api/market_intel/adapters`, `/api/market_intel/dry_run_plan`, `/api/market_intel/discovery_plan`, `/api/market_intel/manual_discovery`, `/api/market_intel/candidate_preview`, `/api/market_intel/platform_seed_plan`, `/api/market_intel/platform_seed_write_guard`, `/api/market_intel/platform_seed_writer_plan`, `/api/market_intel/migration_blueprint`, `/api/market_intel/seed_writer_cli_status`, `/api/market_intel/write_approval_runbook`, `/api/market_intel/deployment_readiness` |
 | `api_routes.py` | 通用任務與查詢 API | `/api/run_task`, `/api/history/*` |
 | `export_routes.py` | 匯出功能 | `/api/export/*` |
 | `import_routes.py` | 匯入功能 | `/api/import_excel`, `/api/import/monthly_summary` |

routes/market_intel_routes.py

@@ -132,6 +132,12 @@ def market_intel_mcp_deploy_preflight():
     return jsonify(_service().build_mcp_deploy_preflight())
 
 
+@market_intel_bp.route("/api/market_intel/mcp_activation_runbook")
+@login_required
+def market_intel_mcp_activation_runbook():
+    return jsonify(_service().build_mcp_activation_runbook())
+
+
 @market_intel_bp.route("/api/market_intel/adapters")
 @login_required
 def market_intel_adapters():

services/market_intel/mcp_activation_runbook.py

@@ -0,0 +1,170 @@
+"""外部 MCP 啟用 runbook preview。
+
+只組裝人工操作順序、gate、command shape 與 fallback；不執行 docker、SSH、
+SQL、health check、env 寫入或 router 啟用。
+"""
+
+from services.market_intel.mcp_deploy_preflight import build_mcp_deploy_preflight_plan
+from services.market_intel.mcp_readiness import build_mcp_readiness_plan
+
+
+def _step(key, label, gate, status, command_preview=None, notes=None):
+    item = {
+        "key": key,
+        "label": label,
+        "gate": gate,
+        "status": status,
+    }
+    if command_preview:
+        item["command_preview"] = command_preview
+    if notes:
+        item["notes"] = notes
+    return item
+
+
+def build_mcp_activation_runbook_preview(
+    *,
+    preflight=None,
+    readiness=None,
+):
+    """建立 MCP 啟用流程；預設只讀 planned，不做 health / DB / docker。"""
+    preflight = preflight or build_mcp_deploy_preflight_plan()
+    readiness = readiness or build_mcp_readiness_plan(execute_requested=False)
+    required_env_ready = bool(preflight["checks"].get("required_env_vars_present"))
+    compose_ready = bool(
+        preflight["checks"].get("compose_file_present")
+        and preflight["checks"].get("all_expected_services_declared")
+        and preflight["checks"].get("all_expected_containers_declared")
+        and preflight["checks"].get("all_public_mcp_ports_localhost_only")
+    )
+    readonly_design_ready = bool(
+        preflight["checks"].get("postgres_readonly_role_required")
+        and preflight["checks"].get("postgres_allowed_tables_limited")
+        and preflight["checks"].get("filesystem_mounts_read_only")
+    )
+    resource_guard_ready = bool(
+        preflight["checks"].get("firecrawl_resource_guard_present")
+        and preflight["checks"].get("chrome_reaper_declared")
+    )
+    router_still_off = bool(preflight["checks"].get("router_flag_still_off_before_health"))
+    health_checked = bool(readiness["readiness_checks"].get("external_server_health_checked"))
+    all_health_passed = bool(readiness["readiness_checks"].get("external_servers_all_healthy"))
+    contract_ready = bool(readiness["readiness_checks"].get("market_intel_tool_contract_ready"))
+
+    stages = [
+        _step(
+            "configure_required_env",
+            "設定 MCP_POSTGRES_PASSWORD、TAVILY_API_KEY、EXA_API_KEY，值不得寫入 repo",
+            "required_env_vars_present",
+            "ready" if required_env_ready else "blocked",
+        ),
+        _step(
+            "create_mcp_readonly_role",
+            "人工確認 momo-db 內存在 mcp_readonly，且只 GRANT 允許表 SELECT",
+            "postgres_readonly_role_required",
+            "ready" if readonly_design_ready else "blocked",
+            command_preview="psql \"$DATABASE_URL\" -v ON_ERROR_STOP=1 -f <reviewed_mcp_readonly_grants.sql>",
+            notes="不可 stop/rm/recreate momo-db；只允許 operator 在 DB 內建立或修正 readonly role。",
+        ),
+        _step(
+            "start_external_mcp_stack",
+            "在 188 主機啟動 docker-compose.mcp.yml 管理的 momo-mcp-* stack",
+            "preflight_ready_to_start_stack",
+            "ready" if preflight["ready_to_start_stack"] else "blocked",
+            command_preview=preflight.get("operator_command_preview"),
+        ),
+        _step(
+            "run_mcp_health_smoke",
+            "確認 3001/3002/3003/3004 四個 localhost health endpoint 全部 200",
+            "external_servers_all_healthy",
+            "pass" if all_health_passed else "pending" if health_checked else "blocked",
+            command_preview="curl http://localhost:3001/health && curl http://localhost:3002/health && curl http://localhost:3003/health && curl http://localhost:3004/health",
+        ),
+        _step(
+            "enable_mcp_router_flag",
+            "只有 health 全過且 operator 批准後，才可設定 MCP_ROUTER_ENABLED=true",
+            "router_enable_after_health",
+            "ready" if all_health_passed and router_still_off and contract_ready else "blocked",
+            command_preview="MCP_ROUTER_ENABLED=true docker compose up -d --no-deps --force-recreate momo-app",
+        ),
+        _step(
+            "run_market_intel_mcp_smoke",
+            "啟用 router 後只跑 market_intel MCP read-only smoke，不寫 market_*",
+            "market_intel_contract_ready",
+            "ready" if contract_ready and all_health_passed else "blocked",
+            command_preview="/api/market_intel/mcp_readiness?execute=true&timeout=3",
+        ),
+    ]
+
+    checks = {
+        "compose_ready": compose_ready,
+        "required_env_ready": required_env_ready,
+        "readonly_design_ready": readonly_design_ready,
+        "resource_guard_ready": resource_guard_ready,
+        "router_still_off_before_health": router_still_off,
+        "market_intel_contract_ready": contract_ready,
+        "health_checked": health_checked,
+        "all_health_passed": all_health_passed,
+        "no_activation_actions_executed": True,
+        "no_database_lifecycle_action_executed": True,
+        "no_database_write_executed": True,
+    }
+    blocked_reasons = [
+        key for key, passed in checks.items()
+        if not passed and key not in {
+            "health_checked",
+            "all_health_passed",
+        }
+    ]
+    if not health_checked:
+        blocked_reasons.append("external_health_smoke_not_executed")
+    elif not all_health_passed:
+        blocked_reasons.append("external_health_smoke_not_passed")
+
+    return {
+        "mode": "mcp_activation_runbook_preview",
+        "ready_for_operator_activation": not blocked_reasons,
+        "checks": checks,
+        "blocked_reasons": blocked_reasons,
+        "stages": stages,
+        "required_env_vars": [
+            item["name"]
+            for item in preflight.get("env_statuses", [])
+            if item.get("required")
+        ],
+        "post_start_health_targets": preflight.get("post_start_health_targets", []),
+        "fallback_plan": [
+            {
+                "key": "router_flag_kill_switch",
+                "label": "若 smoke 失敗，先把 MCP_ROUTER_ENABLED 關回 false，只 recreate momo-app",
+            },
+            {
+                "key": "stop_mcp_stack_only",
+                "label": "外部 MCP stack 異常時，只停 docker-compose.mcp.yml 管理的 momo-mcp-* 容器",
+            },
+            {
+                "key": "preserve_momo_db",
+                "label": "不得 stop/rm/recreate momo-db；必要時只撤回 mcp_readonly grants",
+            },
+        ],
+        "safety_contract": {
+            "does_not_execute_docker": True,
+            "does_not_execute_ssh": True,
+            "does_not_write_env": True,
+            "does_not_create_db_role": True,
+            "does_not_run_health_check": True,
+            "does_not_enable_router": True,
+            "does_not_write_database": True,
+            "does_not_attach_scheduler": True,
+        },
+        "deployment_actions_executed": False,
+        "docker_command_executed": False,
+        "ssh_command_executed": False,
+        "database_session_created": False,
+        "database_write_executed": False,
+        "database_commit_executed": False,
+        "external_network_executed": False,
+        "scheduler_attached": False,
+        "writes_executed": False,
+        "would_write_database": False,
+    }

services/market_intel/service.py

@@ -20,6 +20,7 @@ from services.market_intel.adapters import (
 from services.market_intel.candidate_preview import build_candidate_preview_from_discovery
 from services.market_intel.discovery_runner import ManualDiscoveryRunner
 from services.market_intel.legacy_source_bridge import build_legacy_source_bridge_plan
+from services.market_intel.mcp_activation_runbook import build_mcp_activation_runbook_preview
 from services.market_intel.mcp_contract import build_mcp_tool_contract_preview
 from services.market_intel.mcp_deploy_preflight import build_mcp_deploy_preflight_plan
 from services.market_intel.mcp_readiness import build_mcp_readiness_plan
@@ -66,7 +67,7 @@ class MarketIntelRuntimeStatus:
 class MarketIntelService:
     """市場情報入口服務，先集中 feature gate 與安全狀態。"""
 
-    phase = "phase_30_external_mcp_preflight_preview"
+    phase = "phase_31_mcp_activation_runbook_preview"
 
     def get_runtime_status(self) -> MarketIntelRuntimeStatus:
         return MarketIntelRuntimeStatus(
@@ -335,6 +336,17 @@ class MarketIntelService:
         preflight["phase"] = self.phase
         return preflight
 
+    def build_mcp_activation_runbook(self):
+        """回報 MCP 啟用順序與 gate；不執行任何啟用動作。"""
+        preflight = self.build_mcp_deploy_preflight()
+        readiness = self.build_mcp_readiness()
+        runbook = build_mcp_activation_runbook_preview(
+            preflight=preflight,
+            readiness=readiness,
+        )
+        runbook["phase"] = self.phase
+        return runbook
+
     def build_platform_seed_writer_plan(self, platform_code="all"):
         """建立 platform seed writer dry-run plan，不建立 DB session。"""
         seed_plan = self.build_platform_seed_plan(platform_code=platform_code)
@@ -412,6 +424,7 @@ class MarketIntelService:
         schema_smoke = build_schema_smoke(MARKET_INTEL_TABLES)
         writer_plan = self.build_platform_seed_writer_plan()
         mcp_deploy_preflight = self.build_mcp_deploy_preflight()
+        mcp_activation_runbook = self.build_mcp_activation_runbook()
         checks = {
             "schema_smoke_passed": bool(schema_smoke["passed"]),
             "feature_flags_default_safe": bool(
@@ -447,6 +460,10 @@ class MarketIntelService:
                 mcp_deploy_preflight["mode"] == "mcp_external_deploy_preflight_preview"
                 and not mcp_deploy_preflight["deployment_actions_executed"]
             ),
+            "mcp_activation_runbook_preview_safe": bool(
+                mcp_activation_runbook["mode"] == "mcp_activation_runbook_preview"
+                and not mcp_activation_runbook["deployment_actions_executed"]
+            ),
         }
         ready_for_production_deploy = all(checks.values())
         blocked_reasons = [
@@ -573,6 +590,7 @@ class MarketIntelService:
                 "/api/market_intel/mcp_readiness",
                 "/api/market_intel/mcp_tool_contract",
                 "/api/market_intel/mcp_deploy_preflight",
+                "/api/market_intel/mcp_activation_runbook",
             ],
             "status": status.to_dict(),
             "schema_smoke": schema_smoke,
@@ -590,4 +608,5 @@ class MarketIntelService:
             "mcp_readiness": self.build_mcp_readiness(),
             "mcp_tool_contract": self.build_mcp_tool_contract(),
             "mcp_deploy_preflight": mcp_deploy_preflight,
+            "mcp_activation_runbook": mcp_activation_runbook,
         }

templates/market_intel/disabled.html

@@ -450,6 +450,24 @@
         </div>
     </div>
 
+    <div class="market-intel-panel" data-market-intel-mcp-activation>
+        <div class="market-intel-preview-head">
+            <div>
+                <p class="market-intel-muted momo-mono mb-1">MCP / ACTIVATION RUNBOOK</p>
+                <h2 class="market-intel-preview-title">MCP 啟用 Runbook</h2>
+            </div>
+            <button class="market-intel-icon-button" type="button" title="重新整理 MCP 啟用 Runbook" data-market-intel-mcp-activation-refresh>
+                <i class="fas fa-rotate-right" aria-hidden="true"></i>
+            </button>
+        </div>
+        <div class="market-intel-preview-meta" data-market-intel-mcp-activation-meta>
+            <span class="market-intel-pill">loading</span>
+        </div>
+        <div data-market-intel-mcp-activation-body>
+            <div class="market-intel-empty">讀取 MCP 啟用 Runbook 中...</div>
+        </div>
+    </div>
+
     <div class="market-intel-panel" data-market-intel-migration>
         <div class="market-intel-preview-head">
             <div>
@@ -517,10 +535,11 @@
         const legacyBridgeRoot = document.querySelector('[data-market-intel-legacy-bridge]');
         const mcpReadinessRoot = document.querySelector('[data-market-intel-mcp-readiness]');
         const mcpPreflightRoot = document.querySelector('[data-market-intel-mcp-preflight]');
+        const mcpActivationRoot = document.querySelector('[data-market-intel-mcp-activation]');
         const migrationRoot = document.querySelector('[data-market-intel-migration]');
         const approvalRoot = document.querySelector('[data-market-intel-approval]');
         const deployRoot = document.querySelector('[data-market-intel-deploy]');
-        if (!root && !writerRoot && !cliRoot && !dbProbeRoot && !seedDiffRoot && !legacyBridgeRoot && !mcpReadinessRoot && !mcpPreflightRoot && !migrationRoot && !approvalRoot && !deployRoot) return;
+        if (!root && !writerRoot && !cliRoot && !dbProbeRoot && !seedDiffRoot && !legacyBridgeRoot && !mcpReadinessRoot && !mcpPreflightRoot && !mcpActivationRoot && !migrationRoot && !approvalRoot && !deployRoot) return;
 
         const meta = root ? root.querySelector('[data-market-intel-preview-meta]') : null;
         const body = root ? root.querySelector('[data-market-intel-preview-body]') : null;
@@ -554,6 +573,10 @@
         const mcpPreflightBody = mcpPreflightRoot ? mcpPreflightRoot.querySelector('[data-market-intel-mcp-preflight-body]') : null;
         const mcpPreflightRefresh = mcpPreflightRoot ? mcpPreflightRoot.querySelector('[data-market-intel-mcp-preflight-refresh]') : null;
         const mcpPreflightEndpoint = "{{ url_for('market_intel.market_intel_mcp_deploy_preflight') }}";
+        const mcpActivationMeta = mcpActivationRoot ? mcpActivationRoot.querySelector('[data-market-intel-mcp-activation-meta]') : null;
+        const mcpActivationBody = mcpActivationRoot ? mcpActivationRoot.querySelector('[data-market-intel-mcp-activation-body]') : null;
+        const mcpActivationRefresh = mcpActivationRoot ? mcpActivationRoot.querySelector('[data-market-intel-mcp-activation-refresh]') : null;
+        const mcpActivationEndpoint = "{{ url_for('market_intel.market_intel_mcp_activation_runbook') }}";
         const migrationMeta = migrationRoot ? migrationRoot.querySelector('[data-market-intel-migration-meta]') : null;
         const migrationBody = migrationRoot ? migrationRoot.querySelector('[data-market-intel-migration-body]') : null;
         const migrationRefresh = migrationRoot ? migrationRoot.querySelector('[data-market-intel-migration-refresh]') : null;
@@ -1092,6 +1115,86 @@
             }
         };
 
+        const renderMcpActivationMeta = data => {
+            mcpActivationMeta.innerHTML = [
+                `mode=${data.mode || 'unknown'}`,
+                `ready=${data.ready_for_operator_activation ? 'yes' : 'no'}`,
+                `stages=${(data.stages || []).length}`,
+                `blocked=${(data.blocked_reasons || []).length}`,
+                `docker=${data.docker_command_executed ? 'executed' : 'blocked'}`
+            ].map(item => `<span class="market-intel-pill">${escapeHtml(item)}</span>`).join('');
+        };
+
+        const renderMcpActivationBody = data => {
+            const blockers = (data.blocked_reasons || []).join(' / ');
+            const stages = data.stages || [];
+            const fallback = data.fallback_plan || [];
+            const safety = Object.entries(data.safety_contract || {});
+            const renderStage = item => `
+                <article class="market-intel-operation">
+                    <strong>${escapeHtml(item.key)}</strong>
+                    <small>${escapeHtml(item.label)}</small>
+                    <small>gate=${escapeHtml(item.gate)} / status=${escapeHtml(item.status)}</small>
+                    ${item.command_preview ? `<small>${escapeHtml(item.command_preview)}</small>` : ''}
+                    ${item.notes ? `<small>${escapeHtml(item.notes)}</small>` : ''}
+                </article>
+            `;
+            const renderCheck = (key, label, status) => `
+                <div class="market-intel-check">
+                    <div>
+                        <strong>${escapeHtml(key)}</strong>
+                        <small>${escapeHtml(label || '')}</small>
+                    </div>
+                    <span>${escapeHtml(status)}</span>
+                </div>
+            `;
+
+            mcpActivationBody.innerHTML = `
+                <div class="market-intel-empty mb-3">這是 MCP 啟用順序預覽；不寫 env、不執行 docker/SSH、不建立 DB role、不開 router。${blockers ? `阻擋：${escapeHtml(blockers)}` : ''}</div>
+                <div class="market-intel-deploy-grid">
+                    <div data-market-intel-mcp-activation-stages>
+                        <p class="market-intel-deploy-section-title">ACTIVATION STAGES</p>
+                        <div class="market-intel-operation-list">${
+                            stages.length
+                                ? stages.map(renderStage).join('')
+                                : '<div class="market-intel-empty">尚未提供啟用步驟。</div>'
+                        }</div>
+                    </div>
+                    <div data-market-intel-mcp-activation-safety>
+                        <p class="market-intel-deploy-section-title">SAFETY CONTRACT</p>
+                        <div class="market-intel-check-list">${
+                            safety.length
+                                ? safety.map(([key, value]) => renderCheck(key, '', value ? 'YES' : 'NO')).join('')
+                                : '<div class="market-intel-empty">尚未提供安全合約。</div>'
+                        }</div>
+                    </div>
+                    <div data-market-intel-mcp-activation-fallback>
+                        <p class="market-intel-deploy-section-title">FALLBACK</p>
+                        <div class="market-intel-check-list">${
+                            fallback.length
+                                ? fallback.map(item => renderCheck(item.key, item.label, 'READY')).join('')
+                                : '<div class="market-intel-empty">尚未提供備援方案。</div>'
+                        }</div>
+                    </div>
+                </div>
+            `;
+        };
+
+        const loadMcpActivation = async () => {
+            if (!mcpActivationMeta || !mcpActivationBody) return;
+            mcpActivationBody.innerHTML = '<div class="market-intel-empty">讀取 MCP 啟用 Runbook 中...</div>';
+            try {
+                const response = await fetch(mcpActivationEndpoint, { credentials: 'same-origin' });
+                if (!response.ok) throw new Error(`HTTP ${response.status}`);
+                const data = await response.json();
+                renderMcpActivationMeta(data);
+                renderMcpActivationBody(data);
+            } catch (error) {
+                mcpActivationMeta.innerHTML = '<span class="market-intel-pill">error</span>';
+                mcpActivationBody.innerHTML = `<div class="market-intel-empty">MCP 啟用 Runbook 讀取失敗：${escapeHtml(error.message)}</div>`;
+            }
+        };
+
         const renderMigrationMeta = data => {
             const seedWriter = data.command_plan && data.command_plan.seed_writer_command
                 ? data.command_plan.seed_writer_command
@@ -1350,6 +1453,9 @@
         if (mcpPreflightRefresh) {
             mcpPreflightRefresh.addEventListener('click', loadMcpPreflight);
         }
+        if (mcpActivationRefresh) {
+            mcpActivationRefresh.addEventListener('click', loadMcpActivation);
+        }
         if (migrationRefresh) {
             migrationRefresh.addEventListener('click', loadMigration);
         }
@@ -1367,6 +1473,7 @@
         loadLegacyBridge();
         loadMcpReadiness();
         loadMcpPreflight();
+        loadMcpActivation();
         loadMigration();
         loadApproval();
         loadDeploy();

tests/test_market_intel_skeleton.py

@@ -14,6 +14,7 @@ from services.market_intel.adapters import get_adapter, get_adapter_summaries
 from services.market_intel.candidate_preview import build_candidate_preview_from_discovery
 from services.market_intel.discovery_runner import ManualDiscoveryRunner
 from services.market_intel.html_diagnostics import parse_html_diagnostics
+from services.market_intel.mcp_activation_runbook import build_mcp_activation_runbook_preview
 from services.market_intel.mcp_contract import build_mcp_tool_contract_preview
 from services.market_intel.mcp_deploy_preflight import build_mcp_deploy_preflight_plan
 from services.market_intel.mcp_readiness import build_mcp_readiness_plan
@@ -394,6 +395,10 @@ def test_market_intel_preview_template_uses_safe_fetch_false_endpoint():
     assert "data-market-intel-mcp-preflight-services" in template
     assert "data-market-intel-mcp-preflight-ports" in template
     assert "data-market-intel-mcp-preflight-fallback" in template
+    assert "data-market-intel-mcp-activation" in template
+    assert "data-market-intel-mcp-activation-stages" in template
+    assert "data-market-intel-mcp-activation-safety" in template
+    assert "data-market-intel-mcp-activation-fallback" in template
     assert "data-market-intel-migration" in template
     assert "data-market-intel-migration-tables" in template
     assert "data-market-intel-approval" in template
@@ -409,6 +414,7 @@ def test_market_intel_preview_template_uses_safe_fetch_false_endpoint():
     assert "market_intel.market_intel_legacy_source_bridge" in template
     assert "market_intel.market_intel_mcp_readiness" in template
     assert "market_intel.market_intel_mcp_deploy_preflight" in template
+    assert "market_intel.market_intel_mcp_activation_runbook" in template
     assert "market_intel.market_intel_migration_blueprint" in template
     assert "market_intel.market_intel_write_approval_runbook" in template
     assert "market_intel.market_intel_deployment_readiness" in template
@@ -434,7 +440,7 @@ def test_legacy_source_bridge_default_is_planned_only():
     bridge = MarketIntelService().build_legacy_source_bridge()
 
     assert bridge["mode"] == "legacy_source_bridge_planned"
-    assert bridge["phase"] == "phase_30_external_mcp_preflight_preview"
+    assert bridge["phase"] == "phase_31_mcp_activation_runbook_preview"
     assert bridge["execute_requested"] is False
     assert bridge["read_only_query_executed"] is False
     assert bridge["database_connection_opened"] is False
@@ -592,7 +598,7 @@ def test_mcp_tool_contract_preview_is_read_only_and_whitelisted():
     contract = MarketIntelService().build_mcp_tool_contract()
 
     assert contract["mode"] == "mcp_tool_contract_preview"
-    assert contract["phase"] == "phase_30_external_mcp_preflight_preview"
+    assert contract["phase"] == "phase_31_mcp_activation_runbook_preview"
     assert contract["caller"] == "market_intel"
     assert contract["contract_ready"] is True
     assert contract["blocked_reasons"] == []
@@ -649,6 +655,91 @@ def test_mcp_tool_contract_route_is_preview_only():
     assert data["scheduler_attached"] is False
 
 
+def test_mcp_activation_runbook_blocks_until_env_and_health_pass():
+    preflight = build_mcp_deploy_preflight_plan(env={})
+    runbook = build_mcp_activation_runbook_preview(preflight=preflight)
+
+    assert runbook["mode"] == "mcp_activation_runbook_preview"
+    assert runbook["ready_for_operator_activation"] is False
+    assert "required_env_ready" in runbook["blocked_reasons"]
+    assert "external_health_smoke_not_executed" in runbook["blocked_reasons"]
+    assert runbook["deployment_actions_executed"] is False
+    assert runbook["docker_command_executed"] is False
+    assert runbook["ssh_command_executed"] is False
+    assert runbook["database_session_created"] is False
+    assert runbook["database_write_executed"] is False
+    assert runbook["database_commit_executed"] is False
+    assert runbook["external_network_executed"] is False
+    assert runbook["scheduler_attached"] is False
+    assert runbook["would_write_database"] is False
+    assert runbook["safety_contract"]["does_not_execute_docker"] is True
+    assert runbook["safety_contract"]["does_not_enable_router"] is True
+    assert {item["key"] for item in runbook["stages"]} == {
+        "configure_required_env",
+        "create_mcp_readonly_role",
+        "start_external_mcp_stack",
+        "run_mcp_health_smoke",
+        "enable_mcp_router_flag",
+        "run_market_intel_mcp_smoke",
+    }
+
+
+def test_mcp_activation_runbook_can_be_ready_with_mocked_gates():
+    preflight = build_mcp_deploy_preflight_plan(
+        env={
+            "MCP_POSTGRES_PASSWORD": "secret",
+            "TAVILY_API_KEY": "tavily",
+            "EXA_API_KEY": "exa",
+            "MCP_ROUTER_ENABLED": "false",
+        }
+    )
+    readiness = {
+        "readiness_checks": {
+            "external_server_health_checked": True,
+            "external_servers_all_healthy": True,
+            "market_intel_tool_contract_ready": True,
+        }
+    }
+
+    runbook = build_mcp_activation_runbook_preview(
+        preflight=preflight,
+        readiness=readiness,
+    )
+
+    assert runbook["ready_for_operator_activation"] is True
+    assert runbook["blocked_reasons"] == []
+    assert runbook["checks"]["required_env_ready"] is True
+    assert runbook["checks"]["all_health_passed"] is True
+    assert {
+        item["key"]: item["status"]
+        for item in runbook["stages"]
+    }["enable_mcp_router_flag"] == "ready"
+
+
+def test_mcp_activation_runbook_route_is_preview_only():
+    from routes.market_intel_routes import market_intel_bp
+
+    app = Flask(__name__)
+    app.secret_key = "test-secret"
+    app.register_blueprint(market_intel_bp)
+    client = app.test_client()
+    with client.session_transaction() as session:
+        session["logged_in"] = True
+
+    response = client.get("/api/market_intel/mcp_activation_runbook")
+    data = response.get_json()
+
+    assert response.status_code == 200
+    assert data["mode"] == "mcp_activation_runbook_preview"
+    assert data["phase"] == "phase_31_mcp_activation_runbook_preview"
+    assert data["deployment_actions_executed"] is False
+    assert data["docker_command_executed"] is False
+    assert data["ssh_command_executed"] is False
+    assert data["database_write_executed"] is False
+    assert data["external_network_executed"] is False
+    assert data["scheduler_attached"] is False
+
+
 def test_mcp_deploy_preflight_blocks_without_required_env():
     preflight = build_mcp_deploy_preflight_plan(env={})
 
@@ -712,7 +803,7 @@ def test_mcp_deploy_preflight_route_is_preview_only():
 
     assert response.status_code == 200
     assert data["mode"] == "mcp_external_deploy_preflight_preview"
-    assert data["phase"] == "phase_30_external_mcp_preflight_preview"
+    assert data["phase"] == "phase_31_mcp_activation_runbook_preview"
     assert data["deployment_actions_executed"] is False
     assert data["docker_command_executed"] is False
     assert data["ssh_command_executed"] is False
@@ -727,7 +818,7 @@ def test_mcp_readiness_default_is_planned_only(monkeypatch):
     readiness = MarketIntelService().build_mcp_readiness()
 
     assert readiness["mode"] == "mcp_readiness_planned"
-    assert readiness["phase"] == "phase_30_external_mcp_preflight_preview"
+    assert readiness["phase"] == "phase_31_mcp_activation_runbook_preview"
     assert readiness["execute_requested"] is False
     assert readiness["router_enabled"] is False
     assert readiness["external_mcp_complete"] is False
@@ -1112,6 +1203,7 @@ def test_deployment_readiness_reports_app_only_release_gate():
     assert readiness["checks"]["mcp_readiness_planned_safe"] is True
     assert readiness["checks"]["mcp_tool_contract_ready"] is True
     assert readiness["checks"]["mcp_deploy_preflight_preview_safe"] is True
+    assert readiness["checks"]["mcp_activation_runbook_preview_safe"] is True
     assert readiness["checks"]["writer_plan_dry_run_only"] is True
     assert readiness["writer_plan_summary"]["writes_executed"] is False
     assert "readiness_checks_not_all_passed" not in readiness["blocked_reasons"]
@@ -1130,6 +1222,7 @@ def test_deployment_readiness_reports_app_only_release_gate():
     assert "/api/market_intel/mcp_readiness" in readiness["production_smoke_targets"]
     assert "/api/market_intel/mcp_tool_contract" in readiness["production_smoke_targets"]
     assert "/api/market_intel/mcp_deploy_preflight" in readiness["production_smoke_targets"]
+    assert "/api/market_intel/mcp_activation_runbook" in readiness["production_smoke_targets"]
     assert readiness["write_approval_runbook"]["ready_for_real_write"] is False
     assert readiness["write_approval_runbook"]["writes_executed"] is False
     assert readiness["migration_blueprint"]["migration_executed"] is False
@@ -1144,6 +1237,8 @@ def test_deployment_readiness_reports_app_only_release_gate():
     assert readiness["mcp_tool_contract"]["database_write_executed"] is False
     assert readiness["mcp_deploy_preflight"]["deployment_actions_executed"] is False
     assert readiness["mcp_deploy_preflight"]["docker_command_executed"] is False
+    assert readiness["mcp_activation_runbook"]["deployment_actions_executed"] is False
+    assert readiness["mcp_activation_runbook"]["docker_command_executed"] is False
 
 
 def test_write_approval_runbook_is_read_only_and_blocks_real_write():