Labsco
jcooley8 logo

Pincushion

ā˜… 1

from jcooley8

Stakeholders pin feedback on your live app; your AI coding agent reads it via MCP and fixes it

šŸ”„šŸ”„šŸ”„āœ“ VerifiedFreeAdvanced setup
#automation#slack#database#git#design

Pincushion MCP Server

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.

CLI Flags

npx pincushion-mcp [flags]
FlagDescriptionDefault
--project-dir PATHRoot directory containing .feedback/Current working directory
--sync-url URLSupabase API endpoint for remote syncNone (local only)
--api-key KEYAPI key for Supabase authenticationNone
--license-key KEYPro license key (optional)None
--restEnable REST API modeDisabled (uses MCP/stdio)
--port PORTPort for REST API server3456

Examples

Local project:

npx pincushion-mcp --project-dir /path/to/project

With Supabase sync:

npx pincushion-mcp \
  --project-dir /path/to/project \
  --sync-url https://abcd1234.supabase.co/api \
  --api-key sb_project_key_abc123...

REST API server:

npx pincushion-mcp --rest --port 8080

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

Example:

await mcp.callTool('get_annotations', {
  componentName: 'wmlHomePage',
  status: 'open'
});

search_annotations

Full-text search across all annotations, comments, selectors, and tags.

Parameters:

  • query (string, required) ā€” Search term

Example:

await mcp.callTool('search_annotations', {
  query: 'button label'
});

get_feedback_summary

High-level rollup of all feedback: counts by status, priority, page, and component.

Example:

await mcp.callTool('get_feedback_summary', {});

get_component_feedback

Get all feedback for a specific LWC component with a plain-language summary.

Parameters:

  • componentName (string, required) ā€” LWC component name

Example:

await mcp.callTool('get_component_feedback', {
  componentName: 'wmlHomePage'
});

resolve_annotation

Mark an annotation as resolved after fixing the issue.

Parameters:

  • annotationId (string, required) ā€” Annotation ID
  • comment (string, optional) ā€” Resolution message
  • resolvedBy (string, optional) ā€” Name to attribute resolution (default: "AI Agent")

Example:

await mcp.callTool('resolve_annotation', {
  annotationId: 'ann_abc123',
  comment: 'Updated button label in line 42 of wmlHomePage.js'
});

add_agent_reply

Add a reply to an annotation thread (e.g., ask clarifying questions).

Parameters:

  • annotationId (string, required) ā€” Annotation ID
  • body (string, required) ā€” Reply message
  • author (string, optional) ā€” Author name (default: "AI Agent")

Example:

await mcp.callTool('add_agent_reply', {
  annotationId: 'ann_abc123',
  body: 'Is this button in the main navigation or sidebar?'
});

fix_and_resolve

Combine fixing code and marking an annotation as resolved in one call. Optionally records commit / branch / PR metadata so the dashboard can backlink to what shipped.

Parameters:

  • annotationId (string, required) ā€” Annotation ID
  • fixDescription (string, required) ā€” Description of the fix
  • filePath (string, optional) ā€” File where fix was applied
  • lineNumber (number, optional) ā€” Line number of the fix
  • commitSha (string, optional) ā€” Commit SHA that landed the change
  • branchName (string, optional) ā€” Branch the commit was made on
  • prUrl (string, optional) ā€” Pull request URL (GitHub/GitLab/Bitbucket; shape-validated)

Example:

await mcp.callTool('fix_and_resolve', {
  annotationId: 'ann_abc123',
  fixDescription: 'Updated button label to match design spec',
  filePath: 'src/components/wmlHomePage.js',
  lineNumber: 42,
  commitSha: 'abc123def456',
  branchName: 'pincushion/checkout-fix',
  prUrl: 'https://github.com/acme/app/pull/142'
});

get_implementation_packet

Fetch a single implementation packet for one page URL ā€” selector list, full pin payloads, suggested branch name, and traceability config. Use when an agent wants to batch-fix one page in a single branch.

await mcp.callTool('get_implementation_packet', { pageUrl: '/checkout' });

assign_pin_to_agent

Dispatch a pin straight to your local coding agent. Promotes the pin to ready if not already, marks pending_implementation, and writes a .feedback/.agent-queue/<id>.json trigger file that agent-loop.mjs picks up and shells out to Cursor / Claude Code / Codex.

await mcp.callTool('assign_pin_to_agent', { annotationId: 'ann_abc123' });

Attach a deploy URL to a resolved pin. Typically called by the deploy-hook edge function once production includes the fix, but available manually too.

await mcp.callTool('link_pin_deploy', {
  annotationId: 'ann_abc123',
  deployUrl: 'https://acme-app.vercel.app'
});

record_pin_verification

Write Pincushion AI's post-deploy verdict back to the pin. Called by the critic agent after /critique-latest-deploy runs against a fresh deploy.

await mcp.callTool('record_pin_verification', {
  annotationId: 'ann_abc123',
  status: 'verified',  // or 'regressed' or 'inconclusive'
  notes: 'Button matches the primary token. No regression on adjacent CTAs.'
});

get_time_to_fix_metrics

