PinAppAI
Visual website feedback your coding agent applies: pin change requests on the live site over MCP.
Open source Open in the app JSON README (API)
About
Visual website feedback your coding agent applies: pin change requests on the live site over MCP.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- com.pinappai
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.9.9
- Added
- 2026-08-29 03:01:19
- Updated
- 2026-08-29 03:01:19
- Origin id
com.pinappai/mcp
README
# @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](https://modelcontextprotocol.io) 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.10
- `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.
## What's new in 0.9.9
- `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.
## What's new in 0.9.8
- `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.
## What's new in 0.9.7
- Display name: MCP clients and connector directories now show **PinAppAI** as the server's title (added the `Implementation.title` field). No tool, workflow, or CLI changes.
- The hosted HTTP connector (`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.
## What's new in 0.9.6
- The [MCP Server Registry](https://registry.modelcontextprotocol.io/) entry now also lists the hosted HTTP connector (`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.
- Packaging: the shared tool/prompt registry is now vendored into the published tarball (internal restructuring; no API or tool changes).
## What's new in 0.9.5
- Published to the official [MCP Server Registry](https://registry.modelcontextprotocol.io/) as `com.pinappai/mcp` (the `mcpName` field in package.json is the registry's ownership proof; `server.json` holds the registry metadata). No runtime changes.
## What's new in 0.9.4
- **`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.
## 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:
```bash
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=<this timestamp>" — 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
```bash
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:
```bash
PINAPPAI_API_KEY=ppk_… npx -y @pinappai/mcp
```
Mint a key for this in the admin UI at
[app.pinappai.com/api-keys](https://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
```bash
claude mcp add-json pinappai '{"type":"stdio","command":"npx","args":["-y","@pinappai/mcp"],"env":{"PINAPPAI_API_KEY":"ppk_..."}}'
```
#### Cursor
Edit `~/.cursor/mcp.json`:
```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`:
```json
{
"mcpServers": {
"pinappai": {
"command": "npx",
"args": ["-y", "@pinappai/mcp"],
"env": { "PINAPPAI_API_KEY": "ppk_..." }
}
}
}
```
Restart Claude Desktop.
#### Codex CLI
Edit `~/.codex/config.toml`:
```toml
[mcp_servers.pinappai]
command = "npx"
args = ["-y", "@pinappai/mcp"]
[mcp_servers.pinappai.env]
PINAPPAI_API_KEY = "ppk_..."
```
#### Continue
Edit `~/.continue/config.yaml`:
```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](https://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](https://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](https://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`](https://github.com/DodoGit/pinappai/blob/main/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.