@sebgroup/green-core 2.25.0 → 2.26.0

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

@@ -0,0 +1,99 @@
+/**
+ * Constants for the Green Design System MCP Server
+ */
+/**
+ * Server configuration constants
+ */
+export declare const SERVER_CONFIG: {
+    /** Server name used in MCP protocol */
+    readonly SERVER_NAME: "green-design-system";
+    /** Fallback version if package.json cannot be read */
+    readonly DEFAULT_VERSION: "0.0.0";
+};
+/**
+ * Search configuration constants
+ */
+export declare const SEARCH_CONFIG: {
+    /** Maximum length for regex patterns to prevent ReDoS attacks */
+    readonly MAX_REGEX_LENGTH: 100;
+    /** Default maximum number of search results to return */
+    readonly DEFAULT_MAX_RESULTS: 20;
+    /** Minimum query length required for search */
+    readonly MIN_QUERY_LENGTH: 1;
+};
+/**
+ * Search result tier priorities (lower number = better match)
+ * Used to rank search results by relevance
+ */
+export declare const SEARCH_TIERS: {
+    /** Exact match with tag name (e.g., "gds-button" matches "gds-button") */
+    readonly EXACT_MATCH: 1;
+    /** Tag name starts with search term (e.g., "button" matches "gds-button-group") */
+    readonly STARTS_WITH: 2;
+    /** Tag name contains search term (e.g., "button" matches "gds-radio-button") */
+    readonly TAG_CONTAINS: 3;
+    /** Name or className contains search term */
+    readonly NAME_CONTAINS: 4;
+    /** Description contains search term */
+    readonly DESCRIPTION_CONTAINS: 5;
+};
+/**
+ * File and path constants
+ */
+export declare const PATHS: {
+    /** Name of the root instructions file */
+    readonly INSTRUCTIONS_FILE: "INSTRUCTIONS.md";
+    /** Components index file name */
+    readonly COMPONENTS_INDEX: "components.json";
+    /** Icons index file name */
+    readonly ICONS_INDEX: "icons.json";
+    /** Global index file name */
+    readonly GLOBAL_INDEX: "index.json";
+    /** Package.json file name */
+    readonly PACKAGE_JSON: "package.json";
+};
+/**
+ * URI scheme for Green resources
+ */
+export declare const URI_SCHEME: {
+    /** Protocol scheme for Green resources */
+    readonly SCHEME: "green://";
+    /** Instructions resource URI */
+    readonly INSTRUCTIONS: "green://instructions";
+};
+/**
+ * Component prefixes
+ */
+export declare const PREFIXES: {
+    /** Standard component prefix */
+    readonly COMPONENT: "gds-";
+    /** Icon component prefix */
+    readonly ICON: "gds-icon-";
+};
+/**
+ * Framework types
+ */
+export declare const FRAMEWORKS: readonly ["angular", "react", "web-component"];
+/**
+ * Category types
+ */
+export declare const CATEGORIES: readonly ["component", "icon", "all"];
+/**
+ * Guide categories
+ */
+export declare const GUIDE_CATEGORIES: readonly ["framework-setup", "getting-started", "concepts", "troubleshooting", "migration", "all"];
+/**
+ * Documentation types available for components
+ */
+export declare const DOC_TYPES: {
+    /** Web Component API documentation */
+    readonly API: "api";
+    /** Angular-specific documentation */
+    readonly ANGULAR: "angular";
+    /** React-specific documentation */
+    readonly REACT: "react";
+    /** UX and design guidelines */
+    readonly GUIDELINES: "guidelines";
+    /** Agent-specific usage instructions */
+    readonly INSTRUCTIONS: "instructions";
+};

package/bin/mcp-server/constants.js

