High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: align SMCP instructions with SMCP contract (discovery, MCP_PLUGINS_DIR, --describe, plugin__command, chmod +x)
rootf141e4925b5e
diff --git a/plugins/README.md b/plugins/README.mdindex 6ea389ba..35354a11 100644--- a/plugins/README.md+++ b/plugins/README.md@@ -1,29 +1,58 @@# PinchTab SMCP Plugins-This directory contains MCP (SMCP) plugins for use with [sanctumos/smcp](https://github.com/sanctumos/smcp) or compatible MCP servers.+This directory holds plugins for [SMCP](https://github.com/sanctumos/smcp) (Model Context Protocol server for the Animus/Letta/Sanctum ecosystem). SMCP discovers plugins by scanning a directory for `plugins/<name>/cli.py` and running `python cli.py --describe` to get tool schemas.-## What is SMCP?+## SMCP contract (reference)-**SMCP** is an MCP (Model Context Protocol) server used in the Animus/Letta/Sanctum ecosystem. It discovers plugins in a directory (e.g. `plugins/`), runs `python cli.py --describe` to get tool schemas, and exposes each command as an MCP tool (e.g. `pinchtab__navigate`). AI agents can then call PinchTab through the MCP layer without using HTTP directly.+Instructions below match the SMCP plugin contract. If your SMCP version differs, prefer [sanctumos/smcp](https://github.com/sanctumos/smcp) and its docs.-## SMCP setup (env and paths)+- **Discovery:** SMCP scans the directory set in **`MCP_PLUGINS_DIR`** (or its default `plugins/`). For each subdirectory `<name>` that contains a file **`cli.py`**, it runs `python cli.py --describe` and expects a single JSON object on stdout with:+ - **`plugin`:** `{ "name", "version", "description" }`+ - **`commands`:** array of `{ "name", "description", "parameters": [ { "name", "type", "description", "required", "default" } ] }`+- **Fallback:** If `--describe` is not supported, SMCP may run `python cli.py --help` and scrape an "Available commands:" section (no param schemas).+- **Tool naming:** Registered tools are **`<plugin>__<command>`** (double underscore), e.g. `pinchtab__navigate`. Legacy `plugin.command` may still be supported.+- **Execution:** For a tool call, SMCP runs `python cli.py <command> --arg1 val1 --arg2 val2 ...`. Argument names use **kebab-case** (`--base-url`, `--instance-id`). SMCP maps underscores to dashes; booleans `true` become `--flag` only; arrays become repeated `--arg item`. Default timeout is **300 seconds**. The plugin must print a **single JSON object to stdout**; SMCP returns it as the tool result.+- **Plugin layout:** Each plugin must live in a folder `<name>/` with **`cli.py`** (required, and must be executable). `__init__.py`, `README.md`, and `requirements.txt` are optional.-- **Plugin directory:** Point your MCP server at this repo’s `plugins/` directory.- - **SMCP:** Set `MCP_PLUGINS_DIR` to the absolute path of `plugins/` (e.g. `/path/to/pinchtab/plugins`), or copy the `pinchtab` folder into your existing SMCP `plugins/` directory.-- **PinchTab URL:** The plugin defaults to `http://localhost:9867` (orchestrator). Agents pass `base_url` (and optionally `token`, `instance_id`) per tool call; no extra env vars are required for the plugin itself.-- **Optional:** If PinchTab is protected with `BRIDGE_TOKEN`, agents must pass `token` in the tool args (or you can set it in your MCP server config if it supports per-plugin env).+## Installation (PinchTab plugin)++1. **Point SMCP at this plugins directory**+ - Set **`MCP_PLUGINS_DIR`** to the path of **this** directory (the one that **contains** the `pinchtab` folder).+ - Example: if the repo is at `/home/me/pinchtab`, set `MCP_PLUGINS_DIR=/home/me/pinchtab/plugins`. SMCP will then find `pinchtab/cli.py` and discover the plugin.+ - Alternatively, copy the **`pinchtab`** folder into your existing SMCP plugins directory so you have `.../plugins/pinchtab/cli.py`.++2. **Make the CLI executable**+ ```bash+ chmod +x /path/to/plugins/pinchtab/cli.py+ ```++3. **No Python dependencies** for this plugin (stdlib only). Skip `pip install -r requirements.txt` for runtime.++4. **Restart the SMCP server** so it rescans and loads the plugin.++## Verify discovery++From the repo root:-**Quick check:** From the repo root:```bash-cd plugins/pinchtab && python3 cli.py --describe | head -20+python3 plugins/pinchtab/cli.py --describe | head -30```+You should see JSON with `"plugin": {"name": "pinchtab", ...}` and `"commands": [...]`.++## PinchTab URL and auth++- The plugin defaults to **`--base-url http://localhost:9867`** (orchestrator). Agents pass `base_url`, and optionally `token` and `instance_id`, per tool call; no plugin-specific env vars are required.+- If PinchTab is protected with **`BRIDGE_TOKEN`**, agents must pass `token` in the tool arguments (or configure it in your MCP server if it supports per-plugin env).++---+## pinchtab-Full SMCP plugin for the PinchTab HTTP API: navigate, snapshot, action, text, screenshot, PDF, instances, tabs, and more.+Full SMCP plugin for the PinchTab HTTP API: health, instances, instance-start/stop, tabs, navigate, snapshot, action, actions, text, screenshot, pdf, evaluate, cookies-get, stealth-status.-- **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`+- **Path:** `pinchtab/` (so SMCP sees `plugins/pinchtab/cli.py`).+- **Describe:** `python cli.py --describe` returns the JSON schema above.+- **Tests:** `cd pinchtab && python3 -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.+See [pinchtab/README.md](pinchtab/README.md) for command list and usage.diff --git a/plugins/pinchtab/README.md b/plugins/pinchtab/README.mdindex 7733848f..434efce8 100644--- a/plugins/pinchtab/README.md+++ b/plugins/pinchtab/README.md@@ -1,19 +1,19 @@# PinchTab SMCP Plugin-SMCP (MCP) plugin for [PinchTab](https://github.com/pinchtab/pinchtab): browser control for AI agents via HTTP API.+SMCP plugin for [PinchTab](https://github.com/pinchtab/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 (uses stdlib only)+- No extra Python dependencies (stdlib only)-## SMCP Compatibility+## SMCP contract (this plugin)-- **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.+- **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](../README.md)).## Commands@@ -22,7 +22,7 @@ SMCP (MCP) plugin for [PinchTab](https://github.com/pinchtab/pinchtab): browser| `health` | Health check || `instances` | List instances (orchestrator) || `instance-start` | Start an instance (optional profile-id, mode, port) |-| `instance-stop` | Stop an instance |+| `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) |@@ -30,30 +30,45 @@ SMCP (MCP) plugin for [PinchTab](https://github.com/pinchtab/pinchtab): browser| `actions` | Batch actions (JSON array) || `text` | Extract page text || `screenshot` | Take screenshot |-| `pdf` | Export tab to PDF |+| `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 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`.+- **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 **`BRIDGE_TOKEN`**, pass **`--token YOUR_TOKEN`** in the tool args.-## SMCP setup (env and paths)+## Example (SMCP tool call)-- **MCP_PLUGINS_DIR:** Set to the path of the **parent** `plugins/` directory (the one that contains the `pinchtab` folder). Example: if this repo is at `/home/me/pinchtab`, use `MCP_PLUGINS_DIR=/home/me/pinchtab/plugins`. SMCP will then find `plugins/pinchtab/cli.py` and run `python cli.py --describe`.-- **No plugin-specific env required:** Base URL, token, and instance ID are passed per tool call by the agent. Default base URL is `http://localhost:9867`.-- **Venv (optional):** For running tests only: `cd plugins/pinchtab && python3 -m venv .venv && .venv/bin/pip install pytest && .venv/bin/pytest tests/ -v`. The plugin itself uses stdlib only and does not require a venv at runtime.+1. Agent calls tool **`pinchtab__navigate`** with arguments (e.g. from MCP client):+ ```json+ { "base_url": "http://localhost:9867", "instance_id": "inst_0a89a5bb", "url": "https://example.com" }+ ```+2. SMCP invokes:+ ```bash+ python cli.py navigate --base-url http://localhost:9867 --instance-id inst_0a89a5bb --url https://example.com+ ```+3. Plugin prints to stdout:+ ```json+ { "status": "success", "data": { ... } }+ ```+ SMCP returns that JSON as the tool result.-## Example (SMCP tool call)+## 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.-Agent calls tool `pinchtab__navigate` with args:-`{"base_url": "http://localhost:9867", "instance_id": "inst_0a89a5bb", "url": "https://example.com"}`+## Tests-SMCP runs:-`python cli.py navigate --base-url http://localhost:9867 --instance-id inst_0a89a5bb --url https://example.com`+Optional (for development). From this directory:-Plugin prints to stdout:-`{"status": "success", "data": {...}}`+```bash+python3 -m venv .venv+.venv/bin/pip install pytest+.venv/bin/pytest tests/ -v+```