pipefy-mcp-server 0.3.0a1__tar.gz

pipefy_mcp_server-0.3.0a1/.gitignore

@@ -0,0 +1,56 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Ruff stuff:
+.ruff_cache/
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.mise.toml
+
+# Ralph Wiggum (local autonomous runs; state must not land in git)
+.ralph/
+RALPH_TASK.md
+
+# IDEs and editors
+.cursor/
+.claude/
+# Cursor MCP workspace config (machine-specific paths or local server entries).
+# Carve-out: repo-root .mcp.json is the Claude Code plugin's MCP server config
+# (auto-discovered at plugin root) and is intentionally tracked.
+.mcp.json
+!/.mcp.json
+
+# Tracked release tooling only (ignore ad-hoc local scripts and smoke artifacts)
+scripts/*
+!scripts/bump_version.py
+
+# macOS
+.DS_Store
+**/.DS_Store

pipefy_mcp_server-0.3.0a1/AGENTS.md

@@ -0,0 +1,169 @@
+# MCP package conventions
+
+Scoped to `packages/mcp/`. Repo-wide guidance lives in `../../AGENTS.md`.
+
+## Distribution model
+
+This MCP server is distributed as code that runs in the user's environment as
+a subprocess of the agent runtime (Claude Code, Claude Desktop, etc.). The
+trust boundary is the user; the server has the same filesystem and network
+access the user already has.
+
+Implications for tool design:
+
+- Local filesystem inputs (`file_path`) are first-class. There is no
+  path-traversal threat surface beyond what the user can already access.
+- SSRF guards, redirect loops, and download size caps that defend a hosted
+  server are not appropriate here. They add maintenance cost without buying
+  a security boundary.
+
+A hosted/remote distribution profile is in progress. It runs the server as a
+multi-user HTTP service. Tool exposure there is **default-deny**: only tools
+explicitly marked remote-safe are registered; everything else is withheld. The
+marker is described below.
+
+## Transport profiles
+
+`pipefy-mcp-server` launches with two orthogonal flags:
+
+- **`--profile {local|remote}`** (default `local`, env `PIPEFY_MCP_PROFILE`).
+  - `local`: registers every tool and acts as the one credential resolved at
+    startup. The installed-subprocess case.
+  - `remote`: exposes ONLY the default-deny remote-safe tool surface and, when a
+    resource-server URL is configured, validates an inbound bearer per request.
+- **`--transport {stdio|http}`** (env `PIPEFY_MCP_TRANSPORT`). Left unset it follows
+  the profile: `local` speaks stdio, `remote` serves over Streamable HTTP. Set it
+  explicitly to run `local` over loopback HTTP. `remote` over stdio is rejected: a
+  per-request bearer has no stdio equivalent. The pair is resolved (and validated)
+  once, at startup, by `resolve_mcp_settings`.
+
+Bind host/port come from `PIPEFY_MCP_HOST` / `PIPEFY_MCP_PORT` (defaults
+`127.0.0.1:8000`), overridable with `--host` / `--port`, and matter only over HTTP.
+
+Under `remote` the server acts on behalf of each caller: it validates the inbound
+bearer per request and the one shared client reads that validated bearer per call,
+so concurrent callers each act as themselves rather than as a single identity
+resolved at startup. `local` runs as the one credential resolved at startup. The
+transport still binds loopback-only until the DNS-rebinding host/Origin allowlist
+lands.
+
+**Resource-server profile.** Config is split by domain. *Token validation* is an
+auth concern and lives in `pipefy_auth.JwtValidationSettings` (`settings.jwt`,
+env `PIPEFY_JWT_*`): `ISSUER_URL` (an override; absent it, the inbound issuer
+defaults to the one this process logs into, the `OidcClient` issuer, since in a
+single-realm deployment they are the same IdP), optional `AUDIENCE` /
+`VERIFY_AUDIENCE` (off by default, the same-audience interim), and `JWKS_URI`.
+*Resource identity* is MCP-specific and stays in `pipefy_mcp.ResourceServerSettings`
+(`settings.rs`, env `PIPEFY_MCP_RS_*`): `RESOURCE_SERVER_URL` (this server's public
+canonical URL, e.g. `https://host/mcp`) and `REQUIRED_SCOPES`. The shared
+`PIPEFY_ALLOW_INSECURE_URLS` covers both. The profile activates when
+`RESOURCE_SERVER_URL` is set (the one value that cannot default); there is no
+separate enable flag, just the `remote` profile plus this URL. Set
+`RESOURCE_SERVER_URL` with the stored-session login disabled and no `ISSUER_URL`
+override and startup fails (no issuer to validate against).
+
+The JWKS/RS256 validation lives in `pipefy_auth` (`JwtValidator`); the MCP adapter
+`auth/resource_server.py` (`JwtTokenVerifier`) maps validated claims onto the
+SDK's `AccessToken`. FastMCP serves the RFC 9728 protected-resource metadata and
+the `401` + `WWW-Authenticate` challenge; `build_resource_server_auth` (same
+module) resolves the inbound issuer and pairs the verifier with `AuthSettings`.
+The runtime (`McpRuntime.for_profile`) calls it for the `remote` profile and holds
+the pair as `inbound_auth`, which `server.py` wires into the app.
+
+**Loopback bind.** `_assert_safe_http_bind` restricts the HTTP transport to a
+loopback bind, unconditionally for now. Per-request on-behalf-of identity (each
+call runs as the validated caller, not a single startup identity) means inbound
+identity is not the constraint; the constraint is DNS-rebinding protection, the
+configurable host / Origin allowlist for a proxied deployment. Off-loopback binding
+stays off until that lands (see `experiments/hosted-obo/RFC-OUTLINE.md`). The
+attachment tools' local `file_path` inputs also still assume a loopback peer that
+shares the client's disk (remote-safe file inputs are separate follow-up work).
+
+## Tool registration
+
+Tools are registered **once, at construction** (via `_register_pipefy_tools` in
+`server.py`, reached through `build_pipefy_mcp_server`, which both transports use),
+not inside the FastMCP `lifespan`. The lifespan owns resources only: it yields
+the already-wired app-scoped runtime as the request `lifespan_context`. This
+follows the FastMCP contract, where the lifespan can run per session (per request
+under Streamable HTTP) and so must not mutate the tool table.
+
+Tools take no client at registration. Each tool function declares a
+`ctx: Context` parameter (FastMCP injects it and keeps it out of the tool's
+input schema) and resolves the live client per request with
+`get_pipefy_client(ctx)` (`tools/tool_context.py`), which reads
+`ctx.request_context.lifespan_context.pipefy_client`. Because the client is
+looked up per call rather than captured at registration, tools observe whatever
+the runtime holds without re-registering; under the hosted profile the one shared
+client applies each request's identity itself (via its request-context bearer), so
+identity is per-request even though the client is stable. That is why there is no
+repeat-visit bookkeeping: registration never repeats.
+
+When adding a tool, give it a `ctx: Context` parameter and start its body with
+`client = get_pipefy_client(ctx)`; do not pass a client through `register`.
+
+Both transports launch through the single `run_server` entry point, which resolves
+the profile/transport once (via `resolve_mcp_settings`) and builds the same app
+through `build_pipefy_mcp_server` (same runtime-bound lifespan, same
+`_register_pipefy_tools`), differing only in the transport `run` and HTTP's bind
+concerns. `build_pipefy_mcp_server` constructs one app-scoped `McpRuntime` via
+`McpRuntime.for_profile` (`core/runtime.py`) and binds the lifespan to it.
+`for_profile` is the composition root's one build step: the `remote` profile picks
+a per-request identity and builds the inbound resource-server `(verifier, auth)`
+pair (failing fast when that profile has no resource server); every other profile
+resolves the one startup credential and fails fast when none is configured
+(`StartupIdentity.from_configured_credential`). So a missing credential (or, under
+`remote`, a missing resource server) surfaces when the server is built at startup,
+not on the first tool call. The runtime wires its shared client to whichever
+identity's `httpx.Auth` it was handed and exposes the inbound pair as
+`inbound_auth`, which `build_pipefy_mcp_server` reads into FastMCP. (This also
+means `build_pipefy_mcp_server` resolves the credential, so the live integration
+tests that build the app at import skip themselves when no creds are configured.) Wiring the client at construction is safe off the event
+loop: `PipefyClient` construction does no network I/O and binds nothing to a
+running loop, because its executors open a fresh per-request transport at call
+time; the client built at startup works on whatever loop later serves requests.
+Streamable HTTP re-entering the lifespan per session just yields the same
+already-wired runtime, so there is nothing to rebuild. The runtime holds no
+per-request state: both identity variants carry an `httpx.Auth` the shared client
+applies to every outbound call. `StartupIdentity` carries the one credential
+resolved at startup (stdio/local), while `RequestScopedIdentity` carries a
+`RequestContextBearerAuth` that reads each caller's validated bearer from the
+request context, so one client serves every concurrent caller as themselves.
+
+## Remote-profile tool marker
+
+Under the `remote` profile (`--profile remote` / `PIPEFY_MCP_PROFILE=remote`), the
+server exposes ONLY tools whose registration carries `meta=REMOTE`. Any unmarked
+tool is implicitly withheld (default-deny). Under `local` (the default), all tools
+register and the marker is inert.
+
+The marker is a single co-located source of truth on the `@mcp.tool` decorator:
+
+```python
+from pipefy_mcp.tools.remote_profile import REMOTE
+
+@mcp.tool(annotations=ToolAnnotations(readOnlyHint=True), meta=REMOTE)
+async def get_organization(...): ...
+```
+
+`ToolRegistry.apply_remote_profile()` reads it back via `is_remote_tool` and
+removes every unmarked Pipefy tool at registration time (before the server
+serves anything). The marker is greppable (`rg "meta=REMOTE" packages/mcp`) and
+machine-enforced, unlike the comment-only `GATED:` convention it replaces.
+
+Inclusion criteria for marking a tool remote-safe: it reaches the API with the
+request-scoped bearer and is fully governed by API permissions; it does NOT read
+the local filesystem; it does NOT read process-global settings for a per-user
+decision. Opting a tool in is a deliberate, reviewed change (it shifts the
+`REMOTE_SEED` drift guard in `tests/tools/test_remote_profile.py`).
+
+### Exposure vs input restriction
+
+The `meta` marker expresses **exposure** only: whether a tool is available in the
+remote profile. The retired `GATED:` convention could also express *input*
+restriction within an exposed tool. Where a remotely-exposed tool needs restricted
+inputs (for example the attachment tools, which would accept a `file_url` rather
+than a local `file_path`), enforce that in the tool body gated on
+`settings.mcp.profile == "remote"` at call time, not via the marker. A tool whose
+exclusion deserves a reason gets a plain code comment stating why; the exclusion
+itself needs no annotation.

