frontend-perception-engine 0.1.0__py3-none-any.whl

navigation/mcp/instructions.py

@@ -0,0 +1,36 @@
+"""MCP server preamble — programs host agent behavior. See AGENT_GUIDE.md for full playbooks."""
+
+MCP_INSTRUCTIONS = """\
+Frontend Perception MCP — deterministic browser runtime (no LLM inside this server).
+
+YOU are the brain. This server returns facts only — never "next step" suggestions.
+Read AGENT_GUIDE.md at session start (resource: perception://agent-guide).
+
+Universal loop (AGENT_GUIDE §0):
+  OBSERVE → REASON → ACT → VERIFY → repeat or STOP
+
+Bootstrap (§1):
+  perception_health → perception_session_start → save session_id
+
+Playbooks by task (AGENT_GUIDE.md):
+  §2  Page inspection / new UI     → navigate_and_observe, verify, diff
+  §3  Debugging broken UI          → observe blocking first, fix code, verify + diff
+  §4  Forms & validation           → probe_form, invalid submit, verify, valid fill, verify
+  §5  Navigation & route guards    → probe_guards, auth_gate, state_save/restore
+  §6  Multi-step flows             → flow_describe, per-checkpoint verify
+  §7  Regression verify-only       → observe + verify (no act unless fail)
+  §8  Responsive / viewport        → session_start with viewport, observe + screenshot
+  §9  Feature flags & edge UI      → edge-lab routes, feature-specific verify
+  §10 Code ↔ live UI             → code_context + observe + diff
+
+Hard rules:
+- Never claim UI work is done without perception_verify.
+- Never skip verify after execute_script or execute_actions.
+- Read agent_summary.blocking before advisory warnings.
+- On verify failure: re-observe with screenshot, then perception_diff.
+- perception_auth_gate requires_human → STOP, ask user (no login/MFA loops).
+- probe_form before filling unknown forms; invalid submit before valid.
+- flow_describe gives checkpoints — YOU execute each; MCP does not run flows.
+
+Eval scenario (smoke test your wiring): perception://eval/validation-form
+"""

navigation/mcp/resources.py

@@ -0,0 +1,82 @@
+"""MCP resources — guides, evals, and scan artifacts."""
+from __future__ import annotations
+
+import base64
+import json
+from pathlib import Path
+
+from .scan_registry import ScanRegistry
+
+PROJECT_ROOT = Path(__file__).resolve().parents[3]
+
+
+def list_resources(scans: ScanRegistry | None = None) -> list[dict[str, str]]:
+    resources = [
+        {
+            "uri": "perception://agent-guide",
+            "name": "AGENT_GUIDE",
+            "description": "Primary behavior contract — playbooks for host agent (read at session start)",
+            "mimeType": "text/markdown",
+        },
+        {
+            "uri": "perception://eval/validation-form",
+            "name": "Validation Form Eval",
+            "description": "M3 eval scenario — complete using AGENT_GUIDE §4 form playbook",
+            "mimeType": "text/markdown",
+        },
+    ]
+    if scans is not None:
+        for rec in scans.all():
+            resources.append(
+                {
+                    "uri": f"perception://scan/{rec.scan_id}/report.json",
+                    "name": f"scan_report_{rec.scan_id}",
+                    "description": f"Observation report for {rec.scan_id}",
+                    "mimeType": "application/json",
+                }
+            )
+            if rec.screenshot_path:
+                resources.append(
+                    {
+                        "uri": f"perception://scan/{rec.scan_id}/screenshot.png",
+                        "name": f"scan_screenshot_{rec.scan_id}",
+                        "description": f"Screenshot image for {rec.scan_id}",
+                        "mimeType": "image/png",
+                    }
+                )
+    return resources
+
+
+def read_resource(uri: str, scans: ScanRegistry | None = None) -> tuple[str, str, bool]:
+    """Return (mime_type, payload, is_blob). Raises KeyError if unknown."""
+    if uri == "perception://agent-guide":
+        path = PROJECT_ROOT / "AGENT_GUIDE.md"
+        if not path.is_file():
+            raise FileNotFoundError(f"AGENT_GUIDE.md not found at {path}")
+        return "text/markdown", path.read_text(encoding="utf-8"), False
+
+    if uri == "perception://eval/validation-form":
+        path = PROJECT_ROOT / "evals" / "VALIDATION_FORM_EVAL.md"
+        if not path.is_file():
+            raise FileNotFoundError(f"eval doc not found at {path}")
+        return "text/markdown", path.read_text(encoding="utf-8"), False
+
+    if uri.startswith("perception://scan/") and scans is not None:
+        # pattern: perception://scan/{scan_id}/(report.json|screenshot.png)
+        parts = uri.split("/")
+        if len(parts) >= 5:
+            scan_id = parts[3]
+            artifact = parts[4]
+            rec = scans.get(scan_id)
+            if rec is None:
+                raise KeyError(uri)
+            if artifact == "report.json":
+                return "application/json", json.dumps(rec.observation, indent=2, default=str), False
+            if artifact == "screenshot.png":
+                screenshot_path = Path(str(rec.screenshot_path or ""))
+                if not screenshot_path.is_file():
+                    return "text/plain", "", False
+                raw = screenshot_path.read_bytes()
+                return "image/png", base64.b64encode(raw).decode("ascii"), True
+
+    raise KeyError(uri)

