sonance-brand-mcp 1.3.116 → 1.3.118

package/dist/index.js

@@ -8,6 +8,7 @@ import * as os from "os";
 import { fileURLToPath } from "url";
 import { execSync } from "child_process";
 import sharp from "sharp";
+import { formatCodeBlock, } from "./utils/response-formatter.js";
 // ============================================
 // INSTALLER (--init flag)
 // ============================================
@@ -2634,6 +2635,25 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ["logo_path"],
                 },
             },
+            {
+                name: "get_logo_base64",
+                description: "Returns a logo as base64-encoded data URL ready for embedding in React artifacts, HTML, or web applications. USE THIS for artifacts instead of drawing/approximating logos. Returns a data URL that works directly in <img src='...'> tags. CRITICAL: NEVER draw, recreate, or approximate logos with SVG, CSS, or styled text - always use this tool to get the actual image data.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        logo_path: {
+                            type: "string",
+                            description: "Path to the logo from list_logos output (e.g., 'sonance/Sonance_Logo_2C_Dark_RGB.png')",
+                        },
+                        format: {
+                            type: "string",
+                            enum: ["dataUrl", "base64", "both"],
+                            description: "Output format. 'dataUrl' for img src (default), 'base64' for raw data, 'both' for both formats",
+                        },
+                    },
+                    required: ["logo_path"],
+                },
+            },
             {
                 name: "diagnose_logos",
                 description: "Diagnose logo loading issues. Returns validation status, path resolution examples, and environment info. Use this when logos fail to embed or appear in responses.",
@@ -2915,7 +2935,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             try {
                 const content = fs.readFileSync(getAssetPath("css"), "utf-8");
                 return {
-                    content: [{ type: "text", text: `/* Sonance Brand Theme - globals.css */\n\n${content}` }],
+                    content: [{
+                            type: "text",
+                            text: `# Sonance Brand Theme
+
+${formatCodeBlock(content, { language: "css", filename: "globals.css" })}`
+                        }],
                 };
             }
             catch (e) {
@@ -2964,10 +2989,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     const match = files.find(f => f.toLowerCase() === `${componentName}.tsx`);
                     if (match) {
                         const content = fs.readFileSync(path.join(componentsDir, match), "utf-8");
+                        const matchedName = match.replace('.tsx', '');
                         return {
                             content: [{
                                     type: "text",
-                                    text: `// File: components/ui/${match}\n\n${content}`
+                                    text: `# ${matchedName} Component
+
+${formatCodeBlock(content, { language: "tsx", filename: `components/ui/${match}` })}`
                                 }],
                         };
                     }
@@ -2980,7 +3008,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return {
                     content: [{
                             type: "text",
-                            text: `// File: components/ui/${componentName}.tsx\n\n${content}`
+                            text: `# ${componentName} Component
+
+${formatCodeBlock(content, { language: "tsx", filename: `components/ui/${componentName}.tsx` })}`
                         }],
                 };
             }
@@ -2997,7 +3027,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return {
                     content: [{
                             type: "text",
-                            text: `// File: lib/utils.ts\n// These utilities are used by Sonance UI components\n\n${content}`
+                            text: `# Sonance UI Utilities
+
+These utilities are used by Sonance UI components.
+
+${formatCodeBlock(content, { language: "typescript", filename: "lib/utils.ts" })}`
                         }],
                 };
             }
@@ -3094,6 +3128,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const base64Data = imageBuffer.toString('base64');
                 const mimeType = getImageMimeType(resolvedPath);
                 const fileName = path.basename(resolvedPath);
+                // Create data URL for artifact use
+                const dataUrl = `data:${mimeType};base64,${base64Data}`;
                 // Determine logo variant info for recommendations
                 const isLightLogo = /light|reverse|white/i.test(fileName);
                 const isDarkLogo = /dark|black/i.test(fileName);
@@ -3124,28 +3160,45 @@ ${variantSuggestion}
 
 ---
 
