@sebgroup/green-core 2.21.0-rc.20260112150926042 → 2.21.0-rc.20260113135658239

package/bin/mcp-server/resources.js

@@ -61,6 +61,14 @@ function setupResourceHandlers(server) {
         }
       }
       if (globalIndex) {
+        if (globalIndex.instructions) {
+          resources.push({
+            uri: "green://instructions",
+            name: "Green Design System Instructions",
+            description: "General instructions and guidelines for agents using the Green Design System MCP",
+            mimeType: "text/markdown"
+          });
+        }
         for (const guide of globalIndex.guides) {
           const name = guide.path.replace(/^(guides|concepts)\//, "").replace(/\.md$/, "");
           const category = guide.path.startsWith("guides/") ? "guides" : "concepts";
@@ -82,6 +90,21 @@ function setupResourceHandlers(server) {
   server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     const { uri } = request.params;
     try {
+      if (uri === "green://instructions") {
+        const content2 = await readMcpFile("INSTRUCTIONS.md");
+        if (!content2) {
+          throw new Error("Instructions file not found");
+        }
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: "text/markdown",
+              text: content2
+            }
+          ]
+        };
+      }
       const parsed = parseResourceUri(uri);
       if (!parsed) {
         throw new Error(`Invalid resource URI: ${uri}`);

package/bin/mcp-server/tools.js

@@ -18,19 +18,39 @@ function setupToolHandlers(server) {
       tools: [
         {
           name: "search_components",
-          description: "Search for Green Design System components by name, description, or functionality. Use this when you don't know the exact component name or want to discover available components.",
+          description: "Search for Green Design System components by name, description, or functionality. Use this when you don't know the exact component name or want to discover available components. Supports multi-term searches and regex patterns.",
           inputSchema: {
             type: "object",
             properties: {
               query: {
                 type: "string",
-                description: "Component name or search term (e.g., 'button', 'dropdown', 'form input', 'arrow icon')"
+                description: "Component name or search term. Can be multiple terms separated by spaces/commas (e.g., 'button input radio'). Use regex format (e.g., '^gds-button') if useRegex is true."
               },
               category: {
                 type: "string",
                 enum: ["component", "icon", "all"],
                 description: "Filter by type. Default: 'all'",
                 default: "all"
+              },
+              splitTerms: {
+                type: "boolean",
+                description: "Split query on spaces and commas to search for multiple terms. Default: true",
+                default: true
+              },
+              matchAll: {
+                type: "boolean",
+                description: "When splitTerms is true, require ALL terms to match (AND logic). Default: false (OR logic)",
+                default: false
+              },
+              useRegex: {
+                type: "boolean",
+                description: "Treat query as a regular expression pattern. Default: false",
+                default: false
+              },
+              maxResults: {
+                type: "number",
+                description: "Maximum number of results to return. Default: 20",
+                default: 20
               }
             },
             required: ["query"]
@@ -106,6 +126,15 @@ function setupToolHandlers(server) {
             },
             required: ["name"]
           }
+        },
+        {
+          name: "get_instructions",
+          description: "Get the base instructions for using the Green Design System MCP. These instructions contain critical rules, typography guidelines, layout system requirements, and general best practices that should be read before implementing any Green components.",
+          inputSchema: {
+            type: "object",
+            properties: {},
+            required: []
+          }
         }
       ]
     };
@@ -126,6 +155,8 @@ function setupToolHandlers(server) {
           return await handleListGuides(args);
         case "get_guide":
           return await handleGetGuide(args);
+        case "get_instructions":
+          return await handleGetInstructions();
         default:
           throw new Error(`Unknown tool: ${name}`);
       }
@@ -144,19 +175,93 @@ function setupToolHandlers(server) {
   });
 }
 async function handleSearchComponents(input) {
-  const { query, category = "all" } = input;
+  const {
+    query,
+    category = "all",
+    splitTerms = true,
+    matchAll = false,
+    useRegex = false,
+    maxResults = 20
+  } = input;
   const results = [];
-  const queryLower = query.toLowerCase();
   try {
+    let searchTerms;
+    let regexPattern = null;
+    if (useRegex) {
+      try {
+        if (query.length > 100) {
+          throw new Error("Regex pattern too long (max 100 characters)");
+        }
+        regexPattern = new RegExp(query, "i");
+        searchTerms = [query];
+      } catch (error) {
+        throw new Error(
+          `Invalid regex pattern: ${error instanceof Error ? error.message : "unknown error"}`
+        );
+      }
+    } else if (splitTerms) {
+      searchTerms = query.toLowerCase().split(/[\s,]+/).filter((term) => term.length > 0);
+    } else {
+      searchTerms = [query.toLowerCase()];
+    }
+    if (searchTerms.length === 0) {
+      throw new Error("Query cannot be empty");
+    }
     const loadComponents = category === "component" || category === "all";
     const loadIcons = category === "icon" || category === "all";
     const [componentsIndex, iconsIndex] = await Promise.all([
       loadComponents ? loadComponentsIndex() : Promise.resolve(null),
       loadIcons ? loadIconsIndex() : Promise.resolve(null)
     ]);
+    const checkMatches = (item) => {
+      const tagName = item.tagName.toLowerCase();
+      const name = item.name.toLowerCase();
+      const className = item.className.toLowerCase();
+      const description = item.description?.toLowerCase() || "";
+      if (regexPattern) {
+        const matches2 = regexPattern.test(tagName) || regexPattern.test(name) || regexPattern.test(className) || regexPattern.test(description);
+        if (matches2) {
+          if (regexPattern.test(tagName)) {
+            if (tagName === query.toLowerCase()) return { matches: true, tier: 1, matchedTerms: 1 };
+            if (tagName.startsWith(query.toLowerCase())) return { matches: true, tier: 2, matchedTerms: 1 };
+            return { matches: true, tier: 3, matchedTerms: 1 };
+          }
+          return { matches: true, tier: 4, matchedTerms: 1 };
+        }
+        return { matches: false, tier: 0, matchedTerms: 0 };
+      }
+      let matchedTerms = 0;
+      let bestTier = 999;
+      for (const term of searchTerms) {
+        let termMatched = false;
+        let termTier = 999;
+        if (tagName === `gds-${term}` || tagName === term) {
+          termMatched = true;
+          termTier = Math.min(termTier, 1);
+        } else if (tagName.startsWith(term) || tagName.startsWith(`gds-${term}`)) {
+          termMatched = true;
+          termTier = Math.min(termTier, 2);
+        } else if (tagName.includes(term)) {
+          termMatched = true;
+          termTier = Math.min(termTier, 3);
+        } else if (name.includes(term) || className.includes(term)) {
+          termMatched = true;
+          termTier = Math.min(termTier, 4);
+        } else if (description.includes(term)) {
+          termMatched = true;
+          termTier = Math.min(termTier, 5);
+        }
+        if (termMatched) {
+          matchedTerms++;
+          bestTier = Math.min(bestTier, termTier);
+        }
+      }
+      const matches = matchAll ? matchedTerms === searchTerms.length : matchedTerms > 0;
+      return { matches, tier: matches ? bestTier : 999, matchedTerms };
+    };
     if (componentsIndex) {
       for (const component of componentsIndex.components) {
-        const matches = component.tagName.toLowerCase().includes(queryLower) || component.name.toLowerCase().includes(queryLower) || component.className.toLowerCase().includes(queryLower) || component.description?.toLowerCase().includes(queryLower);
+        const { matches, tier, matchedTerms } = checkMatches(component);
         if (matches) {
           const shortName = component.tagName.replace(/^gds-/, "");
           const resourceUris = {};
@@ -174,23 +279,21 @@ async function handleSearchComponents(input) {
             description: component.description,
             category: "component",
             availableDocs: component.files,
-            resourceUris
+            resourceUris,
+            tier,
+            matchedTerms
           });
         }
       }
     }
     if (iconsIndex) {
       for (const icon of iconsIndex.icons) {
-        const matches = icon.tagName.toLowerCase().includes(queryLower) || icon.name.toLowerCase().includes(queryLower) || icon.className.toLowerCase().includes(queryLower) || icon.description?.toLowerCase().includes(queryLower);
+        const { matches, tier, matchedTerms } = checkMatches(icon);
         if (matches) {
           const shortName = icon.tagName.replace(/^gds-/, "");
           const resourceUris = {};
           for (const docType of icon.files) {
-            resourceUris[docType] = buildResourceUri(
-              "icons",
-              shortName,
-              docType
-            );
+            resourceUris[docType] = buildResourceUri("icons", shortName, docType);
           }
           results.push({
             name: icon.name,
@@ -199,19 +302,23 @@ async function handleSearchComponents(input) {
             description: icon.description,
             category: "icon",
             availableDocs: icon.files,
-            resourceUris
+            resourceUris,
+            tier,
+            matchedTerms
           });
         }
       }
     }
     results.sort((a, b) => {
-      const aExact = a.tagName.toLowerCase() === queryLower;
-      const bExact = b.tagName.toLowerCase() === queryLower;
-      if (aExact && !bExact) return -1;
-      if (!aExact && bExact) return 1;
+      if (a.tier !== b.tier) return a.tier - b.tier;
+      if (splitTerms && a.matchedTerms !== b.matchedTerms)
+        return b.matchedTerms - a.matchedTerms;
       return a.tagName.localeCompare(b.tagName);
     });
-    const limitedResults = results.slice(0, 20);
+    const limitedResults = results.slice(0, maxResults).map((r) => {
+      const { tier, matchedTerms, ...result } = r;
+      return result;
+    });
     return {
       content: [
         {
@@ -408,6 +515,33 @@ ${content}`
     throw new Error(`Failed to get guide: ${error}`);
   }
 }
+async function handleGetInstructions() {
+  try {
+    const globalIndex = await loadGlobalIndex();
+    if (!globalIndex) {
+      throw new Error("Failed to load global index");
+    }
+    if (!globalIndex.instructions) {
+      throw new Error(
+        "Instructions not available. The MCP may not have been generated with instructions support."
+      );
+    }
+    const content = await readMcpFile("INSTRUCTIONS.md");
+    if (!content) {
+      throw new Error("Instructions file not found");
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: content
+        }
+      ]
+    };
+  } catch (error) {
+    throw new Error(`Failed to get instructions: ${error}`);
+  }
+}
 export {
   setupToolHandlers
 };

package/bin/mcp-server/types.d.ts

@@ -59,6 +59,7 @@ export interface IconsIndex {
 export interface GlobalIndex {
     version: string;
     generatedAt: string;
+    instructions?: string;
     components: string;
     icons: string;
     guides: GuideEntry[];
@@ -95,6 +96,10 @@ export interface SearchResult {
 export interface SearchComponentsInput {
     query: string;
     category?: Category;
+    splitTerms?: boolean;
+    matchAll?: boolean;
+    useRegex?: boolean;
+    maxResults?: number;
 }
 export interface GetComponentDocsInput {
     componentName: string;