Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
"version": "0.2.0-beta.1",
"description": "Pipefy workflow integration for Claude Code.",
"author": { "name": "Gabriel Custodio" },
"homepage": "https://github.com/gbrlcustodio/pipefy-mcp-server",
"repository": "https://github.com/gbrlcustodio/pipefy-mcp-server",
"homepage": "https://github.com/pipefy/ai-toolkit",
"repository": "https://github.com/pipefy/ai-toolkit",
"license": "Apache-2.0"
}
6 changes: 3 additions & 3 deletions .mcp.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@
"command": "uvx",
"args": [
"--with",
"pipefy-sdk @ git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/sdk",
"pipefy-sdk @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/sdk",
"--with",
"pipefy-auth @ git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/auth",
"pipefy-auth @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/auth",
"--from",
"git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/mcp",
"git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/mcp",
"pipefy-mcp-server"
]
}
Expand Down
30 changes: 14 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
</div>

<p align="center">
<a href="https://github.com/gbrlcustodio/pipefy-mcp-server/actions/workflows/ci.yml"><img src="https://github.com/gbrlcustodio/pipefy-mcp-server/actions/workflows/ci.yml/badge.svg" alt="CI Status" /></a>
<a href="https://github.com/pipefy/ai-toolkit/actions/workflows/ci.yml"><img src="https://github.com/pipefy/ai-toolkit/actions/workflows/ci.yml/badge.svg" alt="CI Status" /></a>
<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+" /></a>
<a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/badge/uv-package%20manager-blueviolet" alt="uv package manager" /></a>
<a href="https://modelcontextprotocol.io/introduction"><img src="https://img.shields.io/badge/MCP-Server-orange" alt="MCP Server" /></a>
Expand All @@ -18,8 +18,6 @@

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.

> **Disclaimer:** Community-maintained software for developer workflows. It is not an official Pipefy product or an enterprise support channel.

<p align="center">
<a href="#overview">Overview</a> •
<a href="#installation">Installation</a> •
Expand All @@ -43,13 +41,13 @@ Open-source toolkit for **Pipefy** developers: a Model Context Protocol (MCP) se
| **SDK** | `pipefy-sdk` | Vendor GraphQL client, services, and models shared by MCP and CLI. |
| **Skills** | [`skills/`](skills/) | Markdown playbooks (Anthropic Skills format) for common Pipefy workflows. |

