@pinappai/mcp
Advanced tools
Model Context Protocol server for PinAppAI — install with `npx @pinappai/mcp install` + `login`, drive almost the full admin panel from Claude Code / Cursor / etc.
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, Claude Desktop, Cursor, Codex CLI, Continue, Zed, and any other MCP-compatible client.
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.
/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./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.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.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.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).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.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.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)./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..val (they're the revert snapshot);
style commentary goes on a separate line; visual-only changes may
describe./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./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.fetch is not defined stack trace (see Requirements).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:
npxcaches resolved builds, so a new publish doesn't take effect until you clear the cache (rm -rf ~/.npm/_npx) and restart your client.
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.
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).
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.--no-verify never used.Net: 10 prompts total, full pipeline coverage from setup-project through
remove.
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:
The original 6 read tools and 5 read-prompts continue to work unchanged. See "Permissions" below for the security model.
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.
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.
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 mcp add-json pinappai '{"type":"stdio","command":"npx","args":["-y","@pinappai/mcp"],"env":{"PINAPPAI_API_KEY":"ppk_..."}}'
Edit ~/.cursor/mcp.json:
{
"mcpServers": {
"pinappai": {
"command": "npx",
"args": ["-y", "@pinappai/mcp"],
"env": { "PINAPPAI_API_KEY": "ppk_..." }
}
}
}
Restart Cursor.
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.
Edit ~/.codex/config.toml:
[mcp_servers.pinappai]
command = "npx"
args = ["-y", "@pinappai/mcp"]
[mcp_servers.pinappai.env]
PINAPPAI_API_KEY = "ppk_..."
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.
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.
| 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 |
| 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+) |
| 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+) |
| 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).
| 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 |
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:
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.
Operations the admin panel exposes but MCP does NOT:
update_change_request with admin_status: wontfix to remove a row
from the active queue without losing audit history.| 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. |
ppk_… strings.destructiveHint: true so MCP hosts can
surface confirmation prompts before invoke (varies by host).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.
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.
FAQs
Model Context Protocol server for PinAppAI — install with `npx @pinappai/mcp install` + `login`, drive almost the full admin panel from Claude Code / Cursor / etc.
The npm package @pinappai/mcp receives a total of 111 weekly downloads. As such, @pinappai/mcp popularity was classified as not popular.
We found that @pinappai/mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Research
/Security News
A Twitch browser extension on Chrome and Firefox forwards users’ live OAuth session tokens through proxies controlled by a Russian bot service.
Security News
Anthropic found biased reasoning and recklessness drove Claude Mythos 5 to publish malware on PyPI and compromise a security vendor.
Research
/Security News
Malicious Chrome and Firefox extensions target Axiom Trade and Padre users, stealing session tokens and wallet data.