Skip to content

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/.gitignore
index 9dc30d64..9721ec85 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,8 @@
node_modules/
+.venv/
+plugins/*/.venv/
+__pycache__/
+*.pyc
browser-bridge
/pinchtab
coverage.out
diff --git a/plugins/README.md b/plugins/README.md
new file mode 100644
index 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.md
new file mode 100644
index 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.py
new file mode 100644
index 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)
+
+ # pdf
+ 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.toml
new file mode 100644
index 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.txt
new file mode 100644
index 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.0
diff --git a/plugins/pinchtab/tests/__init__.py b/plugins/pinchtab/tests/__init__.py
new file mode 100644
index 00000000..1d2baf7a
--- /dev/null
+++ b/plugins/pinchtab/tests/__init__.py
@@ -0,0 +1 @@
+# Tests for PinchTab SMCP plugin
diff --git a/plugins/pinchtab/tests/conftest.py b/plugins/pinchtab/tests/conftest.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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