pipefy_mcp_server-0.3.0a1/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

pipefy_mcp_server-0.3.0a1/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: pipefy-mcp-server
+Version: 0.3.0a1
+Summary: MCP server that exposes Pipefy's GraphQL API.
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.25.0
+Requires-Dist: pipefy
+Requires-Dist: pipefy-auth
+Requires-Dist: pipefy-infra
+Requires-Dist: pydantic-settings>=2.8.1
+Requires-Dist: pydantic<3,>=2.13.4
+Description-Content-Type: text/markdown
+
+# pipefy-mcp-server
+
+MCP server for Pipefy — **152 tools** for AI agents (Cursor, Claude Desktop, Claude Code, Codex, and any MCP-compatible client). Depends on [`pipefy`](../sdk/README.md) for all GraphQL and API logic.
+
+## Install (pre-launch, v0.1 → v0.5)
+
+```sh
+uvx \
+  --with "pipefy @ 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
+```
+
+The `--with pipefy` / `pipefy-auth` flags are required pre-1.0 because the workspace members are not yet on PyPI. At v1.0 this collapses to `uvx pipefy-mcp-server`.
+
+For per-client wiring (Claude Code / Cursor / Claude Desktop / Codex), see [root `README.md#installation`](../../README.md#installation).
+
+## Configuration
+
+Set the following environment variables (or add them to a `.env` file in the working directory, or pin them in `~/.config/pipefy/config.toml`):
+
+```env
+PIPEFY_SERVICE_ACCOUNT_CLIENT_ID=your_client_id
+PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET=your_client_secret
+# Non-prod environments only:
+# PIPEFY_BASE_URL=https://<your-api-host>
+# PIPEFY_AUTH_URL=https://<your-signin-host>/realms/<realm>
+```
+
+`PIPEFY_BASE_URL` defaults to `https://app.pipefy.com` (drives the four API endpoints) and `PIPEFY_AUTH_URL` defaults to `https://signin.pipefy.com/realms/pipefy` (the OIDC issuer). Set them only for non-prod environments.
+
+Full reference (every `PIPEFY_*` variable, validation rules, TOML schema, precedence chain): [`docs/config.md`](../../docs/config.md).
+
+## Edge cases and alternative wiring
+
+### 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/pipefy/ai-toolkit/issues/235) tracks platform-aware error messaging.
+
+### Claude Code: `claude mcp add` (per-project terminal flow)
+
+Useful when you want to wire the server without editing `~/.claude.json` by hand:
+
+```bash
+claude mcp add --scope project pipefy \
+  -- uvx \
+       --with "pipefy @ 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
+```
+
+Then (repeat for each key you need):
+
+```bash
+claude mcp add-env pipefy PIPEFY_SERVICE_ACCOUNT_CLIENT_ID <YOUR_CLIENT_ID>
+claude mcp add-env pipefy PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET <YOUR_CLIENT_SECRET>
+# Non-prod environments only:
+# claude mcp add-env pipefy PIPEFY_BASE_URL https://<your-api-host>
+# claude mcp add-env pipefy PIPEFY_AUTH_URL https://<your-signin-host>/realms/<realm>
+```
+
+### Claude Code: settings edit (post-plugin install)
+
+The plugin's `.mcp.json` ships `command` + `args` only. To set the `env` block, edit the `pipefy` server entry in `~/.claude.json` (or the Claude Code settings UI):
+
+```json
+{
+  "mcpServers": {
+    "pipefy": {
+      "env": {
+        "PIPEFY_SERVICE_ACCOUNT_CLIENT_ID": "<CLIENT_ID>",
+        "PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET": "<CLIENT_SECRET>"
+      }
+    }
+  }
+}
+```
+
+A live MCP server picks up rotated credentials on its next tool call; if the server failed to start because credentials were missing, restart it (or restart Claude Code) after login completes.
+
+### Local-clone alternative (contributors)
+
+If you have a clone of this repo and want the MCP server to use it directly (without `uvx` fetching from git), launch via `uv run` from the clone:
+
+```json
+{
+  "mcpServers": {
+    "pipefy": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/absolute/path/to/pipefy-mcp-server",
+        "pipefy-mcp-server"
+      ],
+      "env": {
+        "PIPEFY_SERVICE_ACCOUNT_CLIENT_ID": "<CLIENT_ID>",
+        "PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET": "<CLIENT_SECRET>"
+      }
+    }
+  }
+}
+```
+
+This form also works as a per-project `.mcp.json` if your team shares a clone. Committing `.mcp.json` without secrets (placeholders or env injection) keeps team setups consistent.
+
+### Legacy environment variables
+
+`PIPEFY_OAUTH_CLIENT` and `PIPEFY_OAUTH_SECRET` still resolve to the new `PIPEFY_SERVICE_ACCOUNT_*` names with a one-shot stderr deprecation warning. The aliases will be removed in a later `0.2.0-beta.x` release. The `PIPEFY_OAUTH_URL` alias was dropped — set `PIPEFY_BASE_URL` instead. Migration notes: [`docs/MIGRATION.md#service-account-env-var-rename`](../../docs/MIGRATION.md#service-account-env-var-rename).
+
+## Tools
+
+**152 tools** across ten domains (including **Portals**) — see the root [`README.md`](../../README.md#mcp-server) for the full table with per-area links. Deep reference: [`docs/mcp/tools/`](../../docs/mcp/tools/cross-cutting.md) (start with [`cross-cutting.md`](../../docs/mcp/tools/cross-cutting.md)); portals: [`portal.md`](../../docs/mcp/tools/portal.md).
+
+## Development
+
+From the **repository root**:
+
+```bash
+uv sync
+uv run pytest packages/mcp/tests     # MCP tests in isolation
+uv run ruff check packages/mcp/src   # lint
+```
+
+See the root [`README.md`](../../README.md) and [`AGENTS.md`](../../AGENTS.md) for contributor guidance.

pipefy_mcp_server-0.3.0a1/README.md

@@ -0,0 +1,127 @@
+# pipefy-mcp-server
+
+MCP server for Pipefy — **152 tools** for AI agents (Cursor, Claude Desktop, Claude Code, Codex, and any MCP-compatible client). Depends on [`pipefy`](../sdk/README.md) for all GraphQL and API logic.
+
+## Install (pre-launch, v0.1 → v0.5)
+
+```sh
+uvx \
+  --with "pipefy @ 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
+```
+
+The `--with pipefy` / `pipefy-auth` flags are required pre-1.0 because the workspace members are not yet on PyPI. At v1.0 this collapses to `uvx pipefy-mcp-server`.
+
+For per-client wiring (Claude Code / Cursor / Claude Desktop / Codex), see [root `README.md#installation`](../../README.md#installation).
+
+## Configuration
+
+Set the following environment variables (or add them to a `.env` file in the working directory, or pin them in `~/.config/pipefy/config.toml`):
+
+```env
+PIPEFY_SERVICE_ACCOUNT_CLIENT_ID=your_client_id
+PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET=your_client_secret
+# Non-prod environments only:
+# PIPEFY_BASE_URL=https://<your-api-host>
+# PIPEFY_AUTH_URL=https://<your-signin-host>/realms/<realm>
+```
+
+`PIPEFY_BASE_URL` defaults to `https://app.pipefy.com` (drives the four API endpoints) and `PIPEFY_AUTH_URL` defaults to `https://signin.pipefy.com/realms/pipefy` (the OIDC issuer). Set them only for non-prod environments.
+
+Full reference (every `PIPEFY_*` variable, validation rules, TOML schema, precedence chain): [`docs/config.md`](../../docs/config.md).
+
+## Edge cases and alternative wiring
+
+### 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/pipefy/ai-toolkit/issues/235) tracks platform-aware error messaging.
+
+### Claude Code: `claude mcp add` (per-project terminal flow)
+
+Useful when you want to wire the server without editing `~/.claude.json` by hand:
+
+```bash
+claude mcp add --scope project pipefy \
+  -- uvx \
+       --with "pipefy @ 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
+```
+
+Then (repeat for each key you need):
+
+```bash
+claude mcp add-env pipefy PIPEFY_SERVICE_ACCOUNT_CLIENT_ID <YOUR_CLIENT_ID>
+claude mcp add-env pipefy PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET <YOUR_CLIENT_SECRET>
+# Non-prod environments only:
+# claude mcp add-env pipefy PIPEFY_BASE_URL https://<your-api-host>
+# claude mcp add-env pipefy PIPEFY_AUTH_URL https://<your-signin-host>/realms/<realm>
+```
+
+### Claude Code: settings edit (post-plugin install)
+
+The plugin's `.mcp.json` ships `command` + `args` only. To set the `env` block, edit the `pipefy` server entry in `~/.claude.json` (or the Claude Code settings UI):
+
+```json
+{
+  "mcpServers": {
+    "pipefy": {
+      "env": {
+        "PIPEFY_SERVICE_ACCOUNT_CLIENT_ID": "<CLIENT_ID>",
+        "PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET": "<CLIENT_SECRET>"
+      }
+    }
+  }
+}
+```
+
+A live MCP server picks up rotated credentials on its next tool call; if the server failed to start because credentials were missing, restart it (or restart Claude Code) after login completes.
+
+### Local-clone alternative (contributors)
+
+If you have a clone of this repo and want the MCP server to use it directly (without `uvx` fetching from git), launch via `uv run` from the clone:
+
+```json
+{
+  "mcpServers": {
+    "pipefy": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/absolute/path/to/pipefy-mcp-server",
+        "pipefy-mcp-server"
+      ],
+      "env": {
+        "PIPEFY_SERVICE_ACCOUNT_CLIENT_ID": "<CLIENT_ID>",
+        "PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET": "<CLIENT_SECRET>"
+      }
+    }
+  }
+}
+```
+
+This form also works as a per-project `.mcp.json` if your team shares a clone. Committing `.mcp.json` without secrets (placeholders or env injection) keeps team setups consistent.
+
+### Legacy environment variables
+
+`PIPEFY_OAUTH_CLIENT` and `PIPEFY_OAUTH_SECRET` still resolve to the new `PIPEFY_SERVICE_ACCOUNT_*` names with a one-shot stderr deprecation warning. The aliases will be removed in a later `0.2.0-beta.x` release. The `PIPEFY_OAUTH_URL` alias was dropped — set `PIPEFY_BASE_URL` instead. Migration notes: [`docs/MIGRATION.md#service-account-env-var-rename`](../../docs/MIGRATION.md#service-account-env-var-rename).
+
+## Tools
+
+**152 tools** across ten domains (including **Portals**) — see the root [`README.md`](../../README.md#mcp-server) for the full table with per-area links. Deep reference: [`docs/mcp/tools/`](../../docs/mcp/tools/cross-cutting.md) (start with [`cross-cutting.md`](../../docs/mcp/tools/cross-cutting.md)); portals: [`portal.md`](../../docs/mcp/tools/portal.md).
+
+## Development
+
+From the **repository root**:
+
+```bash
+uv sync
+uv run pytest packages/mcp/tests     # MCP tests in isolation
+uv run ruff check packages/mcp/src   # lint
+```
+
+See the root [`README.md`](../../README.md) and [`AGENTS.md`](../../AGENTS.md) for contributor guidance.

pipefy_mcp_server-0.3.0a1/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "pipefy-mcp-server"
+dynamic = ["version"]
+description = "MCP server that exposes Pipefy's GraphQL API."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.27.0",
+    "mcp[cli]>=1.25.0",
+    # Workspace resolves versions in dev; PyPI releases stage these wheels alongside CLI/MCP (see release workflow).
+    "pipefy-auth",
+    "pipefy-infra",
+    "pipefy",
+    "pydantic>=2.13.4,<3",
+    "pydantic-settings>=2.8.1",
+]
+
+[tool.uv.sources]
+pipefy-auth = { workspace = true }
+pipefy-infra = { workspace = true }
+pipefy = { workspace = true }
+
+[project.scripts]
+pipefy-mcp-server = "pipefy_mcp.main:main"
+
+[dependency-groups]
+dev = [
+    "aiohttp>=3.11.16",
+    "pytest>=8.3.5",
+    "pytest-asyncio>=0.26.0",
+    "pytest-cov>=6.1.1",
+    "pytest-mock>=3.14.0",
+    "respx>=0.22.0",
+    "ruff>=0.11.4",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pipefy_mcp"]
+
+[tool.hatch.version]
+path = "src/pipefy_mcp/__init__.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# `src` is the package; `../../packages/sdk/tests` supplies the `_shared` test bundle (live creds, fixtures) without putting the whole repo on sys.path.
+pythonpath = ["src", "tests", "../../packages/sdk/tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --no-header --tb=short"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "module"
+markers = [
+    "unit: marks a test as a unit test",
+    "integration: marks tests that call the live Pipefy GraphQL API (PIPEFY_* env)",
+]
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+lint.extend-select = ["TID251"]
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"pipefy_cli".msg = "pipefy_mcp must not import the CLI package; keep MCP independent of pipefy-cli."
+"pipefy_sdk.services".msg = "Import from pipefy_sdk or pipefy_sdk.ai_* helpers only; pipefy_sdk.services is private to the SDK."
+"pipefy_sdk.queries".msg = "Import from pipefy_sdk only; pipefy_sdk.queries is private to the SDK."

pipefy_mcp_server-0.3.0a1/src/pipefy_mcp/__init__.py

@@ -0,0 +1,16 @@
+"""Pipefy MCP Server package."""
+
+from __future__ import annotations
+
+import re
+
+__version__ = "0.3.0-alpha.1"
+version = __version__
+
+m = re.match(r"^(\d+)\.(\d+)\.(\d+)", __version__)
+if not m:
+    msg = f"__version__ must start with MAJOR.MINOR.PATCH, got {__version__!r}"
+    raise ValueError(msg)
+version_tuple = (int(m[1]), int(m[2]), int(m[3]))
+
+__all__ = ["__version__", "version", "version_tuple"]

pipefy_mcp_server-0.3.0a1/src/pipefy_mcp/_docs.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from pipefy_mcp import __version__
+
+DOCS_SETUP_REF = (
+    f"https://github.com/pipefy/ai-toolkit/blob/v{__version__}/README.md#installation"
+)

pipefy_mcp_server-0.3.0a1/src/pipefy_mcp/auth/__init__.py

@@ -0,0 +1,19 @@
+"""Resource-server auth for the HTTP transport: inbound bearer validation."""
+
+from pipefy_mcp.auth.request_identity import (
+    RequestContextBearerAuth,
+    require_request_bearer,
+)
+from pipefy_mcp.auth.resource_server import (
+    JwtTokenVerifier,
+    ResourceServerAuth,
+    build_resource_server_auth,
+)
+
+__all__ = [
+    "JwtTokenVerifier",
+    "RequestContextBearerAuth",
+    "ResourceServerAuth",
+    "build_resource_server_auth",
+    "require_request_bearer",
+]