@fragments-sdk/cli 0.4.4 → 0.5.0

package/src/mcp/server.ts

@@ -41,7 +41,9 @@ import { projectFields } from './utils.js';
 const TOOL_NAMES = {
   discover: `${BRAND.nameLower}_discover`,
   inspect: `${BRAND.nameLower}_inspect`,
-  recipe: `${BRAND.nameLower}_recipe`,
+  blocks: `${BRAND.nameLower}_blocks`,
+  tokens: `${BRAND.nameLower}_tokens`,
+  implement: `${BRAND.nameLower}_implement`,
   render: `${BRAND.nameLower}_render`,
   fix: `${BRAND.nameLower}_fix`,
 } as const;
@@ -320,26 +322,61 @@ const TOOLS: Tool[] = [
     },
   },
   {
-    name: TOOL_NAMES.recipe,
-    description: `Search and retrieve composition recipes — named patterns showing how design system components wire together for common use cases (e.g., "Login Form", "Settings Page"). Returns the recipe with its code pattern.`,
+    name: TOOL_NAMES.blocks,
+    description: `Search and retrieve composition blocks — named patterns showing how design system components wire together for common use cases (e.g., "Login Form", "Settings Page"). Returns the block with its code pattern.`,
     inputSchema: {
       type: 'object' as const,
       properties: {
         name: {
           type: 'string',
-          description: 'Exact recipe name to retrieve (e.g., "Login Form")',
+          description: 'Exact block name to retrieve (e.g., "Login Form")',
         },
         search: {
           type: 'string',
-          description: 'Free-text search across recipe names, descriptions, tags, and components',
+          description: 'Free-text search across block names, descriptions, tags, and components',
         },
         component: {
           type: 'string',
-          description: 'Filter recipes that use a specific component (e.g., "Button")',
+          description: 'Filter blocks that use a specific component (e.g., "Button")',
+        },
+        category: {
+          type: 'string',
+          description: 'Filter by category (e.g., "authentication", "marketing", "dashboard", "settings", "ecommerce", "ai")',
         },
       },
     },
   },
