pipefy-labs

Open-source toolkit for Pipefy developers: a Model Context Protocol (MCP) server for AI agents, a pipefy CLI for terminals and automation, a shared GraphQL SDK, and a catalog of agent skill playbooks.

Overview • Installation • Repository layout • MCP server • CLI • Agent skills • Documentation • Development • Contributing

Overview

Feedback and issues: GitHub Issues · [email protected]

Installation

Pre-1.0 ships from this git repo via uvx and uv tool install. PyPI becomes the canonical source at v1.0. The current beta line is v0.2.0-beta.* (first tag: v0.2.0-beta.1). Two install paths: the Quick install script below (resolves the latest GitHub Release at runtime and runs uv tool install for you), or Claude Code via the plugin marketplace.

The CLI snippets below pin @latest, a moving git tag the release flow updates to point at the most recent release. To pin a specific version, swap @latest for a version tag (e.g. @v0.2.0-beta.2). The --with pipefy-sdk @ ...#subdirectory=packages/sdk / pipefy-auth @ ...#subdirectory=packages/auth flags are required pre-1.0: this repo is a uv workspace, and the workspace members are not yet published to PyPI, so uv needs them named explicitly. The flags go away at v1.0 (PyPI install).

Two auth paths:

• Human OAuth (interactive): pipefy auth login runs the browser flow and stores a session in your OS keychain. Works anywhere the pipefy CLI is on PATH (uv tool install once, any client can invoke it). Claude Code additionally exposes it as the /pipefy:login slash command via the plugin marketplace. Pipe membership is whatever the signed-in user already has.
• Service account (unattended / CI): provision a Service Account in Pipefy Admin (Admin → Service Accounts) and add that account to every pipe the tools should touch. Wire PIPEFY_SERVICE_ACCOUNT_CLIENT_ID and PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET into the client config below.

Full env-var reference and config.toml precedence: docs/config.md.

Quick install (recommended)

One command installs the CLI + MCP server, optionally adds skills, and registers the MCP server in your client config:

curl -fsSL https://raw.githubusercontent.com/pipefy/ai-toolkit/main/install.sh \
  | sh -s -- --client cursor

Replace --client cursor with one of: claude-code, claude-desktop, codex, or none (prints the snippet to paste). Useful flags:

• --yes skip all confirmation prompts.
• --no-skills skip the npx skills add step.
• --version vX.Y.Z pin a specific GitHub Release tag (default: most recent prerelease or release).
• --dry-run print every command without executing.
• --allow-root opt-in for root execution (refused by default).

After install, run pipefy auth login to authenticate (--device on headless systems). The installer puts pipefy-mcp-server on PATH, so each client's config collapses to {"command": "pipefy-mcp-server"}.

Claude Code

/plugin marketplace add pipefy/ai-toolkit
/plugin install pipefy
/pipefy:install
/pipefy:login

/plugin install pipefy registers the MCP server and the /pipefy:install + /pipefy:login slash commands. /pipefy:install runs uv tool install once to put pipefy on PATH (idempotent). /pipefy:login runs the OAuth browser flow. For hand-wired setups (paste-into-config blocks per client, the macOS errSecParam keychain note, the local-clone alternative for contributors), see packages/mcp/README.md.

CLI

Ad-hoc:

uvx \
  --with "pipefy-sdk @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/sdk" \
  --with "pipefy-auth @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/auth" \
  --from "git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/cli" \
  pipefy-cli --help

Permanent install:

uv tool install \
  --with "pipefy-sdk @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/sdk" \
  --with "pipefy-auth @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/auth" \
  "git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/cli"
pipefy --install-completion bash    # or zsh, fish
pipefy auth login                   # browser OAuth, session in OS keychain

CLI deep-dives (auth precedence, --token / PIPEFY_TOKEN, parity matrix): packages/cli/README.md and docs/cli/.

Skill catalog install

npx skills add pipefy/ai-toolkit                           # all skills
npx skills add pipefy/ai-toolkit --skill pipefy-pipes-and-cards

Catalog and authoring guide: skills/README.md.

Post-1.0 (PyPI preview)

uvx pipefy-mcp-server
uv tool install pipefy-cli

Deprecation and semver (post-1.0): docs/DEPRECATION.md.

Repository layout

uv workspace with three Python packages and a skills catalog. pipefy-sdk is the vendor GraphQL layer; MCP and CLI depend on it and do not import each other.

MCP server

The server registers 149 tools across ten domains. Canonical names: PIPEFY_TOOL_NAMES in packages/mcp/src/pipefy_mcp/tools/registry.py.

Tool descriptions and Args: blocks come from Python docstrings (what MCP clients show to models). Per-area reference docs cover parameters, edge cases, and cross-cutting behavior.

Shared conventions (pagination, IDs, permissions, error shape): docs/mcp/tools/cross-cutting.md.

Command-line interface

The pipefy CLI mirrors shipped MCP capabilities where parity is defined in docs/parity.md. Conventions: Rich output by default, --json for scripts, --yes on destructive commands.

pipefy pipe list --json
pipefy card get 123456789
pipefy introspect query --name getPipe

CLI-specific guides: docs/cli/ (including introspect-then-execute).

Agent skills

The skills/ directory holds workflow playbooks: prerequisites, tool tables (MCP + CLI), steps, and success criteria. Compatible with any agent that reads Markdown (Cursor, Claude Code, Codex, and others). Distribution is via skills.sh (55+ agent targets); install commands are under Installation above.

Full catalog: skills/README.md. Authoring: skills/AGENTS.md. Contributions: CONTRIBUTING.md.

Documentation

Development

Install uv if you don't have it, then from the repository root:

uv sync
[[ -f .env ]] || cp .env.example .env   # first-time setup; then fill in PIPEFY_SERVICE_ACCOUNT_*
uv run pytest -m "not integration"    # unit tests (no live API)
uv run pytest -m integration -v     # live API (requires PIPEFY_*)
uv run ruff check . && uv run ruff format .

MCP Inspector (protocol debugging):

npx @modelcontextprotocol/inspector uv --directory . run pipefy-mcp-server

Adding an MCP tool: implement under packages/mcp/src/pipefy_mcp/tools/, register in ToolRegistry, add the name to PIPEFY_TOOL_NAMES, and ship the matching CLI command (or document a deferral in docs/parity.md). See AGENTS.md for the full TDD workflow.

Contributing

Contributions are welcome via issues and pull requests.