@fragments-sdk/mcp 1.0.1 → 1.0.3

package/dist/index.d.ts

@@ -23,9 +23,49 @@ interface McpPrimitive {
     donts?: string[];
     examples?: unknown[];
 }
+interface McpToken {
+    name: string;
+    value: string;
+    category: string;
+    path?: string[];
+    originalName?: string;
+    tier?: string;
+    type?: string;
+    description?: string;
+}
+interface McpCatalogMetadata {
+    org?: {
+        id?: string;
+        name?: string;
+        slug?: string;
+    };
+    project?: {
+        id?: string;
+        name?: string;
+        slug?: string;
+    };
+    sourceBinding?: {
+        bindingId?: string;
+        projectId?: string;
+        projectName?: string;
+        projectSlug?: string;
+        repoFullName?: string;
+        path?: string | null;
+        resolution?: string;
+    };
+    designSystem?: {
+        name?: string;
+        packageName?: string | null;
+        importPath?: string | null;
+    };
+    revision?: string;
+    updatedAt?: number;
+}
 
 interface DataProvider {
     listPrimitives(): Promise<McpPrimitive[]>;
+    listTokens(): Promise<McpToken[]>;
+    getCatalogMetadata?(): Promise<McpCatalogMetadata | null>;
     conform(input: ConformInput): Promise<ConformResult>;
 }
 interface SamplingInputResponse {
@@ -158,7 +198,9 @@ declare class FragmentsMcpServer {
     constructor(options: FragmentsMcpServerOptions);
     handleJsonRpc(request: JsonRpcRequest): Promise<JsonRpcResponse>;
     private dispatch;
+    private initialize;
     private discover;
+    private serverDescriptor;
     private callTool;
     private readResource;
     private getTask;
@@ -1437,7 +1479,8 @@ declare const fixturePrimitives: McpPrimitive[];
 declare const fixtureConformResult: ConformResult;
 declare function createFixtureProvider(args?: {
     primitives?: McpPrimitive[];
+    tokens?: McpToken[];
     conform?: ConformResult;
 }): DataProvider;
 
-export { type CallToolRequest, type CallToolResult, type ClientCapabilities, type DataProvider, FragmentsMcpServer, type Implementation, type InputRequiredToolResult, type JSONRPCMessage, JSONRPC_VERSION, type JsonObject, type JsonRpcRequest, type JsonRpcResponse, LATEST_PROTOCOL_VERSION, type ListResourcesResult, type ListToolsResult, MCP_APP_RESOURCES, MCP_TOOLS, type McpPrimitive, McpProtocolError, MemoryTaskStore, type ReadResourceRequest, type ReadResourceResult, type RequestMetaObject, type Resource, type ResourceDefinition, type ServerCapabilities, type TaskRecord, type TaskStore, type Tool, type ToolDefinition, type ToolResult, type WorkflowTaskInput, createFixtureProvider, fixtureConformResult, fixturePrimitives, getResource, getTool, handleMcpHttpRequest, handleMcpJsonRpc, listResources, listToolDescriptors };
+export { type CallToolRequest, type CallToolResult, type ClientCapabilities, type DataProvider, FragmentsMcpServer, type Implementation, type InputRequiredToolResult, type JSONRPCMessage, JSONRPC_VERSION, type JsonObject, type JsonRpcRequest, type JsonRpcResponse, LATEST_PROTOCOL_VERSION, type ListResourcesResult, type ListToolsResult, MCP_APP_RESOURCES, MCP_TOOLS, type McpCatalogMetadata, type McpPrimitive, McpProtocolError, type McpToken, MemoryTaskStore, type ReadResourceRequest, type ReadResourceResult, type RequestMetaObject, type Resource, type ResourceDefinition, type ServerCapabilities, type TaskRecord, type TaskStore, type Tool, type ToolDefinition, type ToolResult, type WorkflowTaskInput, createFixtureProvider, fixtureConformResult, fixturePrimitives, getResource, getTool, handleMcpHttpRequest, handleMcpJsonRpc, listResources, listToolDescriptors };

package/dist/index.js

@@ -72,19 +72,34 @@ var LATEST_PROTOCOL_VERSION = "DRAFT-2026-v1";
 var JSONRPC_VERSION = "2.0";
 
 // src/tools/primitives.ts
+var variantSchema = {
+  type: "object",
+  properties: {
+    prop: { type: "string" },
+    values: { type: "array", items: { type: "string" } }
+  },
+  required: ["prop", "values"],
+  additionalProperties: false
+};
 var primitiveSchema = {
   type: "object",
   properties: {
     id: { type: "string" },
     name: { type: "string" },
     primitiveName: { type: "string" },
+    category: { type: ["string", "null"] },
+    status: { type: ["string", "null"] },
     filePath: { type: ["string", "null"] },
     importPath: { type: ["string", "null"] },
     packageName: { type: ["string", "null"] },
     description: { type: "string" },
     usageGuidance: { type: "string" },
     props: { type: "object" },
+    variants: { type: "array", items: variantSchema },
     examples: { type: "array" },
+    dos: { type: "array", items: { type: "string" } },
+    donts: { type: "array", items: { type: "string" } },
+    parentComponentName: { type: ["string", "null"] },
     sourceRepoFullName: { type: ["string", "null"] }
   },
   required: ["id", "name", "primitiveName", "filePath", "importPath"],
@@ -116,11 +131,12 @@ var primitiveTools = [
     },
     async call(_args, context) {
       const primitives = await context.provider.listPrimitives();
-      return primitiveResult(primitives);
+      const metadata = await context.provider.getCatalogMetadata?.();
+      return primitiveResult(primitives, metadata ?? null);
     }
   }
 ];
-function primitiveResult(primitives) {
+function primitiveResult(primitives, metadata) {
   return {
     content: [
       {
@@ -131,24 +147,132 @@ function primitiveResult(primitives) {
     structuredContent: {
       primitiveCount: primitives.length,
       primitives: primitives.map(normalizePrimitive)
+    },
+    _meta: {
+      catalog: metadata
     }
   };
 }
 function normalizePrimitive(primitive) {
+  const props = primitive.props ?? {};
   return {
     id: primitive.id,
     name: primitive.name,
     primitiveName: primitive.primitiveName ?? primitive.name,
+    category: primitive.category ?? null,
+    status: primitive.status ?? null,
     filePath: primitive.filePath ?? null,
     importPath: primitive.importPath ?? null,
     packageName: primitive.packageName ?? null,
     description: primitive.description ?? "",
     usageGuidance: primitive.usageGuidance ?? "",
-    props: primitive.props ?? {},
+    props,
+    variants: deriveVariants(props),
     examples: primitive.examples ?? [],
+    dos: primitive.dos ?? [],
+    donts: primitive.donts ?? [],
+    parentComponentName: primitive.parentComponentName ?? null,
     sourceRepoFullName: primitive.sourceRepoFullName ?? null
   };
 }
+function deriveVariants(props) {
+  const variants = [];
+  for (const [prop, def] of Object.entries(props)) {
+    if (typeof def !== "object" || def === null) continue;
+    const type = def.type;
+    if (typeof type !== "string") continue;
+    const values = parseLiteralUnion(type);
+    if (values.length >= 2) variants.push({ prop, values });
+  }
+  return variants;
+}
+function parseLiteralUnion(type) {
+  const segments = type.split("|").map((segment) => segment.trim());
+  const values = [];
+  for (const segment of segments) {
+    const match = /^(["'])(.+)\1$/.exec(segment);
+    if (!match) return [];
+    values.push(match[2]);
+  }
+  return values;
+}
+
+// src/tools/tokens.ts
+var tokenSchema = {
+  type: "object",
+  properties: {
+    name: { type: "string" },
+    value: { type: "string" },
+    category: { type: "string" },
+    path: { type: "array", items: { type: "string" } },
+    originalName: { type: "string" },
+    tier: { type: "string" },
+    type: { type: "string" },
+    description: { type: "string" }
+  },
+  required: ["name", "value", "category"],
+  additionalProperties: false
+};
+var tokenTools = [
+  {
+    name: "design_system/list_tokens",
+    title: "List Tokens",
+    description: "List the design-system tokens Fragments Cloud has indexed for this project. Returns factual token names, values, categories, and source metadata.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+      maxProperties: 0
+    },
+    outputSchema: {
+      type: "object",
+      properties: {
+        tokenCount: { type: "integer" },
+        tokens: { type: "array", items: tokenSchema }
+      },
+      required: ["tokenCount", "tokens"],
+      additionalProperties: false
+    },
+    annotations: {
+      readOnlyHint: true,
+      idempotentHint: true
+    },
+    async call(_args, context) {
+      const tokens = await context.provider.listTokens();
+      const metadata = await context.provider.getCatalogMetadata?.();
+      return tokenResult(tokens, metadata ?? null);
+    }
+  }
+];
+function tokenResult(tokens, metadata) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: tokens.length === 0 ? "No design-system tokens have been indexed in Fragments Cloud yet." : `Found ${tokens.length} design-system tokens.`
+      }
+    ],
+    structuredContent: {
+      tokenCount: tokens.length,
+      tokens: tokens.map(normalizeToken)
+    },
+    _meta: {
+      catalog: metadata
+    }
+  };
+}
+function normalizeToken(token) {
+  return {
+    name: token.name,
+    value: token.value,
+    category: token.category,
+    path: token.path ?? [],
+    ...token.originalName ? { originalName: token.originalName } : {},
+    ...token.tier ? { tier: token.tier } : {},
+    ...token.type ? { type: token.type } : {},
+    ...token.description ? { description: token.description } : {}
+  };
+}
 
 // src/tools/conform.ts
 var locationSchema = {
@@ -186,7 +310,12 @@ var suggestionSchema = {
   properties: {
     kind: {
       type: "string",
-      enum: ["map-prop-value", "choose-among-alternates", "review-low-confidence"]
+      enum: [
+        "map-prop-value",
+        "choose-among-alternates",
+        "review-low-confidence",
+        "flag-accessibility"
+      ]
     },
     message: { type: "string" },
     canonical: { type: "string" },
@@ -212,7 +341,7 @@ var conformTools = [
   {
     name: "design_system/conform",
     title: "Conform to Design System",
-    description: "Rewrite a snippet of UI code so it matches THIS project's design system. Swaps raw HTML elements and components from other libraries (Material UI, shadcn/ui, Chakra, or custom) to the project's own components and import paths, replaces hardcoded colors/spacing/radii with the project's design tokens, and flags accessibility gaps. Call this whenever the user says 'fix this', 'make this match our design system', 'use our components here', right after pasting markup from elsewhere, or before committing UI you wrote. Input is the code itself \u2014 no repo access needed. Returns a conformed version plus a list of changes with rationale; ambiguous cross-library prop changes come back as suggestions for you to apply.",
+    description: "Rewrite a snippet of UI code so it matches THIS project's design system. Swaps raw HTML elements and components from other libraries (Material UI, shadcn/ui, Chakra, or custom) to the project's own components and import paths, renames cross-library props and translates their values when the mapping is confirmed, and replaces hardcoded colors/spacing/radii with the project's design tokens. Call this whenever the user says 'fix this', 'make this match our design system', 'use our components here', right after pasting markup from elsewhere, or before committing UI you wrote. Input is the code itself \u2014 no repo access needed. Returns a conformed version plus a list of changes with rationale. Ambiguous prop changes and accessibility gaps (e.g. a button or image with no accessible name) come back as suggestions for you to apply \u2014 they are never auto-rewritten.",
     inputSchema: {
       type: "object",
       properties: {
@@ -250,7 +379,17 @@ var conformTools = [
         },
         changes: { type: "array", items: changeSchema },
         suggestions: { type: "array", items: suggestionSchema },
-        unresolved: { type: "array", items: unresolvedSchema }
+        unresolved: { type: "array", items: unresolvedSchema },
+        coverage: {
+          type: "object",
+          properties: {
+            tokens: { type: "integer" },
+            components: { type: "integer" },
+            evaluated: { type: "boolean" }
+          },
+          required: ["tokens", "components", "evaluated"],
+          additionalProperties: false
+        }
       },
       required: ["conformed", "changed", "changes", "suggestions"],
       additionalProperties: false
@@ -290,7 +429,8 @@ function conformResult(result) {
       } : {},
       changes: result.changes,
       suggestions: result.suggestions,
-      unresolved: result.unresolved
+      unresolved: result.unresolved,
+      ...result.coverage ? { coverage: result.coverage } : {}
     }
   };
 }
@@ -325,6 +465,16 @@ var residualSchema = {
   },
   additionalProperties: true
 };
+var coverageSchema = {
+  type: "object",
+  properties: {
+    tokens: { type: "integer" },
+    components: { type: "integer" },
+    evaluated: { type: "boolean" }
+  },
+  required: ["tokens", "components", "evaluated"],
+  additionalProperties: false
+};
 var proveCompliantOutputSchema = {
   type: "object",
   properties: {
@@ -341,7 +491,8 @@ var proveCompliantOutputSchema = {
     changes: { type: "array", items: { type: "object", additionalProperties: true } },
     suggestions: { type: "array", items: residualSchema },
     unresolved: { type: "array", items: residualSchema },
-    passHistory: { type: "array", items: { type: "object", additionalProperties: true } }
+    passHistory: { type: "array", items: { type: "object", additionalProperties: true } },
+    coverage: coverageSchema
   },
   required: [
     "provedCompliant",
@@ -459,12 +610,13 @@ async function proveCompliant(args, context) {
     });
     input.corrections += result.changes.length;
     if (issues === 0) {
+      const evaluated = result.coverage?.evaluated !== false;
       const final2 = completeResult({
         state: input,
         result,
         originalCode: args.code,
-        provedCompliant: true,
-        reason: `0 findings after ${pass} pass${pass === 1 ? "" : "es"}.`
+        provedCompliant: evaluated,
+        reason: evaluated ? `0 findings after ${pass} pass${pass === 1 ? "" : "es"}.` : "the design-system catalog has no tokens or components, so compliance could not be evaluated."
       });
       return finish(context, input.taskId, final2);
     }
@@ -609,7 +761,8 @@ function completeResult(args) {
       changes: args.result.changes,
       suggestions: args.result.suggestions,
       unresolved: args.result.unresolved,
-      passHistory: args.state.passHistory
+      passHistory: args.state.passHistory,
+      ...args.result.coverage ? { coverage: args.result.coverage } : {}
     }
   };
 }
@@ -705,6 +858,7 @@ function emptyConformResult(code) {
 var MAX_SCHEMA_DEPTH = 16;
 var MCP_TOOLS = [
   ...primitiveTools,
+  ...tokenTools,
   ...conformTools,
   ...proveCompliantTools
 ];
@@ -773,7 +927,14 @@ var FragmentsMcpServer = class {
   }
   async dispatch(request) {
     const params = request.params ?? {};
+    if (request.method.startsWith("notifications/")) {
+      return void 0;
+    }
     switch (request.method) {
+      case "initialize":
+        return this.initialize(params);
+      case "ping":
+        return {};
       case "server/discover":
         return this.discover();
       case "tools/list":
@@ -794,7 +955,17 @@ var FragmentsMcpServer = class {
         throw new McpProtocolError(-32601, `Unknown MCP method ${request.method}`);
     }
   }
+  initialize(params) {
+    const requested = params.protocolVersion;
+    return {
+      ...this.serverDescriptor(),
+      protocolVersion: typeof requested === "string" ? requested : LATEST_PROTOCOL_VERSION
+    };
+  }
   discover() {
+    return this.serverDescriptor();
+  }
+  serverDescriptor() {
     return {
       protocolVersion: LATEST_PROTOCOL_VERSION,
       serverInfo: {
@@ -873,6 +1044,20 @@ async function handleMcpHttpRequest(request, options) {
       status: 400
     });
   }
+  const isNotification = body.id === void 0 || typeof body.method === "string" && body.method.startsWith("notifications/");
+  if (isNotification) {
+    try {
+      await handleMcpJsonRpc(body, options);
+    } catch {
+    }
+    return new Response(null, {
+      status: 202,
+      headers: {
+        "Cache-Control": "no-store",
+        "Mcp-Protocol-Version": LATEST_PROTOCOL_VERSION
+      }
+    });
+  }
   const response = await handleMcpJsonRpc(body, options);
   return Response.json(response, {
     status: "error" in response ? 400 : 200,
@@ -1035,6 +1220,27 @@ var fixturePrimitives = [
     }
   }
 ];
+var fixtureTokens = [
+  {
+    name: "color.brand.primary",
+    originalName: "--brand-600",
+    value: "#2563eb",
+    category: "color",
+    path: ["color", "brand", "primary"],
+    tier: "canonical",
+    type: "color",
+    description: "Primary brand color."
+  },
+  {
+    name: "space.4",
+    originalName: "--space-4",
+    value: "16px",
+    category: "spacing",
+    path: ["space", "4"],
+    tier: "canonical",
+    type: "dimension"
+  }
+];
 var fixtureConformResult = {
   conformed: 'import { Button } from "@fixture/ui";\n\n<Button variant="primary" style={{ padding: "var(--space-4)" }}>Send</Button>',
   changed: true,
@@ -1092,11 +1298,15 @@ var fixtureConformResult = {
 };
 function createFixtureProvider(args) {
   const primitives = args?.primitives ?? fixturePrimitives;
+  const tokens = args?.tokens ?? fixtureTokens;
   const conformResult2 = args?.conform ?? fixtureConformResult;
   return {
     async listPrimitives() {
       return primitives;
     },
+    async listTokens() {
+      return tokens;
+    },
     async conform() {
       return conformResult2;
     }