plugins/README.md

PinchTab SMCP Plugins

This directory holds plugins for 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 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

   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:

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 for command list and usage.