@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, Codex CLI, Cursor, Claude Desktop, Continue, Zed, and any other MCP-compatible client.
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.
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.
npx @pinappai/mcp install no longer reports Claude Code as detected on machines that do not have it. Client detection treats "the config file's parent directory exists" as evidence a client is installed, which is sound for ~/.cursor, ~/.codex, ~/.continue and Claude Desktop, but Claude Code's config is ~/.claude.json whose parent is $HOME — present on every machine. So every install announced Claude Code and left a stray ~/.claude.json behind, even for people running only Cursor or Codex. $HOME is now never treated as evidence of an install; a client whose config sits directly in $HOME is detected by its actual config file. Detection of every other client is unchanged, verified across all five. Knock-on: login's "no AI clients detected yet" hint was previously unreachable and can now fire, so a client that is installed but has never been launched (no config file yet) asks you to launch it once first.get_change_request now surfaces screenshot.clean_url — the un-annotated twin of an annotated screenshot (screenshot-annotations feature, landed on main mid-0.9.8-cycle but never released). A field-reconstruction in the tool's response mapping was silently dropping it; now forwarded alongside url. null when a change request has no annotated screenshot or predates the feature. No other tool, workflow, or CLI changes — list_change_requests' canvas-pin position metadata (viewport, pin_kind) needed no MCP-side change, since that tool passes the API response through verbatim and the API-side fix is already live.npx @pinappai/mcp uninstall now also signs you out: it revokes the stored key server-side (best effort) and deletes the local credentials file, so one command fully detaches. The standalone logout command is unchanged, for when you want to sign out without removing the integration. A key supplied via PINAPPAI_API_KEY is never stored in the credentials file, so it is left untouched.Implementation.title field). No tool, workflow, or CLI changes.https://mcp.pinappai.com/mcp, a separate service from this npm package) now supports browser sign-in: connect with OAuth and no API key to paste. This npm package continues to authenticate with a ppk_ key as before.remotes: https://mcp.pinappai.com/mcp), so registry-driven clients can connect without installing this package. The npm package is unchanged in behavior and remains fully supported.com.pinappai/mcp (the mcpName field in package.json is the registry's ownership proof; server.json holds the registry metadata). No runtime changes.logout now revokes the key server-side before deleting the local
credentials file. Previously a "logged out" key stayed valid forever — a
still-running MCP session (or a copied credentials file) kept full access
after an account switch. Now running sessions on the old key stop
authenticating the moment you log out (restart your AI client to pick up
the new account after login). If the server is unreachable, logout says
so and points at the dashboard's API Keys page for manual revocation.auth-help reports who you're signed in as. The verification step now
leads with identity (name, email, workspace, role) via get_me before the
project list — so after switching accounts you can see at a glance which
one this session is actually using./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.--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.instructions tell prompt-less hosts to call it rather than
improvise a workflow from its name.npx @pinappai/mcp embed-widget)
now explains where to run it and exits 2, instead of booting a stray server.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./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 273 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.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Company News
Open source maintainers are under more pressure than ever. We're raising our open source program from the Team plan to the Business plan, free.
Security News
The supply chain control that delays freshly published gems now covers lockfile generation and gem vendoring in Ruby projects.
Security News
During a UK cyber test, a Mythos 5 agent used sockpuppets, social engineering, and prompt injection to try to get a maintainer to merge malware.