@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 204 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
Malicious Chrome and Firefox extensions target Axiom Trade and Padre users, stealing session tokens and wallet data.
Security News
GPT-6 Astra hits 100% on ExploitBench and finds zero-days autonomously, while independent tests reveal scope violations and monitoring gaps.
Product
Socket can now send alerts and supply chain attack notifications to Microsoft Teams, with filters that route the right updates to each channel.