@pinappai/mcp

@pinappai/mcp

Drive almost the full PinAppAI admin panel from any MCP-compatible AI client — list and triage change requests, manage workspaces / projects / members / reviewers, read the audit log.

A Model Context Protocol server. Works in Claude Code, Codex CLI, Cursor, Claude Desktop, Continue, Zed, and any other MCP-compatible client.

Three surfaces

Easy to confuse, so: 10 workflows you invoke, 38 tools your agent calls over the protocol, and 6 CLI commands you type in a terminal (install, login, logout, uninstall, --help, --version).

A workflow is not a shell command — npx @pinappai/mcp apply tells you so rather than running anything. How you invoke one depends on your client, because the MCP spec deliberately leaves prompt UI to each host:

Client	Run the apply workflow
Claude Code	/pinappai:apply
Codex	ask: "run the pinappai apply workflow" (no slash menu for prompts)
Cursor	type / and pick it
Claude Desktop	+ menu, then pinappai, then apply
Continue	/apply, unnamespaced (IDE extension in agent mode, not the cn CLI)
Anything else	ask in plain language

Clients that don't implement MCP prompts reach the same procedures through the pinappai_get_workflow tool, which returns the workflow body verbatim — so the agent follows the real thing instead of improvising from the name.

npx @pinappai/mcp --help lists every workflow and tool in your installed version.

Requirements

Node.js ≥ 18 (the server uses the global fetch). MCP clients launch npx under whatever Node is first on PATH — a stale nvm default can pick an old version. Since 0.6.2 the server exits immediately with a clear message in that case instead of a cryptic ReferenceError: fetch is not defined. Fix by pointing the client's command at a Node 18+ npx, or nvm alias default 18 (or higher), then restart the client.

What's new in 0.9.3

