# jcooley8/pincushion-plugin [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/jcooley8/pincushion-plugin  
**GitHub Stars:** 1  
**npm Downloads (last month):** 2981  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/jcooley8-pincushion-plugin

## Description
Visual feedback as agent work packets. Stakeholders drop pins on your live app; your AI coding agent reads each pin (selector, screenshot, DOM snippet, thread, acceptance criteria) via MCP and ships the fix, recording the commit/branch/PR on resolve. Install: npx pincushion-mcp.

## Tools
Capabilities this server exposes over MCP:

- **get_annotations** — Retrieve annotation pins from the .feedback/ directory. Filter by page URL, LWC component name, or status. Use this to understand what feedback exists before making changes.
- **search_annotations** — Full-text search across all annotation comments, selectors, component names, and tags.
- **get_feedback_summary** — Get a high-level rollup of all open feedback: counts by status, page, and component. Use this to plan what to address first.
- **get_component_feedback** — Get all feedback pins targeting a specific LWC component, with a plain-language summary ready for implementation. Returns element selectors, comments, and thread history.
- **resolve_annotation** — Mark an annotation as resolved after addressing the feedback. Optionally add a resolution comment explaining what was changed.
- **add_agent_reply** — Add a reply to an annotation thread (e.g. to ask a clarifying question or note a finding).
- **get_reply_candidates** — Used by /pincushion-replies. Returns pins where Pincushion AI should respond, with each candidate tagged by trigger reason. Two triggers: (a) "mention" — the latest thread message contains @pincushion AND was authored by a human; (b) "reply-on-bot-pin" — the pin was originally authored by Pincushion AI and the latest message is from a human. Skips resolved/archived pins and any pin where the latest message is already bot-authored (idempotency). Newest-first ordering so the slash command can pace replies.
- **add_bot_reply** — Post a Pincushion AI reply to a pin's thread. Hardcodes author="Pincushion AI" and authorEmail="pincushion-bot@pincushion.io" so the Chrome extension applies bot styling. ONLY call from the /pincushion-replies flow — never as a generic reply. Refuses to post if the latest thread message is already bot-authored (defense-in-depth idempotency).
- **get_pending_critiques** — Used by /critique-latest-deploy. Lists pending critique requests queued by the deploy-hook for the current license. Newer receipts also include a deployment event, prior page outcomes, project-page inventory, and latest per-device capture receipts for truthful local reconciliation before Crit runs. Newest-first. Free on all plans (the gating happened at enqueue time on the deploy-hook side: Pro/Team — including trial-Pro — always enqueue; free licenses enqueue while their monthly AI-action pool has headroom).
- **get_pending_deployment_frame_refreshes** — Lists production deployment frame-refresh work independently of the Critique queue. Use this even when autoCritique is false. The result is redacted: it contains no deployment URL/hash, browser state, storage path, or capture proof. Start a selected run before capturing.
- **start_deployment_capture_run** — Starts one short-lived local frame-refresh run for an exact deployment and returns its opaque proof once. Keep the proof only in process and pass it to authenticated upload_page_snapshot/record_deployment_page_result/complete_deployment_capture_run calls; never put it in capture-snapshot, shell argv, a report, pin, status message, or file.
- **complete_deployment_capture_run** — Requests server-side frame-refresh completion after all exact page/device receipts have been recorded. The server rejects missing, stale, replayed, cross-deployment, or expired capture-run evidence and never treats a queue state as a current frame.
- **complete_critique_request** — Mark a critique_queue request as completed after the critic subagent has run on its page URLs. Pass the request id (from get_pending_critiques) and the total pin_count produced. The server scopes the update to your license — you cannot complete another tenant's request even if you know the id.
- **register_deployment_discovered_pages** — Register the exact bounded URL inventory discovered in one local browser context before staging deployment captures. The backend returns accepted pending pages; upload snapshots and record terminal results only for that returned subset, never for a locally guessed URL.
- **record_deployment_page_result** — Record one terminal page result for a deployment frame refresh. Every non-removed page in an initialized frame refresh must upload a newly staged desktop/mobile image pair from the exact active run, then submit those newly staged desktop/mobile version IDs and hashes with captureRunId and opaque captureProof. For unchanged, the server recomputes the image-byte hashes, accepts only an exact match to the frozen canonical pair, records the new evidence as observed, and discards the private duplicate pair; use updated if either byte hash differs. The deploy hook alone freezes removed rows, so callers cannot submit removed for an initialized run. Only server-confirmed historical pre-frame not_requested receipts retain a legacy no-run route. The server finalizes only after every initialized page has the current exact capture-run pair; a Critique queue state alone is never frame-current.
- **create_critique_pin** — Create a pin authored by Pincushion AI. ONLY call this from the pincushion-critic subagent or the /critique-latest-deploy flow — never from a regular user prompt, since the bot voice is reserved for AI-driven UI/copy/a11y and product-experience feedback (flows, empty/error states, terminology, trust). Each call should produce one tasteful, high-signal pin (max 3 per page in a critique run). The body must be concrete and actionable: name the specific element + the specific problem + the suggested fix in <40 words (up to 55 for a flow critique that must name the step before/after). Forbidden: layout philosophy, business-model commentary, roadmap ideation (a missing affordance at a specific element IS in scope), generic "consider improving hierarchy" advice. Always read the project's critique context (`ai.critique.effectiveContext` from get_project_context — falls back to `brandContext` when no compiled brief exists) before drafting the body so the critique is on-brand. If `ai.critique.staleness` is "stale" or "missing", suggest the user run /refresh-brand before continuing. Repeating the same semantic finding on the same route and selector with only query values changed returns `duplicate_variant`; inspect a distinct state, scenario, or element instead.
- **create_agent_pin** — File a pin as a THIRD-PARTY agent — the write half of the browser-agent → coding-agent handoff. Use when a QA/browser agent (Claude in Chrome, computer-use, a Playwright a11y/visual check, a CI checker) finds a concrete issue on a page and wants to hand it to the implementing agent as a work packet. NOT the Pincushion AI voice: the pin renders as "<agentName> (agent)" with an agent chip (enforced server-side; is_bot/bot styling stays reserved for the critic). Pins start "open" and get triaged like any pin — never pre-approved. Each pin should be one specific element + problem + suggested fix; include acceptanceCriteria when the finding has a testable definition of done. Metered as an AI action (agent_pin). Repeating the same semantic finding on the same route and selector with only query values changed returns `duplicate_variant`; inspect a distinct state, scenario, or element instead.
- **import_qa_results** — Pilot: import already-parsed axe JSON or Playwright JSON from an authenticated owner/editor/developer. Use dryRun=true to preview normalization and exact deduplication identities without writing. Repeated imports update one project + canonical page + device + rule + target record and preserve provenance. Failed observations may create or update open agent pins; passed, skipped, and inconclusive observations never resolve pins, change pin statuses, or qualify as trusted verification. The importer never reads files, fetches URLs, calls a provider, or uploads repository contents.
- **fix_and_resolve** — Resolve a pin after applying a code fix. Transitions the pin directly to "resolved" status so it disappears from the stakeholder view. No thread comment is added — the commit is the record of the fix. Pass commitSha (from `git rev-parse HEAD`), branchName (`git branch --show-current`), and prUrl (from `gh pr view --json url -q .url` if a PR was opened) so the Pincushion dashboard can link the pin to the implementing commit, branch, and PR.
- **get_time_to_fix_metrics** — Compute median + p25/p75 time-to-fix from resolved pins. Returns sample size + threshold flag so callers can honestly hide the metric when the dataset is too small (< 5 resolved pins). This is the marketing proof point that distinguishes Pincushion from "manage feedback" tools — agent-native means fast.
- **record_pin_verification** — Record a caller-reported verification verdict using the compatible legacy workflow. This does not independently prove deployment, check execution, or client acceptance. For pilot projects, submit_verification_report records append-only observations and attach_verification_run obtains separately validated check evidence.
- **submit_verification_report** — Pilot: append a project-scoped caller-reported verification observation. An idempotency key makes retries safe. Reported success is not independent check evidence or client acceptance.
- **attach_verification_run** — Pilot: ask Pincushion to retrieve and validate a configured GitHub Actions run for an existing verification report. The server selects the trusted repository, workflow, checks, and artifacts. This starts no runner and cannot record client acceptance.
- **get_pin_verification** — Read authoritative verification evidence for one explicit project and pin. Separates caller reports, deployment receipts, independently retrieved checks, and client acceptance. Missing evidence stays unknown.
- **get_agency_coordination_state** — Pilot: read the exact owner/editor-only agency coordination state for one project. This does not enable the pilot, grant membership, or reveal internal data to commenters, public reports, widgets, search, attachments, or notifications.
- **set_agency_coordination_pilot** — Pilot: owner-only switch for the private agency coordination increment. It is off by default. Enabling it does not change prices, seats, stakeholder access, public reports, or existing pin workflows.
- **create_agency_label** — Pilot: create an owner/editor-only custom label. Labels are private agency metadata and never alter public annotation tags or appear in a public report.
- **archive_agency_label** — Pilot: archive one owner/editor-only agency label. Archived labels cannot be applied or used in a filtered read.
- **set_agency_pin_labels** — Pilot: replace the private agency-label set on one pin. Every label must belong to the same exact project and be active; cross-project and archived labels fail closed.
- **add_agency_internal_message** — Pilot: append an owner/editor-only internal thread note to one pin. It never enters the public pin thread, report, widget, attachment system, search, or notification pipeline. Reuse the idempotency key only for an identical retry.
- **get_agency_internal_thread** — Pilot: read the append-only internal agency thread for one exact pin. This is restricted server-side to the current project owner/editor and is separate from the public pin discussion.
- **list_agency_pins** — Pilot: read owner/editor-only pins with private labels and evidence summaries. `status`, `pageUrl`, `device`, and `labelIds` compose as an AND filter. The result contains no public-thread expansion, attachments, reviewer email, guest session, or presence data.
- **get_review_activity** — Pilot: read authenticated client-review decisions and completion for exact frozen review versions. It intentionally reports no speculative online/presence state and does not expose reviewers' emails or guest-session identifiers.
- **export_agency_evidence** — Pilot: produce a bounded owner/editor-only structured export for one project, filtered exactly like list_agency_pins. Includes review version and evidence provenance; it omits reviewer email, guest sessions, tokens, attachment locators, signed URLs, and provider payloads. The authenticated browser export relay can render this same authoritative projection as CSV or PDF.
- **link_pin_deploy** — Link a deploy URL to a resolved pin. Typically called by the deploy-hook edge function once a deploy that includes the pin's fix goes live. Stakeholders see the deploy URL on the resolved pin in the dashboard. Re-runs overwrite the previous deploy URL (latest deploy wins).
- **get_setup_instructions** — Continue an existing critique with claim, or start a project with setup and explicit editor selection. Includes authenticated project checks and exact approved-pin implementation guidance; the browser extension is optional.
- **start_quickstart_demo** — Start the 60-second Pincushion quickstart: returns one sample stakeholder feedback pin (element selector + thread + acceptance criteria) on a bundled demo page that is copied to .feedback/.quickstart/landing.html. Edit ONLY that copy to satisfy the pin, then call resolve_quickstart_demo. Nothing is written to the real project or synced to the cloud. Use this to show a new user the full read-pin -> fix-code -> resolve loop.
- **resolve_quickstart_demo** — Finish the quickstart demo loop after editing the demo copy. Confirms the change, returns the bridge to real usage, and cleans up the throwaway .feedback/.quickstart/ files. Does NOT create or resolve any real pin.
- **get_project_context** — Read-only lookup of a project's context (name, URLs, brand context, autoCritique flag, traceability settings). Use this whenever you only need to inspect — never mutates, never touches the network. The Pincushion AI critic subagent calls this before generating any pin, since `configure_project` would otherwise upsert the project, sync to cloud, and create a deploy hook on a typo'd project name. Pass `projectId` for an exact lookup, `name` to look up by display name, or no arguments to list all projects in this workspace.
- **get_project_identity_diagnostic** — Read-only diagnostic for project identity repair. Returns only authentication state, safe key source/last-4 provenance, local project-cache state, candidate statuses, and URL/ID ambiguity. Never returns credentials or performs a network request or mutation.
- **configure_project** — Register a Pincushion project and associate it with your app's URLs. Registration does not call a deployment provider or modify source/CI. The response includes a redacted provider-neutral manual setup handoff. An agent may set deploymentAutomation to "auto" only after explicit owner consent; it first detects all local candidates, requires deploymentProvider when they are ambiguous, and begins an owner-keyed lifecycle only when an admitted provider adapter and private receiver setup are available. Otherwise it stays manual and redacted. Provider read-back is not proof of a first accepted production receipt, reconciliation, fresh desktop/mobile frames, queue completion, or external Crit evidence. Use get_deployment_reconciliation_status for those independent states. **NOTE for read-only use cases:** if you only need to look up brand context, URLs, or other project metadata, call `get_project_context` instead — `configure_project` mutates project registration state.
- **get_deployment_reconciliation_status** — Read a compact, provider-neutral deployment readiness diagnostic. It never creates a binding, rotates a credential, or calls a provider writer. Binding state, first accepted production receipt, reconciliation, fresh desktop/mobile frame state, capture run, queue, and external Crit evidence are reported independently. A claimed Vercel project ID is ownership provenance only and is never treated as a provider binding.
- **manage_deployment_automation** — Owner-keyed deployment automation management. inspect is read-only. repair is available only for a reported orphaned external provisioning attempt. rotate and revoke require confirmed: true. Results are redacted: no endpoint, credential, signing material, provider webhook IDs, or cleanup-debt IDs are returned.
- **update_critique_context** — Lightweight write-only path for the layered critique-context system. Use this from /setup and /refresh-brand after the dev agent has gathered repo signals (README, theme tokens, sample copy, competitor URLs, recent resolved pins) and compiled them into a critique brief. Unlike `configure_project`, this does NOT create a deploy hook, sync members, or validate URLs — it just persists the compiled brief (+ signals + policy) and pushes to cloud. Identify the project by `projectId` or `name`. The compiled `critiqueContext` is what the AI critic actually reads at pin time; `critiqueSignals` + `critiquePolicy` are inputs retained for traceability and the next recompile.
- **get_actionable_pins** — Get all pins waiting for developer attention. Returns three categories: (1) "auto-agent" — pins explicitly sent to the agent via "Send to Agent"; (2) "follow-up" — previously implemented pins with new user comments; (3) "review" — open reviewer comments that a developer has not yet picked up (the standard team collaboration queue). Use this as your starting point for both auto-agent workflows and manual review sessions.
- **claim_pin** — Claim an actionable pin before starting work on it. Transitions the pin from "pending_implementation" to "implementing" so other agents know it is being worked on. Call this before making changes, then call fix_and_resolve when done.
- **approve_pin** — Mark a pin as approved for implementation. Only approved pins should be implemented by agents. This transitions the pin from "open" to "approved" status.
- **assign_pin_to_agent** — Assign a pin directly to your local coding agent. Promotes the pin to "ready" (if not already), marks it as pending_implementation, and drops a trigger file in .feedback/.agent-queue/ that agent-loop.mjs picks up and dispatches to Cursor / Claude Code / Codex. This is the first-class "assign to agent" action — turns a pin into agent work in one call. Workflow: assign_pin_to_agent → (agent-loop dispatches) → fix_and_resolve.
- **implement_approved_pins** — CALL THIS FIRST when approved pins exist. Returns all stakeholder-approved pins grouped into **implementation packets** by page URL, each containing aggregated CSS selectors, full comment threads, and a suggested git branch name. One packet = one branch / one PR. Use the selectors to grep the source code, read the thread to understand what the stakeholder wants, then implement the fix. Workflow: implement_approved_pins → claim_pin → code change → fix_and_resolve. The result exposes both `packets` (canonical) and `pages` (alias).
- **get_implementation_packet** — Get a single implementation packet for one page URL. Useful when you want to batch-fix one page at a time. Returns the same shape as a single entry in implement_approved_pins.packets — pins, aggregated selectors, suggested branch, traceability config. Matches by exact URL or partial substring.
- **get_selected_pins** — Get pins that the developer has selected for implementation from the dashboard or PINS.md checkboxes. Returns the selected pin IDs with full context (element, thread, deep link). Use this to know which pins the developer wants you to work on next.
- **add_member** — Add a collaborator to a Pincushion project. Developers consume a paid seat and can implement pins. Commenters are free and unlimited. Returns an upgrade prompt if the seat limit is reached.
- **list_members** — List all members of a Pincushion project with their roles, plus seat usage info.
- **remove_member** — Remove a collaborator from a Pincushion project. Frees up the seat if they were an editor.
- **create_invite_link** — Generate a Figma-style shareable invite URL for a project. The recipient opens it, enters their name + email, and joins as the specified role. Returns the share URL plus expiry. Owners can mint Editor and Commenter links; Editors can mint Commenter links only. Editor links consume a paid seat on redemption.
- **create_share_report** — Mint a public read-only crit report link (pincushion.io/r/<token>) for a project: numbered pins with threads, screenshots, status, and the branch/PR/deploy/AI-verification trail. Anyone with the link can view it — no extension, no account, nothing to install. Free on every plan. Perfect for handing a design crit to a founder/client, or showing stakeholders what shipped. Optionally scope to a single page URL. Links never expire unless expiresInDays is set; viewers see live pin status.
- **upload_page_snapshot** — Upload a full-page screenshot that turns the public share report into an annotated page: viewers see the real page with numbered pin markers at true positions and click-to-open thread bubbles. Capture the page yourself (kill animations, scroll to force lazy loads, full-page shot, JPEG/WebP ≤5MB), resolve each open pin's element.selector to document-pixel coordinates IN THAT CAPTURE, and pass them as pinPositions. Owner/editor only. One snapshot per (project, page) — re-upload replaces it. pageUrl must match the pins' page_url verbatim.
- **generate_critique_report** — Turns supplied real captures into a report receipt; it does not inspect a page or generate feedback. By default it mints a Crit and therefore requires the exact Pincushion AI pin IDs the critic just created, each positioned in a supplied capture. Set purpose:"capture" only for an explicitly capture-only report.
- **configure_collaboration_integration** — Connect a Pincushion project to Slack, Microsoft Teams, or Discord using an incoming webhook. Low-noise defaults mirror Figma-style subscriptions: pin activity plus the deploy/verify loop, where pin_deployed/pin_verified attach as a quiet threaded reply under the pin (never a new top-level message). The louder agent-pin, email-pin, and share-report events are opt-in. For Discord, create a channel Incoming Webhook (Channel Settings → Integrations → Webhooks) and pass its URL.
- **create_slack_install_link** — Generate an Add-to-Slack OAuth URL pre-bound to a project. Most users should prefer the public storefront URL (also returned, https://pincushion.io/install/slack) — since May 2026, that auto-links to a Pincushion license when the installer's Slack email matches, and channels are subscribed afterward via /pincushion subscribe inside Slack. Use this agent-flow URL only when you want the install to attach to one specific project up front.
- **list_collaboration_integrations** — List Slack and Microsoft Teams webhook subscriptions for a Pincushion project. Webhook URLs are masked.
- **claim_pending_slack_install** — LEGACY FALLBACK. Since May 2026, Slack installs auto-link to a Pincushion license when the installer's Slack email matches, and channels are subscribed via /pincushion subscribe inside Slack — no claim token needed. This tool only applies when the installer's Slack email did NOT match an active Pincushion license at install time (the user sees a claim_token on the post-install page in that case). Pass claimToken (the on-page token, valid 7 days) + projectId to attach the webhook. Calling with no claimToken returns the new flow instructions instead of an error.
- **remove_collaboration_integration** — Remove a Slack, Microsoft Teams, or Discord webhook subscription from a Pincushion project.
- **preview_collaboration_notification** — Preview the Slack, Teams, or Discord notification shape and recommended event routing before connecting a real webhook.
- **set_slack_preferences** — Read or update the caller's Slack DM preferences. Resolves the user via license_key → email, then applies the change across every Slack workspace the email is linked to. Call with no args to see current state. Call with `mute: "1h"` (or "today", "forever", "off") to silence DMs for a window. Call with `eventNewPin: false` (or any event_* flag) to toggle individual event types off. Same surface as the App Home toggles and `/pincushion mute`, accessible from the agent — useful for "mute pin DMs during this refactor" workflows.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "pincushion-plugin": {
    "command": "npx",
    "args": ["-y","pincushion-mcp"]
  }
}
```

## Documentation

## What jcooley8/pincushion-plugin MCP server does

jcooley8/pincushion-plugin turns Pincushion annotations into implementation-oriented work packets for AI coding agents. A pin can carry the affected page URL, element selector, screenshot, viewport, DOM excerpt, discussion thread, project context, likely files, and acceptance criteria. This gives an agent both the location of a problem and the context needed to investigate it.

The server supports the full feedback loop: read incoming pins, search or group them, ask questions in a thread, apply a fix, and mark the item resolved. Resolution can include the commit SHA, branch name, and pull-request URL so the dashboard can connect feedback to shipped code.

## How it works

The package runs with `npx pincushion-mcp`. By default it uses MCP over stdio and reads local project feedback from `.feedback/`. Hosted cloud synchronization can be enabled through sign-in; the normal hosted setup does not require a separate Supabase project, database, or backend API key. A REST mode is also available when an HTTP endpoint is preferred.

The repository includes a Claude Code plugin that starts the MCP process for the open project and provides commands for viewing pins, implementing work, resolving feedback, reviewing summaries, and setup. The server can also be used from other MCP-compatible editors and agents.

## Setup and configuration

For hosted setup, run:

```bash
npx pincushion-mcp setup
```

The setup wizard signs in, asks for project URLs, and lets the user select an editor. Restart the editor afterward and verify the connection by asking the agent to call a project-context or actionable-pins tool. If authentication is missing or expired, run `npx pincushion-mcp login`.

Useful command-line options include:

- `--project-dir PATH` to select the project containing `.feedback/`.
- `--cloud-sync` to explicitly enable hosted synchronization.
- `--rest` to run the REST API mode.
- `--port PORT` to choose the REST port, which defaults to 3456.
- `--sync-url URL` and `--api-key KEY` for the optional legacy self-host adapter.
- `--license-key KEY` to provide an explicit account credential override.

The documented runtime requirement is Node.js 22.22+ within Node 22, or Node 24.

## Tools and capabilities

Feedback discovery includes annotation retrieval with page, LWC component, and status filters; full-text annotation search; status, page, priority, and component summaries; and component-specific feedback with implementation-oriented summaries. `get_implementation_packet` can collect the pins for one page, while `assign_pin_to_agent` places a pin in the local agent queue.

Conversation and completion tools include `add_agent_reply`, `resolve_annotation`, `fix_and_resolve`, and the Pincushion-specific bot reply flow. The combined fix-and-resolve operation can retain file, line, commit, branch, and pull-request details.

Additional workflows cover deployment frame refreshes, pending critique requests, deployment page registration and capture results, AI-authored critique or agent pins, QA JSON imports, time-to-fix metrics, and verification evidence. Pilot agency tools provide private labels, internal messages, and owner/editor coordination state.

## Limitations and notes

Some operations are intentionally restricted to particular workflows. Bot replies and critique pins are reserved for Pincushion AI flows, while agent pins represent third-party QA or browser agents. Deployment capture requires exact page and device receipts from the active run, and the server rejects missing, stale, replayed, cross-deployment, or expired evidence.

QA imports normalize already-parsed axe or Playwright JSON; they do not read files, fetch URLs, call a provider, or upload repository contents. Caller-reported verification is not independent proof of a deployment, check execution, or client acceptance. Time-to-fix metrics include a threshold signal and are intended to be hidden when fewer than five resolved pins are available.

_Full upstream README: https://allmcps.com/mcp/jcooley8-pincushion-plugin/readme_