navigation/mcp/scan_registry.py

@@ -0,0 +1,47 @@
+"""Observation snapshots keyed by scan_id (for diff and audit)."""
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ScanRecord:
+    scan_id: str
+    session_id: str
+    run_id: str
+    url: str
+    observation: dict[str, Any]
+    screenshot_path: str | None = None
+
+
+class ScanRegistry:
+    def __init__(self) -> None:
+        self._scans: dict[str, ScanRecord] = {}
+
+    def register(
+        self,
+        *,
+        session_id: str,
+        run_id: str,
+        url: str,
+        observation: dict[str, Any],
+    ) -> ScanRecord:
+        scan_id = f"scan_{uuid.uuid4().hex[:12]}"
+        rec = ScanRecord(
+            scan_id=scan_id,
+            session_id=session_id,
+            run_id=run_id,
+            url=url,
+            observation=observation,
+            screenshot_path=observation.get("screenshot_path"),
+        )
+        self._scans[scan_id] = rec
+        return rec
+
+    def get(self, scan_id: str) -> ScanRecord | None:
+        return self._scans.get(scan_id)
+
+    def all(self) -> list[ScanRecord]:
+        return list(self._scans.values())

navigation/mcp/server.py

@@ -0,0 +1,229 @@
+"""Frontend Perception MCP server — host agent is the brain; this is the runtime."""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import sys
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+os.environ.setdefault("BROWSER_USE_LOGGING_LEVEL", "warning")
+os.environ.setdefault("BROWSER_USE_SETUP_LOGGING", "false")
+
+logger = logging.getLogger(__name__)
+
+try:
+    import mcp.server.stdio
+    import mcp.types as types
+    from mcp.server import NotificationOptions, Server
+    from mcp.server.models import InitializationOptions
+
+    MCP_AVAILABLE = True
+except ImportError:
+    MCP_AVAILABLE = False
+    types = None  # type: ignore
+
+from .handlers import (
+    handle_auth_gate,
+    handle_code_context,
+    handle_diff,
+    handle_execute_actions,
+    handle_execute_script,
+    handle_flow_describe,
+    handle_health,
+    handle_navigate,
+    handle_navigate_and_observe,
+    handle_observe,
+    handle_probe_form,
+    handle_probe_guards,
+    handle_session_end,
+    handle_session_start,
+    handle_state_list,
+    handle_state_restore,
+    handle_state_save,
+    handle_verify,
+)
+from .instructions import MCP_INSTRUCTIONS
+from .resources import list_resources, read_resource
+from .scan_registry import ScanRegistry
+from .session_store import SessionStore
+from .tools import perception_tools
+
+
+HandlerFn = Callable[..., Awaitable[dict[str, Any]]]
+
+
+class PerceptionMCPServer:
+    def __init__(self) -> None:
+        if not MCP_AVAILABLE:
+            raise RuntimeError("mcp package not installed. pip install mcp")
+        self._store = SessionStore()
+        self._scans = ScanRegistry()
+        self._server = Server("frontend-perception")
+        self._dispatch: dict[str, HandlerFn] = self._build_dispatch()
+
+        @self._server.list_tools()
+        async def list_tools() -> list[types.Tool]:
+            return perception_tools(types)
+
+        @self._server.list_resources()
+        async def list_resources_handler() -> list[types.Resource]:
+            return [
+                types.Resource(
+                    uri=item["uri"],
+                    name=item["name"],
+                    description=item["description"],
+                    mimeType=item["mimeType"],
+                )
+                for item in list_resources(self._scans)
+            ]
+
+        @self._server.read_resource()
+        async def read_resource_handler(uri: str) -> types.TextResourceContents | types.BlobResourceContents:
+            uri_str = str(uri)
+            mime, payload, is_blob = read_resource(uri_str, self._scans)
+            if is_blob:
+                return types.BlobResourceContents(uri=uri_str, mimeType=mime, blob=payload)
+            return types.TextResourceContents(uri=uri_str, mimeType=mime, text=payload)
+
+        @self._server.call_tool()
+        async def call_tool(name: str, arguments: dict[str, Any] | None) -> list[types.TextContent]:
+            args = arguments or {}
+            try:
+                handler = self._dispatch.get(name)
+                if handler is None:
+                    result = {
+                        "contract_version": "1.0",
+                        "tool": name,
+                        "ok": False,
+                        "error": f"unknown tool: {name}",
+                        "data": {},
+                    }
+                else:
+                    result = await handler(args)
+            except Exception as exc:
+                logger.exception("tool %s failed", name)
+                result = {
+                    "contract_version": "1.0",
+                    "tool": name,
+                    "ok": False,
+                    "error": str(exc),
+                    "data": {},
+                }
+            return [types.TextContent(type="text", text=json.dumps(result, indent=2, default=str))]
+
+    def _build_dispatch(self) -> dict[str, HandlerFn]:
+        store = self._store
+        scans = self._scans
+
+        async def health(args: dict[str, Any]) -> dict[str, Any]:
+            return await handle_health(args)
+
+        async def session_start(args: dict[str, Any]) -> dict[str, Any]:
+            return await handle_session_start(store, args)
+
+        async def session_end(args: dict[str, Any]) -> dict[str, Any]:
+            return await handle_session_end(store, args)
+
+        async def navigate(args: dict[str, Any]) -> dict[str, Any]:
+            return await handle_navigate(store, args)
+
+        async def navigate_and_observe(args: dict[str, Any]) -> dict[str, Any]:
+            return await handle_navigate_and_observe(store, scans, args)
+
+        async def observe(args: dict[str, Any]) -> dict[str, Any]:
+            return await handle_observe(store, scans, args)
+
+        async def execute_script(args: dict[str, Any]) -> dict[str, Any]:
+            return await handle_execute_script(store, scans, args)
+
+        async def execute_actions(args: dict[str, Any]) -> dict[str, Any]:
+            return await handle_execute_actions(store, scans, args)
+
+        async def verify(args: dict[str, Any]) -> dict[str, Any]:
+            return await handle_verify(store, args)
+
+        async def diff(args: dict[str, Any]) -> dict[str, Any]:
+            return await handle_diff(scans, args)
+
+        async def auth_gate(args: dict[str, Any]) -> dict[str, Any]:
+            return await handle_auth_gate(store, args)
+
+        async def probe_form(args: dict[str, Any]) -> dict[str, Any]:
+            return await handle_probe_form(store, args)
+
+        async def probe_guards(args: dict[str, Any]) -> dict[str, Any]:
+            return await handle_probe_guards(store, args)
+
+        async def state_save(args: dict[str, Any]) -> dict[str, Any]:
+            return await handle_state_save(store, args)
+
+        async def state_restore(args: dict[str, Any]) -> dict[str, Any]:
+            return await handle_state_restore(store, args)
+
+        async def state_list(args: dict[str, Any]) -> dict[str, Any]:
+            return await handle_state_list(store, args)
+
+        async def flow_describe(args: dict[str, Any]) -> dict[str, Any]:
+            return await handle_flow_describe(args)
+
+        async def code_context(args: dict[str, Any]) -> dict[str, Any]:
+            return await handle_code_context(args)
+
+        return {
+            "perception_health": health,
+            "perception_session_start": session_start,
+            "perception_session_end": session_end,
+            "perception_navigate": navigate,
+            "perception_navigate_and_observe": navigate_and_observe,
+            "perception_observe": observe,
+            "perception_execute_script": execute_script,
+            "perception_execute_actions": execute_actions,
+            "perception_verify": verify,
+            "perception_diff": diff,
+            "perception_auth_gate": auth_gate,
+            "perception_probe_form": probe_form,
+            "perception_probe_guards": probe_guards,
+            "perception_state_save": state_save,
+            "perception_state_restore": state_restore,
+            "perception_state_list": state_list,
+            "perception_flow_describe": flow_describe,
+            "perception_code_context": code_context,
+        }
+
+    async def run(self) -> None:
+        async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
+            await self._server.run(
+                read_stream,
+                write_stream,
+                InitializationOptions(
+                    server_name="frontend-perception",
+                    server_version="0.4.0",
+                    capabilities=self._server.get_capabilities(
+                        notification_options=NotificationOptions(),
+                        experimental_capabilities={},
+                    ),
+                    instructions=MCP_INSTRUCTIONS,
+                ),
+            )
+
+
+async def async_main() -> None:
+    if not MCP_AVAILABLE:
+        print("Install MCP: pip install mcp", file=sys.stderr)
+        raise SystemExit(1)
+    server = PerceptionMCPServer()
+    try:
+        await server.run()
+    finally:
+        await server._store.end_all()
+
+
+def main() -> None:
+    asyncio.run(async_main())
+
+
+if __name__ == "__main__":
+    main()

