@fundamental-styles/mcp 0.41.7-rc.8 → 0.41.7

package/src/data/load-markdown-docs.js

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MarkdownDocCache = void 0;
+exports.getMarkdownCache = getMarkdownCache;
+exports.loadMarkdownDocs = loadMarkdownDocs;
+exports.getMarkdownDoc = getMarkdownDoc;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const markdown_cache_1 = require("./markdown-cache");
+// Re-export for convenience
+var markdown_cache_2 = require("./markdown-cache");
+Object.defineProperty(exports, "MarkdownDocCache", { enumerable: true, get: function () { return markdown_cache_2.MarkdownDocCache; } });
+// Global cache instance with LRU eviction (max 50 components in memory)
+// This reduces memory from ~50MB (all 168 docs) to ~5MB
+let markdownCache = null;
+/**
+ * Get or create the markdown cache instance
+ * @param maxSize Maximum number of docs to keep in cache (default: 50)
+ */
+function getMarkdownCache(maxSize = 50) {
+    if (!markdownCache) {
+        markdownCache = new markdown_cache_1.MarkdownDocCache(maxSize);
+    }
+    return markdownCache;
+}
+/** Resolve path to markdown docs directory — works both from source (dev) and from dist (npm). */
+function resolveMarkdownDocsPath() {
+    // dist path: dist/packages/mcp/data/components/
+    const distPath = (0, path_1.resolve)(__dirname, '..', '..', 'data', 'components');
+    // source path: docs/components/
+    const srcPath = (0, path_1.resolve)(__dirname, '..', '..', '..', '..', 'docs', 'components');
+    try {
+        (0, fs_1.readdirSync)(distPath);
+        return distPath;
+    }
+    catch (_a) {
+        return srcPath;
+    }
+}
+/** Parse frontmatter from markdown content */
+function parseFrontmatter(content) {
+    const frontmatterMatch = content.match(/^---\n([\s\S]+?)\n---\n([\s\S]*)$/);
+    if (!frontmatterMatch) {
+        return { frontmatter: {}, body: content };
+    }
+    const [, frontmatterText, body] = frontmatterMatch;
+    const frontmatter = {};
+    // Simple YAML parser for common types
+    const lines = frontmatterText.split('\n');
+    let currentKey = '';
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        // Array item
+        if (trimmed.startsWith('- ')) {
+            if (currentKey && Array.isArray(frontmatter[currentKey])) {
+                frontmatter[currentKey].push(trimmed.slice(2).trim());
+            }
+            continue;
+        }
+        // Key-value pair
+        const match = trimmed.match(/^([a-zA-Z0-9_-]+):\s*(.*)$/);
+        if (match) {
+            const [, key, value] = match;
+            currentKey = key;
+            // Empty value means array follows
+            if (!value) {
+                frontmatter[key] = [];
+            }
+            else {
+                // Try to parse as number or boolean
+                if (value === 'true') {
+                    frontmatter[key] = true;
+                }
+                else if (value === 'false') {
+                    frontmatter[key] = false;
+                }
+                else if (/^\d+$/.test(value)) {
+                    frontmatter[key] = parseInt(value, 10);
+                }
+                else {
+                    // Remove quotes if present
+                    frontmatter[key] = value.replace(/^["']|["']$/g, '');
+                }
+            }
+        }
+    }
+    return { frontmatter, body };
+}
+/** Extract HTML examples from markdown code blocks */
+function extractExamples(body) {
+    const examples = [];
+    // Find all HTML code blocks with optional preceding heading
+    const htmlBlockRegex = /(?:^|\n)(?:#{2,4}\s+(.+?)\n)?(?:(.+?)\n)?```html\n([\s\S]+?)\n```/g;
+    let match;
+    while ((match = htmlBlockRegex.exec(body)) !== null) {
+        const [, heading, descriptionLine, html] = match;
+        examples.push({
+            title: heading || descriptionLine || 'Example',
+            html: html.trim(),
+            description: heading ? descriptionLine === null || descriptionLine === void 0 ? void 0 : descriptionLine.trim() : undefined
+        });
+    }
+    return examples;
+}
+/**
+ * Load all component markdown documentation files
+ * @deprecated Use getMarkdownCache() for lazy loading instead
+ * This function loads all docs eagerly and can use ~50MB of memory.
+ * The new cache-based approach uses ~5MB.
+ */
+function loadMarkdownDocs() {
+    console.warn('Warning: loadMarkdownDocs() loads all docs eagerly. Consider using getMarkdownCache() for lazy loading.');
+    const docs = new Map();
+    const docsDir = resolveMarkdownDocsPath();
+    try {
+        const files = (0, fs_1.readdirSync)(docsDir).filter((f) => f.endsWith('.md') && f !== 'README.md');
+        for (const file of files) {
+            const filePath = (0, path_1.resolve)(docsDir, file);
+            const content = (0, fs_1.readFileSync)(filePath, 'utf-8');
+            const id = (0, path_1.basename)(file, '.md');
+            const { frontmatter, body } = parseFrontmatter(content);
+            const examples = extractExamples(body);
+            docs.set(id, {
+                id,
+                content,
+                frontmatter: {
+                    component: frontmatter['component'] || id,
+                    title: frontmatter['title'] || id,
+                    selector: frontmatter['selector'] || '',
+                    cssFile: frontmatter['cssFile'] || '',
+                    category: frontmatter['category'],
+                    subcategory: frontmatter['subcategory'],
+                    package: frontmatter['package'],
+                    description: frontmatter['description'],
+                    tags: frontmatter['tags'],
+                    relatedComponents: frontmatter['relatedComponents']
+                },
+                examples
+            });
+        }
+    }
+    catch (error) {
+        console.error('Failed to load markdown docs:', error);
+    }
+    return docs;
+}
+/** Get markdown documentation for a specific component */
+function getMarkdownDoc(componentId) {
+    const docsDir = resolveMarkdownDocsPath();
+    const filePath = (0, path_1.resolve)(docsDir, `${componentId}.md`);
+    try {
+        const content = (0, fs_1.readFileSync)(filePath, 'utf-8');
+        const { frontmatter, body } = parseFrontmatter(content);
+        const examples = extractExamples(body);
+        return {
+            id: componentId,
+            content,
+            frontmatter: {
+                component: frontmatter['component'] || componentId,
+                title: frontmatter['title'] || componentId,
+                selector: frontmatter['selector'] || '',
+                cssFile: frontmatter['cssFile'] || '',
+                category: frontmatter['category'],
+                subcategory: frontmatter['subcategory'],
+                package: frontmatter['package'],
+                description: frontmatter['description'],
+                tags: frontmatter['tags'],
+                relatedComponents: frontmatter['relatedComponents']
+            },
+            examples
+        };
+    }
+    catch (_a) {
+        return null;
+    }
+}
+//# sourceMappingURL=load-markdown-docs.js.map

package/src/data/load-markdown-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-markdown-docs.js","sourceRoot":"","sources":["../../../../../packages/mcp/src/data/load-markdown-docs.ts"],"names":[],"mappings":"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"}

package/src/data/markdown-cache.d.ts

@@ -0,0 +1,60 @@
+import { ComponentMarkdownDoc } from './load-markdown-docs';
+/**
+ * LRU Cache for markdown documentation
+ *
+ * Implements lazy loading with a Least Recently Used (LRU) eviction policy.
+ * This reduces memory usage from ~50MB (all docs) to ~5MB (configurable cache size).
+ */
+export declare class MarkdownDocCache {
+    private cache;
+    private accessOrder;
+    private readonly maxSize;
+    private readonly docsPath;
+    private availableIds;
+    constructor(maxSize?: number);
+    /** Resolve path to markdown docs directory — works both from source (dev) and from dist (npm). */
+    private resolveMarkdownDocsPath;
+    /** Get list of available component IDs (lazy initialization) */
+    private getAvailableIds;
+    /** Load a single markdown document from disk */
+    private loadDoc;
+    /** Parse frontmatter from markdown content */
+    private parseFrontmatter;
+    /** Extract HTML examples from markdown code blocks */
+    private extractExamples;
+    /** Update LRU access order */
+    private updateAccessOrder;
+    /** Evict least recently used item if cache is full */
+    private evictIfNeeded;
+    /**
+     * Get a markdown document by ID (lazy loaded)
+     * @param componentId Component ID (e.g., "button")
+     * @returns ComponentMarkdownDoc or null if not found
+     */
+    get(componentId: string): ComponentMarkdownDoc | null;
+    /**
+     * Get all available component IDs without loading documents
+     * @returns Array of component IDs
+     */
+    keys(): string[];
+    /**
+     * Check if a component exists without loading it
+     * @param componentId Component ID
+     * @returns true if component exists
+     */
+    has(componentId: string): boolean;
+    /**
+     * Get cache statistics
+     * @returns Object with cache metrics
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        hitRate: number;
+        totalComponents: number;
+    };
+    /**
+     * Clear the cache
+     */
+    clear(): void;
+}

package/src/data/markdown-cache.js

@@ -0,0 +1,218 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MarkdownDocCache = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+/**
+ * LRU Cache for markdown documentation
+ *
+ * Implements lazy loading with a Least Recently Used (LRU) eviction policy.
+ * This reduces memory usage from ~50MB (all docs) to ~5MB (configurable cache size).
+ */
+class MarkdownDocCache {
+    constructor(maxSize = 50) {
+        this.cache = new Map();
+        this.accessOrder = [];
+        this.availableIds = null;
+        this.maxSize = maxSize;
+        this.docsPath = this.resolveMarkdownDocsPath();
+    }
+    /** Resolve path to markdown docs directory — works both from source (dev) and from dist (npm). */
+    resolveMarkdownDocsPath() {
+        // dist path: dist/packages/mcp/data/components/
+        const distPath = (0, path_1.resolve)(__dirname, '..', '..', 'data', 'components');
+        // source path: docs/components/
+        const srcPath = (0, path_1.resolve)(__dirname, '..', '..', '..', '..', 'docs', 'components');
+        if ((0, fs_1.existsSync)(distPath)) {
+            return distPath;
+        }
+        return srcPath;
+    }
+    /** Get list of available component IDs (lazy initialization) */
+    getAvailableIds() {
+        if (this.availableIds === null) {
+            this.availableIds = new Set();
+            try {
+                const files = (0, fs_1.readdirSync)(this.docsPath).filter((f) => f.endsWith('.md') && f !== 'README.md');
+                for (const file of files) {
+                    this.availableIds.add((0, path_1.basename)(file, '.md'));
+                }
+            }
+            catch (error) {
+                console.error('Failed to read markdown docs directory:', error);
+            }
+        }
+        return this.availableIds;
+    }
+    /** Load a single markdown document from disk */
+    loadDoc(componentId) {
+        const filePath = (0, path_1.resolve)(this.docsPath, `${componentId}.md`);
+        try {
+            const content = (0, fs_1.readFileSync)(filePath, 'utf-8');
+            const { frontmatter, body } = this.parseFrontmatter(content);
+            const examples = this.extractExamples(body);
+            return {
+                id: componentId,
+                content,
+                frontmatter: {
+                    component: frontmatter['component'] || componentId,
+                    title: frontmatter['title'] || componentId,
+                    selector: frontmatter['selector'] || '',
+                    cssFile: frontmatter['cssFile'] || '',
+                    category: frontmatter['category'],
+                    subcategory: frontmatter['subcategory'],
+                    package: frontmatter['package'],
+                    description: frontmatter['description'],
+                    tags: frontmatter['tags'],
+                    relatedComponents: frontmatter['relatedComponents']
+                },
+                examples
+            };
+        }
+        catch (_a) {
+            return null;
+        }
+    }
+    /** Parse frontmatter from markdown content */
+    parseFrontmatter(content) {
+        const frontmatterMatch = content.match(/^---\n([\s\S]+?)\n---\n([\s\S]*)$/);
+        if (!frontmatterMatch) {
+            return { frontmatter: {}, body: content };
+        }
+        const [, frontmatterText, body] = frontmatterMatch;
+        const frontmatter = {};
+        // Simple YAML parser for common types
+        const lines = frontmatterText.split('\n');
+        let currentKey = '';
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            // Array item
+            if (trimmed.startsWith('- ')) {
+                if (currentKey && Array.isArray(frontmatter[currentKey])) {
+                    frontmatter[currentKey].push(trimmed.slice(2).trim());
+                }
+                continue;
+            }
+            // Key-value pair
+            const match = trimmed.match(/^([a-zA-Z0-9_-]+):\s*(.*)$/);
+            if (match) {
+                const [, key, value] = match;
+                currentKey = key;
+                // Empty value means array follows
+                if (!value) {
+                    frontmatter[key] = [];
+                }
+                else {
+                    // Try to parse as number or boolean
+                    if (value === 'true') {
+                        frontmatter[key] = true;
+                    }
+                    else if (value === 'false') {
+                        frontmatter[key] = false;
+                    }
+                    else if (/^\d+$/.test(value)) {
+                        frontmatter[key] = parseInt(value, 10);
+                    }
+                    else {
+                        // Remove quotes if present
+                        frontmatter[key] = value.replace(/^["']|["']$/g, '');
+                    }
+                }
+            }
+        }
+        return { frontmatter, body };
+    }
+    /** Extract HTML examples from markdown code blocks */
+    extractExamples(body) {
+        const examples = [];
+        // Find all HTML code blocks with optional preceding heading
+        const htmlBlockRegex = /(?:^|\n)(?:#{2,4}\s+(.+?)\n)?(?:(.+?)\n)?```html\n([\s\S]+?)\n```/g;
+        let match;
+        while ((match = htmlBlockRegex.exec(body)) !== null) {
+            const [, heading, descriptionLine, html] = match;
+            examples.push({
+                title: heading || descriptionLine || 'Example',
+                html: html.trim(),
+                description: heading ? descriptionLine === null || descriptionLine === void 0 ? void 0 : descriptionLine.trim() : undefined
+            });
+        }
+        return examples;
+    }
+    /** Update LRU access order */
+    updateAccessOrder(id) {
+        // Remove from current position
+        const index = this.accessOrder.indexOf(id);
+        if (index > -1) {
+            this.accessOrder.splice(index, 1);
+        }
+        // Add to end (most recently used)
+        this.accessOrder.push(id);
+    }
+    /** Evict least recently used item if cache is full */
+    evictIfNeeded() {
+        if (this.cache.size >= this.maxSize && this.accessOrder.length > 0) {
+            const lruId = this.accessOrder.shift();
+            if (lruId) {
+                this.cache.delete(lruId);
+            }
+        }
+    }
+    /**
+     * Get a markdown document by ID (lazy loaded)
+     * @param componentId Component ID (e.g., "button")
+     * @returns ComponentMarkdownDoc or null if not found
+     */
+    get(componentId) {
+        // Check cache first
+        if (this.cache.has(componentId)) {
+            this.updateAccessOrder(componentId);
+            return this.cache.get(componentId);
+        }
+        // Load from disk
+        const doc = this.loadDoc(componentId);
+        if (doc) {
+            this.evictIfNeeded();
+            this.cache.set(componentId, doc);
+            this.updateAccessOrder(componentId);
+        }
+        return doc;
+    }
+    /**
+     * Get all available component IDs without loading documents
+     * @returns Array of component IDs
+     */
+    keys() {
+        return Array.from(this.getAvailableIds());
+    }
+    /**
+     * Check if a component exists without loading it
+     * @param componentId Component ID
+     * @returns true if component exists
+     */
+    has(componentId) {
+        return this.getAvailableIds().has(componentId);
+    }
+    /**
+     * Get cache statistics
+     * @returns Object with cache metrics
+     */
+    getStats() {
+        return {
+            size: this.cache.size,
+            maxSize: this.maxSize,
+            hitRate: this.cache.size > 0 ? (this.accessOrder.length / this.cache.size) : 0,
+            totalComponents: this.getAvailableIds().size
+        };
+    }
+    /**
+     * Clear the cache
+     */
+    clear() {
+        this.cache.clear();
+        this.accessOrder = [];
+    }
+}
+exports.MarkdownDocCache = MarkdownDocCache;
+//# sourceMappingURL=markdown-cache.js.map

package/src/data/markdown-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-cache.js","sourceRoot":"","sources":["../../../../../packages/mcp/src/data/markdown-cache.ts"],"names":[],"mappings":"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"}

package/src/server.js

@@ -9,6 +9,7 @@ const load_examples_1 = require("./data/load-examples");
 const helpers_1 = require("./helpers");
 const changelog_extractor_1 = require("./data/changelog-extractor");
 const component_dependencies_1 = require("./data/component-dependencies");
+const load_markdown_docs_1 = require("./data/load-markdown-docs");
 const component_metadata_1 = require("./types/component-metadata");
 // Load data at startup
 let data;
@@ -29,7 +30,8 @@ catch (_a) {
         htmlExamples: null,
         componentUseCases: null,
         componentGuidance: null,
-        semanticTags: null
+        semanticTags: null,
+        markdownDocs: (0, load_markdown_docs_1.getMarkdownCache)(50)
     };
     console.error('Warning: Failed to load component catalog data.');
 }
@@ -2541,6 +2543,75 @@ Use this when implementing interactive features or adding JavaScript behavior to
     };
 }));
 // ---------------------------------------------------------------------------
