@sebgroup/green-core 2.20.0 → 2.21.0-rc.20260112142904069

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

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/bin/mcp-server/index.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { setupResourceHandlers } from "./resources.js";
+import { setupToolHandlers } from "./tools.js";
+import { getPackageVersion } from "./utils.js";
+async function main() {
+  const packageVersion = await getPackageVersion();
+  const server = new McpServer(
+    {
+      name: "green-design-system",
+      version: packageVersion
+    },
+    {
+      capabilities: {
+        resources: {},
+        tools: {}
+      }
+    }
+  );
+  setupResourceHandlers(server.server);
+  setupToolHandlers(server.server);
+  server.server.onerror = (error) => {
+    console.error("[MCP Error]", error);
+  };
+  process.on("SIGINT", async () => {
+    await server.close();
+    process.exit(0);
+  });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Green Core MCP Server started");
+  console.error(`Version: ${packageVersion}`);
+  console.error("Waiting for requests...");
+}
+main().catch((error) => {
+  console.error("Failed to start server:", error);
+  process.exit(1);
+});

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

@@ -0,0 +1,5 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+/**
+ * Register resource handlers on the MCP server
+ */
+export declare function setupResourceHandlers(server: Server): void;

package/bin/mcp-server/resources.js

@@ -0,0 +1,122 @@
+import "../../chunks/chunk.QU3DSPNU.js";
+import {
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import {
+  loadComponentsIndex,
+  loadIconsIndex,
+  loadGlobalIndex,
+  readMcpFile,
+  buildResourceUri,
+  parseResourceUri
+} from "./utils.js";
+function setupResourceHandlers(server) {
+  server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    const resources = [];
+    try {
+      const [componentsIndex, iconsIndex, globalIndex] = await Promise.all([
+        loadComponentsIndex(),
+        loadIconsIndex(),
+        loadGlobalIndex()
+      ]);
+      if (componentsIndex) {
+        for (const component of componentsIndex.components) {
+          const shortName = component.tagName.replace(/^gds-/, "");
+          for (const docType of component.files) {
+            const uri = buildResourceUri("components", shortName, docType);
+            let description = `${component.tagName} - ${docType} documentation`;
+            if (docType === "angular") {
+              description = `Angular-specific documentation for ${component.tagName}`;
+            } else if (docType === "react") {
+              description = `React-specific documentation for ${component.tagName}`;
+            } else if (docType === "api") {
+              description = `Web Component API documentation for ${component.tagName}`;
+            } else if (docType === "guidelines") {
+              description = `UX and design guidelines for ${component.tagName}`;
+            } else if (docType === "instructions") {
+              description = `Agent-specific usage instructions for ${component.tagName}`;
+            }
+            resources.push({
+              uri,
+              name: `${component.tagName} (${docType})`,
+              description,
+              mimeType: "text/markdown"
+            });
+          }
+        }
+      }
+      if (iconsIndex) {
+        for (const icon of iconsIndex.icons) {
+          const shortName = icon.tagName.replace(/^gds-/, "");
+          for (const docType of icon.files) {
+            const uri = buildResourceUri("icons", shortName, docType);
+            resources.push({
+              uri,
+              name: `${icon.tagName} (${docType})`,
+              description: `${icon.tagName} icon - ${docType} documentation`,
+              mimeType: "text/markdown"
+            });
+          }
+        }
+      }
+      if (globalIndex) {
+        for (const guide of globalIndex.guides) {
+          const name = guide.path.replace(/^(guides|concepts)\//, "").replace(/\.md$/, "");
+          const category = guide.path.startsWith("guides/") ? "guides" : "concepts";
+          const uri = buildResourceUri(category, name);
+          resources.push({
+            uri,
+            name: guide.title,
+            description: guide.description,
+            mimeType: "text/markdown"
+          });
+        }
+      }
+      return { resources };
+    } catch (error) {
+      console.error("Error listing resources:", error);
+      return { resources: [] };
+    }
+  });
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const { uri } = request.params;
+    try {
+      const parsed = parseResourceUri(uri);
+      if (!parsed) {
+        throw new Error(`Invalid resource URI: ${uri}`);
+      }
+      const { category, name, docType } = parsed;
+      let filePath;
+      if (category === "components" || category === "icons") {
+        if (!docType) {
+          throw new Error(`Document type required for ${category}`);
+        }
+        filePath = `${name}/${docType}.md`;
+      } else if (category === "guides" || category === "concepts") {
+        filePath = `${category}/${name}.md`;
+      } else {
+        throw new Error(`Unknown category: ${category}`);
+      }
+      const content = await readMcpFile(filePath);
+      if (!content) {
+        throw new Error(`Resource not found: ${uri}`);
+      }
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: "text/markdown",
+            text: content
+          }
+        ]
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      throw new Error(`Failed to read resource: ${errorMessage}`);
+    }
+  });
+}
+export {
+  setupResourceHandlers
+};

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