-### Implementation (Next.js with next/image)
+## CRITICAL: Logo Usage Rules
+
+> **NEVER draw, recreate, or approximate this logo.** This includes:
+> - SVG drawings or paths
+> - Styled text (e.g., colored letters spelling "SONANCE")
+> - CSS recreations or shapes
+> - Unicode character approximations
+>
+> **ALWAYS use the actual image data provided below.**
+
+---
+
+### For React Artifacts (USE THIS - includes actual image data)
+\`\`\`tsx
+<img
+  src="${dataUrl}"
+  alt="${brandName}"
+  className="h-10 w-auto"
+/>
+\`\`\`
+
+### For Next.js Projects (with file system access)
 \`\`\`tsx
 import Image from 'next/image';
 
-// In your component:
 <Image
   src="${normalizedPath}"
   alt="${brandName}"
   width={150}
   height={40}
   className="h-10 w-auto"
-  priority // Add if logo is above the fold
+  priority
 />
 \`\`\`
 
-### Implementation (React/HTML)
-\`\`\`tsx
-<img
-  src="${normalizedPath}"
-  alt="${brandName}"
-  className="h-10 w-auto"
-/>
+### Base64 Data URL (copy for artifacts)
+Use this data URL directly in img src for artifacts:
+\`\`\`
+${dataUrl}
 \`\`\`
 
 ### With Dark Mode Support
@@ -3154,12 +3207,12 @@ import Image from 'next/image';
 <img
   src="${normalizedPath}"
   alt="${brandName}"
-  className="h-10 w-auto dark:hidden"  {/* Light mode */}
+  className="h-10 w-auto dark:hidden"
 />
 <img
   src="${normalizedPath.replace(/dark/gi, 'Light').replace(/black/gi, 'Reverse')}"
   alt="${brandName}"
-  className="h-10 w-auto hidden dark:block"  {/* Dark mode */}
+  className="h-10 w-auto hidden dark:block"
 />
 \`\`\`
 
@@ -3196,6 +3249,98 @@ import Image from 'next/image';
                 };
             }
         }
+        case "get_logo_base64": {
+            const logoArgs = args;
+            const logoPath = logoArgs.logo_path;
+            const format = logoArgs.format || "dataUrl";
+            if (!logoPath) {
+                return {
+                    content: [{ type: "text", text: "Error: logo_path is required. Use list_logos to see available logos." }],
+                    isError: true,
+                };
+            }
+            try {
+                const resolvedPath = resolveLogoPath(logoPath);
+                if (!resolvedPath) {
+                    return {
+                        content: [{ type: "text", text: `Error: Invalid logo path: ${logoPath}` }],
+                        isError: true,
+                    };
+                }
+                if (!fs.existsSync(resolvedPath)) {
+                    return {
+                        content: [{ type: "text", text: `Error: Logo not found: ${logoPath}. Use list_logos to see available logos.` }],
+                        isError: true,
+                    };
+                }
+                // Read and encode the image
+                const imageBuffer = fs.readFileSync(resolvedPath);
+                const base64Data = imageBuffer.toString('base64');
+                const mimeType = getImageMimeType(resolvedPath);
+                const fileName = path.basename(resolvedPath);
+                const dataUrl = `data:${mimeType};base64,${base64Data}`;
+                // Determine brand for alt text
+                const brandMatch = logoPath.match(/\/(sonance|iport|blaze|james|trufig)/i);
+                const brandName = brandMatch ? brandMatch[1].charAt(0).toUpperCase() + brandMatch[1].slice(1) : "Brand";
+                // Build response based on format
+                let responseText = `## Logo for Artifacts: ${fileName}
+
+> **CRITICAL:** Use ONLY this image data. NEVER draw, recreate, or approximate this logo with SVG, CSS, styled text, or any other method.
+
+### Ready-to-Use Code (copy this directly)
+\`\`\`tsx
+<img
+  src="${dataUrl}"
+  alt="${brandName}"
+  className="h-10 w-auto"
+/>
+\`\`\`
+`;
+                if (format === "dataUrl" || format === "both") {
+                    responseText += `
+### Data URL (use in img src)
+\`\`\`
+${dataUrl}
+\`\`\`
+`;
+                }
+                if (format === "base64" || format === "both") {
+                    responseText += `
+### Raw Base64 Data
+\`\`\`
+${base64Data}
+\`\`\`
+
+**MIME Type:** ${mimeType}
+`;
+                }
+                responseText += `
+---
+
+**File:** ${fileName}
+**Size:** ${imageBuffer.length} bytes
+`;
+                return {
+                    content: [
+                        {
+                            type: "image",
+                            data: base64Data,
+                            mimeType: mimeType,
+                        },
+                        {
+                            type: "text",
+                            text: responseText,
+                        },
+                    ],
+                };
+            }
+            catch (e) {
+                return {
+                    content: [{ type: "text", text: `Error reading logo: ${e}` }],
+                    isError: true,
+                };
+            }
+        }
         case "diagnose_logos": {
             // Run validation and collect diagnostic info
             const validation = validateLogoMap();
@@ -3280,36 +3425,73 @@ ${!validation.valid ? `
         }
         case "get_full_library": {
             try {
-                let fullLibrary = "# Sonance Component Library\n\n";
-                fullLibrary += "This is the complete Sonance UI component library. Copy these files into your project.\n\n";
-                // Add brand guidelines
-                fullLibrary += "---\n\n## 1. Brand Guidelines\n\n";
+                // Build structured response with multiple content blocks for artifact rendering
+                const contentBlocks = [];
+                // Validate and embed logos first
+                validateLogoMap();
+                const lightLogoPath = LOGO_MAP.default.light;
+                const darkLogoPath = LOGO_MAP.default.dark;
+                await embedLogoWithFeedback(lightLogoPath, "Brand Logo (for Light Backgrounds)", contentBlocks);
+                await embedLogoWithFeedback(darkLogoPath, "Brand Logo (for Dark Backgrounds)", contentBlocks);
+                // Section 1: Overview
+                contentBlocks.push({
+                    type: "text",
+                    text: `# Sonance Component Library
+
+This is the complete Sonance UI component library. Copy these files into your project.
+
+## Table of Contents
+1. [Brand Guidelines](#brand-guidelines)
+2. [CSS Theme](#css-theme)
+3. [Utilities](#utilities)
+4. [UI Components](#ui-components)
+5. [Brand Logos](#brand-logos)`
+                });
+                // Section 2: Brand Guidelines
+                let guidelines = "*Brand guidelines not found*";
                 try {
-                    fullLibrary += fs.readFileSync(getAssetPath("guidelines"), "utf-8");
+                    guidelines = fs.readFileSync(getAssetPath("guidelines"), "utf-8");
                 }
                 catch (e) {
-                    fullLibrary += "*Brand guidelines not found*\n";
+                    // Use fallback
                 }
-                // Add CSS theme
-                fullLibrary += "\n\n---\n\n## 2. CSS Theme (globals.css)\n\n```css\n";
+                contentBlocks.push({
+                    type: "text",
+                    text: `## 1. Brand Guidelines\n\n${guidelines}`
+                });
+                // Section 3: CSS Theme (with filename hint)
+                let cssTheme = "/* CSS theme not found */";
                 try {
-                    fullLibrary += fs.readFileSync(getAssetPath("css"), "utf-8");
+                    cssTheme = fs.readFileSync(getAssetPath("css"), "utf-8");
                 }
                 catch (e) {
-                    fullLibrary += "/* CSS theme not found */";
+                    // Use fallback
                 }
-                fullLibrary += "\n```\n";
-                // Add utilities
-                fullLibrary += "\n\n---\n\n## 3. Utilities (lib/utils.ts)\n\n```typescript\n";
+                contentBlocks.push({
+                    type: "text",
+                    text: `## 2. CSS Theme
+
+${formatCodeBlock(cssTheme, { language: "css", filename: "globals.css" })}`
+                });
+                // Section 4: Utilities (with filename hint)
+                let utils = "// Utils not found";
                 try {
-                    fullLibrary += fs.readFileSync(getAssetPath("utils"), "utf-8");
+                    utils = fs.readFileSync(getAssetPath("utils"), "utf-8");
                 }
                 catch (e) {
-                    fullLibrary += "// Utils not found";
+                    // Use fallback
                 }
-                fullLibrary += "\n```\n";
-                // Add components
-                fullLibrary += "\n\n---\n\n## 4. UI Components\n\n";
+                contentBlocks.push({
+                    type: "text",
+                    text: `## 3. Utilities
+
+${formatCodeBlock(utils, { language: "typescript", filename: "lib/utils.ts" })}`
+                });
+                // Section 5: Components - each as a separate block
+                contentBlocks.push({
+                    type: "text",
+                    text: `## 4. UI Components`
+                });
                 try {
                     const componentsDir = getAssetPath("components");
                     const files = fs.readdirSync(componentsDir)
@@ -3318,24 +3500,35 @@ ${!validation.valid ? `
                     for (const file of files) {
                         const componentName = file.replace('.tsx', '');
                         const content = fs.readFileSync(path.join(componentsDir, file), "utf-8");
-                        fullLibrary += `### ${componentName}\n\nFile: \`components/ui/${file}\`\n\n\`\`\`tsx\n${content}\n\`\`\`\n\n`;
+                        contentBlocks.push({
+                            type: "text",
+                            text: `### ${componentName}
+
+${formatCodeBlock(content, { language: "tsx", filename: `components/ui/${file}` })}`
+                        });
                     }
                 }
                 catch (e) {
-                    fullLibrary += "*Components directory not found*\n";
+                    contentBlocks.push({
+                        type: "text",
+                        text: "*Components directory not found*"
+                    });
                 }
-                // Add logo section with implementation guidance
-                fullLibrary += "\n\n---\n\n## 5. Brand Logos\n\n";
-                fullLibrary += "Use these logos in your application. The Sonance+James+IPORT lockup is the default.\n\n";
-                fullLibrary += `### Logo Paths
+                // Section 6: Logo guidance
+                contentBlocks.push({
+                    type: "text",
+                    text: `## 5. Brand Logos
+
+Use these logos in your application. The Sonance+James+IPORT lockup is the default.
+
+### Logo Paths
 | Variant | Path | Use On |
 |---------|------|--------|
 | **Light Backgrounds** | \`/logos/sonance-james-iport/Sonance_James_IPORT_Lockup_Dark.png\` | White, light gray backgrounds |
 | **Dark Backgrounds** | \`/logos/sonance-james-iport/Sonance_James_IPORT_Lockup_Light.png\` | Charcoal, dark backgrounds |
 
 ### Implementation (Next.js)
-\`\`\`tsx
-import Image from 'next/image';
+${formatCodeBlock(`import Image from 'next/image';
 
 // Light mode logo (for light backgrounds)
 <Image
@@ -3355,8 +3548,7 @@ import Image from 'next/image';
   height={40}
   className="h-10 w-auto hidden dark:block"
   priority
-/>
-\`\`\`
+/>`, { language: "tsx", filename: "components/Logo.tsx" })}
 
 ### Sizing Guidelines
 - Header/Navbar: \`h-8\` to \`h-10\` (32-40px)
@@ -3364,18 +3556,8 @@ import Image from 'next/image';
 - Footer: \`h-6\` to \`h-8\` (24-32px)
 
 ### Other Brand Logos
-Use \`list_logos\` to see all available logos, or \`get_logo\` to retrieve a specific logo with implementation code.
-`;
-                // Build content blocks with embedded logos
-                const contentBlocks = [];
-                // Validate and embed logos
-                validateLogoMap();
-                const lightLogoPath = LOGO_MAP.default.light;
-                const darkLogoPath = LOGO_MAP.default.dark;
-                await embedLogoWithFeedback(lightLogoPath, "Brand Logo (for Light Backgrounds)", contentBlocks);
-                await embedLogoWithFeedback(darkLogoPath, "Brand Logo (for Dark Backgrounds)", contentBlocks);
-                // Add the full library text
-                contentBlocks.push({ type: "text", text: fullLibrary });
+Use \`list_logos\` to see all available logos, or \`get_logo\` to retrieve a specific logo with implementation code.`
+                });
                 return {
                     content: contentBlocks,
                 };
@@ -3942,6 +4124,28 @@ Now design the **${component_description}** following these tokens and principle
                 // Single-theme mode: embed the appropriate logo
                 await embedLogoWithFeedback(logoPath, `Brand Logo (${theme === "light" ? "for Light Backgrounds" : "for Dark Backgrounds"})`, contentBlocks);
             }
