@trishchuk/coolors-mcp 1.0.0

package/src/session.ts

@@ -0,0 +1,116 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  ListToolsRequestSchema,
+  McpError,
+} from "@modelcontextprotocol/sdk/types.js";
+import { EventEmitter } from "events";
+import { StrictEventEmitter } from "strict-event-emitter-types";
+import { toJsonSchema } from "xsschema";
+
+import {
+  CoolorsMCPSessionAuth,
+  CoolorsMCPSessionEvents,
+  ServerOptions,
+  Tool,
+} from "./types.js";
+
+export class CoolorsMCPSession extends (EventEmitter as {
+  new (): StrictEventEmitter<EventEmitter, CoolorsMCPSessionEvents>;
+}) {
+  #server: Server;
+  #tools: Tool<CoolorsMCPSessionAuth>[];
+
+  constructor(
+    options: ServerOptions<CoolorsMCPSessionAuth>,
+    tools: Tool<CoolorsMCPSessionAuth>[],
+  ) {
+    super();
+    this.#server = new Server(
+      { name: options.name, version: options.version },
+      { capabilities: { tools: {} } },
+    );
+    this.#tools = tools;
+    this.setupToolHandlers();
+  }
+
+  public async connect(transport: Transport) {
+    await this.#server.connect(transport);
+    this.emit("ready");
+  }
+
+  private setupToolHandlers() {
+    this.#server.setRequestHandler(ListToolsRequestSchema, async () => {
+      return {
+        tools: await Promise.all(
+          this.#tools.map(async (tool) => {
+            return {
+              annotations: tool.annotations,
+              description: tool.description,
+              inputSchema: tool.parameters
+                ? await toJsonSchema(tool.parameters)
+                : {
+                    additionalProperties: false,
+                    properties: {},
+                    type: "object",
+                  },
+              name: tool.name,
+            };
+          }),
+        ),
+      };
+    });
+
+    this.#server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const tool = this.#tools.find(
+        (tool) => tool.name === request.params.name,
+      );
+
+      if (!tool) {
+        throw new McpError(
+          ErrorCode.MethodNotFound,
+          `Unknown tool: ${request.params.name}`,
+        );
+      }
+
+      let args: unknown = undefined;
+
+      if (tool.parameters) {
+        const parsed = await tool.parameters["~standard"].validate(
+          request.params.arguments,
+        );
+
+        if (parsed.issues) {
+          const friendlyErrors = parsed.issues
+            .map((issue) => {
+              const path = issue.path?.join(".") || "root";
+              return `${path}: ${issue.message}`;
+            })
+            .join(", ");
+
+          throw new McpError(
+            ErrorCode.InvalidParams,
+            `Tool '${request.params.name}' parameter validation failed: ${friendlyErrors}. Please check the parameter types and values according to the tool's schema.`,
+          );
+        }
+
+        args = parsed.value;
+      }
+
+      const result = await tool.execute(
+        args as Parameters<typeof tool.execute>[0],
+        {} as CoolorsMCPSessionAuth,
+      );
+
+      if (typeof result === "string") {
+        return {
+          content: [{ text: result, type: "text" }],
+        };
+      }
+
+      return result;
+    });
+  }
+}

package/src/theme/__tests__/matcher.test.ts

