@muloka/figma-console-mcp 0.1.0

package/dist/cloudflare/core/diagnose-tool.js

@@ -0,0 +1,100 @@
+/**
+ * figma_diagnose — a designer-readable health check for figma-console-mcp.
+ *
+ * This is the one tool to point a confused user at. It self-identifies the
+ * server, reports the transport / plugin / token state in plain language,
+ * and explicitly disclaims any token or OAuth error a user might be seeing
+ * in chat (those typically come from a different MCP). The response is
+ * structured so an LLM is likely to surface the `report` field verbatim.
+ */
+import { z } from "zod";
+import { MCP_NAME, withIdentity } from "./identity.js";
+function buildReport(opts) {
+    const lines = [];
+    lines.push(`# ${MCP_NAME} diagnostic`);
+    lines.push("");
+    lines.push(`Server version: ${opts.getServerVersion()}`);
+    lines.push(`Mode: ${opts.mode === "local" ? "Local (stdio + WebSocket plugin bridge)" : "Cloud (Cloudflare Workers)"}`);
+    lines.push("");
+    const plugin = opts.getPluginState?.();
+    lines.push("## Plugin connection");
+    if (!plugin) {
+        lines.push("- No WebSocket server (cloud mode runs without a local plugin bridge unless paired).");
+    }
+    else if (plugin.connected) {
+        const portInfo = plugin.portFallbackFrom && plugin.port && plugin.port !== plugin.portFallbackFrom
+            ? `port ${plugin.port} (fallback from ${plugin.portFallbackFrom})`
+            : plugin.port
+                ? `port ${plugin.port}`
+                : "connected";
+        lines.push(`- ✅ Desktop Bridge plugin connected on ${portInfo}.`);
+        if (plugin.fileName) {
+            lines.push(`- Active file: **${plugin.fileName}**${plugin.currentPage ? ` (page: ${plugin.currentPage})` : ""}.`);
+        }
+        if (plugin.editorType && plugin.editorType !== "figma") {
+            lines.push(`- Editor type: ${plugin.editorType}.`);
+        }
+        if (plugin.pluginUpdateAvailable) {
+            const bundledVersion = opts.getBundledPluginVersion?.() ?? opts.getServerVersion();
+            lines.push(`- ⚠️ **Plugin update available**: the imported plugin${plugin.pluginVersion ? ` (v${plugin.pluginVersion})` : " (version unknown — very old)"} differs from the plugin files this server ships (v${bundledVersion}). Figma caches plugin files, so re-import it: Figma Desktop → Plugins → Development → Import plugin from manifest → select manifest.json. Until then, recently added or fixed plugin features may silently misbehave.`);
+        }
+    }
+    else {
+        lines.push(`- ⚠️ Desktop Bridge plugin not connected${plugin.port ? ` (server is listening on port ${plugin.port})` : ""}.`);
+        lines.push("- To fix: open the Figma Desktop Bridge plugin in Figma Desktop. If it was already running, close and reopen it once.");
+    }
+    lines.push("");
+    const token = opts.getTokenState?.();
+    lines.push("## REST API token");
+    if (!token) {
+        lines.push("- Token state not available in this mode.");
+    }
+    else if (token.hasToken) {
+        lines.push(`- ✅ Figma access token detected (source: ${token.source ?? "unknown"}). REST-based tools should work.`);
+    }
+    else {
+        lines.push("- ⚠️ No Figma access token detected. Plugin-based tools still work; REST-only tools (file data, version history, image rendering) will return an auth error.");
+        if (opts.mode === "local") {
+            lines.push("- To enable REST tools: set FIGMA_ACCESS_TOKEN in your MCP client config. Generate a token at https://www.figma.com/developers/api#access-tokens.");
+        }
+        else {
+            lines.push("- To enable REST tools: authenticate via your MCP client's OAuth flow or pass a Figma personal access token (figd_...) as a Bearer token.");
+        }
+    }
+    lines.push("");
+    lines.push("## If you're seeing token / OAuth errors in chat");
+    lines.push(`If you see messages like "API token has expired" or "Bearer token has expired" and the response above does NOT show a token problem, the error is most likely coming from a **different MCP server**, not from ${MCP_NAME}.`);
+    lines.push("");
+    lines.push("Common cause: Figma's native MCP (often listed as just `Figma` in your MCP client) is also installed and its OAuth session expired. Check your MCP client's server list. Errors from those servers are not produced by figma-console-mcp.");
+    lines.push("");
+    return lines.join("\n");
+}
+export function registerDiagnoseTool(server, options) {
+    server.tool("figma_diagnose", `Designer-readable health check for ${MCP_NAME}. Use this when something seems wrong — it self-identifies the server, reports plugin connection / file / token status in plain language, and disambiguates errors that may be coming from a different Figma-related MCP server. Recommended as the first step when a user reports a "token expired" or "plugin disconnected" issue.`, {
+        verbose: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Include the raw structured state alongside the human-readable report."),
+    }, async ({ verbose }) => {
+        const report = buildReport(options);
+        const details = verbose
+            ? {
+                plugin: options.getPluginState?.() ?? null,
+                token: options.getTokenState?.() ?? null,
+            }
+            : undefined;
+        const payload = withIdentity({
+            report,
+            ...(details ? { details } : {}),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(payload),
+                },
+            ],
+        };
+    });
+}