@@ -0,0 +1,5 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+/**
+ * Register tool handlers on the MCP server
+ */
+export declare function setupToolHandlers(server: Server): void;

package/bin/mcp-server/tools.js

@@ -0,0 +1,413 @@
+import "../../chunks/chunk.QU3DSPNU.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import {
+  buildResourceUri,
+  findComponent,
+  findIcon,
+  loadComponentsIndex,
+  loadGlobalIndex,
+  loadIconsIndex,
+  readMcpFile
+} from "./utils.js";
+function setupToolHandlers(server) {
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      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.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              query: {
+                type: "string",
+                description: "Component name or search term (e.g., 'button', 'dropdown', 'form input', 'arrow icon')"
+              },
+              category: {
+                type: "string",
+                enum: ["component", "icon", "all"],
+                description: "Filter by type. Default: 'all'",
+                default: "all"
+              }
+            },
+            required: ["query"]
+          }
+        },
+        {
+          name: "get_component_docs",
+          description: "Get complete documentation for a specific Green component. ALWAYS specify the framework parameter to get correct import paths, event handling syntax, and framework-specific examples.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              componentName: {
+                type: "string",
+                description: "Component tag name (e.g., 'gds-button') or short name (e.g., 'button')"
+              },
+              framework: {
+                type: "string",
+                enum: ["angular", "react", "web-component"],
+                description: "REQUIRED: Framework you're using. Determines import paths and syntax. Use 'web-component' for vanilla JS/framework-agnostic usage."
+              },
+              includeGuidelines: {
+                type: "boolean",
+                description: "Include UX/design guidelines in response",
+                default: true
+              },
+              includeInstructions: {
+                type: "boolean",
+                description: "Include agent-specific usage instructions if available",
+                default: true
+              }
+            },
+            required: ["componentName", "framework"]
+          }
+        },
+        {
+          name: "list_guides",
+          description: "List available setup guides and conceptual documentation for Green Design System",
+          inputSchema: {
+            type: "object",
+            properties: {
+              category: {
+                type: "string",
+                enum: [
+                  "framework-setup",
+                  "getting-started",
+                  "concepts",
+                  "troubleshooting",
+                  "migration",
+                  "all"
+                ],
+                description: "Filter by category. Default: 'all'",
+                default: "all"
+              },
+              framework: {
+                type: "string",
+                enum: ["angular", "react", "all"],
+                description: "Filter guides relevant to specific framework"
+              }
+            },
+            required: []
+          }
+        },
+        {
+          name: "get_guide",
+          description: "Get the full content of a specific guide. Use list_guides first to discover available guides and their names.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              name: {
+                type: "string",
+                description: "The guide name (e.g., 'angular', 'react', 'installing', 'troubleshooting'). Use list_guides to see available guides."
+              }
+            },
+            required: ["name"]
+          }
+        }
+      ]
+    };
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+      switch (name) {
+        case "search_components":
+          return await handleSearchComponents(
+            args
+          );
+        case "get_component_docs":
+          return await handleGetComponentDocs(
+            args
+          );
+        case "list_guides":
+          return await handleListGuides(args);
+        case "get_guide":
+          return await handleGetGuide(args);
+        default:
+          throw new Error(`Unknown tool: ${name}`);
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${errorMessage}`
+          }
+        ],
+        isError: true
+      };
+    }
+  });
+}
+async function handleSearchComponents(input) {
+  const { query, category = "all" } = input;
+  const results = [];
+  const queryLower = query.toLowerCase();
+  try {
+    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)
+    ]);
+    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);
+        if (matches) {
+          const shortName = component.tagName.replace(/^gds-/, "");
+          const resourceUris = {};
+          for (const docType of component.files) {
+            resourceUris[docType] = buildResourceUri(
+              "components",
+              shortName,
+              docType
+            );
+          }
+          results.push({
+            name: component.name,
+            tagName: component.tagName,
+            className: component.className,
+            description: component.description,
+            category: "component",
+            availableDocs: component.files,
+            resourceUris
+          });
+        }
+      }
+    }
+    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);
+        if (matches) {
+          const shortName = icon.tagName.replace(/^gds-/, "");
+          const resourceUris = {};
+          for (const docType of icon.files) {
+            resourceUris[docType] = buildResourceUri(
+              "icons",
+              shortName,
+              docType
+            );
+          }
+          results.push({
+            name: icon.name,
+            tagName: icon.tagName,
+            className: icon.className,
+            description: icon.description,
+            category: "icon",
+            availableDocs: icon.files,
+            resourceUris
+          });
+        }
+      }
+    }
+    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;
+      return a.tagName.localeCompare(b.tagName);
+    });
+    const limitedResults = results.slice(0, 20);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              query,
+              resultCount: limitedResults.length,
+              totalMatches: results.length,
+              results: limitedResults
+            },
+            null,
+            2
+          )
+        }
+      ]
+    };
+  } catch (error) {
+    throw new Error(`Search failed: ${error}`);
+  }
+}
+async function handleGetComponentDocs(input) {
+  const {
+    componentName,
+    framework,
+    includeGuidelines = true,
+    includeInstructions = true
+  } = input;
+  try {
+    const [componentsIndex, iconsIndex] = await Promise.all([
+      loadComponentsIndex(),
+      loadIconsIndex()
+    ]);
+    if (!componentsIndex || !iconsIndex) {
+      throw new Error("Failed to load component indexes");
+    }
+    const component = findComponent(componentName, componentsIndex.components);
+    const icon = component ? null : findIcon(componentName, iconsIndex.icons);
+    const found = component || icon;
+    if (!found) {
+      throw new Error(
+        `Component not found: ${componentName}. Try using the search_components tool to find available components.`
+      );
+    }
+    const shortName = found.tagName.replace(/^gds-/, "");
+    const category = component ? "components" : "icons";
+    const sections = [];
+    let primaryDoc;
+    if (framework === "angular") {
+      primaryDoc = "angular";
+    } else if (framework === "react") {
+      primaryDoc = "react";
+    } else {
+      primaryDoc = "api";
+    }
+    sections.push(
+      `# ${found.tagName} - ${framework.charAt(0).toUpperCase() + framework.slice(1)}`
+    );
+    sections.push("");
+    if (framework === "angular" || framework === "react") {
+      sections.push(
+        `\u26A0\uFE0F **${framework.charAt(0).toUpperCase() + framework.slice(1)}-Specific Documentation**`
+      );
+      sections.push(
+        `The import paths and syntax below are for ${framework.charAt(0).toUpperCase() + framework.slice(1)} applications.`
+      );
+      sections.push("");
+    }
+    if (found.files.includes(primaryDoc)) {
+      const content = await readMcpFile(`${shortName}/${primaryDoc}.md`);
+      if (content) {
+        const contentWithoutTitle = content.replace(/^#\s+.*?\n/, "");
+        sections.push(contentWithoutTitle);
+        sections.push("");
+      }
+    }
+    if (includeGuidelines && found.files.includes("guidelines")) {
+      const guidelines = await readMcpFile(`${shortName}/guidelines.md`);
+      if (guidelines) {
+        sections.push("---");
+        sections.push("");
+        sections.push("## Design Guidelines");
+        sections.push("");
+        sections.push(guidelines);
+        sections.push("");
+      }
+    }
+    if (includeInstructions && found.files.includes("instructions")) {
+      const instructions = await readMcpFile(`${shortName}/instructions.md`);
+      if (instructions) {
+        sections.push("---");
+        sections.push("");
+        sections.push("## Usage Instructions");
+        sections.push("");
+        sections.push(instructions);
+        sections.push("");
+      }
+    }
+    sections.push("---");
+    sections.push("");
+    sections.push("\u{1F4A1} **Using a different framework?**");
+    sections.push("Call this tool again with:");
+    if (framework !== "angular")
+      sections.push('- `framework: "angular"` for Angular documentation');
+    if (framework !== "react")
+      sections.push('- `framework: "react"` for React documentation');
+    if (framework !== "web-component")
+      sections.push('- `framework: "web-component"` for vanilla JS usage');
+    return {
+      content: [
+        {
+          type: "text",
+          text: sections.join("\n")
+        }
+      ]
+    };
+  } catch (error) {
+    throw error;
+  }
+}
+async function handleListGuides(input) {
+  const { category = "all", framework } = input;
+  try {
+    const globalIndex = await loadGlobalIndex();
+    if (!globalIndex) {
+      throw new Error("Failed to load global index");
+    }
+    let guides = globalIndex.guides;
+    if (category !== "all") {
+      guides = guides.filter((g) => g.category === category);
+    }
+    if (framework && framework !== "all") {
+      guides = guides.filter((g) => g.tags.includes(framework));
+    }
+    const guidesWithUris = guides.map((guide) => {
+      const name = guide.path.replace(/^(guides|concepts)\//, "").replace(/\.md$/, "");
+      const guideCategory = guide.path.startsWith("guides/") ? "guides" : "concepts";
+      const uri = buildResourceUri(guideCategory, name);
+      return {
+        title: guide.title,
+        category: guide.category,
+        description: guide.description,
+        tags: guide.tags,
+        resourceUri: uri
+      };
+    });
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              guideCount: guidesWithUris.length,
+              guides: guidesWithUris
+            },
+            null,
+            2
+          )
+        }
+      ]
+    };
+  } catch (error) {
+    throw new Error(`Failed to list guides: ${error}`);
+  }
+}
+async function handleGetGuide(input) {
+  const { name } = input;
+  try {
+    const globalIndex = await loadGlobalIndex();
+    if (!globalIndex) {
+      throw new Error("Failed to load global index");
+    }
+    const guide = globalIndex.guides.find((g) => {
+      const guideName = g.path.replace(/^(guides|concepts)\//, "").replace(/\.md$/, "");
+      return guideName === name;
+    });
+    if (!guide) {
+      throw new Error(
+        `Guide not found: ${name}. Use list_guides to see available guides.`
+      );
+    }
+    const content = await readMcpFile(guide.path);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `# ${guide.title}
+
+${content}`
+        }
+      ]
+    };
+  } catch (error) {
+    throw new Error(`Failed to get guide: ${error}`);
+  }
+}
+export {
+  setupToolHandlers
+};

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

