plugins/pinchtab/README.md

PinchTab SMCP Plugin

SMCP plugin for PinchTab: browser control for AI agents via the PinchTab HTTP API. Conforms to the SMCP plugin contract (discovery via --describe, tool naming plugin__command, execution via python cli.py <command> --arg val ..., JSON to stdout).

Requirements

• Python 3.9+
• A running PinchTab server (orchestrator on port 9867 or direct instance on 9868+)
• No extra Python dependencies (stdlib only)

SMCP contract (this plugin)

• Discovery: SMCP runs python cli.py --describe. This plugin returns JSON with plugin (name, version, description) and commands (each with name, description, parameters with name, type, description, required, default).
• Tool names: SMCP registers tools as pinchtab__<command> (double underscore), e.g. pinchtab__navigate, pinchtab__instance-start, pinchtab__snapshot.
• Execution: SMCP runs python cli.py <command> --arg1 val1 --arg2 val2 .... Parameter names are kebab-case (e.g. --base-url, --instance-id, --tab-id). The plugin prints a single JSON object to stdout; SMCP uses it as the tool result. Timeout is 300 seconds (SMCP default).
• Layout: This folder must contain cli.py and it must be executable (chmod +x cli.py). SMCP discovers it when MCP_PLUGINS_DIR points at the parent directory that contains this pinchtab folder (see ../README.md).

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 (requires instance-id)
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 (requires tab-id)
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 a direct instance URL.
• Orchestrator + instance: When talking to the orchestrator, pass --instance-id inst_xxxx for instance-scoped calls (navigate, snapshot, action, etc.).
• Token: If PinchTab uses PINCHTAB_TOKEN, pass --token YOUR_TOKEN in the tool args.

Example (SMCP tool call)

1. Agent calls tool pinchtab__navigate with arguments (e.g. from MCP client):

   { "base_url": "http://localhost:9867", "instance_id": "inst_0a89a5bb", "url": "https://pinchtab.com" }
   

2. SMCP invokes:

   python cli.py navigate --base-url http://localhost:9867 --instance-id inst_0a89a5bb --url https://pinchtab.com
   

3. Plugin prints to stdout:

   { "status": "success", "data": { ... } }
   

   SMCP returns that JSON as the tool result.

Installation (summary)

1. Set MCP_PLUGINS_DIR to the path of the parent plugins/ directory (the one that contains this pinchtab folder), or copy this pinchtab folder into your existing SMCP plugins directory.
2. Run chmod +x cli.py.
3. Restart SMCP. No pip install is required for runtime.

Tests

Optional (for development). From this directory:

python3 -m venv .venv
.venv/bin/pip install pytest
.venv/bin/pytest tests/ -v