@@ -0,0 +1,180 @@
+/**
+ * Tests for Theme Color Matcher
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type { ThemeVariables } from "../types.js";
+
+import { findBatchMatches, findClosestThemeColor } from "../matcher.js";
+import { parseThemeVariables } from "../parser.js";
+
+describe("Theme Color Matcher", () => {
+  // Sample theme for testing
+  const sampleThemeCSS = `
+    :root {
+      --color-primary-0: #000000;
+      --color-primary-10: #21005d;
+      --color-primary-20: #381e72;
+      --color-primary-30: #4f378b;
+      --color-primary-40: #6750a4;
+      --color-primary-50: #7f67be;
+      --color-primary-60: #9a82db;
+      --color-primary-70: #b69df8;
+      --color-primary-80: #d0bcff;
+      --color-primary-90: #eaddff;
+      --color-primary-95: #f6edff;
+      --color-primary-99: #fffbfe;
+      --color-primary-100: #ffffff;
+      
+      --color-surface-0: #000000;
+      --color-surface-10: #1c1b1f;
+      --color-surface-90: #e6e1e5;
+      --color-surface-95: #f4eff4;
+      --color-surface-99: #fffbfe;
+      --color-surface-100: #ffffff;
+      
+      --color-error-40: #ba1a1a;
+      --color-error-90: #ffdad6;
+    }
+  `;
+
+  const themeVariables: ThemeVariables = parseThemeVariables(sampleThemeCSS);
+
+  describe("findClosestThemeColor", () => {
+    it("should find exact match", () => {
+      const match = findClosestThemeColor("#6750a4", themeVariables);
+
+      expect(match).toBeDefined();
+      expect(match?.variable).toBe("--color-primary-40");
+      expect(match?.confidence).toBeGreaterThan(95);
+      expect(match?.distance).toBeLessThan(1);
+    });
+
+    it("should find close match", () => {
+      const match = findClosestThemeColor("#6850a0", themeVariables);
+
+      expect(match).toBeDefined();
+      expect(match?.variable).toBe("--color-primary-40");
+      expect(match?.confidence).toBeGreaterThan(70);
+      expect(match?.distance).toBeLessThan(10);
+    });
+
+    it("should return null for colors too far from theme", () => {
+      const match = findClosestThemeColor("#00ff00", themeVariables, {
+        maxDistance: 20,
+      });
+
+      expect(match).toBeNull();
+    });
+
+    it("should use context for better matching", () => {
+      const textMatch = findClosestThemeColor("#1a1a1a", themeVariables, {
+        contextType: "text",
+      });
+
+      const bgMatch = findClosestThemeColor("#f5f5f5", themeVariables, {
+        contextType: "background",
+      });
+
+      expect(textMatch).toBeDefined();
+      expect(bgMatch).toBeDefined();
+
+      // Text should prefer darker colors
+      if (textMatch?.variable.includes("surface")) {
+        expect(textMatch.variable).toMatch(/-(0|10)/);
+      }
+
+      // Background should prefer lighter colors
+      if (bgMatch?.variable.includes("surface")) {
+        expect(bgMatch.variable).toMatch(/-(90|95|99|100)/);
+      }
+    });
+
+    it("should provide alternatives", () => {
+      const match = findClosestThemeColor("#5040a0", themeVariables);
+
+      expect(match).toBeDefined();
+      expect(match?.alternatives).toBeDefined();
+      expect(match?.alternatives.length).toBeGreaterThan(0);
+      expect(match?.alternatives.length).toBeLessThanOrEqual(3);
+    });
+
+    it("should detect semantic role", () => {
+      const match = findClosestThemeColor("#ba1a1a", themeVariables);
+
+      expect(match).toBeDefined();
+      expect(match?.semanticRole).toBe("error");
+    });
+
+    it("should calculate accessibility info for text context", () => {
+      const match = findClosestThemeColor("#000000", themeVariables, {
+        contextType: "text",
+      });
+
+      expect(match).toBeDefined();
+      expect(match?.accessibilityInfo).toBeDefined();
+      expect(match?.accessibilityInfo?.contrastWithBackground).toBeGreaterThan(
+        0,
+      );
+      expect(match?.accessibilityInfo?.meetsAA).toBeDefined();
+      expect(match?.accessibilityInfo?.meetsAAA).toBeDefined();
+    });
+
+    it("should respect preferred role", () => {
+      const match = findClosestThemeColor("#d0bcff", themeVariables, {
+        preferredRole: "primary",
+      });
+
+      expect(match).toBeDefined();
+      expect(match?.variable).toBe("--color-primary-80");
+      expect(match?.semanticRole).toBe("primary");
+    });
+  });
+
+  describe("findBatchMatches", () => {
+    it("should match multiple colors", () => {
+      const colors = ["#6750a4", "#ba1a1a", "#ffffff"];
+      const matches = findBatchMatches(colors, themeVariables);
+
+      expect(matches.size).toBe(3);
+
+      const primaryMatch = matches.get("#6750a4");
+      expect(primaryMatch).toBeDefined();
+      expect(primaryMatch?.variable).toBe("--color-primary-40");
+
+      const errorMatch = matches.get("#ba1a1a");
+      expect(errorMatch).toBeDefined();
+      expect(errorMatch?.variable).toBe("--color-error-40");
+
+      const whiteMatch = matches.get("#ffffff");
+      expect(whiteMatch).toBeDefined();
+      expect(whiteMatch?.variable).toMatch(/-(100|99)$/);
+    });
+
+    it("should handle invalid colors", () => {
+      const colors = ["#6750a4", "invalid", "#ffffff"];
+      const matches = findBatchMatches(colors, themeVariables);
+
+      expect(matches.size).toBe(3);
+      expect(matches.get("invalid")).toBeNull();
+      expect(matches.get("#6750a4")).toBeDefined();
+      expect(matches.get("#ffffff")).toBeDefined();
+    });
+
+    it("should apply context to all colors", () => {
+      const colors = ["#1c1b1f", "#e6e1e5"];
+      const matches = findBatchMatches(colors, themeVariables, {
+        contextType: "text",
+      });
+
+      expect(matches.size).toBe(2);
+
+      const darkMatch = matches.get("#1c1b1f");
+      const lightMatch = matches.get("#e6e1e5");
+
+      expect(darkMatch).toBeDefined();
+      expect(lightMatch).toBeDefined();
+    });
+  });
+});

package/src/theme/__tests__/parser.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Tests for Theme Parser
+ */
+
+import { describe, expect, it } from "vitest";
+
+import {
+  parseThemeVariables,
+  parseThemeVariablesFromObject,
+} from "../parser.js";
+
+describe("Theme Parser", () => {
+  describe("parseThemeVariables", () => {
+    it("should parse CSS custom properties", () => {
+      const css = `
+        :root {
+          --color-primary-0: #000000;
+          --color-primary-50: #1976d2;
+          --color-primary-100: #ffffff;
+          --color-secondary-50: #dc004e;
+        }
+      `;
+
+      const result = parseThemeVariables(css);
+
+      expect(result.primary).toBeDefined();
+      expect(result.primary).toHaveLength(3);
+      expect(result.primary![0].name).toBe("--color-primary-0");
+      expect(result.primary![0].value).toBe("#000000");
+      expect(result.primary![0].tone).toBeCloseTo(0, 1);
+
+      expect(result.secondary).toBeDefined();
+      expect(result.secondary).toHaveLength(1);
+      expect(result.secondary![0].name).toBe("--color-secondary-50");
+    });
+
+    it("should handle different color formats", () => {
+      const css = `
+        :root {
+          --primary: #ff0000;
+          --secondary: rgb(0, 255, 0);
+          --tertiary: hsl(240, 100%, 50%);
+          --neutral: gray;
+        }
+      `;
+
+      const result = parseThemeVariables(css);
+
+      expect(result.primary).toBeDefined();
+      expect(result.primary![0].value).toBe("#ff0000");
+
+      expect(result.secondary).toBeDefined();
+      expect(result.secondary![0].value).toBe("#00ff00");
+
+      expect(result.tertiary).toBeDefined();
+      expect(result.tertiary![0].value).toBe("#0000ff");
+
+      expect(result.neutral).toBeDefined();
+      expect(result.neutral![0].value).toBe("#808080");
+    });
+
+    it("should detect semantic roles from variable names", () => {
+      const css = `
+        :root {
+          --primary-color: #1976d2;
+          --secondary-accent: #dc004e;
+          --error-red: #d32f2f;
+          --surface-light: #f5f5f5;
+          --background-dark: #121212;
+          --border-gray: #e0e0e0;
+          --shadow-color: rgba(0,0,0,0.2);
+        }
+      `;
+
+      const result = parseThemeVariables(css);
+
+      expect(result.primary).toBeDefined();
+      expect(result.primary![0].role).toBe("primary");
+
+      expect(result.secondary).toBeDefined();
+      expect(result.secondary![0].role).toBe("secondary");
+
+      expect(result.error).toBeDefined();
+      expect(result.error![0].role).toBe("error");
+
+      expect(result.surface).toBeDefined();
+      expect(result.surface![0].role).toBe("surface");
+
+      expect(result.background).toBeDefined();
+      expect(result.background![0].role).toBe("background");
+    });
+
+    it("should organize custom roles", () => {
+      const css = `
+        :root {
+          --color-brand-0: #000000;
+          --color-brand-50: #1976d2;
+          --color-brand-100: #ffffff;
+          --accent-warm: #ff6b6b;
+          --random-color: #123456;
+        }
+      `;
+
+      const result = parseThemeVariables(css);
+
+      expect(result.custom).toBeDefined();
+      expect(result.custom!["brand"]).toBeDefined();
+      expect(result.custom!["brand"]).toHaveLength(3);
+      // accent-warm will be parsed as 'accent'
+      expect(result.custom!["accent"]).toBeDefined();
+      expect(result.custom!["uncategorized"]).toBeDefined();
+    });
+
+    it("should sort variables by tone", () => {
+      const css = `
+        :root {
+          --color-primary-90: #e1f5fe;
+          --color-primary-10: #01579b;
+          --color-primary-50: #1976d2;
+        }
+      `;
+
+      const result = parseThemeVariables(css);
+
+      expect(result.primary).toBeDefined();
+      expect(result.primary![0].tone).toBeLessThan(result.primary![1].tone);
+      expect(result.primary![1].tone).toBeLessThan(result.primary![2].tone);
+    });
+  });
+
+  describe("parseThemeVariablesFromObject", () => {
+    it("should parse variables from object", () => {
+      const variables = {
+        "--color-primary-50": "#1976d2",
+        "--color-secondary-50": "#dc004e",
+        "--not-a-color": "16px",
+        "not-a-variable": "#000000",
+      };
+
+      const result = parseThemeVariablesFromObject(variables);
+
+      expect(result.primary).toBeDefined();
+      expect(result.primary).toHaveLength(1);
+      expect(result.secondary).toBeDefined();
+      expect(result.secondary).toHaveLength(1);
+    });
+  });
+});

