@bridge-ds/mcp 0.8.5 → 0.10.0

package/dist/ops.d.ts

@@ -71,6 +71,7 @@ export declare function searchTokens(ctx: BridgeContext, a: {
     type?: string;
     limit?: number;
 }): Promise<{
+    truncated?: string | undefined;
     query: string;
     mode: Combo;
     total: number;
@@ -197,6 +198,46 @@ export declare function getComponentOp(ctx: BridgeContext, a: {
  * CSS module classes, contrast notes, changelog line, existing prose kept) and a prompt for the user's own Claude
  * to write the prose that code cannot tell. Nothing is written.
  */
+/**
+ * The tokens a component reaches: the ones its stylesheets read plus every token they alias, in any mode
+ * (card.bg -> color.surface.raised), so a contrast pair written on semantic tokens matches a component token.
+ */
+export declare function reachedTokens(set: TokenSet, paths: Iterable<string>): Set<string>;
+/**
+ * Contrast pairs that concern a component: both sides among the tokens it reaches (its text on its own surface).
+ * A component that sets no surface of its own (text on whatever it sits on) gets the pairs of the foregrounds it
+ * uses instead. Never a pair that only shares a background with it.
+ */
+export declare function relevantPairs<P extends {
+    foreground: string;
+    background: string;
+}>(pairs: P[], reached: Set<string>): P[];
+/** Characters of the docs prompt per page of bridge_draft_docs: a whole prompt can pass 25,000 characters. */
+export declare const DOCS_PROMPT_PAGE = 12000;
+/** Splits text into pages of at most `size` characters, on line breaks when it can. */
+export declare function textPages(text: string, size: number): string[];
+/**
+ * bridge_draft_docs result for a tool call: the prompt one page at a time (page 1 by default), with a summary of
+ * what the draft holds and how to read the next page. The CLI prints the whole draft and does not page.
+ */
+export declare function pagedDraftDocs<D extends {
+    component: string;
+    prompt: string;
+    prefill: {
+        tokens: string[];
+        contrastNotes: string[];
+        missing: string[];
+    };
+}>(d: D, page?: number, size?: number): {
+    summary: string;
+} & D & {
+    prompt: string;
+    promptPage: {
+        next?: string | undefined;
+        page: number;
+        pages: number;
+    };
+};
 export declare function draftDocsOp(ctx: BridgeContext, a: {
     name: string;
     branch?: string | undefined;
@@ -737,6 +778,7 @@ export declare function getReview(ctx: BridgeContext, a: {
 export declare function reviewRoles(gh: GitHubClient, config: BridgeConfig, approvers: string[]): Promise<{
     unreadableTeams?: string[] | undefined;
     ship: string;
+    tier1Publish: string;
     soloOwner?: string | undefined;
     design: {
         owners: string[];

package/dist/say.d.ts

@@ -0,0 +1,22 @@
+type Surface = {
+    surface: 'mcp' | 'cli';
+};
+/** The MCP wording or the CLI wording, for this context's reader. */
+export declare function say(ctx: Surface, mcp: string, cli: string): string;
+/** Where a change comes from, as the labels say ("source: cli"): what the caller passed, else this context's reader. */
+export declare const sourceOf: (ctx: Surface, source?: "mcp" | "cli" | undefined) => "mcp" | "cli";
+/** The tool in pull request bodies and commit messages: "Bridge MCP" or "the bridge CLI". */
+export declare const toolName: (source: "mcp" | "cli") => "Bridge MCP" | "the bridge CLI";
+/** The same with its source label: "Bridge MCP (source: mcp)". */
+export declare const toolTag: (source: "mcp" | "cli") => string;
+/** How to give Bridge a token where it runs. */
+export declare function addToken(ctx: Surface): string;
+/** "Read-only: ... to open this as a pull request." for previews without a token. */
+export declare function readOnlyPreview(ctx: Surface, what?: string): string;
+/** Thrown when a rule blocks the action (the merge gate, the owner override): not a usage error. */
+export declare class BlockedError extends Error {
+    readonly blocked = true;
+    constructor(message: string);
+}
+export declare const isBlocked: (e: unknown) => e is BlockedError;
+export {};

package/dist/server.d.ts

@@ -2,4 +2,31 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { BridgeContext } from './context.js';
 /** The package version, injected at build time; tests and source runs fall back to "dev". */
 export declare const VERSION: string;
-export declare function createServer(ctx: BridgeContext): McpServer;
+/** The Bridge site: it serves the hosted connector (/mcp) and the official icons. */
+export declare const BRIDGE_SITE = "https://bridge.floriangouloubi.com";
+/**
+ * How clients show this server (MCP 2025-11-25, Implementation: `title` is the display name, `icons` the images; the
+ * SDK here supports that version). `name` stays machine-safe. Icons are absolute https URLs on the same domain as the
+ * hosted connector, PNG first since every client that renders icons must support it.
+ */
+export declare const SERVER_INFO: {
+    name: string;
+    title: string;
+    version: string;
+    websiteUrl: string;
+    icons: {
+        src: string;
+        mimeType: string;
+        sizes: string[];
+    }[];
+};
+/** How a server is built for where it runs. */
+export interface ServerOptions {
+    /**
+     * Tools this server neither lists nor runs. The hosted connector (Bridge inside the team's Claude) leaves out the
+     * merge (bridge_merge_branch and its owner override): agents never merge there, a person does. The local CLI and
+     * MCP server keep every tool.
+     */
+    exclude?: readonly string[] | undefined;
+}
+export declare function createServer(ctx: BridgeContext, opts?: ServerOptions): McpServer;

package/dist/{src-DRJFSLRV.js → src-ATD4DJF3.js}

@@ -11,7 +11,7 @@ import {
   referenceImagePath,
   selectTokenFiles,
   showFile
-} from "./chunk-PMZGEZGX.js";
+} from "./chunk-BZEPCY42.js";
 
 // ../visual/src/run.ts
 import { existsSync as existsSync3 } from "node:fs";
@@ -317,6 +317,17 @@ async function switchStory(page, storyId2) {
   );
   if (!ok) throw new Error("Storybook channel not found");
 }
+async function openMeasurePage(o = {}) {
+  const browser = await launch(o);
+  try {
+    const ctx = await browser.newContext({ viewport: { width: 1200, height: 800 }, deviceScaleFactor: o.scale ?? 1, reducedMotion: "reduce", colorScheme: "light", locale: "en-US", serviceWorkers: "block" });
+    const page = await ctx.newPage();
+    return { page, close: () => browser.close().catch(() => void 0) };
+  } catch (e) {
+    await browser.close().catch(() => void 0);
+    throw e;
+  }
+}
 
 // ../visual/src/composite.ts
 import { readFile, writeFile as writeFile2 } from "node:fs/promises";
@@ -368,6 +379,15 @@ import pixelmatch from "pixelmatch";
 import { PNG } from "pngjs";
 var decodePng = (buf) => PNG.sync.read(buf);
 var encodePng = (png) => PNG.sync.write(png, { colorType: 6 });
+function cropPng(src, x, y, width, height) {
+  const left = Math.max(0, Math.round(x));
+  const top = Math.max(0, Math.round(y));
+  const w = Math.max(1, Math.min(src.width - left, Math.round(width)));
+  const h = Math.max(1, Math.min(src.height - top, Math.round(height)));
+  const out = new PNG({ width: w, height: h });
+  PNG.bitblt(src, out, left, top, w, h, 0, 0);
+  return out;
+}
 function padTo(src, width, height) {
   if (src.width === width && src.height === height) return src;
   const out = new PNG({ width, height });
@@ -1208,9 +1228,12 @@ async function captureFigmaReferences(o) {
   try {
     const ctx = await newContext(browser, { width: 1200, height: 800 }, scale);
     const page = await newPage(ctx);
-    await page.goto(storyUrl(served.url, FIGMA_REFERENCE_STORY, brand, theme), { waitUntil: "load", timeout: 3e4 });
-    await page.waitForSelector("[data-fidelity-root], [data-fidelity-error]", { state: "attached", timeout: 2e4 });
-    await settle(page, { busy: false });
+    const openStory = async () => {
+      await page.goto(storyUrl(served.url, FIGMA_REFERENCE_STORY, brand, theme), { waitUntil: "load", timeout: 3e4 });
+      await page.waitForSelector("[data-fidelity-root], [data-fidelity-error]", { state: "attached", timeout: 2e4 });
+      await settle(page, { busy: false });
+    };
+    await openStory();
     log(`Capturing ${jobs.length} variants at ${scale}x (${brand} ${theme})`);
     for (const j of jobs) {
       const variants = manifest.components[j.component].variants;
@@ -1219,25 +1242,17 @@ async function captureFigmaReferences(o) {
         skipped++;
         continue;
       }
-      const plan = JSON.stringify(j.plan.render);
-      await page.evaluate(
-        ({ id, plan: plan2 }) => new Promise((resolve2) => {
-          const ch = window.__STORYBOOK_ADDONS_CHANNEL__;
-          const done = () => {
-            clearTimeout(timer);
-            ch.off("storyRendered", done);
-            resolve2();
-          };
-          const timer = setTimeout(done, 1e4);
-          ch.on("storyRendered", done);
-          ch.emit("updateStoryArgs", { storyId: id, updatedArgs: { plan: plan2 } });
-        }),
-        { id: FIGMA_REFERENCE_STORY, plan }
-      );
+      const shown = await renderPlan(page, JSON.stringify(j.plan.render));
+      if (shown.broken) {
+        variants[j.key] = { skipped: `the code example threw: ${shown.error ?? "the story did not finish rendering"}` };
+        skipped++;
+        await openStory();
+        continue;
+      }
       await settle(page, { network: false, quiet: 2, interval: 40, busy: false });
       const error = await page.locator("[data-fidelity-error]").first().textContent({ timeout: 200 }).catch(() => null);
       let target = page.locator("[data-fidelity-root] > *").first();
-      if (!error && !await target.count()) {
+      if (!error && (j.plan.render.within || j.plan.render.popup || !await target.count())) {
         const marked = page.locator("[data-fidelity-target]").first();
         await marked.waitFor({ state: "visible", timeout: 3e3 }).catch(() => void 0);
         await settle(page, { network: false, quiet: 2, interval: 40, busy: false });
@@ -1248,6 +1263,15 @@ async function captureFigmaReferences(o) {
         skipped++;
         continue;
       }
+      const transparent = await target.evaluate((el) => {
+        for (let e = el; e; e = e.parentElement) if (getComputedStyle(e).opacity === "0") return true;
+        return false;
+      });
+      if (transparent) {
+        variants[j.key] = { skipped: "the code example rendered invisible (opacity 0)" };
+        skipped++;
+        continue;
+      }
       const file = referenceImagePath(j.component, j.key);
       const path = join4(o.out, file);
       await mkdir4(dirname3(path), { recursive: true });
@@ -1268,6 +1292,35 @@ async function captureFigmaReferences(o) {
   log(`${captured} images, ${skipped} variants skipped. ${manifestPath}`);
   return { manifest, manifestPath, captured, skipped };
 }
+async function renderPlan(page, plan) {
+  const r = await page.evaluate(
+    ({ id, plan: plan2 }) => new Promise((resolve2) => {
+      const ch = window.__STORYBOOK_ADDONS_CHANNEL__;
+      let error;
+      const failed = (p) => {
+        const e = p;
+        error ??= e?.message ?? e?.title ?? e?.description;
+      };
+      const finish = (rendered) => {
+        clearTimeout(timer);
+        ch.off("storyRendered", done);
+        ch.off("storyThrewException", failed);
+        ch.off("storyErrored", failed);
+        resolve2({ rendered, ...error ? { error } : {} });
+      };
+      const done = () => finish(true);
+      document.querySelectorAll("[data-fidelity-target]").forEach((el) => el.removeAttribute("data-fidelity-target"));
+      const timer = setTimeout(() => finish(false), 1e4);
+      ch.on("storyThrewException", failed);
+      ch.on("storyErrored", failed);
+      ch.on("storyRendered", done);
+      ch.emit("updateStoryArgs", { storyId: id, updatedArgs: { plan: plan2 } });
+    }),
+    { id: FIGMA_REFERENCE_STORY, plan }
+  );
+  const errorScreen = await page.evaluate(() => document.body.classList.contains("sb-show-errordisplay"));
+  return { broken: !r.rendered || !!r.error || errorScreen, ...r.error ? { error: r.error } : {} };
+}
 export {
   COMMENT_MARKER,
   DEFAULT_ROUTES,
@@ -1276,11 +1329,13 @@ export {
   boxesFromDiff,
   captureFigmaReferences,
   changedTokens,
+  cropPng,
   decodePng,
   diffPngs,
   encodePng,
   hasVisualChange,
   linkNodeModules,
+  openMeasurePage,
   padTo,
   planImpact,
   rankShots,

package/dist/studio.d.ts

@@ -94,6 +94,7 @@ export declare function getSettings(ctx: BridgeContext): Promise<{
     main: string;
     roles: {
         teamsNotRead?: string[] | undefined;
+        tier1Publish: string;
         soloOwner?: string | undefined;
         designApproval: string[];
         techApproval: string[];
@@ -114,6 +115,16 @@ export declare function getSettings(ctx: BridgeContext): Promise<{
     visualImpact: import("@bridge-ds/core").VisualImpactMode;
     note: string;
 }>;
+/**
+ * One count of components everywhere: the component folders (snapshot.json and llms.txt count the same), then what the
+ * other numbers are: layout helpers have no Figma component, and in Figma popups and items are sets of their own.
+ */
+export declare function coverageLine(s: {
+    inFigma: number;
+    drafted: number;
+    layout: number;
+    total: number;
+}, figmaSets: number): string;
 /** Which components are in Figma (Studio's "In Figma" column), and whether code images exist for the fidelity check. */
 export declare function figmaCoverage(ctx: BridgeContext, a?: {
     component?: string | undefined;

package/dist/suggestions.d.ts

@@ -9,7 +9,9 @@ export declare const SUGGEST_RIGHTS = "Issues: read and write (Contents: read is
  */
 export declare function changesFor(ctx: BridgeContext, explicit?: ChangesMode | undefined): Promise<ChangesMode>;
 /** What to do next once a suggestion is filed. The wording matches the issue's "How to apply". */
-export declare const appliedNext: (n: number) => string;
+export declare const appliedNext: (n: number, ctx?: {
+    surface: "mcp" | "cli";
+}) => string;
 /** Why nothing was filed: no GitHub repo, or no token that can write issues. */
 export declare function noSuggestionAccess(ctx: BridgeContext, gh: GitHubClient | null): string;
 /**
@@ -144,6 +146,7 @@ export declare function getSuggestionOp(ctx: BridgeContext, a: {
         }[];
     } | undefined;
     approvals: {
+        ownerOverride?: string | undefined;
         soloOwner?: string | undefined;
         notCounted?: string[] | undefined;
         staleReviews?: string[] | undefined;
@@ -224,7 +227,13 @@ export declare function getSuggestionOp(ctx: BridgeContext, a: {
         merged: boolean;
     }[];
 }>;
-export type SuggestionReviewEventArg = 'approve' | 'request-changes' | 'comment' | 'decline';
+export type SuggestionReviewEventArg = 'approve' | 'request-changes' | 'comment' | 'decline' | 'override';
+/** The owner override on a suggestion, as Studio and History say it. */
+export declare const suggestionOverrideLine: (o: {
+    login: string;
+    reason: string;
+    missing: readonly string[];
+}) => string;
 /**
  * bridge_review_suggestion / `bridge review <n>`: approve, request changes, comment on or decline a suggestion, as the
  * token's user. Approvals count only from the owners in bridge.config.json and only on the version reviewed
@@ -242,6 +251,16 @@ export declare function reviewSuggestionOp(ctx: BridgeContext, a: {
     number: number;
     status: SuggestionStatus;
     said: string;
+} | {
+    next: string;
+    warnings?: string[] | undefined;
+    number: number;
+    event: "override";
+    counts: boolean;
+    version: string;
+    status: SuggestionStatus;
+    said: string;
+    comment: string;
 } | {
     next: string;
     warnings?: string[] | undefined;

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@bridge-ds/mcp",
-  "version": "0.8.5",
+  "version": "0.10.0",
   "type": "module",
   "description": "Bridge MCP server: lets Claude (Claude Code, Claude Desktop or any MCP client) read, check and propose changes to a DTCG design system repo through pull requests.",
-  "license": "MIT",
+  "license": "FSL-1.1-MIT",
   "author": "Florian Gouloubi",
   "homepage": "https://github.com/peterbono/ai-design-system-demo/tree/main/packages/mcp#readme",
   "repository": {
@@ -51,11 +51,12 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && vitest run --config vitest.config.ts",
     "start": "node dist/index.js",
+    "readme:tools": "BRIDGE_UPDATE_README=1 vitest run --config vitest.config.ts packages/mcp/test/readme.test.ts",
     "build:package": "node ../../scripts/build-packages.mjs mcp"
   },
   "dependencies": {
-    "@bridge-ds/core": "^0.18.0",
-    "@bridge-ds/visual": "^0.3.12",
+    "@bridge-ds/core": "^0.20.0",
+    "@bridge-ds/visual": "^0.3.14",
     "@modelcontextprotocol/sdk": "1.31.0",
     "typescript": "5.9.3",
     "zod": "3.25.76"