package/dist/cloudflare/core/diff/changelog-formatter.js

@@ -0,0 +1,275 @@
+/**
+ * Pure-function markdown formatter for version diff results.
+ *
+ * Takes a diff payload (the structured response from figma_diff_versions)
+ * plus optional author/label metadata for the from/to versions, and produces
+ * a release-notes-style markdown string.
+ *
+ * Mode-aware:
+ *   summary  — header + a single line of counts
+ *   standard — header + page section + per-component counts
+ *   detailed — header + page section + per-component property/binding details
+ *
+ * Pure: no I/O, no side effects. Trivially testable.
+ */
+export function formatChangelogMarkdown(input, mode = "standard") {
+    const lines = [];
+    // Header
+    const title = input.file_name ? `${input.file_name} — Change Log` : "Figma File Change Log";
+    lines.push(`# ${title}`);
+    lines.push("");
+    lines.push(`**From:** ${formatVersionRef(input.from_meta, input.from_version_id, false)}`);
+    lines.push(`**To:** ${formatVersionRef(input.to_meta, input.to_version_id, true)}`);
+    const span = computeSpanDays(input.from_meta?.created_at, input.to_meta?.created_at);
+    if (span !== null) {
+        lines.push(`**Span:** ${span} day${span === 1 ? "" : "s"}`);
+    }
+    lines.push("");
+    // Summary mode: one-line punch line
+    if (mode === "summary") {
+        lines.push(formatSummaryLine(input));
+        lines.push("");
+        appendNotes(lines, input.notes);
+        return lines.join("\n").trimEnd() + "\n";
+    }
+    // Page Structure section (always for standard/detailed)
+    appendPageStructureSection(lines, input.page_structure);
+    // Components section
+    if (input.scoped_nodes && input.scoped_nodes.length > 0) {
+        appendComponentsSection(lines, input.scoped_nodes, mode);
+    }
+    else {
+        lines.push("## Components");
+        lines.push("");
+        lines.push("_No components were scoped for this changelog. Pass `component_ids` to include per-component changes._");
+        lines.push("");
+    }
+    appendNotes(lines, input.notes);
+    return lines.join("\n").trimEnd() + "\n";
+}
+// ============================================================================
+// Section formatters
+// ============================================================================
+function appendPageStructureSection(lines, page) {
+    const total = page.summary.added + page.summary.removed + page.summary.renamed;
+    lines.push("## Page Structure");
+    lines.push("");
+    if (total === 0) {
+        lines.push("_No page-level changes._");
+        lines.push("");
+        return;
+    }
+    if (page.pages_added.length > 0) {
+        lines.push(`**Added (${page.pages_added.length}):**`);
+        for (const p of page.pages_added)
+            lines.push(`- ${escapeMd(p.name)} \`${p.id}\``);
+        lines.push("");
+    }
+    if (page.pages_removed.length > 0) {
+        lines.push(`**Removed (${page.pages_removed.length}):**`);
+        for (const p of page.pages_removed)
+            lines.push(`- ${escapeMd(p.name)} \`${p.id}\``);
+        lines.push("");
+    }
+    if (page.pages_renamed.length > 0) {
+        lines.push(`**Renamed (${page.pages_renamed.length}):**`);
+        for (const r of page.pages_renamed) {
+            lines.push(`- \`${r.id}\`: ${escapeMd(r.old_name)} → ${escapeMd(r.new_name)}`);
+        }
+        lines.push("");
+    }
+}
+function appendComponentsSection(lines, scoped, mode) {
+    lines.push("## Components");
+    lines.push("");
+    const withChanges = scoped.filter((n) => n.change_count > 0);
+    const unchanged = scoped.filter((n) => n.change_count === 0 && n.notes.length === 0);
+    const notFound = scoped.filter((n) => n.notes.some((note) => note.toLowerCase().includes("not found")));
+    if (withChanges.length === 0 && unchanged.length === 0 && notFound.length === 0) {
+        lines.push("_No scoped components had changes._");
+        lines.push("");
+        return;
+    }
+    for (const n of withChanges) {
+        appendComponentBlock(lines, n, mode);
+    }
+    if (unchanged.length > 0) {
+        lines.push(`**No changes:** ${unchanged.map((n) => `\`${n.node_name || n.node_id}\``).join(", ")}`);
+        lines.push("");
+    }
+    if (notFound.length > 0) {
+        lines.push(`**Not found in either version:** ${notFound.map((n) => `\`${n.node_id || "(empty)"}\``).join(", ")}`);
+        lines.push("");
+    }
+}
+function appendComponentBlock(lines, n, mode) {
+    const heading = n.node_name ? `${n.node_name}` : "(unnamed)";
+    lines.push(`### ${escapeMd(heading)} — \`${n.node_id}\``);
+    lines.push(`**${n.change_count} change${n.change_count === 1 ? "" : "s"}**`);
+    // Each subsequent sub-section adds its own single-blank-line separator so
+    // we don't end up with two consecutive blank lines when one of these
+    // sub-sections is empty. (Earlier versions unconditionally pushed a blank
+    // after the change count then again before each sub-section, producing
+    // double-blanks in the common case.)
+    const bullets = [];
+    if (n.name_changed) {
+        bullets.push(`- Renamed: \`${escapeMd(n.name_changed.from)}\` → \`${escapeMd(n.name_changed.to)}\``);
+    }
+    if (n.description_changed) {
+        const fromLen = n.description_changed.from.length;
+        const toLen = n.description_changed.to.length;
+        bullets.push(`- Description changed (${fromLen} → ${toLen} chars)`);
+    }
+    if (n.children_added.length > 0) {
+        const inline = n.children_added.map((c) => `\`${escapeMd(c.name || c.id)}\``).join(", ");
+        bullets.push(`- Children added (${n.children_added.length}): ${inline}`);
+    }
+    if (n.children_removed.length > 0) {
+        const inline = n.children_removed.map((c) => `\`${escapeMd(c.name || c.id)}\``).join(", ");
+        bullets.push(`- Children removed (${n.children_removed.length}): ${inline}`);
+    }
+    if (bullets.length > 0) {
+        lines.push("");
+        lines.push(...bullets);
+    }
+    if (n.component_properties && hasAnyPropChanges(n.component_properties.summary)) {
+        const s = n.component_properties.summary;
+        const parts = [];
+        if (s.added > 0)
+            parts.push(`${s.added} added`);
+        if (s.removed > 0)
+            parts.push(`${s.removed} removed`);
+        if (s.type_changed > 0)
+            parts.push(`${s.type_changed} type changed`);
+        if (s.default_changed > 0)
+            parts.push(`${s.default_changed} default changed`);
+        lines.push("");
+        lines.push(`**Component properties:** ${parts.join(", ")}`);
+        if (mode === "detailed") {
+            for (const p of n.component_properties.added) {
+                lines.push(`- ➕ \`${escapeMd(p.name)}\` (${p.type}, default: \`${stringifyValue(p.default_value)}\`)`);
+            }
+            for (const p of n.component_properties.removed) {
+                lines.push(`- ➖ \`${escapeMd(p.name)}\` (${p.type})`);
+            }
+            for (const t of n.component_properties.type_changed) {
+                lines.push(`- 🔄 \`${escapeMd(t.name)}\`: ${t.from_type} → ${t.to_type}`);
+            }
+            for (const d of n.component_properties.default_changed) {
+                lines.push(`- ⚙️ \`${escapeMd(d.name)}\`: \`${stringifyValue(d.from_default)}\` → \`${stringifyValue(d.to_default)}\``);
+            }
+        }
+    }
+    if (n.binding_changes.length > 0) {
+        lines.push("");
+        lines.push(`**Variable bindings (${n.binding_changes.length}):**`);
+        if (mode === "detailed") {
+            for (const b of n.binding_changes) {
+                const arrow = b.change_kind === "added"
+                    ? `→ \`${b.to_variable_id}\``
+                    : b.change_kind === "removed"
+                        ? `(removed, was \`${b.from_variable_id}\`)`
+                        : `\`${b.from_variable_id}\` → \`${b.to_variable_id}\``;
+                lines.push(`- ${escapeMd(b.node_name || b.node_id)} — \`${b.property}\` ${arrow}`);
+            }
+        }
+        else {
+            // standard mode: group by change_kind, give counts
+            const counts = { added: 0, removed: 0, rebound: 0 };
+            for (const b of n.binding_changes)
+                counts[b.change_kind]++;
+            const parts = [];
+            if (counts.added > 0)
+                parts.push(`${counts.added} added`);
+            if (counts.removed > 0)
+                parts.push(`${counts.removed} removed`);
+            if (counts.rebound > 0)
+                parts.push(`${counts.rebound} rebound`);
+            lines.push(`_${parts.join(", ")}._`);
+        }
+    }
+    lines.push("");
+}
+function appendNotes(lines, notes) {
+    if (!notes || notes.length === 0)
+        return;
+    lines.push("## Notes");
+    lines.push("");
+    for (const n of notes)
+        lines.push(`- ${n}`);
+    lines.push("");
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function formatVersionRef(meta, versionId, isTo) {
+    if (meta?.is_head || versionId === "current") {
+        const date = meta?.created_at ? formatDate(meta.created_at) : "current state";
+        const user = meta?.user_handle ? ` by ${meta.user_handle}` : "";
+        return `Current state (last modified ${date}${user})`;
+    }
+    if (!meta) {
+        return `\`${versionId}\` _(metadata not available)_`;
+    }
+    const label = meta.label && meta.label.trim() !== "" ? `"${meta.label}"` : "_(unlabeled)_";
+    const date = meta.created_at ? formatDate(meta.created_at) : "";
+    const user = meta.user_handle ? `by ${meta.user_handle}` : "";
+    const parts = [label, date, user].filter(Boolean).join(" — ");
+    return `${parts} \`${versionId}\``;
+}
+function formatSummaryLine(input) {
+    const p = input.page_structure.summary;
+    const componentCount = input.scoped_nodes?.filter((n) => n.change_count > 0).length ?? 0;
+    const totalComponentChanges = input.scoped_nodes?.reduce((acc, n) => acc + n.change_count, 0) ?? 0;
+    const parts = [];
+    if (p.added > 0)
+        parts.push(`${p.added} page${p.added === 1 ? "" : "s"} added`);
+    if (p.removed > 0)
+        parts.push(`${p.removed} page${p.removed === 1 ? "" : "s"} removed`);
+    if (p.renamed > 0)
+        parts.push(`${p.renamed} page${p.renamed === 1 ? "" : "s"} renamed`);
+    if (componentCount > 0) {
+        parts.push(`${componentCount} component${componentCount === 1 ? "" : "s"} with ${totalComponentChanges} change${totalComponentChanges === 1 ? "" : "s"}`);
+    }
+    if (parts.length === 0)
+        return "_No structural changes detected._";
+    return parts.join("; ") + ".";
+}
+function computeSpanDays(fromIso, toIso) {
+    if (!fromIso || !toIso)
+        return null;
+    const from = new Date(fromIso).getTime();
+    const to = new Date(toIso).getTime();
+    if (isNaN(from) || isNaN(to))
+        return null;
+    return Math.max(0, Math.round((to - from) / (1000 * 60 * 60 * 24)));
+}
+function formatDate(iso) {
+    // ISO 8601 is fine as-is for release notes; trim time if it's midnight UTC for cleaner output
+    const d = new Date(iso);
+    if (isNaN(d.getTime()))
+        return iso;
+    return d.toISOString().slice(0, 10);
+}
+function escapeMd(s) {
+    // Escape characters that would break markdown. Keep light — release notes
+    // should be readable, not over-escaped.
+    return s.replace(/([\\`*_{}\[\]<>])/g, "\\$1");
+}
+function stringifyValue(v) {
+    if (v === undefined)
+        return "?"; // standard mode strips defaults; render placeholder
+    if (v === null)
+        return "null";
+    if (typeof v === "string")
+        return v;
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+function hasAnyPropChanges(s) {
+    return s.added > 0 || s.removed > 0 || s.type_changed > 0 || s.default_changed > 0;
+}