Pro/Team feature ā€” Free callers get sample size + upgrade hint. Median + p25/p75 of pin-to-resolve duration, with a 5-pin minimum so the metric is never noise.

await mcp.callTool('get_time_to_fix_metrics', { scope: 'project', projectId: 'pc_proj_abc' });
// ā†’ { sampleSize, thresholdMet, median, p25, p75, medianHuman, ... }

get_setup_instructions (NEW)

Get setup and configuration instructions for all supported agents.

Example:

await mcp.callTool('get_setup_instructions', {});

Slack and Microsoft Teams integrations

Pincushion can notify Slack or Microsoft Teams through project-scoped incoming webhooks. The defaults are intentionally quiet and Figma-inspired: notify when a pin is ready for implementation, when someone is @mentioned, and when a collaborator adds follow-up on work already being handled. Every newly dropped pin and every resolution are opt-in events.

Recommended use cases:

  • Developer channel: pin_ready and follow_up
  • Design or PM channel: mention and optionally resolved
  • Launch or QA channel: pageUrlPatterns plus pin_ready, follow_up, and resolved
  • Temporary incident channel: enable a focused subscription, then pause it after the ship window

Example:

await mcp.callTool('configure_collaboration_integration', {
  projectId: 'my-project',
  provider: 'slack',
  webhookUrl: 'https://hooks.slack.com/services/...',
  targetLabel: '#product-feedback',
  events: ['pin_ready', 'mention', 'follow_up'],
  pageUrlPatterns: ['staging.example.com/checkout'],
  sendTest: true
});

For Slack, use create_slack_install_link when the hosted Slack app secrets are configured. It returns an Add-to-Slack URL; after approval, Slack returns the incoming webhook and Pincushion stores it automatically.

Use list_collaboration_integrations to audit configured destinations, remove_collaboration_integration to disconnect one, and preview_collaboration_notification to see the payload shape before adding a real webhook. Webhook URLs are stored server-side and returned only as masked values.

Auto-Agent Loop (Optional)

For agents that don't watch the file system (Claude Code, Cursor, generic), agent-loop.mjs polls .feedback/.agent-queue/ and dispatches new pins to the configured agent automatically.

# from inside the pincushion-mcp directory
npm run agent-loop -- --project-dir /path/to/your/project

# or directly
node agent-loop.mjs --project-dir /path/to/your/project [--agent claude-code|cursor|generic] [--interval 3000]

The bridge (server.js) writes one trigger file per approved pin into .feedback/.agent-queue/. The loop reads them, builds a prompt with the pin's thread + element selector, and shells out to the chosen agent. The agent uses MCP tools (claim_pin ā†’ fix ā†’ fix_and_resolve) and the queue file is removed when the pin closes.

detectAgent() auto-detects claude or cursor on the PATH; falls back to generic (writes the prompt to .feedback/.agent-prompt and stdout). Run with --interval 3000 to control poll cadence.

Local File Structure

The server reads annotations from .feedback/ in your project:

.feedback/
ā”œā”€ā”€ annotations/
ā”‚   ā”œā”€ā”€ example-com-login.json
ā”‚   ā”œā”€ā”€ example-com-dashboard.json
ā”‚   ā””ā”€ā”€ ...
ā””ā”€ā”€ index.json

Each annotation file contains:

{
  "pageUrl": "https://example.com/login",
  "pageTitle": "Login",
  "annotations": [
    {
      "id": "ann_abc123",
      "status": "open",
      "priority": "high",
      "tags": ["design", "accessibility"],
      "createdAt": "2026-03-19T10:30:00Z",
      "element": {
        "lwcComponent": "wmlLoginForm",
        "selector": ".login-button",
        "textContent": "Sign In"
      },
      "thread": [
        {
          "author": "Design Team",
          "timestamp": "2026-03-19T10:30:00Z",
          "body": "Button label should say 'Sign In' not 'Login'",
          "type": "comment"
        }
      ]
    }
  ]
}

Supabase Sync

To sync annotations with a remote Supabase database:

  1. Set up a Supabase project at supabase.com
  2. Create an annotations table with columns matching the annotation schema
  3. Generate an API key from your project settings
  4. Configure the server with --sync-url and --api-key

Example:

npx pincushion-mcp \
  --project-dir . \
  --sync-url https://your-project.supabase.co/rest/v1 \
  --api-key sb_project_key_abc123...

The server merges local .feedback/ files with remote data, with remote taking precedence on newer updates.

Pro License

Pincushion Pro includes additional features. Activate with --license-key:

npx pincushion-mcp --project-dir . --license-key YOUR_PRO_KEY

Development

Clone the repository and install dependencies:

git clone https://github.com/jcooley8/pincushion-plugin.git
cd pincushion-plugin
npm install

Run the server:

npm start

Or with test data:

npm start -- --project-dir ./test-feedback

Support

Changelog

v1.0.0 (March 2026)

  • Initial release
  • Support for Cursor, Claude Desktop, Claude Code, VS Code, Windsurf, Antigravity
  • Local .feedback/ file support
  • Supabase remote sync
  • REST API wrapper for non-MCP clients
  • New tools: fix_and_resolve, get_setup_instructions