@maz-ui/mcp 5.0.0-beta.3 → 5.0.0-beta.30

package/README.md

@@ -193,7 +193,7 @@ The server exposes documentation through MCP resources with the following URI pa
 - **`maz-ui://component/{ComponentName}`** - Individual component documentation
   - Examples: `maz-ui://component/MazBtn`, `maz-ui://component/MazInput`
 - **`maz-ui://guide/{guideName}`** - Setup and usage guides
-  - Examples: `maz-ui://guide/getting-started`, `maz-ui://guide/vue`, `maz-ui://guide/nuxt`
+  - Examples: `maz-ui://guide/getting-started`, `maz-ui://guide/vue`, `maz-ui://ecosystem/nuxt`
 - **`maz-ui://composable/{composableName}`** - Vue composable documentation
   - Examples: `maz-ui://composable/use-toast`, `maz-ui://composable/use-dialog`
 - **`maz-ui://directive/{directiveName}`** - Vue directive documentation

package/dist/mcp.d.mts

@@ -16,7 +16,7 @@ interface DocumentMetadata {
     sections: SectionMetadata[];
 }
 
-type DocumentType = 'component' | 'guide' | 'composable' | 'directive' | 'plugin' | 'helper';
+type DocumentType = 'component' | 'guide' | 'composable' | 'directive' | 'plugin' | 'util' | 'node';
 interface Document {
     name: string;
     type: DocumentType;
@@ -46,7 +46,11 @@ interface DocumentationDiagnostics {
         total: number;
         list: string[];
     };
-    helpers: {
+    utils: {
+        total: number;
+        list: string[];
+    };
+    node: {
         total: number;
         list: string[];
     };
@@ -58,7 +62,10 @@ interface DocumentationDiagnostics {
         composablesDir: string;
         directivesDir: string;
         pluginsDir: string;
-        helpersDir: string;
+        ecosystemDir: string;
+        utilsDir: string;
+        nodeDir: string;
+        iconsDir: string;
     };
 }
 declare class DocumentationService {
@@ -69,7 +76,11 @@ declare class DocumentationService {
     private readonly composablesDir;
     private readonly directivesDir;
     private readonly pluginsDir;
-    private readonly helpersDir;
+    private readonly ecosystemDir;
+    private readonly utilsDir;
+    private readonly utilsTypesDir;
+    private readonly nodeDir;
+    private readonly iconsDir;
     private readonly metadataExtractor;
     constructor();
     private pascalToKebabCase;
@@ -85,8 +96,10 @@ declare class DocumentationService {
     getAllDirectives(): string[];
     getPluginDocumentation(pluginName: string): string;
     getAllPlugins(): string[];
-    getHelperDocumentation(helperName: string): string;
-    getAllHelpers(): string[];
+    getUtilDocumentation(utilName: string): string;
+    getAllUtils(): string[];
+    getNodeDocumentation(nodeName: string): string;
+    getAllNode(): string[];
     getAllDocuments(): Document[];
     private buildDocument;
     getOverview(): string;
@@ -96,7 +109,7 @@ declare class DocumentationService {
 
 /**
  * MCP server for Maz-UI documentation
- * Provides robust access to Vue.js components, guides, composables, directives, plugins, and helper utilities
+ * Provides robust access to Vue.js components, guides, composables, directives, plugins, utils and node utilities
  * with fuzzy search, comprehensive indexing, and intelligent fallbacks
  */
 declare class MazUiMcpServer {
@@ -120,9 +133,9 @@ declare class MazUiMcpServer {
      */
     private getComponentType;
     /**
-     * Determine helper type for better categorization
+     * Determine util type for better categorization
      */
-    private getHelperType;
+    private getUtilType;
     /**
      * Resolve a document name using intelligent matching:
      * PascalCase (MazBtn), kebab-case (maz-btn), short name (btn), aliases

package/dist/mcp.d.ts

@@ -16,7 +16,7 @@ interface DocumentMetadata {
     sections: SectionMetadata[];
 }
 
-type DocumentType = 'component' | 'guide' | 'composable' | 'directive' | 'plugin' | 'helper';
+type DocumentType = 'component' | 'guide' | 'composable' | 'directive' | 'plugin' | 'util' | 'node';
 interface Document {
     name: string;
     type: DocumentType;
@@ -46,7 +46,11 @@ interface DocumentationDiagnostics {
         total: number;
         list: string[];
     };
-    helpers: {
+    utils: {
+        total: number;
+        list: string[];
+    };
+    node: {
         total: number;
         list: string[];
     };
@@ -58,7 +62,10 @@ interface DocumentationDiagnostics {
         composablesDir: string;
         directivesDir: string;
         pluginsDir: string;
-        helpersDir: string;
+        ecosystemDir: string;
+        utilsDir: string;
+        nodeDir: string;
+        iconsDir: string;
     };
 }
 declare class DocumentationService {
@@ -69,7 +76,11 @@ declare class DocumentationService {
     private readonly composablesDir;
     private readonly directivesDir;
     private readonly pluginsDir;
-    private readonly helpersDir;
+    private readonly ecosystemDir;
+    private readonly utilsDir;
+    private readonly utilsTypesDir;
+    private readonly nodeDir;
+    private readonly iconsDir;
     private readonly metadataExtractor;
     constructor();
     private pascalToKebabCase;
@@ -85,8 +96,10 @@ declare class DocumentationService {
     getAllDirectives(): string[];
     getPluginDocumentation(pluginName: string): string;
     getAllPlugins(): string[];
-    getHelperDocumentation(helperName: string): string;
-    getAllHelpers(): string[];
+    getUtilDocumentation(utilName: string): string;
+    getAllUtils(): string[];
+    getNodeDocumentation(nodeName: string): string;
+    getAllNode(): string[];
     getAllDocuments(): Document[];
     private buildDocument;
     getOverview(): string;
@@ -96,7 +109,7 @@ declare class DocumentationService {
 
 /**
  * MCP server for Maz-UI documentation
- * Provides robust access to Vue.js components, guides, composables, directives, plugins, and helper utilities
+ * Provides robust access to Vue.js components, guides, composables, directives, plugins, utils and node utilities
  * with fuzzy search, comprehensive indexing, and intelligent fallbacks
  */
 declare class MazUiMcpServer {
@@ -120,9 +133,9 @@ declare class MazUiMcpServer {
      */
     private getComponentType;
     /**
-     * Determine helper type for better categorization
+     * Determine util type for better categorization
      */
-    private getHelperType;
+    private getUtilType;
     /**
      * Resolve a document name using intelligent matching:
      * PascalCase (MazBtn), kebab-case (maz-btn), short name (btn), aliases

package/dist/mcp.mjs

@@ -3,11 +3,11 @@ import { getErrorMessage } from '@maz-ui/utils/helpers/getErrorMessage';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ListResourcesRequestSchema, ReadResourceRequestSchema, ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const version = "5.0.0-beta.2";
+const version = "5.0.0-beta.30";
 
 class MetadataExtractor {
   extract(name, type, content, manualTags = []) {
@@ -248,7 +248,11 @@ class DocumentationService {
   composablesDir;
   directivesDir;
   pluginsDir;
-  helpersDir;
+  ecosystemDir;
+  utilsDir;
+  utilsTypesDir;
+  nodeDir;
+  iconsDir;
   metadataExtractor = new MetadataExtractor();
   constructor() {
     const localDocsRoot = resolve(_dirname, "../docs/src");
@@ -260,7 +264,11 @@ class DocumentationService {
     this.composablesDir = join(this.docsRoot, "composables");
     this.directivesDir = join(this.docsRoot, "directives");
     this.pluginsDir = join(this.docsRoot, "plugins");
-    this.helpersDir = join(this.docsRoot, "helpers");
+    this.ecosystemDir = join(this.docsRoot, "ecosystem");
+    this.utilsDir = join(this.ecosystemDir, "utils");
+    this.utilsTypesDir = join(this.utilsDir, "types");
+    this.nodeDir = join(this.ecosystemDir, "node");
+    this.iconsDir = join(this.ecosystemDir, "icons");
   }
   pascalToKebabCase(pascalName) {
     return pascalName.replace(/([A-Z])/g, "-$1").toLowerCase().replace(/^-/, "");
@@ -275,13 +283,20 @@ class DocumentationService {
       return "";
     }
   }
-  listMarkdownFiles(dirPath) {
+  listMarkdownFiles(dirPath, options = {}) {
     try {
       if (!existsSync(dirPath)) {
         return [];
       }
-      const files = readdirSync(dirPath);
-      return files.filter((file) => file.endsWith(".md") && file !== "index.md").map((file) => file.replace(".md", "")).sort();
+      const entries = readdirSync(dirPath);
+      return entries.filter((entry) => {
+        if (!entry.endsWith(".md"))
+          return false;
+        if (!options.keepIndex && entry === "index.md")
+          return false;
+        const fullPath = join(dirPath, entry);
+        return statSync(fullPath).isFile();
+      }).map((file) => file.replace(".md", "")).sort();
     } catch {
       return [];
     }
@@ -322,12 +337,38 @@ ${generatedDoc}`;
     return Array.from(allComponents).sort();
   }
   // ========== GUIDES ==========
+  // Aggregates: guide/*.md + ecosystem/*.md (standalone) + ecosystem/icons/*.md (index.md → 'icons')
   getGuideDocumentation(guideName) {
-    const guidePath = join(this.guidesDir, `${guideName}.md`);
-    return this.readMarkdownFile(guidePath);
+    const candidates = [
+      join(this.guidesDir, `${guideName}.md`),
+      join(this.ecosystemDir, `${guideName}.md`),
+      join(this.iconsDir, `${guideName}.md`)
+    ];
+    if (guideName === "icons") {
+      candidates.push(join(this.iconsDir, "index.md"));
+    }
+    for (const path of candidates) {
+      const content = this.readMarkdownFile(path);
+      if (content)
+        return content;
+    }
+    return "";
   }
   getAllGuides() {
-    return this.listMarkdownFiles(this.guidesDir);
+    const guides = /* @__PURE__ */ new Set();
+    for (const name of this.listMarkdownFiles(this.guidesDir)) {
+      guides.add(name);
+    }
+    for (const name of this.listMarkdownFiles(this.ecosystemDir)) {
+      guides.add(name);
+    }
+    for (const name of this.listMarkdownFiles(this.iconsDir)) {
+      guides.add(name);
+    }
+    if (existsSync(join(this.iconsDir, "index.md"))) {
+      guides.add("icons");
+    }
+    return Array.from(guides).sort();
   }
   // ========== COMPOSABLES ==========
   getComposableDocumentation(composableName) {
@@ -353,13 +394,34 @@ ${generatedDoc}`;
   getAllPlugins() {
     return this.listMarkdownFiles(this.pluginsDir);
   }
-  // ========== HELPERS ==========
-  getHelperDocumentation(helperName) {
-    const helperPath = join(this.helpersDir, `${helperName}.md`);
-    return this.readMarkdownFile(helperPath);
+  // ========== UTILS ==========
+  // Aggregates: ecosystem/utils/*.md + ecosystem/utils/types/*.md
+  getUtilDocumentation(utilName) {
+    const candidates = [
+      join(this.utilsDir, `${utilName}.md`),
+      join(this.utilsTypesDir, `${utilName}.md`)
+    ];
+    for (const path of candidates) {
+      const content = this.readMarkdownFile(path);
+      if (content)
+        return content;
+    }
+    return "";
+  }
+  getAllUtils() {
+    const utils = /* @__PURE__ */ new Set([
+      ...this.listMarkdownFiles(this.utilsDir),
+      ...this.listMarkdownFiles(this.utilsTypesDir)
+    ]);
+    return Array.from(utils).sort();
+  }
+  // ========== NODE ==========
+  getNodeDocumentation(nodeName) {
+    const nodePath = join(this.nodeDir, `${nodeName}.md`);
+    return this.readMarkdownFile(nodePath);
   }
-  getAllHelpers() {
-    return this.listMarkdownFiles(this.helpersDir);
+  getAllNode() {
+    return this.listMarkdownFiles(this.nodeDir);
   }
   // ========== UNIFIED LOADING ==========
   getAllDocuments() {
@@ -375,7 +437,8 @@ ${generatedDoc}`;
       { type: "composable", names: this.getAllComposables(), getContent: (name) => this.getComposableDocumentation(name) },
       { type: "directive", names: this.getAllDirectives(), getContent: (name) => this.getDirectiveDocumentation(name) },
       { type: "plugin", names: this.getAllPlugins(), getContent: (name) => this.getPluginDocumentation(name) },
-      { type: "helper", names: this.getAllHelpers(), getContent: (name) => this.getHelperDocumentation(name) }
+      { type: "util", names: this.getAllUtils(), getContent: (name) => this.getUtilDocumentation(name) },
+      { type: "node", names: this.getAllNode(), getContent: (name) => this.getNodeDocumentation(name) }
     ];
     for (const category of categories) {
       for (const name of category.names) {
@@ -403,52 +466,33 @@ ${generatedDoc}`;
   searchDocumentation(query) {
     const searchTerm = query.toLowerCase();
     const results = [];
-    const components = this.getAllComponents();
-    for (const component of components) {
-      if (component.toLowerCase().includes(searchTerm)) {
-        results.push(`component:${component}`);
-      }
-    }
-    const guides = this.getAllGuides();
-    for (const guide of guides) {
-      if (guide.toLowerCase().includes(searchTerm)) {
-        results.push(`guide:${guide}`);
-      }
-    }
-    const composables = this.getAllComposables();
-    for (const composable of composables) {
-      if (composable.toLowerCase().includes(searchTerm)) {
-        results.push(`composable:${composable}`);
-      }
-    }
-    const directives = this.getAllDirectives();
-    for (const directive of directives) {
-      if (directive.toLowerCase().includes(searchTerm)) {
-        results.push(`directive:${directive}`);
-      }
-    }
-    const plugins = this.getAllPlugins();
-    for (const plugin of plugins) {
-      if (plugin.toLowerCase().includes(searchTerm)) {
-        results.push(`plugin:${plugin}`);
-      }
-    }
-    const helpers = this.getAllHelpers();
-    for (const helper of helpers) {
-      if (helper.toLowerCase().includes(searchTerm)) {
-        results.push(`helper:${helper}`);
+    const buckets = [
+      { type: "component", names: this.getAllComponents() },
+      { type: "guide", names: this.getAllGuides() },
+      { type: "composable", names: this.getAllComposables() },
+      { type: "directive", names: this.getAllDirectives() },
+      { type: "plugin", names: this.getAllPlugins() },
+      { type: "util", names: this.getAllUtils() },
+      { type: "node", names: this.getAllNode() }
+    ];
+    for (const { type, names } of buckets) {
+      for (const name of names) {
+        if (name.toLowerCase().includes(searchTerm)) {
+          results.push(`${type}:${name}`);
+        }
       }
     }
     return results;
   }
   getDiagnostics() {
-    const [components, guides, composables, directives, plugins, helpers] = [
+    const [components, guides, composables, directives, plugins, utils, nodeItems] = [
       this.getAllComponents(),
       this.getAllGuides(),
       this.getAllComposables(),
       this.getAllDirectives(),
       this.getAllPlugins(),
-      this.getAllHelpers()
+      this.getAllUtils(),
+      this.getAllNode()
     ];
     let withManualDoc = 0;
     let withGeneratedDoc = 0;
@@ -486,9 +530,13 @@ ${generatedDoc}`;
         total: plugins.length,
         list: plugins
       },
-      helpers: {
-        total: helpers.length,
-        list: helpers
+      utils: {
+        total: utils.length,
+        list: utils
+      },
+      node: {
+        total: nodeItems.length,
+        list: nodeItems
       },
       paths: {
         docsRoot: this.docsRoot,
@@ -498,7 +546,10 @@ ${generatedDoc}`;
         composablesDir: this.composablesDir,
         directivesDir: this.directivesDir,
         pluginsDir: this.pluginsDir,
-        helpersDir: this.helpersDir
+        ecosystemDir: this.ecosystemDir,
+        utilsDir: this.utilsDir,
+        nodeDir: this.nodeDir,
+        iconsDir: this.iconsDir
       }
     };
   }
@@ -926,24 +977,44 @@ class MazUiMcpServer {
         uri: `plugin://${plugin}`
       });
     }
-    const helpers = this.documentationService.getAllHelpers();
-    for (const helper of helpers) {
-      const helperType = this.getHelperType(helper);
+    const utils = this.documentationService.getAllUtils();
+    for (const util of utils) {
+      const utilType = this.getUtilType(util);
       const tags = [
-        "helper",
+        "util",
         "utility",
         "function",
-        helper,
-        helperType,
-        ...this.generateSearchTags(helper)
+        "maz-ui-utils",
+        util,
+        utilType,
+        ...this.generateSearchTags(util)
       ];
       index.push({
-        type: "helper",
-        name: helper,
-        displayName: `${helper} Helper`,
-        description: `Utility helper: ${helper} - ${helperType} utility functions for data processing and manipulation`,
+        type: "util",
+        name: util,
+        displayName: `${util} Util`,
+        description: `Utility from @maz-ui/utils: ${util} - ${utilType} utility for data processing and manipulation`,
         tags,
-        uri: `helper://${helper}`
+        uri: `util://${util}`
+      });
+    }
+    const nodeItems = this.documentationService.getAllNode();
+    for (const nodeItem of nodeItems) {
+      const tags = [
+        "node",
+        "server",
+        "cli",
+        "maz-ui-node",
+        nodeItem,
+        ...this.generateSearchTags(nodeItem)
+      ];
+      index.push({
+        type: "node",
+        name: nodeItem,
+        displayName: `${nodeItem} Node Utility`,
+        description: `Node.js utility from @maz-ui/node: ${nodeItem} - server-side helper for scripts, CLI and SSR runtimes`,
+        tags,
+        uri: `node://${nodeItem}`
       });
     }
     this.documentationIndex = index;
@@ -1016,10 +1087,10 @@ class MazUiMcpServer {
     return "general";
   }
   /**
-   * Determine helper type for better categorization
+   * Determine util type for better categorization
    */
-  getHelperType(helperName) {
-    const lowerName = helperName.toLowerCase();
+  getUtilType(utilName) {
+    const lowerName = utilName.toLowerCase();
     if (lowerName.includes("string") || lowerName.includes("text"))
       return "string";
     if (lowerName.includes("date") || lowerName.includes("time"))
@@ -1145,9 +1216,10 @@ class MazUiMcpServer {
       composable: "Composables",
       directive: "Directives",
       plugin: "Plugins",
-      helper: "Helpers"
+      util: "Utils",
+      node: "Node Utilities"
     };
-    const typeOrder = ["component", "guide", "composable", "directive", "plugin", "helper"];
+    const typeOrder = ["component", "guide", "composable", "directive", "plugin", "util", "node"];
     let result = `# Maz-UI Documentation (${filteredIndex.length} items)
 
 `;
@@ -1230,7 +1302,8 @@ ${suggestions}
       composable: (name) => this.documentationService.getComposableDocumentation(name),
       directive: (name) => this.documentationService.getDirectiveDocumentation(name),
       plugin: (name) => this.documentationService.getPluginDocumentation(name),
-      helper: (name) => this.documentationService.getHelperDocumentation(name)
+      util: (name) => this.documentationService.getUtilDocumentation(name),
+      node: (name) => this.documentationService.getNodeDocumentation(name)
     };
     const getContent = contentMethods[doc.type];
     return getContent ? getContent(doc.name) : "";
@@ -1277,7 +1350,8 @@ ${suggestions}
 - **${diagnostics.composables.total} Composables** - Vue 3 reactive utilities
 - **${diagnostics.directives.total} Directives** - DOM helpers
 - **${diagnostics.plugins.total} Plugins** - App-wide services
-- **${diagnostics.helpers.total} Helpers** - Utility functions
+- **${diagnostics.utils.total} Utils** - Utility functions from @maz-ui/utils
+- **${diagnostics.node.total} Node Utilities** - Server-side helpers from @maz-ui/node
 - **${diagnostics.guides.total} Guides** - Documentation
 
 ## Getting Started
@@ -1302,11 +1376,14 @@ Use the MCP tools to explore components and features:
           case "plugin":
             content = this.documentationService.getPluginDocumentation(name);
             break;
-          case "helper":
-            content = this.documentationService.getHelperDocumentation(name);
+          case "util":
+            content = this.documentationService.getUtilDocumentation(name);
+            break;
+          case "node":
+            content = this.documentationService.getNodeDocumentation(name);
             break;
           default:
-            throw new Error(`Unknown resource type: ${type}. Valid types: overview, component, guide, composable, directive, plugin, helper`);
+            throw new Error(`Unknown resource type: ${type}. Valid types: overview, component, guide, composable, directive, plugin, util, node`);
         }
         if (!content) {
           throw new Error(`Documentation not found for ${type}: ${name}`);
@@ -1337,7 +1414,7 @@ Use the MCP tools to explore components and features:
                 },
                 category: {
                   type: "string",
-                  enum: ["component", "guide", "composable", "directive", "plugin", "helper"],
+                  enum: ["component", "guide", "composable", "directive", "plugin", "util", "node"],
                   description: "Optional filter to restrict results to a specific documentation category"
                 },
                 maxResults: {
@@ -1363,7 +1440,7 @@ Use the MCP tools to explore components and features:
                 },
                 type: {
                   type: "string",
-                  enum: ["auto", "component", "guide", "composable", "directive", "plugin", "helper"],
+                  enum: ["auto", "component", "guide", "composable", "directive", "plugin", "util", "node"],
                   description: 'Type hint to improve search accuracy (optional). Use "auto" to search all types.',
                   default: "auto"
                 }
@@ -1373,13 +1450,13 @@ Use the MCP tools to explore components and features:
           },
           {
             name: "list",
-            description: "Browse all available Maz-UI documentation grouped by category. Returns a structured list with counters per category and for each item: name, displayName, description. Use this tool to discover what components, composables, directives, plugins, helpers, and guides are available. Examples: list all docs, list only components, list composables.",
+            description: "Browse all available Maz-UI documentation grouped by category. Returns a structured list with counters per category and for each item: name, displayName, description. Use this tool to discover what components, composables, directives, plugins, utils, node utilities and guides are available. Examples: list all docs, list only components, list composables.",
             inputSchema: {
               type: "object",
               properties: {
                 category: {
                   type: "string",
-                  enum: ["all", "component", "guide", "composable", "directive", "plugin", "helper"],
+                  enum: ["all", "component", "guide", "composable", "directive", "plugin", "util", "node"],
                   description: 'Filter by documentation category. Use "all" or omit to see everything.',
                   default: "all"
                 }