Skip to content

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.md
index 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.md
index 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
+```