navigation/mcp/session_store.py

@@ -0,0 +1,87 @@
+"""Browser session lifecycle for MCP tools."""
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from navigation.perception.state_manager import StateManager
+
+
+@dataclass
+class SessionRecord:
+    session_id: str
+    base_url: str
+    browser: Any
+    artifacts_dir: Path
+    state_manager: StateManager = field(default_factory=StateManager)
+    run_counter: int = 0
+    current_run_id: str = ""
+
+    def next_run_id(self) -> str:
+        self.run_counter += 1
+        self.current_run_id = f"run_{self.run_counter:04d}"
+        return self.current_run_id
+
+
+class SessionStore:
+    def __init__(self, artifacts_root: Path | None = None) -> None:
+        self._sessions: dict[str, SessionRecord] = {}
+        self._artifacts_root = artifacts_root or Path.cwd() / "artifacts" / "mcp"
+
+    def get(self, session_id: str) -> SessionRecord | None:
+        return self._sessions.get(session_id)
+
+    def require(self, session_id: str) -> SessionRecord:
+        rec = self.get(session_id)
+        if rec is None:
+            raise KeyError(f"unknown session_id: {session_id}")
+        return rec
+
+    async def start(
+        self,
+        *,
+        base_url: str,
+        headless: bool = True,
+        viewport_width: int = 1920,
+        viewport_height: int = 1080,
+    ) -> SessionRecord:
+        from browser_use import BrowserProfile, BrowserSession
+
+        session_id = f"sess_{uuid.uuid4().hex[:12]}"
+        artifacts_dir = self._artifacts_root / session_id
+        artifacts_dir.mkdir(parents=True, exist_ok=True)
+
+        browser = BrowserSession(
+            browser_profile=BrowserProfile(
+                headless=headless,
+                viewport={"width": viewport_width, "height": viewport_height},
+            )
+        )
+        await browser.start()
+        await browser.navigate_to(base_url.rstrip("/"))
+
+        rec = SessionRecord(
+            session_id=session_id,
+            base_url=base_url.rstrip("/"),
+            browser=browser,
+            artifacts_dir=artifacts_dir,
+        )
+        rec.next_run_id()
+        self._sessions[session_id] = rec
+        return rec
+
+    async def end(self, session_id: str) -> bool:
+        rec = self._sessions.pop(session_id, None)
+        if rec is None:
+            return False
+        try:
+            await rec.browser.kill()
+        except Exception:
+            pass
+        return True
+
+    async def end_all(self) -> None:
+        for sid in list(self._sessions):
+            await self.end(sid)