• Answering "n" to apply's Case-A /changes/ prompt no longer strands the batch (#123). The marker written at the end of an apply run used to land inside the batch it points at, so the documented recovery — "run generate-changes-page when ready" — always found an empty range and the batch's CRs sat in in_review forever. Now a declined Case-A prompt records "changes_page_pending": true + "batch_base_sha" (the landing commit's parent) in .pinappai/last-applied.json; generate-changes-page scopes from that base (including every declined batch — the oldest base is preserved across repeated declines) and clears the flag once the page lands. A later apply's Case-A Y pays the same debt inline.

What's new in 0.9.2

• --help answers instead of starting a server. Any unrecognized argv used to fall through to the stdio-server bootstrap, so npx @pinappai/mcp --help silently booted a server on a terminal nobody was speaking JSON-RPC on. Now --help / -h / help and --version / -v print, and --help lists every workflow and tool read from the live registry. Works logged-out.
• pinappai_get_workflow (38th tool) — returns a workflow's full procedure as text, so clients that don't implement MCP prompts still run the real thing. Codex and Cline have no prompt support at all; VS Code, Zed and Claude Desktop each use different syntax. Tools are universal, so the workflows now ride them. Read-only: it returns text, and every destructive step stays behind the existing confirm=true tools.
• Server instructions tell prompt-less hosts to call it rather than improvise a workflow from its name.
• A workflow name used as a CLI command (npx @pinappai/mcp embed-widget) now explains where to run it and exits 2, instead of booting a stray server.
• Every printed invocation is the npx form. pinappai-mcp login only reaches PATH after a global install, but the documented flow is npx — so the next step after install died with command not found.

What's new in 0.9.1

• /pinappai:apply now surfaces the device and viewport the reviewer used. Each pinappai_list_apply_inbox row carries device_label / orientation and, for pins, viewport_w × viewport_h — so the apply run reproduces and verifies the fix at the width the reviewer actually saw, not just desktop.

What's new in 0.9.0

• /pinappai:apply now honors workspace AI instructions — house rules a Team workspace saves once (admin → workspace settings → AI instructions) and every apply run follows: code style, verification commands, file boundaries. The pinappai_list_apply_inbox response carries them as workspace_instructions.

What's new in 0.7.2 – 0.8.2

• 0.7.2 — reset now wipes pins/comments/screenshots too (see the reset bullet under 0.7.0, amended above); prompt copy matches.
• 0.7.3 — update_project gains primary_origin / preview_origin (the no-install review link + its branch-preview variant); the three apply-flow prompts offer to wire a new branch's deploy URL to the preview review link after landing.
• 0.7.4 — /changes/ content contract: before/after texts are copied verbatim from the source file, typographic punctuation included.
• 0.7.5 — the Apply batch gate gains per-CR walkthrough modes ("only ask about the unclear ones", "step through every CR") with one-question-per-CR flow; per-CR outcome report.
• 0.7.6 — prompt UX pass: legacy prompts (fix-changes, apply-decisions, triage-and-resolve) point at /pinappai:apply first; setup-project derives project fields from the repo and asks once, audits Permissions-Policy, and offers the review link; remove offers to disable the review link (the proxy outlives the embed); stale-/changes/ regeneration is automatic with a landing-step veto.
• 0.7.8 — privileged /changes/ registration: new pinappai_register_change_items tool; every /changes/-producing prompt ends with a mandatory registration call (client-side self-registration was removed server-side — the public endpoint returns 410).
• 0.7.9 — staleness pass: triage-and-resolve prompt removed (its admin_status pipeline only fed the retired v1/v2 dashboards); legacy iteration tools are marked LEGACY in their descriptions; analyze / summarize / marker copy now point at /pinappai:apply and understand #N commit references.
• 0.8.0 — legacy dashboard sunset: the fix-changes and apply-decisions prompts and the five legacy iteration tools (pinappai_open_iteration, pinappai_mark_iteration_applied, pinappai_mark_change_request_applied, pinappai_acknowledge_change_request, update_change_request) are REMOVED — /pinappai:apply + pinappai_apply_change_requests are the only apply path. Current totals: 37 tools, 10 prompts.
• 0.8.1 — resilience: prompt files are snapshotted into memory at server startup, so a mid-session npx cache sweep (npm cache clean, cache eviction) can no longer ENOENT the lazy prompt reads; disk stays the primary source (dev edits still apply without restart). Stale compiled outputs no longer ship (prebuild dist clean).
• 0.8.2 — license change: published under the PinAppAI Client License (proprietary — install and run freely to use the PinAppAI service; no redistribution or derivative works). Versions ≤ 0.8.1 remain MIT.

What's new in 0.7.1

• ✂️ Text-selection pins in the apply loop — /pinappai:apply and /pinappai:fix-changes now branch on pin_kind: 'text': the reviewer highlighted an exact text range; replace exactly that range using the selection_prefix / selection_suffix / selection_occurrence anchors.
• /changes/ page skeleton is now a shared contract (_shared/changes-page-skeleton.md, embedded in all four producer prompts): self-contained page (no site layout / cookie banners over the review UI), h2-per-page grouping with source-file meta, banner + generated stamp. Previously apply-generated pages only referenced these rules by name and shipped embedded in the site theme.
• Before/After content discipline in the item contract: text changes carry the LITERAL old/new text in .val (they're the revert snapshot); style commentary goes on a separate line; visual-only changes may describe.

What's new in 0.7.0

• /pinappai:reset-project prompt + pinappai_reset_review_data tool — reset a project's review data to zero: permanently deletes its change requests, iterations, reviewer decisions, AND all pins/comments with their screenshots on the server (pins joined the wipe in 0.7.2's server behavior — earlier "pins survive" wording no longer applies), then offers to remove the repo's static /changes/ page and .pinappai/last-applied.json marker. Explicit confirmation required; admin role required; not recoverable.
• Deleted change requests no longer haunt the review overlay. The widget now registers each /changes/ item's originating CR id (data-pp-applied-cr-id), and the server drops items whose CR was deleted — at registration time, at read time, and on CR delete. On the /changes/ page itself, items whose CR is gone no longer render a decision bar. Regenerate /changes/ via /pinappai:apply to pick up the attribute on older pages.

What's new in 0.6.2

• Fail-fast on Node < 18 — actionable error instead of a deep fetch is not defined stack trace (see Requirements).
• Honest version reporting — serverInfo.version is read from package.json at runtime; it was previously hardcoded and stale, so MCP logs reported the wrong version.
• /pinappai:apply emits the /changes/ locator attributes (data-pp-page-url + data-pp-source-selector) on every generated item (added 0.6.1). Without data-pp-page-url the in-page "N changes to review" chip never appears — regenerate /changes/ via /pinappai:apply to pick up the fix.

Upgrading: npx caches resolved builds, so a new publish doesn't take effect until you clear the cache (rm -rf ~/.npm/_npx) and restart your client.

What's new in 0.5.0

Zero-arg prompts. The project argument is now optional on these prompts (analyze, remove, summarize, generate-changes-page). When omitted, the prompt resolves the project from .pinappai/context.json if bound, otherwise calls list_projects and asks you to pick (auto-selects when your workspace has one project). On first pick, it offers to bind the slug back to the repo so every subsequent run is zero-prompt.

Customer-facing impact: /pinappai:apply-decisions works directly — no slug typing. generate-changes-page no longer asks you to paste a pk_... widget key either; it derives the key from the resolved project's api_key field via get_project.

setup-project writes .pinappai/context.json on install so the first /pinappai:apply-decisions after install skips the bind-to-repo prompt entirely. One file ships with the install commit alongside .pinappai/last-applied.json.

apply-decisions Step 7 closes the iteration loop. After applying the batch, the prompt asks Regenerate /changes/ now? [Y/n] and stages the regenerated page alongside the source edits + marker so the whole round lands in a single commit. Default is yes. Skip with n to regenerate manually later via /pinappai:generate-changes-page.

New shared block: _shared/project-resolution.md centralizes the explicit-arg → context.json → list_projects fallback chain so all 7 slug-aware prompts behave identically. Same pattern as the existing marker-write.md / landing-chooser.md / widget-snippet.md shared blocks — change one file, every prompt updates.

5 new iteration-loop tools from the Phase 3 server-side parallel /me API surface: pinappai_open_iteration, pinappai_list_iterations, pinappai_get_iteration_coverage, pinappai_acknowledge_change_request, pinappai_mark_iteration_applied. 32 tools total.

Two new prompts: /pinappai:embed-widget (install widget into an existing project) and /pinappai:analyze (read-only triage report, produces a cluster summary without editing source). 11 prompts total.

What's new in 0.4.0

The install flow stops asking you to copy-paste a long JSON snippet:

npx @pinappai/mcp install   # write the MCP entry into your AI client configs
npx @pinappai/mcp login     # browser sign-in; mints a per-machine key

That's it. login opens a browser tab, you sign in, pick a workspace if you have multiple, click Authorize, and the CLI saves the freshly minted ppk_… key to a local credentials file. Restart your AI client and the slash commands appear.

Four new subcommands: install, login, logout, uninstall. Mirrors gh auth login, wrangler login, vercel login, etc. — your muscle memory transfers.

Matched server-side feature: a new device-code endpoint group at /api/v1/cli/auth/* and a workspace-picker page at app.pinappai.com/cli-approve.html. CI / scripted installs still work via the PINAPPAI_API_KEY env var (see "CI / headless" below).

Plus a small naming cleanup: the old /pinappai:uninstall slash command is now /pinappai:remove (since it removes the widget from your customer's site, distinct from pinappai-mcp uninstall which removes the MCP from your AI client config).

What's new in 0.3.0

v0.3.0 adds the two prompts that close the iteration loop plus the shared infrastructure that makes the loop iteration-aware:

• /pinappai:apply-decisions — fetch admin-queued decisions, group by file, apply rollbacks (revert to original) and modifies (apply reviewer's literal request) in one batch. Mirrors fix-changes shape but for the Approvals path. The MCP-native version of the admin's "Copy decisions for AI" export.
• /pinappai:remove — strip widget + /changes/ + helpers when you're shipping the rewrite. Four git grep verification steps. Preserves the .pinappai/ directory by design — re-installing later drops you back into the same baseline.

New shared infrastructure across all applies-to-source prompts:

• .pinappai/last-applied.json — iteration boundary marker (ISO timestamp). Written at end of every apply run. The next /changes/ regen scopes to "git log --since=" — reviewers only see what's drifted since the last apply.
• .pinappai/context.json — project-shape cache (stack, build / lint commands, route convention, localization, text_lives_in). Detected once, then read by every prompt.
• Landing-chooser pattern — every prompt that edits source ends with a verbatim a/b/c/d picker (new branch / commit current / stage only / skip) so the AI never auto-commits. Branch protection respected; --no-verify never used.

Net: 10 prompts total, full pipeline coverage from setup-project through remove.

What's new in 0.2.0

The original v0.1.x release was read-only — list projects, list change requests, fetch screenshots, run pattern analysis. v0.2.0 adds write tools that mirror the admin panel surface so a Claude Code user can do almost everything from inside their editor:

• Project lifecycle (create / update / archive / unarchive)
• Workspace lifecycle (list / create / rename / soft-delete)
• Members + reviewers (invite / role change / remove / revoke)
• Change-request status transitions (open → processing → done / wontfix)
• Audit-log review (Business tier, owner role)
• API-key list / revoke / restore (creating new keys still happens in the admin UI — by design)
• Self-service profile + GDPR Art. 15 data export

The original 6 read tools and 5 read-prompts continue to work unchanged. See "Permissions" below for the security model.

Install

Recommended (0.4.0+) — two commands, no key copy/paste

npx @pinappai/mcp install   # registers the MCP server in your AI client configs
npx @pinappai/mcp login     # opens browser, mints a per-machine key, saves it locally

install writes the MCP entry into every detected AI client config (Claude Code, Cursor, Claude Desktop, Codex CLI, Continue). login opens your browser for sign-in, picks a workspace if you have multiple, and saves the freshly minted key to a local credentials file under ~/.config/pinappai/. Restart your AI client and the slash commands appear under /pinappai:….

To check who you're signed in as or change accounts, run npx @pinappai/mcp login again — it overwrites the existing credentials. To sign out, npx @pinappai/mcp logout deletes the credentials file. To remove the MCP entry from your AI client configs, npx @pinappai/mcp uninstall.

CI / headless / scripted installs

The browser-based login doesn't fit non-interactive environments, so the MCP server also reads PINAPPAI_API_KEY from the env first, with the credentials file as a fallback. For CI:

PINAPPAI_API_KEY=ppk_… npx -y @pinappai/mcp

Mint a key for this in the admin UI at app.pinappai.com/api-keys — name it after the machine / pipeline so you can revoke it cleanly later.

Manual install (advanced)

If you'd rather wire the MCP into a single client by hand — or you need to pin a specific version — these are the per-client snippets the new install writes for you. You can edit them directly and skip the install command.

Claude Code

claude mcp add-json pinappai '{"type":"stdio","command":"npx","args":["-y","@pinappai/mcp"],"env":{"PINAPPAI_API_KEY":"ppk_..."}}'

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "pinappai": {
      "command": "npx",
      "args": ["-y", "@pinappai/mcp"],
      "env": { "PINAPPAI_API_KEY": "ppk_..." }
    }
  }
}

Restart Cursor.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pinappai": {
      "command": "npx",
      "args": ["-y", "@pinappai/mcp"],
      "env": { "PINAPPAI_API_KEY": "ppk_..." }
    }
  }
}

Restart Claude Desktop.

Codex CLI

Edit ~/.codex/config.toml:

[mcp_servers.pinappai]
command = "npx"
args = ["-y", "@pinappai/mcp"]

[mcp_servers.pinappai.env]
PINAPPAI_API_KEY = "ppk_..."

Continue

Edit ~/.continue/config.yaml:

mcpServers:
  - name: pinappai
    command: npx
    args:
      - "-y"
      - "@pinappai/mcp"
    env:
      PINAPPAI_API_KEY: ppk_...

PINAPPAI_API_BASE defaults to https://api.pinappai.com. Override in the env block if you're hitting a non-prod base.

Verify

In your AI client, type /pinappai — the slash commands should auto-complete. If they don't, run /pinappai:auth-help and the AI walks you through diagnosis.

Tools

Read tools (v0.1.x)

Tool	Returns
list_projects	Projects this key can access (slug, name, domain, counts)
get_review_summary	Totals + by-page + by-reviewer for a project
list_change_requests	Filtered list with cursor pagination (default: change_requested only)
get_change_request	Full CR detail + related[] (same selector + same page) + optional inline image
analyze_patterns	Deterministic groupings + heuristic clusters + (when sampling supported) AI-judged clusters
get_screenshot	Inline image content block for a CR's screenshot

Project + change-request writes (v0.2.0)

Tool	Effect
get_project	Single project detail (incl. embeddable widget api_key)
create_project	Create a new project in the api-key's workspace (editor+)
update_project	Rename / change allowed_origins / toggle anonymous reviewers (editor+)
archive_project	Soft-archive, reversible (owner)
unarchive_project	Restore an archived project (owner)
update_change_request	Transition admin_status: open → processing → done / wontfix (editor+)

Workspace + member + reviewer writes (v0.2.0)

Tool	Effect
list_workspaces	All workspaces the user is a member of (across keys)
create_workspace	Create a new workspace owned by the user (Team / Business tier for additional ones)
get_workspace	The api-key's workspace details + role
update_workspace	Rename / re-slug (owner)
delete_workspace	Soft-delete with 7-day grace, recoverable via email magic link (owner)
list_members / invite_member / update_member_role / remove_member	Member CRUD (admin+). On a full Team plan, invite_member returns 409 seat_required — the MCP surface never charges a seat; add one on the billing page (billing owner) first, then invite.
list_reviewers / invite_reviewer / revoke_reviewer	Project reviewer CRUD (editor+)

Audit + api-keys + me (v0.2.0)

Tool	Effect
list_audit_events	Paginated audit-log read for the workspace (owner, Business tier)
list_api_keys / get_api_key	List + detail (no plaintext returned) (admin+)
revoke_api_key	Soft-revoke; refuses to revoke the calling key (admin+)
restore_api_key	Undo a revoke within 7 days (admin+)
get_me	Whoami probe (user + workspace + role + key metadata)
update_me_profile	Change the user's display name
export_my_data	GDPR Art. 15 right-of-access export

API-key creation is intentionally NOT exposed — mint keys at app.pinappai.com/api-keys. Permanent project deletion + change-request hard-delete are also admin-UI-only (irreversible operations stay human-driven).

Prompts (slash commands)

Slash command	Purpose
/pinappai:setup-project	Pick / create workspace → create project → emit widget snippet → bootstrap iteration marker
/pinappai:generate-changes-page	Generate or regenerate /changes/; reads .pinappai/last-applied.json to scope diff
/pinappai:remove	Strip widget + /changes/ + helpers when shipping; preserves .pinappai/
/pinappai:analyze	Read-only triage report (no edits)
/pinappai:summarize	PR body / changelog / customer email generator
/pinappai:audit-review	Pull recent audit events, summarize unusual activity
/pinappai:auth-help	Setup walkthrough

Permissions

A ppk_… key inherits the full workspace role of the user who minted it. Owner-minted keys can do owner-only things via MCP (delete the workspace, invite admins, read the audit log). Viewer-minted keys are read-only.

This means losing a ppk_ key is roughly as bad as losing the issuing user's session for that workspace. Treat them with the same care:

• Mint a separate key per machine / context, named so you can identify what it's for.
• Revoke + re-mint immediately if a key leaks.
• Don't commit ppk_ strings to source control.

The api-key inherits the workspace boundary too — it can only act on projects / members / reviewers / audit rows of ONE workspace, regardless of how many other workspaces the issuing user belongs to. To act on a different workspace, mint a new key for that workspace.

Safe-by-design omissions

Operations the admin panel exposes but MCP does NOT:

• Creating new API keys — minting a key is a "give an LLM forever- power" action. We require a human at the dashboard.
• Permanent project deletion — irreversible cascade through R2 + feedback rows.
• Hard-deleting individual change requests — irreversible. Use update_change_request with admin_status: wontfix to remove a row from the active queue without losing audit history.
• Account deletion / MFA setup / session management — multi-factor flows that need a human at the dashboard.
• Widget upload of screenshots / expected items — those are reviewer-side widget APIs, not admin operations.

Troubleshooting

Symptom	Likely cause + fix
auth_invalid_key error	Your ppk_… is missing, malformed, revoked, or expired. Run /pinappai:auth-help or visit app.pinappai.com/api-keys.
not_found for a project	Run list_projects to see what your key can access. Cross-workspace ids return not_found (not 403) on purpose.
forbidden when calling a write tool	Your key's role is below what the tool requires. get_me shows your role; mint a key as a higher-role user, or ask one to do the action.
cannot_revoke_self	You tried to revoke_api_key with the calling key's id. Mint a replacement first, then revoke from the admin UI.
plan_upgrade_required on list_audit_events	Audit log is a Business-tier feature. See pinappai.com/pricing.
AI clusters not appearing	Your AI client may not support MCP sampling/createMessage. The tool degrades gracefully — it returns deterministic clusters + an ai_clustering_hint for the AI to apply inline.
Slash commands missing	Confirm your client supports MCP prompts/list. Try restarting the client after install.

Security

• Plaintext keys are HMAC-hashed with a server-side pepper before storage. Never logged. Never echoed.
• Stderr redaction strips any accidentally-emitted ppk_… strings.
• Write tools annotated with destructiveHint: true so MCP hosts can surface confirmation prompts before invoke (varies by host).
• Key rotation runbook + incident playbook live in docs/api-keys.md in the source repo.

NEVER commit your ppk_ key to source control. The MCP itself redacts it from logs; you should treat it the same way at the application level.

License

PinAppAI Client License (proprietary) — see the LICENSE file. Install and run freely to use the PinAppAI service; redistribution, modification and derivative works are not permitted. Versions up to and including 0.8.1 were published under MIT.