@@ -0,0 +1,111 @@
+/**
+ * Type definitions for Green Design System MCP Server
+ */
+/**
+ * Component metadata from components.json
+ */
+export interface ComponentEntry {
+    name: string;
+    tagName: string;
+    className: string;
+    description?: string;
+    path: string;
+    files: string[];
+    subcomponents?: Array<{
+        tagName: string;
+        description?: string;
+    }>;
+}
+/**
+ * Icon metadata from icons.json
+ */
+export interface IconEntry {
+    name: string;
+    tagName: string;
+    className: string;
+    description?: string;
+    path: string;
+    files: string[];
+}
+/**
+ * Guide metadata from index.json
+ */
+export interface GuideEntry {
+    title: string;
+    path: string;
+    category: string;
+    description: string;
+    tags: string[];
+}
+/**
+ * Components index structure
+ */
+export interface ComponentsIndex {
+    version: string;
+    generatedAt: string;
+    components: ComponentEntry[];
+}
+/**
+ * Icons index structure
+ */
+export interface IconsIndex {
+    version: string;
+    generatedAt: string;
+    icons: IconEntry[];
+}
+/**
+ * Global index structure
+ */
+export interface GlobalIndex {
+    version: string;
+    generatedAt: string;
+    components: string;
+    icons: string;
+    guides: GuideEntry[];
+}
+/**
+ * Framework types
+ */
+export type Framework = 'angular' | 'react' | 'web-component';
+/**
+ * Category types for search
+ */
+export type Category = 'component' | 'icon' | 'all';
+/**
+ * Guide category types
+ */
+export type GuideCategory = 'framework-setup' | 'getting-started' | 'concepts' | 'troubleshooting' | 'migration' | 'all';
+/**
+ * Search result
+ */
+export interface SearchResult {
+    name: string;
+    tagName: string;
+    className: string;
+    description?: string;
+    category: 'component' | 'icon';
+    availableDocs: string[];
+    resourceUris: {
+        [key: string]: string;
+    };
+}
+/**
+ * Tool input schemas
+ */
+export interface SearchComponentsInput {
+    query: string;
+    category?: Category;
+}
+export interface GetComponentDocsInput {
+    componentName: string;
+    framework: Framework;
+    includeGuidelines?: boolean;
+    includeInstructions?: boolean;
+}
+export interface ListGuidesInput {
+    category?: GuideCategory;
+    framework?: 'angular' | 'react' | 'all';
+}
+export interface GetGuideInput {
+    name: string;
+}