Feedback and issues: [GitHub Issues](https://github.com/gbrlcustodio/pipefy-mcp-server/issues) · **dev@pipefy.com**
Feedback and issues: [GitHub Issues](https://github.com/pipefy/ai-toolkit/issues) · **dev@pipefy.com**

---

## 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`](https://github.com/gbrlcustodio/pipefy-mcp-server/releases/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.
> 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`](https://github.com/pipefy/ai-toolkit/releases/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).

Expand All @@ -65,15 +63,15 @@ Full env-var reference and `config.toml` precedence: [`docs/config.md`](docs/con
One command installs the CLI + MCP server, optionally adds skills, and registers the MCP server in your client config:

```sh
curl -fsSL https://raw.githubusercontent.com/gbrlcustodio/pipefy-mcp-server/main/install.sh \
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](https://github.com/gbrlcustodio/pipefy-mcp-server/releases) tag (default: most recent prerelease or release).
- `--version vX.Y.Z` pin a specific [GitHub Release](https://github.com/pipefy/ai-toolkit/releases) tag (default: most recent prerelease or release).
- `--dry-run` print every command without executing.
- `--allow-root` opt-in for root execution (refused by default).

Expand All @@ -82,7 +80,7 @@ After install, run `pipefy auth login` to authenticate (`--device` on headless s
### Claude Code

```text
/plugin marketplace add gbrlcustodio/pipefy-mcp-server
/plugin marketplace add pipefy/ai-toolkit
/plugin install pipefy
/pipefy:install
/pipefy:login
Expand All @@ -96,19 +94,19 @@ Ad-hoc:

```sh
uvx \
--with "pipefy-sdk @ git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/sdk" \
--with "pipefy-auth @ git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/auth" \
--from "git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/cli" \
--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:

```sh
uv tool install \
--with "pipefy-sdk @ git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/sdk" \
--with "pipefy-auth @ git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/auth" \
"git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/cli"
--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
```
Expand All @@ -118,8 +116,8 @@ CLI deep-dives (auth precedence, `--token` / `PIPEFY_TOKEN`, parity matrix): [`p
### Skill catalog install

```sh
npx skills add gbrlcustodio/pipefy-mcp-server # all skills
npx skills add gbrlcustodio/pipefy-mcp-server --skill pipefy-pipes-and-cards
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`](skills/README.md).
Expand Down
2 changes: 1 addition & 1 deletion RELEASE.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ PyPI publishing is **disabled** for tags that do not start with `v1.`. Pre-relea

### Public beta line (`v0.2.0-beta.*`)

The next **GitHub pre-release** after the standalone repo’s [`v0.1.0-beta.1`](https://github.com/gbrlcustodio/pipefy-mcp-server/releases/tag/v0.1.0-beta.1) is the **`v0.2.0-beta.*`** series on this monorepo (first cut: **`v0.2.0-beta.1`** unless you intentionally reuse another suffix). Same mechanics as any other **v0.x** tag: attach wheels to the GitHub Release; **no PyPI** until **`v1.`**.
The next **GitHub pre-release** after the standalone repo’s [`v0.1.0-beta.1`](https://github.com/pipefy/ai-toolkit/releases/tag/v0.1.0-beta.1) is the **`v0.2.0-beta.*`** series on this monorepo (first cut: **`v0.2.0-beta.1`** unless you intentionally reuse another suffix). Same mechanics as any other **v0.x** tag: attach wheels to the GitHub Release; **no PyPI** until **`v1.`**.

The Release workflow requires the git tag (without leading `v`) to **exactly match** `__version__` in `packages/sdk/src/pipefy_sdk/__init__.py` (and the MCP/CLI/Auth/Infra copies). For example tag **`v0.2.0-beta.1`** implies **`__version__ = "0.2.0-beta.1"`** in all five packages before you push the tag (set via step 2 below using `version=0.2.0-beta.1`, or edit the five `__init__.py` files together).

Expand Down
6 changes: 3 additions & 3 deletions commands/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ Otherwise prompt the user to confirm running:

```
uv tool install --force \
--with "pipefy-sdk @ git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/sdk" \
--with "pipefy-auth @ git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/auth" \
"git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/cli"
--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"
```

Verify with `pipefy --version`.
4 changes: 2 additions & 2 deletions docs/MIGRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,8 +67,8 @@ pipefy card get 12345
**`skills/` catalog** — Anthropic Skills-format playbooks for common Pipefy workflows, consumable by any LLM agent. Install via [`skills.sh`](https://github.com/vercel-labs/skills):

```sh
npx skills add gbrlcustodio/pipefy-mcp-server # all skills
npx skills add gbrlcustodio/pipefy-mcp-server --skill pipefy-pipes-and-cards
npx skills add pipefy/ai-toolkit # all skills
npx skills add pipefy/ai-toolkit --skill pipefy-pipes-and-cards
```

---
Expand Down
2 changes: 1 addition & 1 deletion install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

set -eu

REPO="gbrlcustodio/pipefy-mcp-server"
REPO="pipefy/ai-toolkit"
TOOLS="pipefy_cli pipefy_mcp_server" # wheels installed as standalone uv tools

YES=0
Expand Down
12 changes: 6 additions & 6 deletions packages/cli/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,19 +6,19 @@ Typer-based CLI for Pipefy. Exposes all MCP tool capabilities as terminal comman

```sh
uvx \
--with "pipefy-sdk @ git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/sdk" \
--with "pipefy-auth @ git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/auth" \
--from "git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/cli" \
--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" \
--refresh pipefy-cli
```

Or persistently:

```sh
uv tool install \
--with "pipefy-sdk @ git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/sdk" \
--with "pipefy-auth @ git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/auth" \
"git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/cli"
--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"
```

The `--with` flags are required pre-1.0 because the workspace members are not yet on PyPI. At v1.0 this collapses to `uv tool install pipefy-cli`.
Expand Down
14 changes: 7 additions & 7 deletions packages/mcp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ MCP server for Pipefy — **149 tools** for AI agents (Cursor, Claude Desktop, C

```sh
uvx \
--with "pipefy-sdk @ git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/sdk" \
--with "pipefy-auth @ git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/auth" \
--from "git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/mcp" \
--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/mcp" \
--refresh pipefy-mcp-server
```

Expand Down Expand Up @@ -36,7 +36,7 @@ Full reference (every `PIPEFY_*` variable, validation rules, TOML schema, preced

### macOS keychain `errSecParam (-25244)`

`pipefy auth login` may exit with `errSecParam (-25244)` at the final keychain-write step even though OAuth itself succeeded. The cause is not yet reliably diagnosed — direct `keyring.set_password` calls from the same uv-tool-installed Python succeed under repro testing, so this is likely a transient `Security.framework` condition rather than a deterministic per-binary ACL problem. If it occurs, retry the slash command (Claude Code) or `pipefy auth login` (terminal) first; as a fallback, run `pipefy auth login` once from a regular Terminal.app session and approve any macOS keychain dialog that appears. [Issue #235](https://github.com/gbrlcustodio/pipefy-mcp-server/issues/235) tracks platform-aware error messaging.
`pipefy auth login` may exit with `errSecParam (-25244)` at the final keychain-write step even though OAuth itself succeeded. The cause is not yet reliably diagnosed — direct `keyring.set_password` calls from the same uv-tool-installed Python succeed under repro testing, so this is likely a transient `Security.framework` condition rather than a deterministic per-binary ACL problem. If it occurs, retry the slash command (Claude Code) or `pipefy auth login` (terminal) first; as a fallback, run `pipefy auth login` once from a regular Terminal.app session and approve any macOS keychain dialog that appears. [Issue #235](https://github.com/pipefy/ai-toolkit/issues/235) tracks platform-aware error messaging.

### Claude Code: `claude mcp add` (per-project terminal flow)

Expand All @@ -45,9 +45,9 @@ Useful when you want to wire the server without editing `~/.claude.json` by hand
```bash
claude mcp add --scope project pipefy \
-- uvx \
--with "pipefy-sdk @ git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/sdk" \
--with "pipefy-auth @ git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/auth" \
--from "git+https://github.com/gbrlcustodio/pipefy-mcp-server@latest#subdirectory=packages/mcp" \
--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/mcp" \
pipefy-mcp-server
```

Expand Down
4 changes: 3 additions & 1 deletion packages/mcp/src/pipefy_mcp/_docs.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,6 @@

from pipefy_mcp import __version__

DOCS_SETUP_REF = f"https://github.com/gbrlcustodio/pipefy-mcp-server/blob/v{__version__}/README.md#installation"
DOCS_SETUP_REF = (
f"https://github.com/pipefy/ai-toolkit/blob/v{__version__}/README.md#installation"
)
8 changes: 4 additions & 4 deletions skills/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,17 @@ Markdown playbooks in **Anthropic Skills** format: each file describes a Pipefy
**Install via [`skills.sh`](https://github.com/vercel-labs/skills)** (55+ agent targets — Claude Code, Cursor, Codex, OpenCode, …):

```bash
npx skills add gbrlcustodio/pipefy-mcp-server # all skills
npx skills add gbrlcustodio/pipefy-mcp-server --skill pipefy-pipes-and-cards
npx skills add gbrlcustodio/pipefy-mcp-server -g -a claude-code -y # CI-friendly
npx skills add pipefy/ai-toolkit # all skills
npx skills add pipefy/ai-toolkit --skill pipefy-pipes-and-cards
npx skills add pipefy/ai-toolkit -g -a claude-code -y # CI-friendly
```

`skills.sh` reads canonical `skills/**/SKILL.md` files directly from this repo; no install or wheel needed.

**Reference from source (no install):**

```bash
git clone https://github.com/gbrlcustodio/pipefy-mcp-server.git
git clone https://github.com/pipefy/ai-toolkit.git
# Reference paths such as skills/pipes-and-cards/pipefy-pipes-and-cards/SKILL.md
# in your IDE rules or agent context.
```
Expand Down
Loading