| # PinchTab SMCP Plugins |
|
|
| 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. |
|
|
| ## SMCP contract (reference) |
|
|
| Instructions below match the SMCP plugin contract. If your SMCP version differs, prefer [sanctumos/smcp](https://github.com/sanctumos/smcp) and its docs. |
|
|
| - **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. |
| |
| ## 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: |
| |
| ```bash |
| 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 **`PINCHTAB_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: health, instances, instance-start/stop, tabs, navigate, snapshot, action, actions, text, screenshot, pdf, evaluate, cookies-get, stealth-status. |
|
|
| - **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 command list and usage. |
|
|
