@shog-lab/pi-toolkit

Common pi extensions — web search and MCP bridge.

A drop-in package adding lightweight external tool integrations to any pi setup. Composes naturally with pi-mind (memory) and pi-bus (multi-agent messaging + cron).

Extensions

| Extension (dir) | Tool name(s) | Backend | Required env | |---|---|---|---| | web-search | web_search | mmx CLI | (mmx config) | | mcp-bridge | <server>_<tool> per MCP server | Any MCP server | mcp-servers.json config |

0.4.0 removed understand-image. Modern models increasingly support native vision (e.g. MiniMax-M3), so a separate mmx-backed image-understanding tool is no longer worth the dependency. If your model has native vision, pass images directly; otherwise add a vision tool yourself.

0.3.0 removed subagent. It lived here for historical reasons but is conceptually infrastructure (child-process spawning), not a tool. Extracted to its own package: npm i -D @shog-lab/pi-subagent. The tool name (spawn_subagent) is unchanged.

cron moved to @shog-lab/pi-bus. Cron delivers scheduled messages through the bus inbox, so it belongs with bus rather than toolkit.

Dir names are kebab-case (matching the convention used by pi-mind's extensions and skills). Tool names stay snake_case so the LLM-facing surface is stable across this rename.

mcp-bridge silently skips registration when no mcp-servers.json exists, so install pi-toolkit even if you only use some extensions.

Browser automation is an explicit opt-in. If the host project also installs agent-browser, pi-toolkit-init links its upstream agent-browser skill so the agent knows how to use the CLI. Toolkit no longer depends on agent-browser by default.

Install

Pi-native install (recommended for pi users):

pi install npm:@shog-lab/pi-toolkit

Node/npm install (works well inside existing Node repos):

npm i -D @shog-lab/pi-toolkit

pnpm install:

pnpm add -D @shog-lab/pi-toolkit
INIT_CWD="$PWD" pnpm exec pi-toolkit-init

postinstall still tries to symlink extensions/*/ into the host repo's .pi/extensions/ for npm users. pnpm users should run the explicit init command because pnpm may block lifecycle scripts.

Optional browser automation:

pnpm add -D agent-browser
INIT_CWD="$PWD" pnpm exec pi-toolkit-init

Configure

MCP servers (figma, filesystem, etc.)

Create mcp-servers.json (or .pi/mcp-servers.json) at the host repo root:

{
  "figma": {
    "command": "npx",
    "args": ["-y", "figma-developer-mcp", "--stdio"],
    "env": { "FIGMA_API_KEY": "your-key" }
  },
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/expose"]
  }
}

On next pi launch, mcp-bridge:

1. Spawns each declared server as a child process
2. Runs the MCP initialize handshake
3. Calls tools/list to discover tools
4. Registers each as a pi tool, prefixed with the server name: figma_get_node, filesystem_read_file, etc.

Failures (server not installed, bad config, missing env) log a warning and skip that server — they don't crash pi or other tools.

Find more MCP servers at https://github.com/modelcontextprotocol/servers.

Use

cd ~/my-repo
pi   # all configured extensions/tools auto-loaded

License

MIT