+  {
+    name: TOOL_NAMES.tokens,
+    description: `List available CSS design tokens (custom properties) by category. Use this when you need to style custom elements or override defaults — no more guessing variable names. Filter by category or search by keyword.`,
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        category: {
+          type: 'string',
+          description: 'Filter by category (e.g., "colors", "spacing", "typography", "surfaces", "shadows", "radius", "borders", "text", "focus", "layout", "code", "component-sizing")',
+        },
+        search: {
+          type: 'string',
+          description: 'Search token names (e.g., "accent", "hover", "padding")',
+        },
+      },
+    },
+  },
+  {
+    name: TOOL_NAMES.implement,
+    description: `One-shot implementation helper. Describe what you want to build and get everything needed in a single call: best-matching component(s) with full props and code examples, relevant composition blocks, and applicable CSS tokens. Saves multiple round-trips.`,
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        useCase: {
+          type: 'string',
+          description: 'What you want to implement (e.g., "login form", "data table with sorting", "streaming chat messages")',
+        },
+      },
+      required: ['useCase'],
+    },
+  },
   {
     name: TOOL_NAMES.render,
     description: `Render a component and return a screenshot. Optionally compare against a stored baseline ('baseline: true') or against a Figma design ('figmaUrl'). Use this to verify your implementation looks correct.`,
@@ -457,6 +494,11 @@ export function createMcpServer(config: McpServerConfig): Server {
     const content = await readFile(paths[0], 'utf-8');
     segmentsData = JSON.parse(content) as CompiledSegmentsFile;
 
+    // Normalize legacy "recipes" key to "blocks"
+    if (!segmentsData.blocks && segmentsData.recipes) {
+      segmentsData.blocks = segmentsData.recipes;
+    }
+
     // Track per-segment package names from each source file
     if (segmentsData.packageName) {
       for (const name of Object.keys(segmentsData.segments)) {
@@ -473,8 +515,10 @@ export function createMcpServer(config: McpServerConfig): Server {
         }
       }
       Object.assign(segmentsData.segments, extra.segments);
-      if (extra.recipes) {
-        segmentsData.recipes = { ...segmentsData.recipes, ...extra.recipes };
+      // Support both "blocks" (new) and "recipes" (legacy) keys
+      const extraBlocks = extra.blocks ?? extra.recipes;
+      if (extraBlocks) {
+        segmentsData.blocks = { ...segmentsData.blocks, ...extraBlocks };
       }
     }
 
@@ -487,6 +531,9 @@ export function createMcpServer(config: McpServerConfig): Server {
    * falls back to the first fragments.json packageName, then project package.json.
    */
   async function getPackageName(segmentName?: string): Promise<string> {
+    // Ensure segments are loaded (populates segmentPackageMap)
+    await loadSegments();
+
     // Check per-segment map first (handles multi-library merges correctly)
     if (segmentName) {
       const segPkg = segmentPackageMap.get(segmentName);
@@ -497,10 +544,9 @@ export function createMcpServer(config: McpServerConfig): Server {
       return defaultPackageName;
     }
 
-    // Prefer packageName from compiled fragments.json
-    const data = await loadSegments();
-    if (data.packageName) {
-      defaultPackageName = data.packageName;
+    // Prefer packageName from first fragments.json
+    if (segmentsData?.packageName) {
+      defaultPackageName = segmentsData.packageName;
       return defaultPackageName;
     }
 
@@ -615,7 +661,7 @@ export function createMcpServer(config: McpServerConfig): Server {
           // --- Context mode: compact or format specified with no specific query ---
           if (compact || (args?.format && !useCase && !componentForAlts && !category && !search && !status)) {
             const segments = Object.values(data.segments);
-            const recipes = Object.values(data.recipes ?? {});
+            const allBlocks = Object.values(data.blocks ?? data.recipes ?? {});
 
             const { content: ctxContent, tokenEstimate } = generateContext(segments, {
               format,
@@ -624,7 +670,7 @@ export function createMcpServer(config: McpServerConfig): Server {
                 code: includeCode,
                 relations: includeRelations,
               },
-            }, recipes);
+            }, allBlocks);
 
             return {
               content: [{
@@ -778,6 +824,31 @@ export function createMcpServer(config: McpServerConfig): Server {
               ? `These components work well together. For example, ${suggestions[0].component} can be combined with ${suggestions.slice(1, 3).map(s => s.component).join(' and ')}.`
               : undefined;
 
+            // Detect if query is about styling/tokens rather than components
+            const STYLE_KEYWORDS = ['color', 'spacing', 'padding', 'margin', 'font', 'border', 'radius', 'shadow', 'variable', 'token', 'css', 'theme', 'dark mode', 'background', 'hover'];
+            const isStyleQuery = STYLE_KEYWORDS.some((kw) => useCaseLower.includes(kw));
+
+            // Determine no-match quality
+            const noMatch = suggestions.length === 0;
+            const weakMatch = !noMatch && suggestions.every((s) => s.confidence === 'low');
+
+            let recommendation: string;
+            let nextStep: string | undefined;
+            if (noMatch) {
+              recommendation = isStyleQuery
+                ? `No matching components found. Your query seems styling-related — try ${TOOL_NAMES.tokens} to find CSS custom properties.`
+                : 'No matching components found. Try different keywords or browse all components with fragments_discover.';
+              nextStep = isStyleQuery
+                ? `Use ${TOOL_NAMES.tokens}(search: "${searchTerms[0]}") to find design tokens.`
+                : undefined;
+            } else if (weakMatch) {
+              recommendation = `Weak matches only — ${suggestions[0].component} might work but confidence is low.${isStyleQuery ? ` If you need a CSS variable, try ${TOOL_NAMES.tokens}.` : ''}`;
+              nextStep = `Use ${TOOL_NAMES.inspect}("${suggestions[0].component}") to check if it fits, or try broader search terms.`;
+            } else {
+              recommendation = `Best match: ${suggestions[0].component} (${suggestions[0].confidence} confidence) - ${suggestions[0].description}`;
+              nextStep = `Use ${TOOL_NAMES.inspect}("${suggestions[0].component}") for full details.`;
+            }
+
             return {
               content: [{
                 type: 'text' as const,
@@ -785,13 +856,11 @@ export function createMcpServer(config: McpServerConfig): Server {
                   useCase,
                   context: context || undefined,
                   suggestions: suggestions.map(({ score, ...rest }) => rest),
-                  recommendation: suggestions.length > 0
-                    ? `Best match: ${suggestions[0].component} (${suggestions[0].confidence} confidence) - ${suggestions[0].description}`
-                    : 'No matching components found. Try different keywords or browse with fragments_discover.',
+                  noMatch,
+                  weakMatch,
+                  recommendation,
                   compositionHint,
-                  nextStep: suggestions.length > 0
-                    ? `Use fragments_inspect("${suggestions[0].component}") for full details.`
-                    : undefined,
+                  nextStep,
                 }, null, 2),
               }],
             };
@@ -1031,53 +1100,60 @@ export function createMcpServer(config: McpServerConfig): Server {
         }
 
         // ================================================================
-        // RECIPE — unchanged
+        // BLOCKS — composition patterns
         // ================================================================
-        case TOOL_NAMES.recipe: {
+        case TOOL_NAMES.blocks: {
           const data = await loadSegments();
-          const recipeName = args?.name as string | undefined;
+          const blockName = args?.name as string | undefined;
           const search = (args?.search as string)?.toLowerCase() ?? undefined;
           const component = (args?.component as string)?.toLowerCase() ?? undefined;
+          const category = (args?.category as string)?.toLowerCase() ?? undefined;
 
-          const allRecipes = Object.values(data.recipes ?? {});
+          const allBlocks = Object.values(data.blocks ?? data.recipes ?? {});
 
-          if (allRecipes.length === 0) {
+          if (allBlocks.length === 0) {
             return {
               content: [{
                 type: 'text' as const,
                 text: JSON.stringify({
                   total: 0,
-                  recipes: [],
-                  hint: `No recipes found. Run \`${BRAND.cliCommand} build\` after adding .recipe.ts files.`,
+                  blocks: [],
+                  hint: `No blocks found. Run \`${BRAND.cliCommand} build\` after adding .block.ts files.`,
                 }, null, 2),
               }],
             };
           }
 
-          let filtered = allRecipes;
+          let filtered = allBlocks;
 
-          if (recipeName) {
+          if (blockName) {
             filtered = filtered.filter(
-              r => r.name.toLowerCase() === recipeName.toLowerCase()
+              b => b.name.toLowerCase() === blockName.toLowerCase()
             );
           }
 
           if (search) {
-            filtered = filtered.filter(r => {
+            filtered = filtered.filter(b => {
               const haystack = [
-                r.name,
-                r.description,
-                ...(r.tags ?? []),
-                ...r.components,
-                r.category,
+                b.name,
+                b.description,
+                ...(b.tags ?? []),
+                ...b.components,
+                b.category,
               ].join(' ').toLowerCase();
               return haystack.includes(search);
             });
           }
 
           if (component) {
-            filtered = filtered.filter(r =>
-              r.components.some(c => c.toLowerCase() === component)
+            filtered = filtered.filter(b =>
+              b.components.some(c => c.toLowerCase() === component)
+            );
+          }
+
+          if (category) {
+            filtered = filtered.filter(b =>
+              b.category.toLowerCase() === category
             );
           }
 
@@ -1086,7 +1162,213 @@ export function createMcpServer(config: McpServerConfig): Server {
               type: 'text' as const,
               text: JSON.stringify({
                 total: filtered.length,
-                recipes: filtered,
+                blocks: filtered,
+              }, null, 2),
+            }],
+          };
+        }
+
+        // ================================================================
+        // TOKENS — list CSS custom properties by category
+        // ================================================================
+        case TOOL_NAMES.tokens: {
+          const data = await loadSegments();
+          const category = (args?.category as string)?.toLowerCase() ?? undefined;
+          const search = (args?.search as string)?.toLowerCase() ?? undefined;
+
+          const tokenData = data.tokens;
+
+          if (!tokenData || tokenData.total === 0) {
+            return {
+              content: [{
+                type: 'text' as const,
+                text: JSON.stringify({
+                  total: 0,
+                  categories: {},
+                  hint: `No design tokens found. Add a tokens.include pattern to your ${BRAND.configFile} and run \`${BRAND.cliCommand} build\`.`,
+                }, null, 2),
+              }],
+            };
+          }
+
+          // Filter by category and/or search
+          let filteredCategories: Record<string, Array<{ name: string; description?: string }>> = {};
+          let filteredTotal = 0;
+
+          for (const [cat, tokens] of Object.entries(tokenData.categories)) {
+            // Filter by category
+            if (category && cat !== category) continue;
+
+            // Filter by search term within this category
+            let filtered = tokens;
+            if (search) {
+              filtered = tokens.filter(
+                (t) => t.name.toLowerCase().includes(search) ||
+                       (t.description && t.description.toLowerCase().includes(search))
+              );
+            }
+
+            if (filtered.length > 0) {
+              filteredCategories[cat] = filtered;
+              filteredTotal += filtered.length;
+            }
+          }
+
+          // Build usage hint based on context
+          let hint: string | undefined;
+          if (filteredTotal === 0) {
+            const availableCategories = Object.keys(tokenData.categories);
+            hint = search
+              ? `No tokens matching "${search}". Try: ${availableCategories.join(', ')}`
+              : category
+                ? `Category "${category}" not found. Available: ${availableCategories.join(', ')}`
+                : undefined;
+          } else if (!category && !search) {
+            hint = `Use var(--token-name) in your CSS/styles. Filter by category or search to narrow results.`;
+          }
+
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify({
+                prefix: tokenData.prefix,
+                total: filteredTotal,
+                totalAvailable: tokenData.total,
+                categories: filteredCategories,
+                ...(hint && { hint }),
+                ...((!category && !search) && {
+                  availableCategories: Object.entries(tokenData.categories).map(
+                    ([cat, tokens]) => ({ category: cat, count: tokens.length })
+                  ),
+                }),
+              }, null, 2),
+            }],
+          };
+        }
+
+        // ================================================================
+        // IMPLEMENT — one-shot discover + inspect + blocks + tokens
+        // ================================================================
+        case TOOL_NAMES.implement: {
+          const data = await loadSegments();
+          const useCase = args?.useCase as string;
+          if (!useCase) {
+            throw new Error('useCase is required');
+          }
+
+          const useCaseLower = useCase.toLowerCase();
+          const searchTerms = useCaseLower.split(/\s+/).filter(Boolean);
+
+          // 1. Score all segments (same logic as discover suggest)
+          const synonymMap: Record<string, string[]> = {
+            'form': ['input', 'field', 'submit', 'validation'],
+            'input': ['form', 'field', 'text', 'entry'],
+            'button': ['action', 'click', 'submit', 'trigger'],
+            'alert': ['notification', 'message', 'warning', 'error', 'feedback'],
+            'notification': ['alert', 'message', 'toast'],
+            'card': ['container', 'panel', 'box', 'content'],
+            'toggle': ['switch', 'checkbox', 'boolean'],
+            'badge': ['tag', 'label', 'status', 'indicator'],
+            'login': ['auth', 'signin', 'authentication', 'form'],
+            'chat': ['message', 'conversation', 'ai'],
+            'table': ['data', 'grid', 'list', 'rows'],
+          };
+
+          const expandedTerms = new Set(searchTerms);
+          searchTerms.forEach((term) => {
+            const synonyms = synonymMap[term];
+            if (synonyms) synonyms.forEach((syn) => expandedTerms.add(syn));
+          });
+
+          const scored = Object.values(data.segments).map((s) => {
+            let score = 0;
+            const nameLower = s.meta.name.toLowerCase();
+            if (searchTerms.some((t) => nameLower.includes(t))) score += 15;
+            else if (Array.from(expandedTerms).some((t) => nameLower.includes(t))) score += 8;
+            const desc = s.meta.description?.toLowerCase() ?? '';
+            score += searchTerms.filter((t) => desc.includes(t)).length * 6;
+            const tags = s.meta.tags?.map((t) => t.toLowerCase()) ?? [];
+            score += searchTerms.filter((t) => tags.some((tag) => tag.includes(t))).length * 4;
+            const whenUsed = s.usage?.when?.join(' ').toLowerCase() ?? '';
+            score += searchTerms.filter((t) => whenUsed.includes(t)).length * 10;
+            score += Array.from(expandedTerms).filter((t) => !searchTerms.includes(t) && whenUsed.includes(t)).length * 5;
+            if (s.meta.category && searchTerms.some((t) => s.meta.category!.toLowerCase().includes(t))) score += 8;
+            if (s.meta.status === 'stable') score += 5;
+            if (s.meta.status === 'deprecated') score -= 25;
+            return { segment: s, score };
+          });
+
+          const topMatches = scored
+            .filter((s) => s.score >= 8)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, 3);
+
+          // 2. Build component details for top matches
+          const components = await Promise.all(
+            topMatches.map(async ({ segment: s, score }) => {
+              const pkgName = await getPackageName(s.meta.name);
+              const examples = s.variants.slice(0, 2).map((v) => ({
+                variant: v.name,
+                code: v.code ?? `<${s.meta.name} />`,
+              }));
+              const propsSummary = Object.entries(s.props ?? {}).slice(0, 10).map(
+                ([name, p]) => `${name}${p.required ? ' (required)' : ''}: ${p.type}${p.values ? ` = ${p.values.join('|')}` : ''}`
+              );
+              return {
+                name: s.meta.name,
+                category: s.meta.category,
+                description: s.meta.description,
+                confidence: score >= 25 ? 'high' : score >= 15 ? 'medium' : 'low',
+                import: `import { ${s.meta.name} } from '${pkgName}';`,
+                props: propsSummary,
+                examples,
+                guidelines: filterPlaceholders(s.usage?.when).slice(0, 3),
+                accessibility: s.usage?.accessibility?.slice(0, 2) ?? [],
+              };
+            })
+          );
+
+          // 3. Find relevant blocks
+          const allBlocks = Object.values(data.blocks ?? data.recipes ?? {});
+          const matchingBlocks = allBlocks
+            .filter((b) => {
+              const haystack = [b.name, b.description, ...(b.tags ?? []), ...b.components, b.category].join(' ').toLowerCase();
+              return searchTerms.some((t) => haystack.includes(t)) ||
+                     topMatches.some(({ segment }) => b.components.some((c) => c.toLowerCase() === segment.meta.name.toLowerCase()));
+            })
+            .slice(0, 2)
+            .map((b) => ({ name: b.name, description: b.description, components: b.components, code: b.code }));
+
+          // 4. Find relevant tokens
+          const tokenData = data.tokens;
+          let relevantTokens: Record<string, string[]> | undefined;
+          if (tokenData) {
+            const STYLE_KEYWORDS = ['color', 'spacing', 'padding', 'margin', 'font', 'border', 'radius', 'shadow', 'background', 'hover', 'theme'];
+            const styleTerms = searchTerms.filter((t) => STYLE_KEYWORDS.includes(t));
+            if (styleTerms.length > 0) {
+              relevantTokens = {};
+              for (const [cat, tokens] of Object.entries(tokenData.categories)) {
+                const matching = tokens.filter((t) => styleTerms.some((st) => t.name.includes(st) || cat.includes(st)));
+                if (matching.length > 0) {
+                  relevantTokens[cat] = matching.map((t) => t.name);
+                }
+              }
+              if (Object.keys(relevantTokens).length === 0) relevantTokens = undefined;
+            }
+          }
+
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify({
+                useCase,
+                components,
+                blocks: matchingBlocks.length > 0 ? matchingBlocks : undefined,
+                tokens: relevantTokens,
+                noMatch: components.length === 0,
+                summary: components.length > 0
+                  ? `Found ${components.length} component(s) for "${useCase}". ${matchingBlocks.length > 0 ? `Plus ${matchingBlocks.length} ready-to-use block(s).` : ''}`
+                  : `No components match "${useCase}". Try ${TOOL_NAMES.discover} with different terms${tokenData ? ` or ${TOOL_NAMES.tokens} for CSS variables` : ''}.`,
               }, null, 2),
             }],
           };