High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
Add SMCP plugin for PinchTab with full test suite
rootca50139f99ed
diff --git a/.gitignore b/.gitignoreindex 9dc30d64..9721ec85 100644--- a/.gitignore+++ b/.gitignore@@ -1,4 +1,8 @@node_modules/+.venv/+plugins/*/.venv/+__pycache__/+*.pycbrowser-bridge/pinchtabcoverage.outdiff --git a/plugins/README.md b/plugins/README.mdnew file mode 100644index 00000000..75bdaf16--- /dev/null+++ b/plugins/README.md@@ -0,0 +1,13 @@+# PinchTab SMCP Plugins++This directory contains MCP (SMCP) plugins for use with [sanctumos/smcp](https://github.com/sanctumos/smcp) or compatible MCP servers.++## pinchtab++Full SMCP plugin for the PinchTab HTTP API: navigate, snapshot, action, text, screenshot, PDF, instances, tabs, and more.++- **Location:** `pinchtab/`+- **Discovery:** `python cli.py --describe` (JSON with plugin + commands)+- **Tests:** `cd pinchtab && python -m venv .venv && .venv/bin/pip install pytest && .venv/bin/pytest tests/ -v`++See [pinchtab/README.md](pinchtab/README.md) for usage and SMCP compatibility notes.diff --git a/plugins/pinchtab/README.md b/plugins/pinchtab/README.mdnew file mode 100644index 00000000..efd5d7fa--- /dev/null+++ b/plugins/pinchtab/README.md@@ -0,0 +1,53 @@+# PinchTab SMCP Plugin++SMCP (MCP) plugin for [PinchTab](https://github.com/pinchtab/pinchtab): browser control for AI agents via HTTP API.++## Requirements++- Python 3.9++- A running PinchTab server (orchestrator on port 9867 or direct instance on 9868+)+- No extra Python dependencies (uses stdlib only)++## SMCP Compatibility++- **Discovery:** `python cli.py --describe` returns JSON with `plugin` and `commands`.+- **Tool names:** SMCP registers tools as `pinchtab__<command>` (e.g. `pinchtab__navigate`, `pinchtab__snapshot`).+- **Execution:** SMCP runs `python cli.py <command> --arg1 val1 ...`; plugin prints a single JSON object to stdout.+- **Parameters:** All options use `--kebab-case`; SMCP maps from tool args to CLI args.++## Commands++| Command | Description |+|--------|-------------|+| `health` | Health check |+| `instances` | List instances (orchestrator) |+| `instance-start` | Start an instance (optional profile-id, mode, port) |+| `instance-stop` | Stop an instance |+| `tabs` | List tabs |+| `navigate` | Navigate to URL |+| `snapshot` | Get accessibility tree (filter, format, selector, max-tokens, diff) |+| `action` | Single action: click, type, press, focus, fill, hover, select, scroll |+| `actions` | Batch actions (JSON array) |+| `text` | Extract page text |+| `screenshot` | Take screenshot |+| `pdf` | Export tab to PDF |+| `evaluate` | Run JavaScript |+| `cookies-get` | Get cookies |+| `stealth-status` | Stealth/fingerprint status |++## Usage++- **Base URL:** `--base-url http://localhost:9867` (default). Use orchestrator URL or direct instance URL.+- **Orchestrator + instance:** When using the orchestrator, pass `--instance-id inst_xxxx` for instance-scoped calls (navigate, snapshot, action, etc.).+- **Token:** `--token YOUR_TOKEN` when PinchTab is protected with `BRIDGE_TOKEN`.++## Example (SMCP tool call)++Agent calls tool `pinchtab__navigate` with args:+`{"base_url": "http://localhost:9867", "instance_id": "inst_0a89a5bb", "url": "https://example.com"}`++SMCP runs:+`python cli.py navigate --base-url http://localhost:9867 --instance-id inst_0a89a5bb --url https://example.com`++Plugin prints to stdout:+`{"status": "success", "data": {...}}`diff --git a/plugins/pinchtab/cli.py b/plugins/pinchtab/cli.pynew file mode 100644index 00000000..e57e30ad--- /dev/null+++ b/plugins/pinchtab/cli.py@@ -0,0 +1,529 @@+#!/usr/bin/env python3+"""+PinchTab SMCP Plugin++Exposes PinchTab's HTTP API as MCP tools for use with SMCP (sanctumos/smcp).+All operations (navigate, snapshot, action, text, screenshot, etc.) are available.+Supports both single-bridge (base_url = instance) and orchestrator (base_url + instance_id).++Copyright (c) 2026 actuallyrizzn. PinchTab (c) pinchtab.+"""++import argparse+import json+import sys+import traceback+from typing import Any, Dict, List, Optional+from urllib.error import HTTPError, URLError+from urllib.parse import urlencode+from urllib.request import Request, urlopen++PLUGIN_VERSION = "0.1.0"+DEBUG_TRACEBACKS = False+++def _error_response(error: str, error_type: str, include_traceback: bool = False) -> Dict[str, Any]:+ out: Dict[str, Any] = {+ "status": "error",+ "error": error,+ "error_type": error_type,+ }+ if include_traceback and DEBUG_TRACEBACKS:+ out["traceback"] = traceback.format_exc()+ return out+++def _canonical_option_name(action: argparse.Action) -> str:+ for opt in action.option_strings:+ if opt.startswith("--"):+ return opt[2:].replace("_", "-")+ return action.dest.replace("_", "-")+++def _arg_type_name(action: argparse.Action) -> str:+ if isinstance(action, argparse._StoreTrueAction):+ return "boolean"+ if getattr(action, "type", None) is int:+ return "integer"+ if getattr(action, "type", None) is float:+ return "number"+ return "string"+++def _describe_action(action: argparse.Action) -> Optional[Dict[str, Any]]:+ if action.dest in ("help", "command") or getattr(action, "help", None) == argparse.SUPPRESS:+ return None+ default = None if action.default is argparse.SUPPRESS else action.default+ return {+ "name": _canonical_option_name(action),+ "type": _arg_type_name(action),+ "description": (action.help or "").strip(),+ "required": bool(getattr(action, "required", False)),+ "default": default,+ }+++def _get_subparsers_action(parser: argparse.ArgumentParser) -> Optional[argparse._SubParsersAction]:+ for a in parser._actions:+ if isinstance(a, argparse._SubParsersAction):+ return a+ return None+++def _api_request(+ base_url: str,+ method: str,+ path: str,+ token: Optional[str] = None,+ body: Optional[Dict[str, Any]] = None,+ query: Optional[Dict[str, Any]] = None,+ timeout: int = 60,+) -> Dict[str, Any]:+ """Perform HTTP request to PinchTab API. base_url has no trailing slash."""+ url = base_url.rstrip("/") + path+ if query:+ url += "?" + urlencode({k: v for k, v in query.items() if v is not None})+ headers = {"Accept": "application/json", "Content-Type": "application/json"}+ if token:+ headers["Authorization"] = f"Bearer {token}"+ data = json.dumps(body).encode("utf-8") if body else None+ req = Request(url, data=data, method=method, headers=headers)+ try:+ with urlopen(req, timeout=timeout) as resp:+ raw = resp.read().decode("utf-8")+ if not raw:+ return {}+ return json.loads(raw)+ except HTTPError as e:+ try:+ err_body = e.read().decode("utf-8")+ return json.loads(err_body)+ except Exception:+ return _error_response(f"HTTP {e.code}: {e.reason}", "api_error")+ except URLError as e:+ return _error_response(f"Request failed: {e.reason}", "connection_error")+ except json.JSONDecodeError as e:+ return _error_response(f"Invalid JSON: {e}", "parse_error")+++def _instance_path(base_url: str, instance_id: Optional[str]) -> str:+ """Prefix for instance-scoped paths. If instance_id set, base is orchestrator."""+ if instance_id:+ return f"/instances/{instance_id}"+ return ""+++# --- Commands ---++def cmd_health(args: Dict[str, Any], base_url: str, token: Optional[str]) -> Dict[str, Any]:+ path = _instance_path(base_url, args.get("instance-id")) + "/health"+ out = _api_request(base_url, "GET", path or "/health", token=token, timeout=10)+ if "status" in out and out.get("status") == "error":+ return out+ return {"status": "success", "data": out}+++def cmd_instances(args: Dict[str, Any], base_url: str, token: Optional[str]) -> Dict[str, Any]:+ out = _api_request(base_url, "GET", "/instances", token=token)+ if isinstance(out, list):+ return {"status": "success", "instances": out}+ if out.get("status") == "error":+ return out+ return {"status": "success", "data": out}+++def cmd_instance_start(args: Dict[str, Any], base_url: str, token: Optional[str]) -> Dict[str, Any]:+ body = {}+ if args.get("profile-id"):+ body["profileId"] = args["profile-id"]+ if args.get("mode"):+ body["mode"] = args["mode"]+ if args.get("port") is not None:+ body["port"] = str(args["port"])+ out = _api_request(base_url, "POST", "/instances/start", token=token, body=body if body else None)+ if out.get("status") == "error":+ return out+ return {"status": "success", "instance": out}+++def cmd_instance_stop(args: Dict[str, Any], base_url: str, token: Optional[str]) -> Dict[str, Any]:+ iid = args.get("instance-id")+ if not iid:+ return _error_response("instance-id is required", "validation_error")+ out = _api_request(base_url, "POST", f"/instances/{iid}/stop", token=token)+ if out.get("status") == "error":+ return out+ return {"status": "success", "data": out}+++def cmd_tabs(args: Dict[str, Any], base_url: str, token: Optional[str]) -> Dict[str, Any]:+ prefix = _instance_path(base_url, args.get("instance-id"))+ path = f"{prefix}/tabs" if prefix else "/tabs"+ out = _api_request(base_url, "GET", path, token=token)+ if isinstance(out, list):+ return {"status": "success", "tabs": out}+ if out.get("status") == "error":+ return out+ return {"status": "success", "data": out}+++def cmd_navigate(args: Dict[str, Any], base_url: str, token: Optional[str]) -> Dict[str, Any]:+ url = args.get("url")+ if not url:+ return _error_response("url is required", "validation_error")+ prefix = _instance_path(base_url, args.get("instance-id"))+ path = f"{prefix}/navigate" if prefix else "/navigate"+ body = {+ "url": url,+ "timeout": args.get("timeout"),+ "blockImages": args.get("block-images"),+ "newTab": args.get("new-tab"),+ }+ body = {k: v for k, v in body.items() if v is not None}+ out = _api_request(base_url, "POST", path, token=token, body=body)+ if out.get("status") == "error":+ return out+ return {"status": "success", "data": out}+++def cmd_snapshot(args: Dict[str, Any], base_url: str, token: Optional[str]) -> Dict[str, Any]:+ prefix = _instance_path(base_url, args.get("instance-id"))+ path = f"{prefix}/snapshot" if prefix else "/snapshot"+ query = {+ "tabId": args.get("tab-id"),+ "filter": args.get("filter"),+ "format": args.get("format"),+ "selector": args.get("selector"),+ "maxTokens": args.get("max-tokens"),+ "diff": "true" if args.get("diff") else None,+ "depth": args.get("depth"),+ "noAnimations": "true" if args.get("no-animations") else None,+ }+ query = {k: v for k, v in query.items() if v is not None}+ out = _api_request(base_url, "GET", path, token=token, query=query)+ if out.get("status") == "error":+ return out+ return {"status": "success", "data": out}+++def cmd_action(args: Dict[str, Any], base_url: str, token: Optional[str]) -> Dict[str, Any]:+ kind = args.get("kind")+ if not kind:+ return _error_response("kind is required (click, type, press, focus, fill, hover, select, scroll)", "validation_error")+ prefix = _instance_path(base_url, args.get("instance-id"))+ path = f"{prefix}/action" if prefix else "/action"+ body = {"kind": kind}+ if args.get("ref"):+ body["ref"] = args["ref"]+ if args.get("key"):+ body["key"] = args["key"]+ if args.get("text") is not None:+ body["text"] = args["text"]+ if args.get("value") is not None:+ body["value"] = args["value"]+ if args.get("selector"):+ body["selector"] = args["selector"]+ if args.get("scroll-y") is not None:+ body["scrollY"] = args["scroll-y"]+ if args.get("wait-nav"):+ body["waitNav"] = True+ out = _api_request(base_url, "POST", path, token=token, body=body)+ if out.get("status") == "error":+ return out+ return {"status": "success", "data": out}+++def cmd_actions(args: Dict[str, Any], base_url: str, token: Optional[str]) -> Dict[str, Any]:+ actions_list = args.get("actions")+ if not actions_list:+ return _error_response("actions (JSON array) is required", "validation_error")+ if isinstance(actions_list, str):+ try:+ actions_list = json.loads(actions_list)+ except json.JSONDecodeError:+ return _error_response("actions must be a JSON array", "validation_error")+ prefix = _instance_path(base_url, args.get("instance-id"))+ path = f"{prefix}/actions" if prefix else "/actions"+ body = {"actions": actions_list, "stopOnError": args.get("stop-on-error", False)}+ if args.get("tab-id"):+ body["tabId"] = args["tab-id"]+ out = _api_request(base_url, "POST", path, token=token, body=body)+ if out.get("status") == "error":+ return out+ return {"status": "success", "data": out}+++def cmd_text(args: Dict[str, Any], base_url: str, token: Optional[str]) -> Dict[str, Any]:+ prefix = _instance_path(base_url, args.get("instance-id"))+ path = f"{prefix}/text" if prefix else "/text"+ query = {"tabId": args.get("tab-id"), "mode": args.get("mode")}+ query = {k: v for k, v in query.items() if v is not None}+ out = _api_request(base_url, "GET", path, token=token, query=query)+ if out.get("status") == "error":+ return out+ return {"status": "success", "data": out}+++def cmd_screenshot(args: Dict[str, Any], base_url: str, token: Optional[str]) -> Dict[str, Any]:+ prefix = _instance_path(base_url, args.get("instance-id"))+ path = f"{prefix}/screenshot" if prefix else "/screenshot"+ query = {"tabId": args.get("tab-id"), "raw": "true" if args.get("raw") else None, "quality": args.get("quality")}+ query = {k: v for k, v in query.items() if v is not None}+ out = _api_request(base_url, "GET", path, token=token, query=query)+ if out.get("status") == "error":+ return out+ return {"status": "success", "data": out}+++def cmd_pdf(args: Dict[str, Any], base_url: str, token: Optional[str]) -> Dict[str, Any]:+ tab_id = args.get("tab-id")+ if not tab_id:+ return _error_response("tab-id is required for PDF export", "validation_error")+ prefix = _instance_path(base_url, args.get("instance-id"))+ path = f"{prefix}/tabs/{tab_id}/pdf" if prefix else f"/tabs/{tab_id}/pdf"+ query = {+ "raw": "true" if args.get("raw") else None,+ "landscape": "true" if args.get("landscape") else None,+ "scale": args.get("scale"),+ }+ query = {k: v for k, v in query.items() if v is not None}+ out = _api_request(base_url, "GET", path, token=token, query=query)+ if out.get("status") == "error":+ return out+ return {"status": "success", "data": out}+++def cmd_evaluate(args: Dict[str, Any], base_url: str, token: Optional[str]) -> Dict[str, Any]:+ expr = args.get("expression")+ if not expr:+ return _error_response("expression is required", "validation_error")+ prefix = _instance_path(base_url, args.get("instance-id"))+ path = f"{prefix}/evaluate" if prefix else "/evaluate"+ out = _api_request(base_url, "POST", path, token=token, body={"expression": expr})+ if out.get("status") == "error":+ return out+ return {"status": "success", "data": out}+++def cmd_cookies_get(args: Dict[str, Any], base_url: str, token: Optional[str]) -> Dict[str, Any]:+ prefix = _instance_path(base_url, args.get("instance-id"))+ path = f"{prefix}/cookies" if prefix else "/cookies"+ out = _api_request(base_url, "GET", path, token=token)+ if out.get("status") == "error":+ return out+ return {"status": "success", "data": out}+++def cmd_stealth_status(args: Dict[str, Any], base_url: str, token: Optional[str]) -> Dict[str, Any]:+ prefix = _instance_path(base_url, args.get("instance-id"))+ path = f"{prefix}/stealth/status" if prefix else "/stealth/status"+ out = _api_request(base_url, "GET", path, token=token)+ if out.get("status") == "error":+ return out+ return {"status": "success", "data": out}+++def get_plugin_description(parser: argparse.ArgumentParser) -> Dict[str, Any]:+ commands: List[Dict[str, Any]] = []+ sub = _get_subparsers_action(parser)+ if sub:+ for cmd_name, cmd_parser in sub.choices.items():+ params = []+ for a in cmd_parser._actions:+ d = _describe_action(a)+ if d:+ params.append(d)+ commands.append({+ "name": cmd_name,+ "description": (cmd_parser.description or "").strip(),+ "parameters": params,+ })+ return {+ "plugin": {+ "name": "pinchtab",+ "version": PLUGIN_VERSION,+ "description": "Browser control for AI agents via PinchTab HTTP API. Navigate, snapshot, action (click/type/press), text, screenshot, PDF, evaluate, instances, tabs.",+ },+ "commands": commands,+ }+++def build_parser() -> argparse.ArgumentParser:+ parser = argparse.ArgumentParser(+ description="PinchTab SMCP plugin — browser control via HTTP API",+ formatter_class=argparse.RawDescriptionHelpFormatter,+ )+ parser.add_argument("--describe", action="store_true", help="Output plugin description JSON")+ parser.add_argument("--debug", action="store_true", help="Include tracebacks in errors")+ parser.add_argument("--base-url", dest="base_url", default="http://localhost:9867", help="PinchTab base URL (orchestrator or instance)")+ parser.add_argument("--token", help="Bearer token (BRIDGE_TOKEN)")+ parser.add_argument("--instance-id", dest="instance_id", help="Instance ID when using orchestrator")+ sub = parser.add_subparsers(dest="command", help="Commands")++ def add_common(p: argparse.ArgumentParser) -> None:+ p.add_argument("--base-url", dest="base_url", default="http://localhost:9867")+ p.add_argument("--token")+ p.add_argument("--instance-id", dest="instance_id")++ # health+ p_health = sub.add_parser("health", help="Health check")+ add_common(p_health)++ # instances+ p_inst = sub.add_parser("instances", help="List instances (orchestrator)")+ add_common(p_inst)++ # instance-start+ p_start = sub.add_parser("instance-start", help="Start an instance")+ add_common(p_start)+ p_start.add_argument("--profile-id", dest="profile_id")+ p_start.add_argument("--mode", choices=["headless", "headed"])+ p_start.add_argument("--port", type=int)++ # instance-stop (instance-id from add_common; required at runtime in handler)+ p_stop = sub.add_parser("instance-stop", help="Stop an instance (requires --instance-id)")+ add_common(p_stop)++ # tabs+ p_tabs = sub.add_parser("tabs", help="List tabs")+ add_common(p_tabs)++ # navigate+ p_nav = sub.add_parser("navigate", help="Navigate to URL")+ add_common(p_nav)+ p_nav.add_argument("--url", required=True)+ p_nav.add_argument("--timeout", type=int)+ p_nav.add_argument("--block-images", dest="block_images", action="store_true")+ p_nav.add_argument("--new-tab", dest="new_tab", action="store_true")++ # snapshot+ p_snap = sub.add_parser("snapshot", help="Get accessibility tree snapshot")+ add_common(p_snap)+ p_snap.add_argument("--tab-id", dest="tab_id")+ p_snap.add_argument("--filter", choices=["interactive", "all"])+ p_snap.add_argument("--format", choices=["json", "text", "compact", "yaml"])+ p_snap.add_argument("--selector")+ p_snap.add_argument("--max-tokens", dest="max_tokens", type=int)+ p_snap.add_argument("--diff", action="store_true")+ p_snap.add_argument("--depth", type=int)+ p_snap.add_argument("--no-animations", dest="no_animations", action="store_true")++ # action+ p_act = sub.add_parser("action", help="Single action: click, type, press, focus, fill, hover, select, scroll")+ add_common(p_act)+ p_act.add_argument("--kind", required=True, choices=["click", "type", "press", "focus", "fill", "hover", "select", "scroll"])+ p_act.add_argument("--ref")+ p_act.add_argument("--key")+ p_act.add_argument("--text")+ p_act.add_argument("--value")+ p_act.add_argument("--selector")+ p_act.add_argument("--scroll-y", dest="scroll_y", type=int)+ p_act.add_argument("--wait-nav", dest="wait_nav", action="store_true")++ # actions (batch)+ p_acts = sub.add_parser("actions", help="Batch actions (JSON array)")+ add_common(p_acts)+ p_acts.add_argument("--actions", required=True, help="JSON array of action objects")+ p_acts.add_argument("--tab-id", dest="tab_id")+ p_acts.add_argument("--stop-on-error", dest="stop_on_error", action="store_true")++ # text+ p_text = sub.add_parser("text", help="Extract page text")+ add_common(p_text)+ p_text.add_argument("--tab-id", dest="tab_id")+ p_text.add_argument("--mode", choices=["readability", "raw"])++ # screenshot+ p_ss = sub.add_parser("screenshot", help="Take screenshot")+ add_common(p_ss)+ p_ss.add_argument("--tab-id", dest="tab_id")+ p_ss.add_argument("--raw", action="store_true")+ p_ss.add_argument("--quality", type=int)++ p_pdf = sub.add_parser("pdf", help="Export tab to PDF")+ add_common(p_pdf)+ p_pdf.add_argument("--tab-id", dest="tab_id", required=True)+ p_pdf.add_argument("--raw", action="store_true")+ p_pdf.add_argument("--landscape", action="store_true")+ p_pdf.add_argument("--scale", type=float)++ # evaluate+ p_eval = sub.add_parser("evaluate", help="Run JavaScript in page")+ add_common(p_eval)+ p_eval.add_argument("--expression", required=True)++ # cookies+ p_cook = sub.add_parser("cookies-get", help="Get cookies")+ add_common(p_cook)++ # stealth-status+ p_stealth = sub.add_parser("stealth-status", help="Stealth/fingerprint status")+ add_common(p_stealth)++ return parser+++def main() -> None:+ global DEBUG_TRACEBACKS+ parser = build_parser()+ try:+ args = parser.parse_args()+ except SystemExit as e:+ if e.code == 0:+ raise+ err = _error_response("Invalid arguments", "argument_error", include_traceback=False)+ print(json.dumps(err, indent=2), file=sys.stderr)+ print(json.dumps(err, indent=2))+ sys.exit(e.code if isinstance(e.code, int) else 2)++ DEBUG_TRACEBACKS = bool(getattr(args, "debug", False))+ if args.describe:+ print(json.dumps(get_plugin_description(parser), indent=2))+ sys.exit(0)+ if not args.command:+ parser.print_help()+ sys.exit(1)++ base_url = getattr(args, "base_url", "http://localhost:9867") or "http://localhost:9867"+ token = getattr(args, "token", None)+ args_dict: Dict[str, Any] = {}+ for k, v in vars(args).items():+ if k in ("command", "describe", "debug"):+ continue+ if v is None:+ continue+ key = k.replace("_", "-")+ args_dict[key] = v++ commands = {+ "health": cmd_health,+ "instances": cmd_instances,+ "instance-start": cmd_instance_start,+ "instance-stop": cmd_instance_stop,+ "tabs": cmd_tabs,+ "navigate": cmd_navigate,+ "snapshot": cmd_snapshot,+ "action": cmd_action,+ "actions": cmd_actions,+ "text": cmd_text,+ "screenshot": cmd_screenshot,+ "pdf": cmd_pdf,+ "evaluate": cmd_evaluate,+ "cookies-get": cmd_cookies_get,+ "stealth-status": cmd_stealth_status,+ }+ fn = commands.get(args.command)+ if not fn:+ result = _error_response(f"Unknown command: {args.command}", "argument_error", include_traceback=False)+ else:+ try:+ result = fn(args_dict, base_url, token)+ except Exception as e:+ result = _error_response(str(e), "unknown_error")+ print(json.dumps(result, indent=2))+ sys.exit(0 if result.get("status") == "success" else 1)+++if __name__ == "__main__":+ main()diff --git a/plugins/pinchtab/pyproject.toml b/plugins/pinchtab/pyproject.tomlnew file mode 100644index 00000000..8c551aa7--- /dev/null+++ b/plugins/pinchtab/pyproject.toml@@ -0,0 +1,15 @@+[build-system]+requires = []+build-backend = "setuptools.build_meta"++[project]+name = "pinchtab-smcp-plugin"+version = "0.1.0"+description = "SMCP plugin for PinchTab browser control API"+readme = "README.md"+requires-python = ">=3.9"++[tool.pytest.ini_options]+testpaths = ["tests"]+pythonpath = ["."]+addopts = "-v"diff --git a/plugins/pinchtab/requirements.txt b/plugins/pinchtab/requirements.txtnew file mode 100644index 00000000..56403451--- /dev/null+++ b/plugins/pinchtab/requirements.txt@@ -0,0 +1,3 @@+# PinchTab SMCP plugin — stdlib only, no dependencies for runtime.+# Test dependencies:+pytest>=7.0diff --git a/plugins/pinchtab/tests/__init__.py b/plugins/pinchtab/tests/__init__.pynew file mode 100644index 00000000..1d2baf7a--- /dev/null+++ b/plugins/pinchtab/tests/__init__.py@@ -0,0 +1 @@+# Tests for PinchTab SMCP plugindiff --git a/plugins/pinchtab/tests/conftest.py b/plugins/pinchtab/tests/conftest.pynew file mode 100644index 00000000..4d82d433--- /dev/null+++ b/plugins/pinchtab/tests/conftest.py@@ -0,0 +1,8 @@+"""Pytest configuration and shared fixtures."""+import sys+from pathlib import Path++# Ensure plugin cli is importable+plugin_root = Path(__file__).resolve().parent.parent+if str(plugin_root) not in sys.path:+ sys.path.insert(0, str(plugin_root))diff --git a/plugins/pinchtab/tests/test_plugin_functional.py b/plugins/pinchtab/tests/test_plugin_functional.pynew file mode 100644index 00000000..e30a8ad1--- /dev/null+++ b/plugins/pinchtab/tests/test_plugin_functional.py@@ -0,0 +1,192 @@+"""+Functional tests for plugin command handlers.++Uses mocks so no real PinchTab server is required. Ensures each command+builds correct request and handles response.+"""++import json+from unittest.mock import patch, MagicMock++import pytest++# Import after path fix in conftest+import cli # noqa: E402+++def base_url():+ return "http://localhost:9867"+++def token():+ return None+++def test_health_success(base_url, token):+ with patch("cli._api_request") as m:+ m.return_value = {"ok": True}+ result = cli.cmd_health({}, base_url, token)+ assert result["status"] == "success"+ assert "data" in result+ m.assert_called_once()+ call_args = m.call_args+ assert call_args[0][2] == "/health" # path without instance prefix+++def test_health_with_instance_id(base_url, token):+ with patch("cli._api_request") as m:+ m.return_value = {}+ cli.cmd_health({"instance-id": "inst_abc"}, base_url, token)+ m.assert_called_once()+ assert "/instances/inst_abc/health" in m.call_args[0][2]+++def test_navigate_requires_url(base_url, token):+ result = cli.cmd_navigate({}, base_url, token)+ assert result["status"] == "error"+ assert result["error_type"] == "validation_error"+++def test_navigate_success(base_url, token):+ with patch("cli._api_request") as m:+ m.return_value = {}+ result = cli.cmd_navigate({"url": "https://example.com"}, base_url, token)+ assert result["status"] == "success"+ m.assert_called_once()+ body = m.call_args[1]["body"]+ assert body["url"] == "https://example.com"+++def test_navigate_with_options(base_url, token):+ with patch("cli._api_request") as m:+ m.return_value = {}+ cli.cmd_navigate({+ "url": "https://example.com",+ "block-images": True,+ "new-tab": True,+ "timeout": 60,+ }, base_url, token)+ body = m.call_args[1]["body"]+ assert body["blockImages"] is True+ assert body["newTab"] is True+ assert body["timeout"] == 60+++def test_snapshot_query_params(base_url, token):+ with patch("cli._api_request") as m:+ m.return_value = {"nodes": []}+ cli.cmd_snapshot({+ "filter": "interactive",+ "format": "compact",+ "max-tokens": 2000,+ }, base_url, token)+ m.assert_called_once()+ query = m.call_args[1]["query"]+ assert query.get("filter") == "interactive"+ assert query.get("format") == "compact"+ assert query.get("maxTokens") == 2000+++def test_action_click(base_url, token):+ with patch("cli._api_request") as m:+ m.return_value = {}+ result = cli.cmd_action({+ "kind": "click",+ "ref": "e5",+ }, base_url, token)+ assert result["status"] == "success"+ body = m.call_args[1]["body"]+ assert body["kind"] == "click"+ assert body["ref"] == "e5"+++def test_action_type(base_url, token):+ with patch("cli._api_request") as m:+ m.return_value = {}+ cli.cmd_action({"kind": "type", "ref": "e3", "text": "hello"}, base_url, token)+ body = m.call_args[1]["body"]+ assert body["kind"] == "type"+ assert body["text"] == "hello"+++def test_action_requires_kind(base_url, token):+ result = cli.cmd_action({"ref": "e5"}, base_url, token)+ assert result["status"] == "error"+ assert result["error_type"] == "validation_error"+++def test_instance_stop_requires_instance_id(base_url, token):+ result = cli.cmd_instance_stop({}, base_url, token)+ assert result["status"] == "error"+ assert "instance-id" in result["error"].lower()+++def test_instance_stop_success(base_url, token):+ with patch("cli._api_request") as m:+ m.return_value = {"id": "inst_xyz", "status": "stopped"}+ result = cli.cmd_instance_stop({"instance-id": "inst_xyz"}, base_url, token)+ assert result["status"] == "success"+ m.assert_called_once()+ assert m.call_args[0][2] == "/instances/inst_xyz/stop"+++def test_pdf_requires_tab_id(base_url, token):+ result = cli.cmd_pdf({}, base_url, token)+ assert result["status"] == "error"+ assert result["error_type"] == "validation_error"+++def test_pdf_success(base_url, token):+ with patch("cli._api_request") as m:+ m.return_value = {"data": "base64..."}+ result = cli.cmd_pdf({"tab-id": "tab_abc", "instance-id": "inst_1"}, base_url, token)+ assert result["status"] == "success"+ assert m.call_args[0][2] == "/instances/inst_1/tabs/tab_abc/pdf"+++def test_instances_list(base_url, token):+ with patch("cli._api_request") as m:+ m.return_value = [{"id": "inst_1", "port": "9868"}]+ result = cli.cmd_instances({}, base_url, token)+ assert result["status"] == "success"+ assert "instances" in result+ assert len(result["instances"]) == 1+++def test_instance_start_body(base_url, token):+ with patch("cli._api_request") as m:+ m.return_value = {"id": "inst_new", "status": "starting"}+ cli.cmd_instance_start({+ "profile-id": "prof_123",+ "mode": "headed",+ "port": 9999,+ }, base_url, token)+ body = m.call_args[1]["body"]+ assert body["profileId"] == "prof_123"+ assert body["mode"] == "headed"+ assert body["port"] == "9999"+++def test_evaluate_requires_expression(base_url, token):+ result = cli.cmd_evaluate({}, base_url, token)+ assert result["status"] == "error"+ assert result["error_type"] == "validation_error"+++def test_evaluate_success(base_url, token):+ with patch("cli._api_request") as m:+ m.return_value = {"result": "Page title"}+ result = cli.cmd_evaluate({"expression": "document.title"}, base_url, token)+ assert result["status"] == "success"+ body = m.call_args[1]["body"]+ assert body["expression"] == "document.title"+++def test_api_error_propagated(base_url, token):+ with patch("cli._api_request") as m:+ m.return_value = {"status": "error", "error": "Connection refused", "error_type": "connection_error"}+ result = cli.cmd_health({}, base_url, token)+ assert result["status"] == "error"+ assert result["error_type"] == "connection_error"diff --git a/plugins/pinchtab/tests/test_smcp_compat.py b/plugins/pinchtab/tests/test_smcp_compat.pynew file mode 100644index 00000000..af818811--- /dev/null+++ b/plugins/pinchtab/tests/test_smcp_compat.py@@ -0,0 +1,270 @@+"""+SMCP compatibility tests.++Ensures the plugin satisfies SMCP discovery and execution contract:+- --describe returns valid JSON with plugin + commands + parameters+- All commands are invocable with correct args+- Output is always a single JSON object to stdout+- No functionality missing (all PinchTab API operations covered)+"""++import json+import subprocess+import sys+from pathlib import Path++import pytest++# Run cli.py as module or script+PLUGIN_DIR = Path(__file__).resolve().parent.parent+CLI = PLUGIN_DIR / "cli.py"+++def run_cli(*args: str, timeout: int = 10) -> tuple[str, str, int]:+ """Run cli.py with args; return (stdout, stderr, returncode)."""+ proc = subprocess.run(+ [sys.executable, str(CLI)] + list(args),+ capture_output=True,+ text=True,+ timeout=timeout,+ cwd=str(PLUGIN_DIR),+ )+ return proc.stdout, proc.stderr, proc.returncode+++def run_describe() -> dict:+ """Run --describe and parse JSON."""+ out, err, code = run_cli("--describe")+ assert code == 0, f"describe failed: stdout={out!r} stderr={err!r}"+ return json.loads(out)+++# --- Describe contract (SMCP discovery) ---+++def test_describe_returns_valid_json():+ """--describe must output a single valid JSON object."""+ payload = run_describe()+ assert isinstance(payload, dict)+ assert "plugin" in payload+ assert "commands" in payload+++def test_describe_plugin_schema():+ """Plugin object must have name, version, description."""+ payload = run_describe()+ plugin = payload["plugin"]+ assert plugin["name"] == "pinchtab"+ assert "version" in plugin+ assert isinstance(plugin["version"], str)+ assert "description" in plugin+++def test_describe_commands_list():+ """Commands must be a list of command objects."""+ payload = run_describe()+ commands = payload["commands"]+ assert isinstance(commands, list)+ for cmd in commands:+ assert "name" in cmd+ assert "description" in cmd+ assert "parameters" in cmd+ assert isinstance(cmd["parameters"], list)+++def test_describe_parameter_schema():+ """Each parameter must have name, type, description, required, default."""+ payload = run_describe()+ for cmd in payload["commands"]:+ for param in cmd["parameters"]:+ assert "name" in param+ assert param["type"] in ("string", "integer", "number", "boolean", "array", "object")+ assert "required" in param+ assert isinstance(param["required"], bool)+++def test_describe_all_required_commands_present():+ """All PinchTab API operations must be exposed as commands."""+ payload = run_describe()+ names = {c["name"] for c in payload["commands"]}+ required = {+ "health",+ "instances",+ "instance-start",+ "instance-stop",+ "tabs",+ "navigate",+ "snapshot",+ "action",+ "actions",+ "text",+ "screenshot",+ "pdf",+ "evaluate",+ "cookies-get",+ "stealth-status",+ }+ missing = required - names+ assert not missing, f"Missing commands: {missing}"+++def test_describe_navigate_has_url():+ """navigate command must have url parameter."""+ payload = run_describe()+ nav = next(c for c in payload["commands"] if c["name"] == "navigate")+ param_names = [p["name"] for p in nav["parameters"]]+ assert "url" in param_names+++def test_describe_snapshot_has_filter_and_format():+ """snapshot command must have filter and format for token control."""+ payload = run_describe()+ snap = next(c for c in payload["commands"] if c["name"] == "snapshot")+ param_names = [p["name"] for p in snap["parameters"]]+ assert "filter" in param_names+ assert "format" in param_names+++def test_describe_action_has_kind_and_ref():+ """action command must have kind and ref."""+ payload = run_describe()+ act = next(c for c in payload["commands"] if c["name"] == "action")+ param_names = [p["name"] for p in act["parameters"]]+ assert "kind" in param_names+++def test_describe_pdf_requires_tab_id():+ """pdf command must have tab-id required."""+ payload = run_describe()+ pdf_cmd = next(c for c in payload["commands"] if c["name"] == "pdf")+ tab_param = next((p for p in pdf_cmd["parameters"] if p["name"] == "tab-id"), None)+ assert tab_param is not None+ assert tab_param["required"] is True+++# --- Execution contract: JSON only to stdout ---+++def test_help_exits_nonzero():+ """No command should exit 0 and print help only (no JSON)."""+ out, err, code = run_cli()+ assert code != 0+++def test_unknown_command_returns_json_error():+ """Unknown command should print JSON with error_type."""+ out, err, code = run_cli("not-a-command")+ assert code != 0+ data = json.loads(out)+ assert "status" in data+ assert data.get("status") == "error"+ assert "error_type" in data+++def test_validation_errors_return_json():+ """Missing required args must return JSON error (validation_error or argument_error)."""+ out, err, code = run_cli("navigate", "--base-url", "http://localhost:9867")+ assert code != 0+ data = json.loads(out)+ assert data.get("status") == "error"+ assert data.get("error_type") in ("validation_error", "argument_error")+++def test_instance_stop_missing_id_returns_validation_error():+ """instance-stop without instance-id must return validation_error."""+ out, err, code = run_cli("instance-stop", "--base-url", "http://localhost:9867")+ assert code != 0+ data = json.loads(out)+ assert data.get("status") == "error"+ assert data.get("error_type") == "validation_error"+++def test_pdf_missing_tab_id_returns_validation_error():+ """pdf without tab-id must return validation_error or argument_error."""+ out, err, code = run_cli("pdf", "--base-url", "http://localhost:9867")+ assert code != 0+ data = json.loads(out)+ assert data.get("status") == "error"+ assert data.get("error_type") in ("validation_error", "argument_error")+++def test_action_missing_kind_returns_validation_error():+ """action without kind must return validation_error or argument_error."""+ out, err, code = run_cli("action", "--base-url", "http://localhost:9867")+ assert code != 0+ data = json.loads(out)+ assert data.get("status") == "error"+ assert data.get("error_type") in ("validation_error", "argument_error")+++def test_actions_missing_actions_returns_error():+ """actions without --actions must fail (arg parse or validation_error)."""+ out, err, code = run_cli("actions", "--base-url", "http://localhost:9867")+ assert code != 0+ data = json.loads(out)+ assert data.get("status") == "error"+++def test_evaluate_missing_expression_returns_validation_error():+ """evaluate without expression must return validation_error or argument_error."""+ out, err, code = run_cli("evaluate", "--base-url", "http://localhost:9867")+ assert code != 0+ data = json.loads(out)+ assert data.get("status") == "error"+ assert data.get("error_type") in ("validation_error", "argument_error")+++# --- SMCP invocation style: kebab-case args ---+++def test_smcp_style_invoke_navigate_with_kebab_args():+ """SMCP passes --url, --instance-id etc.; plugin must accept and return JSON."""+ out, err, code = run_cli(+ "navigate",+ "--base-url", "http://127.0.0.1:9999",+ "--url", "https://example.com",+ )+ # Server likely unreachable -> connection_error; we only require valid JSON+ data = json.loads(out)+ assert "status" in data+ assert data["status"] in ("success", "error")+ if data["status"] == "error":+ assert "error_type" in data+++def test_smcp_style_invoke_snapshot_with_options():+ """Snapshot with filter and format (common agent pattern)."""+ out, err, code = run_cli(+ "snapshot",+ "--base-url", "http://127.0.0.1:9999",+ "--filter", "interactive",+ "--format", "compact",+ )+ data = json.loads(out)+ assert "status" in data+++def test_smcp_style_invoke_action_click():+ """Action click with ref."""+ out, err, code = run_cli(+ "action",+ "--base-url", "http://127.0.0.1:9999",+ "--kind", "click",+ "--ref", "e5",+ )+ data = json.loads(out)+ assert "status" in data+++def test_success_response_structure():+ """When command succeeds (or server returns 200), response has status success and data."""+ # We can't guarantee server is up; test that our success path structure is correct+ # by testing that connection_error has status/error/error_type+ out, err, code = run_cli("health", "--base-url", "http://127.0.0.1:9999")+ data = json.loads(out)+ assert "status" in data+ if data["status"] == "success":+ assert "data" in data+ else:+ assert "error" in data+ assert "error_type" in data