@@ -0,0 +1,85 @@
+import "../../chunks/chunk.QU3DSPNU.js";
+const SERVER_CONFIG = {
+  /** Server name used in MCP protocol */
+  SERVER_NAME: "green-design-system",
+  /** Fallback version if package.json cannot be read */
+  DEFAULT_VERSION: "0.0.0"
+};
+const SEARCH_CONFIG = {
+  /** Maximum length for regex patterns to prevent ReDoS attacks */
+  MAX_REGEX_LENGTH: 100,
+  /** Default maximum number of search results to return */
+  DEFAULT_MAX_RESULTS: 20,
+  /** Minimum query length required for search */
+  MIN_QUERY_LENGTH: 1
+};
+const SEARCH_TIERS = {
+  /** Exact match with tag name (e.g., "gds-button" matches "gds-button") */
+  EXACT_MATCH: 1,
+  /** Tag name starts with search term (e.g., "button" matches "gds-button-group") */
+  STARTS_WITH: 2,
+  /** Tag name contains search term (e.g., "button" matches "gds-radio-button") */
+  TAG_CONTAINS: 3,
+  /** Name or className contains search term */
+  NAME_CONTAINS: 4,
+  /** Description contains search term */
+  DESCRIPTION_CONTAINS: 5
+};
+const PATHS = {
+  /** Name of the root instructions file */
+  INSTRUCTIONS_FILE: "INSTRUCTIONS.md",
+  /** Components index file name */
+  COMPONENTS_INDEX: "components.json",
+  /** Icons index file name */
+  ICONS_INDEX: "icons.json",
+  /** Global index file name */
+  GLOBAL_INDEX: "index.json",
+  /** Package.json file name */
+  PACKAGE_JSON: "package.json"
+};
+const URI_SCHEME = {
+  /** Protocol scheme for Green resources */
+  SCHEME: "green://",
+  /** Instructions resource URI */
+  INSTRUCTIONS: "green://instructions"
+};
+const PREFIXES = {
+  /** Standard component prefix */
+  COMPONENT: "gds-",
+  /** Icon component prefix */
+  ICON: "gds-icon-"
+};
+const FRAMEWORKS = ["angular", "react", "web-component"];
+const CATEGORIES = ["component", "icon", "all"];
+const GUIDE_CATEGORIES = [
+  "framework-setup",
+  "getting-started",
+  "concepts",
+  "troubleshooting",
+  "migration",
+  "all"
+];
+const DOC_TYPES = {
+  /** Web Component API documentation */
+  API: "api",
+  /** Angular-specific documentation */
+  ANGULAR: "angular",
+  /** React-specific documentation */
+  REACT: "react",
+  /** UX and design guidelines */
+  GUIDELINES: "guidelines",
+  /** Agent-specific usage instructions */
+  INSTRUCTIONS: "instructions"
+};
+export {
+  CATEGORIES,
+  DOC_TYPES,
+  FRAMEWORKS,
+  GUIDE_CATEGORIES,
+  PATHS,
+  PREFIXES,
+  SEARCH_CONFIG,
+  SEARCH_TIERS,
+  SERVER_CONFIG,
+  URI_SCHEME
+};

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