+            // Add critical logo usage warning
+            contentBlocks.push({
+                type: "text",
+                text: `## Logo Usage Warning
+
+> **CRITICAL:** The logo image(s) shown above are the ONLY acceptable representations.
+>
+> **NEVER:**
+> - Draw the logo with SVG paths or shapes
+> - Recreate it with styled text or colored letters
+> - Approximate it with CSS or Unicode characters
+>
+> **ALWAYS:**
+> - Use the embedded image directly in your artifact
+> - Or use \`get_logo_base64\` for a ready-to-use data URL
+> - If you cannot embed the image, use placeholder text: "[Logo: ${brand.charAt(0).toUpperCase() + brand.slice(1)}]"
+
+To get the logo as a base64 data URL for artifacts, use:
+\`\`\`
+get_logo_base64({ logo_path: "${logoPath}" })
+\`\`\``,
+            });
             // Add the main response text
             contentBlocks.push({ type: "text", text: response });
             return {
@@ -4979,6 +5183,23 @@ ${palette.preferredTheme === "dark" ? `- **Note**: ${palette.name} prefers dark
                 type: "text",
                 text: `## Logo Usage\n\nTo add the logo to your document:\n1. Save the appropriate logo image above (right-click → Save as)\n2. Use the saved path in your code:\n\n**Word (python-docx):**\n\`\`\`python\ndoc.add_picture('logo_dark.png', width=Inches(2))  # For light backgrounds\n\`\`\`\n\n**PDF (ReportLab):**\n\`\`\`python\ncontent.append(Image('logo_dark.png', width=2*inch, height=0.5*inch))\n\`\`\`\n`,
             });