package/src/theme/__tests__/refactor.test.ts

@@ -0,0 +1,224 @@
+/**
+ * Tests for CSS Refactoring Utilities
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { parseThemeVariables } from "../parser.js";
+import {
+  generateRefactoringReport,
+  refactorColor,
+  refactorCss,
+} from "../refactor.js";
+
+describe("CSS Refactoring", () => {
+  const themeCSS = `
+    :root {
+      --color-primary-40: #6750a4;
+      --color-primary-60: #9a82db;
+      --color-primary-80: #d0bcff;
+      --color-surface-10: #1c1b1f;
+      --color-surface-90: #e6e1e5;
+      --color-surface-99: #fffbfe;
+      --color-error-40: #ba1a1a;
+      --color-neutral-50: #79747e;
+      --color-outline-50: #79747e;
+    }
+  `;
+
+  const themeVariables = parseThemeVariables(themeCSS);
+
+  describe("refactorCss", () => {
+    it("should refactor hex colors", () => {
+      const css = `.button {
+        background-color: #6750a4;
+        color: #fffbfe;
+        border: 1px solid #79747e;
+      }`;
+
+      const result = refactorCss(css, themeVariables);
+
+      expect(result.statistics.totalColors).toBe(3);
+      expect(result.statistics.replacedColors).toBe(3);
+      expect(result.refactored).toContain("var(--color-primary-40)");
+      expect(result.refactored).toContain("var(--color-surface-99)");
+      expect(result.refactored).toContain("var(--color-");
+    });
+
+    it("should preserve original colors as comments when requested", () => {
+      const css = `.button { background: #6750a4; }`;
+
+      const result = refactorCss(css, themeVariables, {
+        addComments: true,
+        preserveOriginal: true,
+      });
+
+      expect(result.refactored).toContain("/* #6750a4 */");
+      expect(result.refactored).toContain("var(--color-primary-40)");
+    });
+
+    it("should not preserve original when disabled", () => {
+      const css = `.button { background: #6750a4; }`;
+
+      const result = refactorCss(css, themeVariables, {
+        addComments: false,
+        preserveOriginal: false,
+      });
+
+      expect(result.refactored).not.toContain("/* #6750a4 */");
+      expect(result.refactored).toContain("var(--color-primary-40)");
+    });
+
+    it("should handle rgb colors", () => {
+      const css = `.text { color: rgb(28, 27, 31); }`;
+
+      // Lower confidence threshold since HCT conversion may cause slight differences
+      const result = refactorCss(css, themeVariables, { minConfidence: 60 });
+
+      expect(result.statistics.totalColors).toBe(1);
+      expect(result.statistics.replacedColors).toBe(1);
+      expect(result.refactored).toContain("var(--color-surface-10)");
+    });
+
+    it("should respect minimum confidence", () => {
+      const css = `.button { background: #5040a0; }`; // Similar but not exact
+
+      const result = refactorCss(css, themeVariables, {
+        minConfidence: 95,
+      });
+
+      expect(result.statistics.replacedColors).toBe(0);
+      expect(result.warnings.length).toBeGreaterThan(0);
+      expect(result.warnings[0].type).toBe("low-confidence");
+    });
+
+    it("should generate warnings for no matches", () => {
+      const css = `.button { background: #00ff00; }`; // Green - not in theme
+
+      const result = refactorCss(css, themeVariables);
+
+      expect(result.statistics.replacedColors).toBe(0);
+      expect(result.warnings.length).toBe(1);
+      expect(result.warnings[0].type).toBe("no-match");
+    });
+
+    it("should use context from CSS properties", () => {
+      const css = `
+        .element {
+          color: #1c1b1f;
+          background-color: #fffbfe;
+          border-color: #79747e;
+          box-shadow: 0 2px 4px #1c1b1f;
+        }
+      `;
+
+      const result = refactorCss(css, themeVariables);
+
+      expect(result.statistics.replacedColors).toBe(4);
+      expect(result.replacements[0].context).toBe("text");
+      expect(result.replacements[1].context).toBe("background");
+      expect(result.replacements[2].context).toBe("border");
+      expect(result.replacements[3].context).toBe("shadow");
+    });
+
+    it("should add summary comment when requested", () => {
+      const css = `.button { background: #6750a4; }`;
+
+      const result = refactorCss(css, themeVariables, {
+        addComments: true,
+      });
+
+      expect(result.refactored).toContain(
+        "/* CSS Refactored with Theme Variables",
+      );
+      expect(result.refactored).toContain("Total colors found:");
+      expect(result.refactored).toContain("Colors replaced:");
+    });
+
+    it("should track line and column positions", () => {
+      const css = `.button {\n  background: #6750a4;\n  color: #fffbfe;\n}`;
+
+      const result = refactorCss(css, themeVariables);
+
+      expect(result.replacements[0].line).toBe(2);
+      expect(result.replacements[1].line).toBe(3);
+      expect(result.replacements[0].column).toBeGreaterThan(0);
+    });
+  });
+
+  describe("refactorColor", () => {
+    it("should refactor single color", () => {
+      const result = refactorColor("#6750a4", themeVariables);
+
+      expect(result.variable).toBe("--color-primary-40");
+      expect(result.confidence).toBeGreaterThan(95);
+      expect(result.alternatives).toBeDefined();
+    });
+
+    it("should return null for no match", () => {
+      const result = refactorColor("#00ff00", themeVariables);
+
+      expect(result.variable).toBeNull();
+      expect(result.confidence).toBe(0);
+      expect(result.alternatives).toHaveLength(0);
+    });
+
+    it("should use context when provided", () => {
+      const result = refactorColor("#79747e", themeVariables, "border");
+
+      expect(result.variable).toBe("--color-outline-50");
+      expect(result.confidence).toBeGreaterThan(0);
+    });
+  });
+
+  describe("generateRefactoringReport", () => {
+    it("should generate markdown report", () => {
+      const css = `
+        .button {
+          background: #6750a4;
+          color: #fffbfe;
+          border: 1px solid #00ff00;
+        }
+      `;
+
+      const result = refactorCss(css, themeVariables);
+      const report = generateRefactoringReport(result);
+
+      expect(report).toContain("# CSS Refactoring Report");
+      expect(report).toContain("## Summary");
+      expect(report).toContain("Total colors found:");
+      expect(report).toContain("## Replacements");
+      expect(report).toContain("## Warnings");
+    });
+
+    it("should group replacements by confidence", () => {
+      const css = `
+        .high { color: #6750a4; }
+        .medium { color: #6751a5; }
+        .low { color: #5040a0; }
+      `;
+
+      const result = refactorCss(css, themeVariables, {
+        minConfidence: 30,
+      });
+      const report = generateRefactoringReport(result);
+
+      expect(report).toMatch(
+        /High Confidence|Medium Confidence|Low Confidence/,
+      );
+    });
+
+    it("should group warnings by type", () => {
+      const css = `
+        .no-match { color: #00ff00; }
+        .low-conf { color: #123456; }
+      `;
+
+      const result = refactorCss(css, themeVariables);
+      const report = generateRefactoringReport(result);
+
+      expect(report).toContain("No Matches Found");
+      expect(report).toMatch(/Low Confidence|No Matches/);
+    });
+  });
+});

package/src/theme/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Theme Module
+ * Export all theme-related functionality
+ */
+
+// Matcher
+export { findBatchMatches, findClosestThemeColor } from "./matcher.js";
+
+// Parser
+export {
+  parseThemeVariables,
+  parseThemeVariablesFromObject,
+} from "./parser.js";
+
+// Refactor
+export {
+  generateRefactoringReport,
+  refactorColor,
+  refactorCss,
+} from "./refactor.js";
+
+// Types
+export type {
+  ColorContext,
+  ColorReplacement,
+  MatchingOptions,
+  RefactoringResult,
+  RefactoringWarning,
+  SemanticRole,
+  ThemeMatch,
+  ThemeQualityReport,
+  ThemeVariable,
+  ThemeVariables,
+} from "./types.js";