+// Tool: get_component_markdown
+// ---------------------------------------------------------------------------
+server.tool('get_component_markdown', `Get complete markdown documentation for a component, including all HTML examples with modifiers.
+This returns the full auto-generated component documentation from Storybook stories.
+Contains complete HTML examples with all variants, modifiers, and states.
+Use this when you need comprehensive examples or want to see all available variations.`, {
+    component: zod_1.z.string().describe('Component ID (e.g., "button", "table", "dialog")'),
+    examplesOnly: zod_1.z.boolean().optional().default(false).describe('Return only HTML examples without frontmatter/description (default: false)')
+}, (_a) => tslib_1.__awaiter(void 0, [_a], void 0, function* ({ component, examplesOnly = false }) {
+    const doc = data.markdownDocs.get(component);
+    if (!doc) {
+        // Try to find similar component names
+        const similar = Array.from(data.markdownDocs.keys())
+            .filter(id => id.includes(component.toLowerCase()) || component.toLowerCase().includes(id))
+            .slice(0, 5);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: `No markdown documentation found for component: ${component}`,
+                        suggestion: similar.length > 0
+                            ? `Did you mean one of these? ${similar.join(', ')}`
+                            : `Try list_components to see all available components.`,
+                        availableComponents: similar.length > 0 ? similar : undefined
+                    }, null, 2)
+                }
+            ]
+        };
+    }
+    if (examplesOnly) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        component: doc.frontmatter.component,
+                        title: doc.frontmatter.title,
+                        totalExamples: doc.examples.length,
+                        examples: doc.examples
+                    }, null, 2)
+                }
+            ]
+        };
+    }
+    // Return full documentation
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    component: doc.frontmatter.component,
+                    title: doc.frontmatter.title,
+                    selector: doc.frontmatter.selector,
+                    cssFile: doc.frontmatter.cssFile,
+                    category: doc.frontmatter.category,
+                    subcategory: doc.frontmatter.subcategory,
+                    description: doc.frontmatter.description,
+                    tags: doc.frontmatter.tags,
+                    relatedComponents: doc.frontmatter.relatedComponents,
+                    totalExamples: doc.examples.length,
+                    examples: doc.examples,
+                    fullMarkdown: doc.content
+                }, null, 2)
+            }
+        ]
+    };
+}));
+// ---------------------------------------------------------------------------
 // Tool: list_mcp_resources
 // ---------------------------------------------------------------------------
 server.tool('list_mcp_resources', `List all available resources in the fundamental-styles MCP.