+            // Add critical logo usage warning
+            templateContentBlocks.push({
+                type: "text",
+                text: `## Logo Warning
+
+> **CRITICAL:** Use ONLY the actual logo image files shown above.
+>
+> **NEVER:**
+> - Draw the logo with shapes or vector tools in your document
+> - Recreate it with styled text or colored letters
+> - Use any visual approximation or placeholder
+>
+> **ALWAYS:**
+> - Save and embed the actual PNG image file
+> - Use the code snippets above that reference the saved image file
+> - The logo images are embedded above - save them directly`,
+            });
             // Add the main template text
             templateContentBlocks.push({ type: "text", text: template });
             return {
@@ -5270,6 +5491,23 @@ ${rebrandArgs.source_format === "word" ? `
                     text: `> **Logo Note:** Brand logos could not be embedded automatically. Download the appropriate ${palette.name} logo from your brand assets folder or use the \`get_logo\` tool.`,
                 });
             }
+            // Add critical logo usage warning
+            rebrandContentBlocks.push({
+                type: "text",
+                text: `## Logo Usage Warning
+
+> **CRITICAL:** When adding the logo to your document, use the ACTUAL image files shown above.
+>
+> **NEVER:**
+> - Draw the logo with shapes or vector tools
+> - Recreate it with styled text or colored letters
+> - Use any visual approximation
+>
+> **ALWAYS:**
+> - Download and embed the actual logo image
+> - Or use \`get_logo_base64\` for a data URL for web/HTML
+> - For Word/PDF: Save the image above and use it directly`,
+            });
             // Add the main guide text
             rebrandContentBlocks.push({ type: "text", text: rebrandGuide });
             return {
@@ -5380,7 +5618,26 @@ npm install @radix-ui/react-slot @radix-ui/react-dialog
 
 4. Copy the CSS and component files as described below
 `;
-            const response = `# ${palette.name} App Starter Kit
+            // Build structured response with multiple content blocks for artifact rendering
+            const contentBlocks = [];
+            // Validate logo map on first use
+            validateLogoMap();
+            // Map brand to centralized LOGO_MAP (sonance uses default lockup)
+            const brandLogoKey = brand === "sonance" ? "default" : brand;
+            const lightLogoPath = LOGO_MAP[brandLogoKey]?.light || LOGO_MAP.default.light;
+            const darkLogoPath = LOGO_MAP[brandLogoKey]?.dark || LOGO_MAP.default.dark;
+            const lightEmbedded = await embedLogoWithFeedback(lightLogoPath, "Logo for Light Backgrounds", contentBlocks);
+            const darkEmbedded = await embedLogoWithFeedback(darkLogoPath, "Logo for Dark Backgrounds", contentBlocks);
+            if (!lightEmbedded && !darkEmbedded) {
+                contentBlocks.push({
+                    type: "text",
+                    text: `> **Logo Note:** Brand logos could not be embedded. Use \`list_logos\` and \`get_logo\` to retrieve logo assets manually.`,
+                });
+            }
+            // Section 1: Overview and Setup Instructions
+            contentBlocks.push({
+                type: "text",
+                text: `# ${palette.name} App Starter Kit
 
 **App Type:** ${appType}
 **Framework:** ${framework}
@@ -5390,37 +5647,39 @@ npm install @radix-ui/react-slot @radix-ui/react-dialog
 
 ---
 
-${setupInstructions}
-
----
-
-## Global Styles (copy to globals.css)
-
-\`\`\`css
-${cssTheme}
-\`\`\`
-
----
-
-## Utility Functions (copy to lib/utils.ts)
-
-\`\`\`typescript
-${utils}
-\`\`\`
-
----
-
-## Required Components (${componentSources.length} total)
-
-${componentSources.map(c => `### ${c.name}.tsx
+${setupInstructions}`
+            });
+            // Section 2: Global Styles (with filename hint for artifact rendering)
+            contentBlocks.push({
+                type: "text",
+                text: `## Global Styles
 
-\`\`\`tsx
-${c.source}
-\`\`\``).join("\n\n")}
+${formatCodeBlock(cssTheme, { language: "css", filename: "globals.css" })}`
+            });
+            // Section 3: Utility Functions (with filename hint)
+            contentBlocks.push({
+                type: "text",
+                text: `## Utility Functions
 
----
+${formatCodeBlock(utils, { language: "typescript", filename: "lib/utils.ts" })}`
+            });
+            // Section 4: Each component as a separate content block
+            contentBlocks.push({
+                type: "text",
+                text: `## Required Components (${componentSources.length} total)`
+            });
+            for (const comp of componentSources) {
+                contentBlocks.push({
+                    type: "text",
+                    text: `### ${comp.name}.tsx
 
-## Page Template: ${appType}
+${formatCodeBlock(comp.source, { language: "tsx", filename: `components/ui/${comp.name}.tsx` })}`
+                });
+            }
+            // Section 5: Page Template
+            contentBlocks.push({
+                type: "text",
+                text: `## Page Template: ${appType}
 
 ${layout.description}
 
@@ -5430,13 +5689,12 @@ ${layout.structure}
 - Grid: \`${layout.gridLayout}\`
 - Spacing: \`${layout.spacing}\`
 
-\`\`\`tsx
-${layout.template}
-\`\`\`
-
----
-
-## Quick Reference
+${formatCodeBlock(layout.template, { language: "tsx", filename: "app/page.tsx" })}`
+            });
+            // Section 6: Quick Reference
+            contentBlocks.push({
+                type: "text",
+                text: `## Quick Reference
 
 ### ${palette.name} Brand Colors
 - **Primary:** ${palette.primary} (bg-primary, text-primary)
@@ -5461,25 +5719,8 @@ ${layout.template}
 
 ---
 
-Now you have everything needed to build a ${palette.name}-branded ${appType} application!
-`;
-            // Embed logos using centralized LOGO_MAP with proper error feedback
-            const contentBlocks = [];
-            // Validate logo map on first use
-            validateLogoMap();
-            // Map brand to centralized LOGO_MAP (sonance uses default lockup)
-            const brandLogoKey = brand === "sonance" ? "default" : brand;
-            const lightLogoPath = LOGO_MAP[brandLogoKey]?.light || LOGO_MAP.default.light;
-            const darkLogoPath = LOGO_MAP[brandLogoKey]?.dark || LOGO_MAP.default.dark;
-            const lightEmbedded = await embedLogoWithFeedback(lightLogoPath, "Logo for Light Backgrounds", contentBlocks);
-            const darkEmbedded = await embedLogoWithFeedback(darkLogoPath, "Logo for Dark Backgrounds", contentBlocks);
-            if (!lightEmbedded && !darkEmbedded) {
-                contentBlocks.push({
-                    type: "text",
-                    text: `> **Logo Note:** Brand logos could not be embedded. Use \`list_logos\` and \`get_logo\` to retrieve logo assets manually.`,
-                });
-            }
-            contentBlocks.push({ type: "text", text: response });
+Now you have everything needed to build a ${palette.name}-branded ${appType} application!`
+            });
             return {
                 content: contentBlocks,
             };
@@ -5957,31 +6198,49 @@ Use \`redesign_app\` tool on individual files for detailed transformation instru
             }
             const components = COMPONENT_CATEGORIES[category];
             const componentsDir = getAssetPath("components");
-            let response = `# ${category.charAt(0).toUpperCase() + category.slice(1)} Components (${components.length} components)\n\n`;
-            response += `Use these components for ${category === "forms" ? "building forms and capturing user input" :
+            // Build structured response with multiple content blocks
+            const contentBlocks = [];
+            const categoryDescription = category === "forms" ? "building forms and capturing user input" :
                 category === "navigation" ? "navigation and menus" :
                     category === "feedback" ? "user feedback and notifications" :
                         category === "overlays" ? "modals, dialogs, and overlays" :
                             category === "data-display" ? "displaying data and content" :
                                 category === "layout" ? "page structure and layouts" :
-                                    "utility purposes"}.\n\n---\n\n`;
+                                    "utility purposes";
+            contentBlocks.push({
+                type: "text",
+                text: `# ${category.charAt(0).toUpperCase() + category.slice(1)} Components (${components.length} components)
+
+Use these components for ${categoryDescription}.`
+            });
             for (const compName of components) {
                 const filePath = path.join(componentsDir, `${compName}.tsx`);
                 if (fs.existsSync(filePath)) {
                     try {
                         const content = fs.readFileSync(filePath, "utf-8");
-                        response += `## ${compName}\n\nFile: \`components/ui/${compName}.tsx\`\n\n\`\`\`tsx\n${content}\n\`\`\`\n\n---\n\n`;
+                        contentBlocks.push({
+                            type: "text",
+                            text: `## ${compName}
+
+${formatCodeBlock(content, { language: "tsx", filename: `components/ui/${compName}.tsx` })}`
+                        });
                     }
                     catch {
-                        response += `## ${compName}\n\n*Could not read component file*\n\n---\n\n`;
+                        contentBlocks.push({
+                            type: "text",
+                            text: `## ${compName}\n\n*Could not read component file*`
+                        });
                     }
                 }
                 else {
-                    response += `## ${compName}\n\n*Component file not found*\n\n---\n\n`;
+                    contentBlocks.push({
+                        type: "text",
+                        text: `## ${compName}\n\n*Component file not found*`
+                    });
                 }
             }
             return {
-                content: [{ type: "text", text: response }],
+                content: contentBlocks,
             };
         }
         default:

package/dist/utils/response-formatter.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Response formatter utilities for artifact-friendly MCP outputs
+ *
+ * These utilities help format code blocks with proper language identifiers
+ * and filename hints that Claude Desktop can render as artifacts.
+ */
+export interface CodeBlockOptions {
+    language: string;
+    filename?: string;
+}
+export interface MultiFileSection {
+    filename: string;
+    content: string;
+    language: string;
+    description?: string;
+}
+/**
+ * Format a code block with proper language identifier and optional filename hint
+ *
+ * @example
+ * formatCodeBlock(cssContent, { language: 'css', filename: 'globals.css' })
+ * // Returns: ```css:globals.css\n{content}\n```
+ */
+export declare function formatCodeBlock(code: string, options: CodeBlockOptions): string;
+/**
+ * Format multiple files as separate code blocks with headers
+ *
+ * @example
+ * formatMultiFile([
+ *   { filename: 'button.tsx', content: '...', language: 'tsx' },
+ *   { filename: 'card.tsx', content: '...', language: 'tsx' }
+ * ])
+ */
+export declare function formatMultiFile(sections: MultiFileSection[]): string;
+/**
+ * Auto-detect the language of code content
+ *
+ * @example
+ * detectLanguage('import React from "react"') // returns 'tsx'
+ * detectLanguage(':root { --color: red; }')   // returns 'css'
+ */
+export declare function detectLanguage(content: string): string;
+/**
+ * Split large content into manageable chunks based on natural boundaries
+ *
+ * @param content - The content to split
+ * @param options - Split options
+ * @returns Array of content chunks
+ */
+export declare function splitContent(content: string, options?: {
+    maxLines?: number;
+    splitOn?: RegExp;
+}): string[];
+/**
+ * Generate a table of contents from markdown content
+ *
+ * @param content - Markdown content with headings
+ * @returns Markdown-formatted table of contents
+ */
+export declare function generateTOC(content: string): string;
+/**
+ * Create a section with header and formatted code block
+ *
+ * @example
+ * createCodeSection('Global Styles', cssContent, { language: 'css', filename: 'globals.css' })
+ */
+export declare function createCodeSection(title: string, code: string, options: CodeBlockOptions): string;
+/**
+ * Get file extension to language mapping
+ */
+export declare function extensionToLanguage(ext: string): string;

package/dist/utils/response-formatter.js

@@ -0,0 +1,152 @@
+/**
+ * Response formatter utilities for artifact-friendly MCP outputs
+ *
+ * These utilities help format code blocks with proper language identifiers
+ * and filename hints that Claude Desktop can render as artifacts.
+ */
+/**
+ * Format a code block with proper language identifier and optional filename hint
+ *
+ * @example
+ * formatCodeBlock(cssContent, { language: 'css', filename: 'globals.css' })
+ * // Returns: ```css:globals.css\n{content}\n```
+ */
+export function formatCodeBlock(code, options) {
+    const { language, filename } = options;
+    const header = filename ? `${language}:${filename}` : language;
+    return `\`\`\`${header}\n${code}\n\`\`\``;
+}
+/**
+ * Format multiple files as separate code blocks with headers
+ *
+ * @example
+ * formatMultiFile([
+ *   { filename: 'button.tsx', content: '...', language: 'tsx' },
+ *   { filename: 'card.tsx', content: '...', language: 'tsx' }
+ * ])
+ */
+export function formatMultiFile(sections) {
+    return sections.map(section => {
+        const header = section.description
+            ? `### ${section.filename}\n\n${section.description}\n\n`
+            : `### ${section.filename}\n\n`;
+        return header + formatCodeBlock(section.content, {
+            language: section.language,
+            filename: section.filename
+        });
+    }).join('\n\n---\n\n');
+}
+/**
+ * Auto-detect the language of code content
+ *
+ * @example
+ * detectLanguage('import React from "react"') // returns 'tsx'
+ * detectLanguage(':root { --color: red; }')   // returns 'css'
+ */
+export function detectLanguage(content) {
+    // React/TSX patterns (check first - most specific)
+    if (/^['"]use client['"]|import.*from\s+['"]react['"]|<[A-Z][a-zA-Z]*[\s/>]/m.test(content)) {
+        return 'tsx';
+    }
+    // CSS patterns
+    if (/^:root\s*\{|@tailwind|@layer|--[a-z-]+:|@import\s+['"]|@media\s*\(/m.test(content)) {
+        return 'css';
+    }
+    // TypeScript patterns (non-React)
+    if (/^interface\s+\w+|^type\s+\w+\s*=|^export\s+type\s+|:\s*(string|number|boolean|void)\s*[;,)]/m.test(content)) {
+        return 'typescript';
+    }
+    // JSON patterns
+    if (/^\s*\{[\s\S]*"[^"]+"\s*:/m.test(content)) {
+        return 'json';
+    }
+    // Python patterns
+    if (/^from\s+\w+\s+import|^import\s+\w+|^def\s+\w+\s*\(|^class\s+\w+(\s*\(|:)/m.test(content)) {
+        return 'python';
+    }
+    // Bash/Shell patterns
+    if (/^#!/m.test(content) || /^\s*(npm|npx|yarn|pnpm|git|cd|mkdir|curl|wget)\s/m.test(content)) {
+        return 'bash';
+    }
+    // HTML patterns
+    if (/^<!DOCTYPE|^<html|^<head|^<body/im.test(content)) {
+        return 'html';
+    }
+    // Markdown patterns
+    if (/^#{1,6}\s+|^\*{1,2}[^*]|^\[.*\]\(.*\)|^>\s+/m.test(content)) {
+        return 'markdown';
+    }
+    return 'text';
+}
+/**
+ * Split large content into manageable chunks based on natural boundaries
+ *
+ * @param content - The content to split
+ * @param options - Split options
+ * @returns Array of content chunks
+ */
+export function splitContent(content, options = {}) {
+    const { maxLines = 200, splitOn = /^(?=#{1,3}\s)/m } = options;
+    const lines = content.split('\n');
+    if (lines.length <= maxLines) {
+        return [content];
+    }
+    // Try to split on natural boundaries (headers)
+    const sections = content.split(splitOn).filter(Boolean);
+    if (sections.length > 1) {
+        return sections;
+    }
+    // Fall back to line-based splitting
+    const chunks = [];
+    for (let i = 0; i < lines.length; i += maxLines) {
+        chunks.push(lines.slice(i, i + maxLines).join('\n'));
+    }
+    return chunks;
+}
+/**
+ * Generate a table of contents from markdown content
+ *
+ * @param content - Markdown content with headings
+ * @returns Markdown-formatted table of contents
+ */
+export function generateTOC(content) {
+    const headings = content.match(/^#{1,3}\s+.+$/gm) || [];
+    return headings.map(heading => {
+        const level = (heading.match(/^#+/) || [''])[0].length;
+        const text = heading.replace(/^#+\s+/, '');
+        const anchor = text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/-+$/, '');
+        const indent = '  '.repeat(level - 1);
+        return `${indent}- [${text}](#${anchor})`;
+    }).join('\n');
+}
+/**
+ * Create a section with header and formatted code block
+ *
+ * @example
+ * createCodeSection('Global Styles', cssContent, { language: 'css', filename: 'globals.css' })
+ */
+export function createCodeSection(title, code, options) {
+    return `## ${title}\n\n${formatCodeBlock(code, options)}`;
+}
+/**
+ * Get file extension to language mapping
+ */
+export function extensionToLanguage(ext) {
+    const map = {
+        '.tsx': 'tsx',
+        '.ts': 'typescript',
+        '.jsx': 'tsx',
+        '.js': 'javascript',
+        '.css': 'css',
+        '.scss': 'scss',
+        '.json': 'json',
+        '.md': 'markdown',
+        '.py': 'python',
+        '.html': 'html',
+        '.sh': 'bash',
+        '.bash': 'bash',
+        '.yaml': 'yaml',
+        '.yml': 'yaml',
+    };
+    return map[ext.toLowerCase()] || 'text';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sonance-brand-mcp",
-  "version": "1.3.116",
+  "version": "1.3.118",
   "description": "MCP Server for Sonance Brand Guidelines and Component Library - gives Claude instant access to brand colors, typography, and UI components.",
   "main": "dist/index.js",
   "type": "module",