@@ -0,0 +1,90 @@
+/**
+ * Error handling for the Green Design System MCP Server
+ */
+/**
+ * Error codes for MCP operations
+ */
+export declare enum McpErrorCode {
+    /** Invalid input parameter provided */
+    INVALID_INPUT = "INVALID_INPUT",
+    /** Requested resource not found */
+    NOT_FOUND = "NOT_FOUND",
+    /** Failed to load required data files */
+    DATA_LOAD_FAILED = "DATA_LOAD_FAILED",
+    /** Invalid resource URI format */
+    INVALID_URI = "INVALID_URI",
+    /** File system operation failed */
+    FILE_ERROR = "FILE_ERROR",
+    /** Invalid regex pattern */
+    INVALID_REGEX = "INVALID_REGEX",
+    /** Search operation failed */
+    SEARCH_FAILED = "SEARCH_FAILED",
+    /** Internal server error */
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+}
+/**
+ * Base error class for MCP server errors
+ * Provides structured error information for better debugging and error handling
+ */
+export declare class McpError extends Error {
+    readonly code: McpErrorCode;
+    readonly context?: Record<string, unknown> | undefined;
+    /**
+     * Create a new MCP error
+     * @param message - Human-readable error message
+     * @param code - Error code for programmatic handling
+     * @param context - Additional context information about the error
+     */
+    constructor(message: string, code: McpErrorCode, context?: Record<string, unknown> | undefined);
+    /**
+     * Convert error to JSON representation
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown when input validation fails
+ */
+export declare class ValidationError extends McpError {
+    readonly field?: string | undefined;
+    constructor(message: string, field?: string | undefined, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when a resource is not found
+ */
+export declare class NotFoundError extends McpError {
+    readonly resourceType: string;
+    readonly resourceId: string;
+    constructor(message: string, resourceType: string, resourceId: string, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when data loading fails
+ */
+export declare class DataLoadError extends McpError {
+    readonly filePath: string;
+    constructor(message: string, filePath: string, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when a regex pattern is invalid
+ */
+export declare class RegexError extends McpError {
+    readonly pattern: string;
+    constructor(message: string, pattern: string, context?: Record<string, unknown>);
+}
+/**
+ * Convert any error to an MCP error response format
+ * @param error - The error to convert
+ * @returns Formatted error response
+ */
+export declare function formatErrorResponse(error: unknown): {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    isError: boolean;
+};
+/**
+ * Log error with structured information
+ * @param error - The error to log
+ * @param operation - The operation that failed
+ */
+export declare function logError(error: unknown, operation: string): void;

package/bin/mcp-server/errors.js

@@ -0,0 +1,145 @@
+import "../../chunks/chunk.QU3DSPNU.js";
+var McpErrorCode = /* @__PURE__ */ ((McpErrorCode2) => {
+  McpErrorCode2["INVALID_INPUT"] = "INVALID_INPUT";
+  McpErrorCode2["NOT_FOUND"] = "NOT_FOUND";
+  McpErrorCode2["DATA_LOAD_FAILED"] = "DATA_LOAD_FAILED";
+  McpErrorCode2["INVALID_URI"] = "INVALID_URI";
+  McpErrorCode2["FILE_ERROR"] = "FILE_ERROR";
+  McpErrorCode2["INVALID_REGEX"] = "INVALID_REGEX";
+  McpErrorCode2["SEARCH_FAILED"] = "SEARCH_FAILED";
+  McpErrorCode2["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+  return McpErrorCode2;
+})(McpErrorCode || {});
+class McpError extends Error {
+  /**
+   * Create a new MCP error
+   * @param message - Human-readable error message
+   * @param code - Error code for programmatic handling
+   * @param context - Additional context information about the error
+   */
+  constructor(message, code, context) {
+    super(message);
+    this.code = code;
+    this.context = context;
+    this.name = "McpError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, McpError);
+    }
+  }
+  /**
+   * Convert error to JSON representation
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      context: this.context,
+      stack: this.stack
+    };
+  }
+}
+class ValidationError extends McpError {
+  constructor(message, field, context) {
+    super(message, "INVALID_INPUT" /* INVALID_INPUT */, {
+      ...context,
+      field
+    });
+    this.field = field;
+    this.name = "ValidationError";
+  }
+}
+class NotFoundError extends McpError {
+  constructor(message, resourceType, resourceId, context) {
+    super(message, "NOT_FOUND" /* NOT_FOUND */, {
+      ...context,
+      resourceType,
+      resourceId
+    });
+    this.resourceType = resourceType;
+    this.resourceId = resourceId;
+    this.name = "NotFoundError";
+  }
+}
+class DataLoadError extends McpError {
+  constructor(message, filePath, context) {
+    super(message, "DATA_LOAD_FAILED" /* DATA_LOAD_FAILED */, {
+      ...context,
+      filePath
+    });
+    this.filePath = filePath;
+    this.name = "DataLoadError";
+  }
+}
+class RegexError extends McpError {
+  constructor(message, pattern, context) {
+    super(message, "INVALID_REGEX" /* INVALID_REGEX */, {
+      ...context,
+      pattern
+    });
+    this.pattern = pattern;
+    this.name = "RegexError";
+  }
+}
+function formatErrorResponse(error) {
+  let message;
+  let code;
+  let context;
+  if (error instanceof McpError) {
+    message = error.message;
+    code = error.code;
+    context = error.context;
+  } else if (error instanceof Error) {
+    message = error.message;
+    code = "INTERNAL_ERROR" /* INTERNAL_ERROR */;
+  } else {
+    message = String(error);
+    code = "INTERNAL_ERROR" /* INTERNAL_ERROR */;
+  }
+  let errorText = `Error: ${message}`;
+  if (code) {
+    errorText = `Error [${code}]: ${message}`;
+  }
+  if (context && Object.keys(context).length > 0) {
+    errorText += `
+
+Context: ${JSON.stringify(context, null, 2)}`;
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: errorText
+      }
+    ],
+    isError: true
+  };
+}
+function logError(error, operation) {
+  const logData = {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    operation
+  };
+  if (error instanceof McpError) {
+    logData.errorCode = error.code;
+    logData.message = error.message;
+    logData.context = error.context;
+  } else if (error instanceof Error) {
+    logData.errorType = error.name;
+    logData.message = error.message;
+    logData.stack = error.stack;
+  } else {
+    logData.error = String(error);
+  }
+  console.error("[MCP Error]", JSON.stringify(logData));
+}
+export {
+  DataLoadError,
+  McpError,
+  McpErrorCode,
+  NotFoundError,
+  RegexError,
+  ValidationError,
+  formatErrorResponse,
+  logError
+};

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,41 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { SERVER_CONFIG } from "./constants.js";
+import { logError } from "./errors.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: SERVER_CONFIG.SERVER_NAME,
+      version: packageVersion
+    },
+    {
+      capabilities: {
+        resources: {},
+        tools: {}
+      }
+    }
+  );
+  setupResourceHandlers(server.server);
+  setupToolHandlers(server.server);
+  server.server.onerror = (error) => {
+    logError(error, "mcpServer");
+  };
+  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,159 @@
+import "../../chunks/chunk.QU3DSPNU.js";
+import {
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { PATHS, URI_SCHEME } from "./constants.js";
+import { logError, NotFoundError } from "./errors.js";
+import {
+  buildResourceUri,
+  loadComponentsIndex,
+  loadGlobalIndex,
+  loadIconsIndex,
+  parseResourceUri,
+  readMcpFile
+} 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) {
+        if (globalIndex.instructions) {
+          resources.push({
+            uri: URI_SCHEME.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";
+          const uri = buildResourceUri(category, name);
+          resources.push({
+            uri,
+            name: guide.title,
+            description: guide.description,
+            mimeType: "text/markdown"
+          });
+        }
+      }
+      return { resources };
+    } catch (error) {
+      logError(error, "listResources");
+      return { resources: [] };
+    }
+  });
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const { uri } = request.params;
+    try {
+      if (uri === URI_SCHEME.INSTRUCTIONS) {
+        const content2 = await readMcpFile(PATHS.INSTRUCTIONS_FILE);
+        if (!content2) {
+          throw new NotFoundError(
+            "Instructions file not found",
+            "file",
+            PATHS.INSTRUCTIONS_FILE
+          );
+        }
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: "text/markdown",
+              text: content2
+            }
+          ]
+        };
+      }
+      const parsed = parseResourceUri(uri);
+      if (!parsed) {
+        throw new NotFoundError(`Invalid resource URI format`, "uri", uri);
+      }
+      const { category, name, docType } = parsed;
+      let filePath;
+      if (category === "components" || category === "icons") {
+        if (!docType) {
+          throw new NotFoundError(
+            `Document type required for ${category}`,
+            "docType",
+            uri
+          );
+        }
+        filePath = `${name}/${docType}.md`;
+      } else if (category === "guides" || category === "concepts") {
+        filePath = `${category}/${name}.md`;
+      } else {
+        throw new NotFoundError(
+          `Unknown category: ${category}`,
+          "category",
+          uri
+        );
+      }
+      const content = await readMcpFile(filePath);
+      if (!content) {
+        throw new NotFoundError(`Resource not found`, "file", filePath, { uri });
+      }
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: "text/markdown",
+            text: content
+          }
+        ]
+      };
+    } catch (error) {
+      logError(error, "readResource");
+      throw error;
+    }
+  });
+}
+export {
+  setupResourceHandlers
+};

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

