@estebanivar/vqa-mcp 0.35.0

package/dist/client.js

@@ -0,0 +1,145 @@
+// Cherry backend client. Talks to the existing REST API
+// (estebanivar-vqa-backend/src/app/api/{pins,threads}) with a minted
+// extension JWT read from disk PER REQUEST — rotatable without a server
+// restart. 401s surface as a friendly re-mint message, never a stack trace.
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const DEFAULT_TOKEN_FILE = join(homedir(), ".config", "estebanivar-vqa-keys", "agent-token.txt");
+export class TokenError extends Error {
+    friendly = true;
+}
+export class CherryClient {
+    base;
+    tokenFile;
+    workspace;
+    constructor(opts) {
+        this.base = (opts?.base ?? process.env.CHERRY_BACKEND_URL ?? "http://localhost:3001").replace(/\/$/, "");
+        this.tokenFile = opts?.tokenFile ?? process.env.CHERRY_TOKEN_FILE ?? DEFAULT_TOKEN_FILE;
+        this.workspace = opts?.workspace ?? process.env.CHERRY_WORKSPACE ?? undefined;
+    }
+    readToken() {
+        // Direct env token wins (the CONNECT AGENT one-liner embeds it); the
+        // token FILE is the rotatable power-user path (re-read per request).
+        const envToken = process.env.CHERRY_TOKEN?.trim();
+        if (envToken)
+            return envToken;
+        let raw;
+        try {
+            raw = readFileSync(this.tokenFile, "utf-8");
+        }
+        catch {
+            throw new TokenError(`No Cherry agent token: set CHERRY_TOKEN, or write one to ${this.tokenFile}. ` +
+                `Get a fresh token from the Cherry extension popup → CONNECT AGENT.`);
+        }
+        const token = raw.trim();
+        if (!token) {
+            throw new TokenError(`Cherry agent token file ${this.tokenFile} is empty — re-mint via the popup's CONNECT AGENT.`);
+        }
+        return token;
+    }
+    url(path, params) {
+        const u = new URL(this.base + path);
+        if (this.workspace)
+            u.searchParams.set("workspace", this.workspace);
+        for (const [k, v] of Object.entries(params ?? {})) {
+            if (v !== undefined)
+                u.searchParams.set(k, v);
+        }
+        return u.toString();
+    }
+    async request(path, init, params) {
+        const token = this.readToken();
+        const res = await fetch(this.url(path, params), {
+            ...init,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                ...(init?.body ? { "Content-Type": "application/json" } : {}),
+                ...(init?.headers ?? {}),
+            },
+        });
+        if (res.status === 401) {
+            const viaEnv = Boolean(process.env.CHERRY_TOKEN?.trim());
+            throw new TokenError(viaEnv
+                ? "Cherry backend returned 401 — the CHERRY_TOKEN in your MCP config expired or is invalid. " +
+                    "Re-copy the setup from the Cherry extension popup → CONNECT AGENT and re-run it."
+                : `Cherry backend returned 401 — the token at ${this.tokenFile} expired or is invalid. ` +
+                    "Get a fresh one from the Cherry extension popup → CONNECT AGENT and write it there.");
+        }
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            throw new Error(`Cherry backend ${init?.method ?? "GET"} ${path} failed: ${res.status} ${body.slice(0, 300)}`);
+        }
+        return (await res.json());
+    }
+    /** Presence heartbeat. The backend stamps `agentLastSeen` ONLY on
+     *  GET /api/pins?kind=prompt for an agent actor (backend pins/route.ts:80 —
+     *  `kind === "prompt"` is required; kind=pin/all do NOT stamp). That stamp is
+     *  what keeps the extension's INSPECT panel "agent connected" (5-min window).
+     *  So ping MUST use kind:"prompt". The return value is ignored — listing the
+     *  prompt queue is read-only (no drain), so this is a safe idempotent poke.
+     *  Swallows transient errors so a blip never kills the keepalive loop. */
+    async ping() {
+        try {
+            await this.listPins({ kind: "prompt" });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** All pins in the workspace (optionally origin-scoped). Backend GET /api/pins is workspace-wide
+     *  already; `kind` opts into prompt rows (agent mail from INSPECT SEND) or "all" — the backend's
+     *  default listing returns regular pins only, which is also what keeps prompts invisible to the
+     *  overlay UI. */
+    async listPins(opts) {
+        const data = await this.request("/api/pins", undefined, {
+            origin: opts?.origin,
+            kind: opts?.kind,
+        });
+        return data.pins ?? [];
+    }
+    /** Single pin by id. The backend has no GET /api/pins/:id — list + find across BOTH kinds
+     *  (workspace-scoped, fine at Phase-1 volume). */
+    async getPin(pinId) {
+        const pins = await this.listPins({ kind: "all" });
+        return pins.find((p) => p.id === pinId) ?? null;
+    }
+    /** Create a REGION-anchored pin (agent-authored comment). The backend
+     *  wants anchor.rect as a [x, y, w, h] tuple in viewport coords; origin
+     *  and route arrive pre-split (origin = scheme+host+port, route = path).
+     *  kind defaults to "pin" server-side — i.e. VISIBLE in the overlay,
+     *  which is the point of an agent comment. */
+    async createPin(opts) {
+        const data = await this.request("/api/pins", {
+            method: "POST",
+            body: JSON.stringify({
+                anchor: { kind: "region", rect: opts.rect },
+                text: opts.text,
+                origin: opts.origin,
+                route: opts.route,
+                viewport: opts.viewport,
+            }),
+        });
+        return data.pin;
+    }
+    /** Append a thread reply. Author = the token's user; the thread shows who wrote it. */
+    async reply(pinId, text) {
+        const data = await this.request(`/api/pins/${encodeURIComponent(pinId)}/thread`, { method: "POST", body: JSON.stringify({ text }) });
+        return data.pin;
+    }
+    /** Status-only PATCH — triage is allowed for any workspace member. */
+    async setStatus(pinId, status) {
+        const data = await this.request(`/api/pins/${encodeURIComponent(pinId)}`, { method: "PATCH", body: JSON.stringify({ status }) });
+        return data.pin;
+    }
+    /** Fetch a screenshot (Vercel Blob URL — public) as base64 for MCP image content. */
+    async fetchImage(url) {
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new Error(`screenshot fetch failed: ${res.status} for ${url}`);
+        const mimeType = res.headers.get("content-type")?.split(";")[0] || "image/png";
+        const buf = Buffer.from(await res.arrayBuffer());
+        return { data: buf.toString("base64"), mimeType };
+    }
+}

package/dist/drain-prompt.js

@@ -0,0 +1,53 @@
+// The drain protocol, shipped INSIDE the server as an MCP prompt so agents
+// get it with zero skill/config installs (Claude Code surfaces MCP prompts
+// as slash commands — /cherry:drain). Version-locks the protocol to the
+// package. Mirrors Esteban's local /cherry skill minus the machine-specific
+// repos.json map (unknown origins are handled conversationally instead).
+export function drainPromptText(origin) {
+    const repos = process.env.CHERRY_REPOS;
+    const repoMap = repos
+        ? `\nKnown origin → repo map (from CHERRY_REPOS):\n${repos}\n`
+        : "";
+    return `Drain the Cherry change-request queue ONCE, then stop.
+
+Cherry is a visual-QA browser extension: the user hovers an element on their
+page, types a change request ("wrong icon", "don't round this border"), and
+hits SEND. Those requests are waiting in the queue for you now.
+
+## Protocol (drain-once — never wait, poll, or re-check afterward)
+
+1. Call cherry_pending${origin ? ` with origin "${origin}"` : ""} ONCE. It
+   returns kind="prompt" items (invisible agent mail from INSPECT SEND).
+   Empty → say "queue empty". If the user asked you to also handle their
+   VISIBLE annotation pins (or the empty result surprises them), call it one
+   more time with kind: "all" — that is the only permitted second call.
+2. Per request, oldest first:
+   - cherry_get for the full packet (the user's words, the component's
+     identity, file:line when the page was a dev build, a durable selector,
+     and computed specs in design-token vocabulary).
+   - cherry_screenshot ONLY if the text is ambiguous without seeing it.
+   - Work out which LOCAL REPO the page belongs to.${repoMap}
+     If the origin isn't known to you, ASK the user ("which local repo is
+     http://localhost:3000?") and REMEMBER the answer somewhere durable you
+     own (CLAUDE.md, AGENTS.md, your memory) so you never ask twice.
+   - Locate the code: file:line hint first; otherwise hunt by component
+     name / design-system identity / selector / the specs' class names.
+   - Apply the change.
+   - cherry_reply with a 1-3 line summary of the ACTUAL diff (file + what
+     changed). If the app's dev server does NOT hot-reload (plain node/tsx
+     servers), say so in the reply ("restart the dev server to see it") —
+     a correct but invisible fix reads as a failed fix.
+   - cherry_resolve.
+   - Ambiguous or out-of-scope request → cherry_reply asking the clarifying
+     question, do NOT resolve, move on.
+3. Final report: N resolved, M replied-pending, files touched per repo.
+4. STOP. No waiting, no polling, no scheduling. The queue is drained when
+   this list is empty; the user will invoke you again when there's more.
+
+Failure rules: a 401/token error from any cherry tool → surface its message
+to the user and STOP (never retry in a loop). A file:line that doesn't match
+current code means a stale dev-build hint — fall back to component/selector
+hunting rather than trusting the line. If your change would collide with
+uncommitted local edits in that file, reply on the request describing the
+conflict and leave it open instead of resolving.`;
+}

package/dist/index.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// cherry-qa MCP server — stdio, drain-once. The queue is the pin store
+// (Cherry backend / Neon); a Claude session connects, drains, disconnects.
+// No HTTP listener, no sessions, no watching (Phase-1 spec: async only).
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { CherryClient } from "./client.js";
+import { registerTools } from "./tools.js";
+import { drainPromptText } from "./drain-prompt.js";
+const server = new McpServer({ name: "cherry-qa", version: "0.35.0" });
+const client = new CherryClient();
+registerTools(server, client);
+// Presence heartbeat. This stdio server lives for the whole Claude session, so
+// while it's up we keep the extension's INSPECT panel showing "agent connected"
+// (backend's 5-min agentLastSeen window). Without this, presence only refreshes
+// when a cherry_* tool happens to run, so the panel blinks to "NO AGENT" whenever
+// the session sits idle. Every 2 min beats the 5-min window with margin. The
+// first beat fires immediately so the panel flips within one of its 60s polls.
+// unref() so the loop never keeps the process alive on its own.
+const HEARTBEAT_MS = 2 * 60 * 1000;
+void client.ping();
+const heartbeat = setInterval(() => void client.ping(), HEARTBEAT_MS);
+if (typeof heartbeat.unref === "function")
+    heartbeat.unref();
+// The drain protocol ships with the server: agents surface MCP prompts as
+// commands (Claude Code → /cherry:drain), so users need no skill installs.
+server.prompt("drain", "Drain the Cherry change-request queue once — apply each described change to source, reply with the diff, resolve. Stops when empty; never polls.", { origin: z.string().optional().describe("Scope to one page origin, e.g. http://localhost:3000") }, ({ origin }) => ({
+    messages: [
+        { role: "user", content: { type: "text", text: drainPromptText(origin) } },
+    ],
+}));
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("[cherry-qa] stdio server ready");

package/dist/packet.js

@@ -0,0 +1,69 @@
+// The agent packet — one markdown block per pin (spec §2), optimized so the
+// receiving session needs near-zero exploration: request thread, element
+// identity + file:line, durable selectors, page URL, token-first specs, and
+// the screenshot pointer.
+import { formatSpecs } from "./specs-format.js";
+function pageUrl(pin) {
+    const origin = pin.origin ?? "";
+    return origin ? `${origin}${pin.route}` : pin.route;
+}
+// SEND-created pins carry the typed text as the pin's own `text` and/or the
+// first thread comment. Render pin.text first (when set), then the thread
+// oldest→newest, skipping a first comment that merely echoes pin.text.
+function requestLines(pin) {
+    const lines = [];
+    const pinText = (pin.text ?? "").trim();
+    if (pinText)
+        lines.push(`"${pinText}" — ${pin.author}, ${pin.createdAt}`);
+    (pin.thread ?? []).forEach((entry, i) => {
+        const text = (entry.text ?? "").trim();
+        if (!text)
+            return;
+        if (i === 0 && pinText && text === pinText)
+            return; // SEND echo
+        lines.push(`"${text}" — ${entry.by}, ${entry.at}`);
+    });
+    if (lines.length === 0)
+        lines.push("(no request text — see screenshot)");
+    return lines;
+}
+export function buildPacket(pin) {
+    const lines = [];
+    lines.push(`## Change request ${pin.id}`);
+    lines.push("");
+    lines.push(...requestLines(pin));
+    lines.push("");
+    const c = pin.component;
+    if (c) {
+        const src = c.source ? ` (${c.source})` : "";
+        const loc = c.file ? ` — ${c.file}${c.line ? `:${c.line}` : ""}` : "";
+        const variant = c.variant ? ` variant="${c.variant}"` : "";
+        lines.push(`**Element:** ${c.dsLabel ?? c.name}${variant}${src}${loc}`);
+    }
+    else {
+        lines.push(`**Element:** (no component binding)`);
+    }
+    const selector = c?.selector ?? pin.anchor?.selector;
+    const fallback = c?.fallbackSelector ?? pin.anchor?.fallbackSelector;
+    if (selector) {
+        lines.push(`**Selector:** ${selector}${fallback && fallback !== selector ? ` (fallback: ${fallback})` : ""}`);
+    }
+    else if (pin.anchor?.kind === "region" && pin.anchor.rect) {
+        lines.push(`**Region:** page rect [${pin.anchor.rect.join(", ")}]`);
+    }
+    lines.push(`**Page:** ${pageUrl(pin)} (route ${pin.route})`);
+    lines.push(`**Status:** ${pin.status}${pin.priority ? ` · ${pin.priority}` : ""} · created ${pin.createdAt}`);
+    lines.push("");
+    const specsText = formatSpecs(c?.specs);
+    if (specsText) {
+        lines.push(`**Specs (token-first):**`);
+        lines.push(specsText);
+    }
+    else {
+        lines.push(`**Specs:** none captured (older pin — inspect the live element if needed)`);
+    }
+    lines.push("");
+    const hasImage = Boolean(pin.screenshot) || Boolean(pin.shots && pin.shots.length > 0);
+    lines.push(hasImage ? `**Screenshot:** cherry_screenshot ${pin.id}` : `**Screenshot:** none`);
+    return lines.join("\n");
+}

package/dist/specs-format.js

@@ -0,0 +1,126 @@
+// Token-first ComponentSpecs serialization for the agent packet.
+// Mirrors the InspectOverlay value grammar (packages/vqa-react/src/
+// InspectOverlay.tsx: colorText / fmtPaddingHud): a value that matches a
+// page-exposed custom property leads with the raw value and IDENTIFIES as
+// the token — `8px = var(--radius-mm-md)` — because "what is this in my
+// system's vocabulary" is the question. Near-misses whisper drift:
+// `7px (≈ --radius-mm-md 8px)`. Off-token values stay plain. Pure —
+// no DOM, no IO.
+/** `8px = var(--radius-mm-md)` exact · `7px (≈ --radius-mm-md 8px)` near-miss · `7px` plain */
+export function lengthValue(l) {
+    const px = `${l.px}px`;
+    if (l.token)
+        return `${px} = var(${l.token})`;
+    if (l.nearest)
+        return `${px} (≈ ${l.nearest.token} ${l.nearest.px}px)`;
+    return px;
+}
+/** `#fafafa = var(--color-mm-fg)` exact · `#fafafa` plain · alpha noted as `@0.5` */
+export function colorValue(c) {
+    const alpha = c.alpha !== undefined && c.alpha < 1 ? ` @${c.alpha}` : "";
+    if (c.token)
+        return `${c.hex}${alpha} = var(${c.token})`;
+    return `${c.hex}${alpha}`;
+}
+// Collapsed box edges, InspectOverlay's fmtPaddingHud rule: "12" uniform,
+// "8·16" v/h pairs, else all four.
+function edgesText([t, r, b, l]) {
+    if (t === r && r === b && b === l)
+        return String(t);
+    if (t === b && r === l)
+        return `${t}·${r}`;
+    return `${t}·${r}·${b}·${l}`;
+}
+function radiusValue(radius) {
+    // Uniform px radii carry token identification; per-corner stays text.
+    if (radius.px !== undefined) {
+        return lengthValue({ px: radius.px, token: radius.token, nearest: radius.nearest });
+    }
+    return radius.text;
+}
+/**
+ * Serialize a pin's stored ComponentSpecs into compact token-first lines.
+ * Absent specs (older pins) → null; callers render a graceful placeholder.
+ */
+export function formatSpecs(specs) {
+    if (!specs || typeof specs !== "object")
+        return null;
+    const lines = [];
+    const box = specs.box;
+    if (box) {
+        // Every field individually guarded — shapes are intentionally loose
+        // (older pins predate several fields) and a partial box must degrade,
+        // not crash cherry_get (review 2026-07-06 #2).
+        const parts = [];
+        if (typeof box.width === "number" && typeof box.height === "number") {
+            parts.push(`size ${box.width}×${box.height}`);
+        }
+        if (box.radius)
+            parts.push(`radius ${radiusValue(box.radius)}`);
+        if (Array.isArray(box.padding))
+            parts.push(`padding ${edgesText(box.padding)}`);
+        if (Array.isArray(box.margin)) {
+            const margin = edgesText(box.margin);
+            if (margin !== "0")
+                parts.push(`margin ${margin}`);
+        }
+        if (box.border)
+            parts.push(`border ${box.border}`);
+        if (parts.length)
+            lines.push(parts.join(" · "));
+    }
+    const t = specs.typography;
+    if (t) {
+        const parts = [`font ${t.family} ${t.sizeText || `${t.sizePx}px`}/${t.weight}`, `line-height ${t.lineHeight}`];
+        if (t.letterSpacing)
+            parts.push(`tracking ${t.letterSpacing}`);
+        lines.push(parts.join(" · "));
+    }
+    const c = specs.color;
+    if (c && (c.text || c.background)) {
+        const parts = [];
+        if (c.text)
+            parts.push(`text ${colorValue(c.text)}`);
+        if (c.background)
+            parts.push(`${c.text ? "on " : "bg "}${colorValue(c.background)}`);
+        let line = parts.join(" ");
+        if (specs.contrast) {
+            line += ` · contrast ${specs.contrast.ratio}:1 ${specs.contrast.aa ? "AA ✓" : specs.contrast.aaLarge ? "AA-large only" : "AA ✗"}`;
+        }
+        lines.push(line);
+    }
+    const l = specs.layout;
+    if (l) {
+        const parts = [l.display];
+        if (l.direction)
+            parts.push(l.direction);
+        if (l.justify && l.justify !== "normal")
+            parts.push(`justify ${l.justify}`);
+        if (l.align && l.align !== "normal")
+            parts.push(`align ${l.align}`);
+        if (l.gap)
+            parts.push(`gap ${lengthValue(l.gap)}`);
+        lines.push(parts.join(" · "));
+    }
+    const e = specs.effects;
+    if (e) {
+        const parts = [];
+        if (e.opacity !== undefined && e.opacity !== 1)
+            parts.push(`opacity ${e.opacity}`);
+        if (e.shadow)
+            parts.push(`shadow ${e.shadow}`);
+        if (e.transform)
+            parts.push(`transform ${e.transform}`);
+        if (e.transition)
+            parts.push(`transition ${e.transition}`);
+        if (e.backgroundImage)
+            parts.push(`bg-image ${e.backgroundImage}`);
+        if (parts.length)
+            lines.push(parts.join(" · "));
+    }
+    const img = specs.img;
+    if (img) {
+        lines.push(`img ${img.src} · natural ${img.naturalW}×${img.naturalH} · rendered ${img.renderedW}×${img.renderedH}${img.alt ? ` · alt "${img.alt}"` : ""}`);
+    }
+    return lines.length ? lines.join("\n") : null;
+}

package/dist/tools.js

@@ -0,0 +1,154 @@
+// The six cherry-qa tools — drain-once bridge over the pin store. Every
+// tool is a single request/response against the live backend; nothing here
+// watches, polls, or schedules anything.
+import { z } from "zod";
+import { TokenError } from "./client.js";
+import { buildPacket } from "./packet.js";
+function text(s) {
+    return { content: [{ type: "text", text: s }] };
+}
+// Friendly error surface: token problems return their message verbatim
+// (never a stack trace); everything else keeps enough detail to debug.
+function errText(e) {
+    if (e instanceof TokenError)
+        return text(e.message);
+    return text(`cherry-qa error: ${e instanceof Error ? e.message : String(e)}`);
+}
+function firstCommentText(p) {
+    const own = (p.text ?? "").trim();
+    if (own)
+        return own;
+    return (p.thread?.[0]?.text ?? "").trim();
+}
+export function registerTools(server, client) {
+    server.tool("cherry_pending", "List OPEN Cherry change requests (oldest first). Defaults to kind=prompt — the invisible agent-mail queue from INSPECT SEND (no UI pins). Pass kind=pin for regular annotation pins or kind=all for both. Optionally scope to one origin (e.g. http://localhost:6010).", {
+        origin: z.string().optional().describe("Scheme+host+port to scope to; omit for the whole workspace"),
+        kind: z
+            .enum(["prompt", "pin", "all"])
+            .optional()
+            .describe("prompt (default) = agent mail from INSPECT SEND; pin = visible annotation pins; all = both"),
+    }, async (args) => {
+        try {
+            const kind = args.kind ?? "prompt";
+            const pins = await client.listPins({ origin: args.origin, kind });
+            const open = pins
+                .filter((p) => p.status === "open")
+                .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+            if (open.length === 0)
+                return text(kind === "prompt" ? "Queue empty — no pending prompts." : "Queue empty — no open Cherry pins.");
+            const items = open.map((p) => ({
+                id: p.id,
+                text: firstCommentText(p) || "(no text)",
+                component: p.component
+                    ? `${p.component.dsLabel ?? p.component.name}${p.component.file ? ` — ${p.component.file}${p.component.line ? `:${p.component.line}` : ""}` : ""}`
+                    : undefined,
+                page: `${p.origin ?? ""}${p.route}`,
+                route: p.route,
+                createdAt: p.createdAt,
+                hasSpecs: Boolean(p.component?.specs),
+            }));
+            return text(JSON.stringify({ count: items.length, pins: items }, null, 2));
+        }
+        catch (e) {
+            return errText(e);
+        }
+    });
+    server.tool("cherry_get", "Get the full agent packet for one pin: request thread, element identity + file:line, selectors, page URL, token-first specs, screenshot pointer.", { pinId: z.string() }, async ({ pinId }) => {
+        try {
+            const pin = await client.getPin(pinId);
+            if (!pin)
+                return text(`No pin ${pinId} in this workspace.`);
+            return text(buildPacket(pin));
+        }
+        catch (e) {
+            return errText(e);
+        }
+    });
+    server.tool("cherry_screenshot", "Fetch a pin's screenshot as an image (element auto-capture first, region shots after).", { pinId: z.string() }, async ({ pinId }) => {
+        try {
+            const pin = await client.getPin(pinId);
+            if (!pin)
+                return text(`No pin ${pinId} in this workspace.`);
+            const urls = [];
+            if (pin.screenshot)
+                urls.push(pin.screenshot);
+            for (const s of pin.shots ?? [])
+                urls.push(s.url);
+            if (urls.length === 0)
+                return text(`Pin ${pinId} has no screenshot.`);
+            const images = await Promise.all(urls.map((u) => client.fetchImage(u)));
+            return {
+                content: images.map((img) => ({
+                    type: "image",
+                    data: img.data,
+                    mimeType: img.mimeType,
+                })),
+            };
+        }
+        catch (e) {
+            return errText(e);
+        }
+    });
+    server.tool("cherry_comment", "CREATE a comment pin on a page (agent-authored, region-anchored) — it appears in the Cherry overlay as a numbered marker + thread, like a teammate's annotation. Coordinates are viewport px on that page; open the page in a browser first to measure. Author = the token's user.", {
+        url: z.string().url().describe("Full page URL the comment belongs to (origin+path are derived from it)"),
+        rect: z
+            .object({
+            x: z.number().finite(),
+            y: z.number().finite(),
+            width: z.number().finite().positive(),
+            height: z.number().finite().positive(),
+        })
+            .describe("Viewport-px region the comment points at"),
+        text: z.string().min(1).describe("The comment body"),
+        viewport: z
+            .object({ w: z.number().int().positive(), h: z.number().int().positive() })
+            .optional()
+            .describe("Viewport size the rect was measured in (defaults to 1440×820 if omitted)"),
+    }, async (args) => {
+        try {
+            const u = new URL(args.url);
+            const { x, y, width, height } = args.rect;
+            if (x < 0 || y < 0)
+                return text("cherry_comment: rect x/y must be ≥ 0 (viewport coordinates).");
+            const pin = await client.createPin({
+                origin: u.origin,
+                route: u.pathname + u.search,
+                rect: [x, y, width, height],
+                text: args.text,
+                viewport: args.viewport ?? { w: 1440, h: 820 },
+            });
+            return text(`Comment pin ${pin.id} created on ${u.origin}${u.pathname} (region ${Math.round(width)}×${Math.round(height)} @ ${Math.round(x)},${Math.round(y)}). ` +
+                `It's live in the Cherry overlay; thread replies land via cherry_reply.`);
+        }
+        catch (e) {
+            return errText(e);
+        }
+    });
+    server.tool("cherry_reply", "Reply in a pin's thread (plain text — the thread shows the author, no bot prefix). Use for 'here is what changed' summaries or clarifying questions.", { pinId: z.string(), text: z.string().min(1) }, async (args) => {
+        try {
+            const pin = await client.reply(args.pinId, args.text);
+            return text(`Replied on ${args.pinId}. Thread length: ${pin.thread?.length ?? "?"}.`);
+        }
+        catch (e) {
+            return errText(e);
+        }
+    });
+    server.tool("cherry_resolve", "Mark a pin resolved (only after the change is actually applied and summarized via cherry_reply).", { pinId: z.string() }, async ({ pinId }) => {
+        try {
+            const pin = await client.setStatus(pinId, "resolved");
+            return text(`Pin ${pinId} → ${pin.status}.`);
+        }
+        catch (e) {
+            return errText(e);
+        }
+    });
+    server.tool("cherry_reopen", "Reopen a resolved pin (status back to open).", { pinId: z.string() }, async ({ pinId }) => {
+        try {
+            const pin = await client.setStatus(pinId, "open");
+            return text(`Pin ${pinId} → ${pin.status}.`);
+        }
+        catch (e) {
+            return errText(e);
+        }
+    });
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+// Local mirrors of the wire shapes this bridge consumes. The backend's
+// WirePin (estebanivar-vqa-backend/src/lib/shape.ts) and vqa-react's
+// ComponentSpecs (packages/vqa-react/src/specs.ts) are the sources of
+// truth — these are read-side subsets, intentionally loose (older pins
+// predate several fields).
+export {};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@estebanivar/vqa-mcp",
+  "version": "0.35.0",
+  "description": "cherry-qa MCP server — drain-once agent bridge over the Cherry pin store",
+  "type": "module",
+  "bin": {
+    "cherry-qa-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18"
+  }
+}