jcooley8/pincushion-plugin

The implementation-context layer for AI-native development. Stakeholders drop visual pins on any page of your live app; your AI coding agent reads each pin through MCP and ships the fix — in Claude Code, Cursor, VS Code, Windsurf, or any MCP client.
What makes a Pincushion pin different
A pin isn't a feedback item — it's an **agent work packet**. Each one carries everything an agent needs to implement the change without a back-and-forth:
- **URL + element selector** — exactly what, exactly where
- **Screenshot + viewport + DOM snippet** — the visual and structural context
- **Thread + project context** — the conversation and the codebase it lives in
- **Likely files + acceptance criteria** — where to look, and how to know it's done
The loop closes itself: a stakeholder pins it → your agent reads it via MCP and fixes it in your IDE → the resolve records the commit, branch, and PR → an optional post-deploy critique verifies the fix actually landed.
This server is also how Pincushion AI runs design/copy/a11y critiques on a live page and writes the pins straight back onto it.
Hosted quick start
Use Node.js 22.22+ within Node 22, or Node 24, and run this in your app's repository:
The guided wizard signs you in to Pincushion, asks you to review the project URLs,
and explicitly choose an editor. It writes supported project MCP configuration when
safe; Manual, Skip, or a conflicting existing configuration can leave it unchanged.
Restart the editor and ask your agent to call get_project_context and
get_actionable_pins; configuration written alone does not verify a connection.
If you already have a critique report, run its npx pincushion-mcp claim
command from the owning app's repository instead, then verify a real pin read.
Pincushion hosts cloud sync. The normal setup does not require your own Supabase
project, database table, or backend API key. Sign-in supplies the existing account's
cloud credentials automatically; npx pincushion-mcp login is the recovery command
if sign-in is missing or expired. Do not paste credentials into issue reports.
Setup connects feedback access; it does not generate an AI critique. Critique execution
requires a supported coding-agent workflow and real page captures. A public report
lets reviewers add pins without an extension. Install the
optional Chrome extension only when you want
to place feedback directly on other web pages.
Use the maintained MCP setup guide for exact Claude Code,
Cursor, VS Code, and Codex commands, and the public documentation
for current plan limits and troubleshooting. The optional legacy self-host connection flags below are not prerequisites for
hosted setup.
CLI Flags
| Flag | Description | Default |
|------|-------------|---------|
| --project-dir PATH | Root directory containing .feedback/ | Current working directory |
| --sync-url URL | Optional legacy self-host adapter endpoint; not hosted setup | None |
| --api-key KEY | Optional legacy self-host adapter credential; not hosted setup | None |
| --license-key KEY | Explicit account credential override; normal hosted setup uses sign-in | Signed-in account when available |
| --cloud-sync | Turn hosted cloud sync on explicitly; it also turns on by itself when a signed-in account or PINCUSHION_LICENSE_KEY is present | On when an account is found |
| --rest | Enable REST API mode | Disabled (uses MCP/stdio) |
| --port PORT | Port for REST API server | 3456 |
Examples
**Local project:**
**Optional legacy self-host adapter (not hosted Pincushion setup):**
**REST API server:**
---
Tools
get_annotations
Retrieve annotations from .feedback/. Filter by page, component, or status.
**Parameters:**
- pageUrl (string, optional) — Filter by page URL (partial match)
- componentName (string, optional) — Filter by LWC component name
- status (string, optional) — Filter by open, in-progress, or resolved