@@ -0,0 +1,32 @@
+/**
+ * Search engine for components and icons
+ * Handles complex matching logic with tiered relevance ranking
+ */
+import type { ComponentEntry, IconEntry, SearchResult } from './types.js';
+/**
+ * Parse search query into terms or regex
+ * @param query - Search query
+ * @param splitTerms - Whether to split query into multiple terms
+ * @param useRegex - Whether to treat query as regex
+ * @returns Search terms and optional regex pattern
+ */
+export declare function parseSearchQuery(query: string, splitTerms: boolean, useRegex: boolean): {
+    searchTerms: string[];
+    regexPattern: RegExp | null;
+};
+/**
+ * Search components and icons with tiered relevance ranking
+ * @param components - Array of component entries to search
+ * @param icons - Array of icon entries to search
+ * @param query - Original search query
+ * @param searchTerms - Parsed search terms
+ * @param regexPattern - Optional regex pattern
+ * @param matchAll - Whether all terms must match
+ * @param splitTerms - Whether terms were split
+ * @param maxResults - Maximum number of results to return
+ * @param buildResourceUris - Function to build resource URIs for a match
+ * @returns Sorted array of search results
+ */
+export declare function performSearch(components: ComponentEntry[], icons: IconEntry[], query: string, searchTerms: string[], regexPattern: RegExp | null, matchAll: boolean, splitTerms: boolean, maxResults: number, buildResourceUris: (item: ComponentEntry | IconEntry, category: 'component' | 'icon') => {
+    [key: string]: string;
+}): SearchResult[];